@@ -1087,7 +1088,7 @@
adbinpg_node_tree
- The column default value, in nodeToString()
+ The column default or generation expression, in nodeToString()
representation. Use pg_get_expr(adbin, adrelid) to
convert it to an SQL expression.
@@ -1185,17 +1186,6 @@
-
-
- attcacheoffint4
-
-
- 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
-
-
-
atttypmodint4
@@ -1270,7 +1260,7 @@
attnotnullbool
- This represents a not-null constraint.
+ This column has a (possibly invalid) not-null constraint.
@@ -1317,8 +1307,10 @@
If a zero byte (''), then not a generated column.
- Otherwise, s = stored. (Other values might be added
- in the future.)
+ Otherwise, s = stored, v =
+ virtual. A stored generated column is physically stored like a normal
+ column. A virtual generated column is physically stored as a null
+ value, with the actual value being computed at run time.
@@ -1590,7 +1582,7 @@
rolpasswordtext
- Password (possibly encrypted); null if none. The format depends
+ Encrypted password; null if none. The format depends
on the form of encryption used.
@@ -1617,6 +1609,15 @@
will store the md5 hash of xyzzyjoe.
+
+
+ Support for MD5-encrypted passwords is deprecated and will be removed in a
+ future release of PostgreSQL. Refer to
+ for details about migrating to another
+ password type.
+
+
+
If the password is encrypted with SCRAM-SHA-256, it has the format:
@@ -1626,11 +1627,6 @@ SCRAM-SHA-256$<iteration count>:&l
ServerKey are in Base64 encoded format. This format is
the same as that specified by RFC 5803.
-
-
- A password that does not follow either of those formats is assumed to be
- unencrypted.
-
@@ -1955,7 +1951,7 @@ SCRAM-SHA-256$<iteration count>:&l
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
+ if any; zero for indexes, sequences, and TOAST tables, which have
no pg_type entry
@@ -2065,6 +2061,27 @@ SCRAM-SHA-256$<iteration count>:&l
+
+
+ relallfrozenint4
+
+
+ Number of pages that are marked all-frozen in the table's visibility
+ map. This is only an estimate used for triggering autovacuums. It can
+ also be used along with relallvisible for
+ scheduling manual vacuums and tuning vacuum's freezing
+ behavior.
+
+ It is updated by
+ VACUUM,
+ ANALYZE,
+ and a few DDL commands such as
+ CREATE INDEX.
+
+
+
+
reltoastrelidoid
@@ -2384,9 +2401,9 @@ SCRAM-SHA-256$<iteration count>:&l
collproviderchar
- Provider of the collation: d = database
- default, c = libc, i = icu
-
+ Provider of the collation: d = database default,
+ b = builtin, c = libc,
+ i = icu
@@ -2501,14 +2518,10 @@ SCRAM-SHA-256$<iteration count>:&l
- The catalog pg_constraint stores check, primary
- key, unique, foreign key, and exclusion constraints on tables, as well as
- not-null constraints on domains.
+ The catalog pg_constraint stores check, not-null,
+ 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 on relations are represented in the
- pg_attribute
- catalog, not here.
@@ -2570,7 +2583,7 @@ SCRAM-SHA-256$<iteration count>:&l
c = check constraint,
f = foreign key constraint,
- n = not-null constraint (domains only),
+ n = not-null constraint,
p = primary key constraint,
u = unique constraint,
t = constraint trigger,
@@ -2596,13 +2609,21 @@ SCRAM-SHA-256$<iteration count>:&l
+
+
+ conenforcedbool
+
+
+ Is the constraint enforced?
+
+
+
convalidatedbool
Has the constraint been validated?
- Currently, can be false only for foreign keys and CHECK constraints
@@ -2729,6 +2750,17 @@ SCRAM-SHA-256$<iteration count>:&l
+
+
+ conperiodbool
+
+
+ This constraint is defined with WITHOUT OVERLAPS
+ (for primary keys and unique constraints) or PERIOD
+ (for foreign keys).
+
+
+
conkeyint2[]
@@ -2798,7 +2830,8 @@ SCRAM-SHA-256$<iteration count>:&l
(references pg_operator.oid)
- If an exclusion constraint, list of the per-column exclusion operators
+ If an exclusion constraint or WITHOUT OVERLAPS
+ primary key/unique constraint, list of the per-column exclusion operators.
@@ -3028,9 +3061,8 @@ SCRAM-SHA-256$<iteration count>:&l
datlocproviderchar
- Locale provider for this database: c = libc,
- i = icu
-
+ Locale provider for this database: b = builtin,
+ c = libc, i = icu
@@ -3126,7 +3158,7 @@ SCRAM-SHA-256$<iteration count>:&l
datcollatetext
- LC_COLLATE for this database
+ LC_COLLATE for this database (ignored unless datlocprovider is c)
@@ -3322,7 +3354,8 @@ SCRAM-SHA-256$<iteration count>:&l
S = sequence,
f = function,
T = type,
- n = schema
+ n = schema,
+ L = large object
@@ -3350,8 +3383,8 @@ SCRAM-SHA-256$<iteration count>:&l
- Note that when an ACL entry in another catalog is null, it is taken
- to represent the hard-wired default privileges for its object,
+ Note that when an ACL entry in another catalog is null,
+ it is taken to represent the hard-wired default privileges for its object,
not whatever might be in pg_default_acl
at the moment. pg_default_acl is only consulted during
object creation.
@@ -6024,7 +6057,7 @@ SCRAM-SHA-256$<iteration count>:&l
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.
+ is not leakproof.
@@ -6388,6 +6421,20 @@ SCRAM-SHA-256$<iteration count>:&l
publication instead of its own.
+
+
+
+ pubgencolschar
+
+
+ Controls how to handle generated column replication when there is no
+ publication column list:
+ n = generated columns in the tables associated with
+ the publication should not be replicated,
+ s = stored generated columns in the tables associated
+ with the publication should be replicated.
+
+
@@ -7168,7 +7215,7 @@ SCRAM-SHA-256$<iteration count>:&l
The referenced object (which must be a role) is mentioned in the
- ACL (access control list, i.e., privileges list) of the
+ ACL of the
dependent object. (A SHARED_DEPENDENCY_ACL entry is
not made for the owner of the object, since the owner will have
a SHARED_DEPENDENCY_OWNER entry anyway.)
@@ -7183,9 +7230,6 @@ SCRAM-SHA-256$<iteration count>:&l
The referenced object (which must be a role) is mentioned in a
pg_init_privs
entry for the dependent object.
- (A SHARED_DEPENDENCY_INITACL entry is not made for
- the owner of the object, since the owner will have
- a SHARED_DEPENDENCY_OWNER entry anyway.)
@@ -7927,7 +7971,7 @@ SCRAM-SHA-256$<iteration count>:&l
Finish LSN of the transaction whose changes are to be skipped, if a valid
- LSN; otherwise 0/0.
+ LSN; otherwise 0/0000000.
@@ -8033,11 +8077,48 @@ SCRAM-SHA-256$<iteration count>:&l
If true, the associated replication slots (i.e. the main slot and the
- table sync slots) in the upstream database are enabled to be
+ table synchronization slots) in the upstream database are enabled to be
synchronized to the standbys
+
+
+ subretaindeadtuplesbool
+
+
+ If true, the detection of is
+ enabled and the information (e.g., dead tuples, commit timestamps, and
+ origins) on the subscriber that is useful for conflict detection is
+ retained.
+
+
+
+
+
+ submaxretentionint4
+
+
+ The maximum duration (in milliseconds) for which information (e.g., dead
+ tuples, commit timestamps, and origins) useful for conflict detection can
+ be retained.
+
+
+
+
+
+ subretentionactivebool
+
+
+ The retention status of information (e.g., dead tuples, commit
+ timestamps, and origins) useful for conflict detection. True if
+ retain_dead_tuples
+ is enabled, and the retention duration has not exceeded
+ max_retention_duration,
+ when defined.
+
+
+
subconninfotext
diff --git a/doc/src/sgml/charset.sgml b/doc/src/sgml/charset.sgml
index daf671e620545..59b27c3c370e2 100644
--- a/doc/src/sgml/charset.sgml
+++ b/doc/src/sgml/charset.sgml
@@ -100,7 +100,7 @@ initdb --locale=sv_SE
LC_COLLATE
- String sort order
+ String sort order (ignored unless the provider is libc)LC_CTYPE
@@ -377,8 +377,9 @@ initdb --locale-provider=icu --icu-locale=en
The builtin provider uses built-in operations. Only
- the C and C.UTF-8 locales are
- supported for this provider.
+ the C, C.UTF-8, and
+ PG_UNICODE_FAST locales are supported for this
+ provider.
The C locale behavior is identical to the
@@ -392,6 +393,13 @@ initdb --locale-provider=icu --icu-locale=en
regular expression character classes are based on the "POSIX
Compatible" semantics, and the case mapping is the "simple" variant.
+
+ The PG_UNICODE_FAST locale is available only when
+ the database encoding is UTF-8, and the behavior is
+ based on Unicode. The collation uses the code point values only. The
+ regular expression character classes are based on the "Standard"
+ semantics, and the case mapping is the "full" variant.
+
@@ -862,7 +870,7 @@ SELECT * FROM test1 ORDER BY a || b COLLATE "fr_FR";
This SQL standard collation sorts using the Unicode Collation
Algorithm with the Default Unicode Collation Element Table. It is
available in all encodings. ICU support is required to use this
- collation, and behavior may change if Postgres is built with a
+ collation, and behavior may change if PostgreSQL is built with a
different version of ICU. (This collation has the same behavior as
the ICU root locale; see .)
@@ -886,6 +894,23 @@ SELECT * FROM test1 ORDER BY a || b COLLATE "fr_FR";
+
+ pg_unicode_fast
+
+
+ This collation sorts by Unicode code point values rather than natural
+ language order. For the functions lower,
+ initcap, and upper it uses
+ Unicode full case mapping. For pattern matching (including regular
+ expressions), it uses the Standard variant of Unicode Compatibility
+ Properties. Behavior is efficient and stable within a
+ Postgres major version. It is only
+ available for encoding UTF8.
+
+
+
+
pg_c_utf8
@@ -897,7 +922,7 @@ SELECT * FROM test1 ORDER BY a || b COLLATE "fr_FR";
expressions), it uses the POSIX Compatible variant of Unicode Compatibility
Properties. Behavior is efficient and stable within a
- Postgres major version. This collation is
+ PostgreSQL major version. This collation is
only available for encoding UTF8.
@@ -1197,7 +1222,7 @@ CREATE COLLATION ignore_accents (provider = icu, locale = 'und-u-ks-level1-kc-tr
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
+ such as some pattern matching operations. Therefore, they should be used
only in cases where they are specifically wanted.
@@ -1320,7 +1345,9 @@ SELECT 'w;x*y-z' = 'wxyz' COLLATE num_ignore_punct; -- true
level4
- Punctuation
+ Punctuationonly with
+ ka-shifted; see truetruefalse
@@ -1844,7 +1871,7 @@ ORDER BY c COLLATE ebcdic;
Traditional Chinese, TaiwaneseYesYes
- 1–3
+ 1–4
diff --git a/doc/src/sgml/client-auth.sgml b/doc/src/sgml/client-auth.sgml
index cf5eb22fc8905..51b95ed04f399 100644
--- a/doc/src/sgml/client-auth.sgml
+++ b/doc/src/sgml/client-auth.sgml
@@ -531,6 +531,15 @@ include_dir directory
user's password. See
for details.
+
+
+ Support for MD5-encrypted passwords is deprecated and will be
+ removed in a future release of
+ PostgreSQL. Refer to
+ for details about migrating to
+ another password type.
+
+
@@ -647,6 +656,16 @@ include_dir directory
+
+
+ oauth
+
+
+ Authorize and optionally authenticate using a third-party OAuth 2.0
+ identity provider. See for details.
+
+
+
@@ -810,12 +829,11 @@ host all all ::1/128 trust
host all all localhost trust
# The same using a regular expression for DATABASE, that allows connection
-# to the database db1, db2 and any databases with a name beginning with "db"
-# and finishing with a number using two to four digits (like "db1234" or
-# "db12").
+# to any databases with a name beginning with "db" and finishing with a
+# number using two to four digits (like "db1234" or "db12").
#
-# TYPE DATABASE USER ADDRESS METHOD
-local db1,"/^db\d{2,4}$",db2 all localhost trust
+# TYPE DATABASE USER ADDRESS METHOD
+host "/^db\d{2,4}$" 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
@@ -985,8 +1003,9 @@ local db1,db2,@demodbs all md5
the remainder of the field is treated as a regular expression.
(See for details of
PostgreSQL's regular expression syntax.) The regular
- expression can include a single capture, or parenthesized subexpression,
- which can then be referenced in the database-username
+ expression can include a single capture, or parenthesized subexpression.
+ The portion of the system user name that matched the capture can then
+ be referenced in the database-username
field as \1 (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
@@ -1004,12 +1023,11 @@ mymap /^(.*)@otherdomain\.com$ guest
If the database-username field starts with
a slash (/), the remainder of the field is treated
- as a regular expression (see
- for details of PostgreSQL's regular
- expression syntax). It is not possible to use \1
- to use a capture from regular expression on
- system-username for a regular expression
- on database-username.
+ as a regular expression.
+ When the database-username field is a regular
+ expression, it is not possible to use \1 within it to
+ refer to a capture from the system-username
+ field.
@@ -1135,6 +1153,12 @@ omicron bryanh guest1
only on OpenBSD).
+
+
+ OAuth authorization/authentication,
+ which relies on an external OAuth 2.0 identity provider.
+
+
@@ -1261,6 +1285,14 @@ omicron bryanh guest1
server is encrypted for SCRAM (see below), then SCRAM-based
authentication will automatically be chosen instead.
+
+
+
+ Support for MD5-encrypted passwords is deprecated and will be removed
+ in a future release of PostgreSQL. Refer to
+ the text below for details about migrating to another password type.
+
+
@@ -1911,13 +1943,19 @@ omicron bryanh guest1
+
+
+
+
+ The following option may be used as an alternative way to write some of the
+ above LDAP options in a more compact and standard form:
+ ldapurl
An RFC 4516
- 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
+ LDAP URL. The format is
ldap[s]://host[:port]/basedn[?[attribute][?[scope][?[filter]]]]
@@ -1959,7 +1997,8 @@ ldap[s]://host[:port]/
It is an error to mix configuration options for simple bind with options
- for search+bind.
+ for search+bind. To use ldapurl in simple bind mode, the
+ URL must not contain a basedn or query elements.
@@ -1995,6 +2034,16 @@ host ... ldap ldapserver=ldap.example.net ldapprefix="cn=" ldapsuffix=", dc=exam
succeeds, the database access is granted.
+
+ Here is a different simple-bind configuration, which uses the LDAPS scheme
+ and a custom port number, written as a URL:
+
+host ... ldap ldapurl="ldaps://ldap.example.net:49151" ldapprefix="cn=" ldapsuffix=", dc=example, dc=net"
+
+ This is slightly more compact than specifying ldapserver,
+ ldapscheme, and ldapport separately.
+
+
Here is an example for a search+bind configuration:
@@ -2296,6 +2345,242 @@ host ... radius radiusservers="server1,server2" radiussecrets="""secret one"",""
+
+ OAuth Authorization/Authentication
+
+
+ OAuth Authorization/Authentication
+
+
+
+ OAuth 2.0 is an industry-standard framework, defined in
+ RFC 6749,
+ to enable third-party applications to obtain limited access to a protected
+ resource.
+
+ OAuth client support has to be enabled when PostgreSQL
+ is built, see for more information.
+
+
+
+ This documentation uses the following terminology when discussing the OAuth
+ ecosystem:
+
+
+
+
+ Resource Owner (or End User)
+
+
+ The user or system who owns protected resources and can grant access to
+ them. This documentation also uses the term end user
+ when the resource owner is a person. When you use
+ psql to connect to the database using OAuth,
+ you are the resource owner/end user.
+
+
+
+
+
+ Client
+
+
+ The system which accesses the protected resources using access
+ tokens. Applications using libpq, such as psql,
+ are the OAuth clients when connecting to a
+ PostgreSQL cluster.
+
+
+
+
+
+ Resource Server
+
+
+ The system hosting the protected resources which are
+ accessed by the client. The PostgreSQL
+ cluster being connected to is the resource server.
+
+
+
+
+
+ Provider
+
+
+ The organization, product vendor, or other entity which develops and/or
+ administers the OAuth authorization servers and clients for a given application.
+ Different providers typically choose different implementation details
+ for their OAuth systems; a client of one provider is not generally
+ guaranteed to have access to the servers of another.
+
+
+ This use of the term "provider" is not standard, but it seems to be in
+ wide use colloquially. (It should not be confused with OpenID's similar
+ term "Identity Provider". While the implementation of OAuth in
+ PostgreSQL is intended to be interoperable
+ and compatible with OpenID Connect/OIDC, it is not itself an OIDC client
+ and does not require its use.)
+
+
+
+
+
+ Authorization Server
+
+
+ The system which receives requests from, and issues access tokens to,
+ the client after the authenticated resource owner has given approval.
+ PostgreSQL does not provide an authorization
+ server; it is the responsibility of the OAuth provider.
+
+
+
+
+
+ Issuer
+
+
+ An identifier for an authorization server, printed as an
+ https:// URL, which provides a trusted "namespace"
+ for OAuth clients and applications. The issuer identifier allows a
+ single authorization server to talk to the clients of mutually
+ untrusting entities, as long as they maintain separate issuers.
+
+
+
+
+
+
+
+
+ For small deployments, there may not be a meaningful distinction between
+ the "provider", "authorization server", and "issuer". However, for more
+ complicated setups, there may be a one-to-many (or many-to-many)
+ relationship: a provider may rent out multiple issuer identifiers to
+ separate tenants, then provide multiple authorization servers, possibly
+ with different supported feature sets, to interact with their clients.
+
+
+
+
+
+ PostgreSQL supports bearer tokens, defined in
+ RFC 6750,
+ which are a type of access token used with OAuth 2.0 where the token is an
+ opaque string. The format of the access token is implementation specific
+ and is chosen by each authorization server.
+
+
+
+ The following configuration options are supported for OAuth:
+
+
+ issuer
+
+
+ An HTTPS URL which is either the exact
+ issuer identifier of the
+ authorization server, as defined by its discovery document, or a
+ well-known URI that points directly to that discovery document. This
+ parameter is required.
+
+
+ When an OAuth client connects to the server, a URL for the discovery
+ document will be constructed using the issuer identifier. By default,
+ this URL uses the conventions of OpenID Connect Discovery: the path
+ /.well-known/openid-configuration will be appended
+ to the end of the issuer identifier. Alternatively, if the
+ issuer contains a /.well-known/
+ path segment, that URL will be provided to the client as-is.
+
+
+
+ The OAuth client in libpq requires the server's issuer setting to
+ exactly match the issuer identifier which is provided in the discovery
+ document, which must in turn match the client's
+ setting. No variations in
+ case or formatting are permitted.
+
+
+
+
+
+
+ scope
+
+
+ A space-separated list of the OAuth scopes needed for the server to
+ both authorize the client and authenticate the user. Appropriate values
+ are determined by the authorization server and the OAuth validation
+ module used (see for more
+ information on validators). This parameter is required.
+
+
+
+
+
+ validator
+
+
+ The library to use for validating bearer tokens. If given, the name must
+ exactly match one of the libraries listed in
+ . This parameter is
+ optional unless oauth_validator_libraries contains
+ more than one library, in which case it is required.
+
+
+
+
+
+ map
+
+
+ Allows for mapping between OAuth identity provider and database user
+ names. See for details. If a
+ map is not specified, the user name associated with the token (as
+ determined by the OAuth validator) must exactly match the role name
+ being requested. This parameter is optional.
+
+
+
+
+
+
+ delegate_ident_mapping
+
+
+
+ An advanced option which is not intended for common use.
+
+
+ When set to 1, standard user mapping with
+ pg_ident.conf is skipped, and the OAuth validator
+ takes full responsibility for mapping end user identities to database
+ roles. If the validator authorizes the token, the server trusts that
+ the user is allowed to connect under the requested role, and the
+ connection is allowed to proceed regardless of the authentication
+ status of the user.
+
+
+ This parameter is incompatible with map.
+
+
+
+ delegate_ident_mapping provides additional
+ flexibility in the design of the authentication system, but it also
+ requires careful implementation of the OAuth validator, which must
+ determine whether the provided token carries sufficient end-user
+ privileges in addition to the standard
+ checks required of all validators. Use with caution.
+
+
+
+
+
+
+
+
Authentication Problems
diff --git a/doc/src/sgml/config.sgml b/doc/src/sgml/config.sgml
index 698169afdb6aa..2a3685f474a96 100644
--- a/doc/src/sgml/config.sgml
+++ b/doc/src/sgml/config.sgml
@@ -140,7 +140,7 @@
An example of what this file might look like is:
# This is a comment
-log_connections = yes
+log_connections = all
log_destination = 'syslog'
search_path = '"$user", public'
shared_buffers = 128MB
@@ -337,7 +337,7 @@ UPDATE pg_settings SET setting = reset_val WHERE name = 'configuration_parameter
command-line parameter, or its equivalent
variation. For example,
-postgres -c log_connections=yes --log-destination='syslog'
+postgres -c log_connections=all --log-destination='syslog'
Settings provided in this way override those set via
postgresql.conf or ALTER SYSTEM,
@@ -708,7 +708,7 @@ include_dir 'conf.d'
- PostgreSQL sizes certain resources based directly on the value of
+ PostgreSQL sizes certain resources based directly on the value of
max_connections. Increasing its value leads to
higher allocation of those resources, including shared memory.
@@ -731,7 +731,7 @@ include_dir 'conf.d'
Determines the number of connection slots that are
reserved for connections by roles with privileges of the
- pg_use_reserved_connections
+
role. Whenever the number of free connection slots is greater than
but less than or
equal to the sum of superuser_reserved_connections
@@ -1124,6 +1124,14 @@ include_dir 'conf.d'
mechanism, and hence not work with passwords encrypted with
SCRAM-SHA-256. See for more details.
+
+
+ Support for MD5-encrypted passwords is deprecated and will be removed
+ in a future release of PostgreSQL. Refer
+ to for details about migrating to
+ another password type.
+
+
@@ -1147,6 +1155,22 @@ include_dir 'conf.d'
+
+ md5_password_warnings (boolean)
+
+ md5_password_warnings configuration parameter
+
+
+
+
+ Controls whether a WARNING about MD5 password
+ deprecation is produced when a CREATE ROLE or
+ ALTER ROLE statement sets an MD5-encrypted password.
+ The default value is on.
+
+
+
+
krb_server_keyfile (string)
@@ -1201,6 +1225,32 @@ include_dir 'conf.d'
+
+
+ oauth_validator_libraries (string)
+
+ oauth_validator_libraries configuration parameter
+
+
+
+
+ The library/libraries to use for validating OAuth connection tokens. If
+ only one validator library is provided, it will be used by default for
+ any OAuth connections; otherwise, all
+ oauth HBA entries
+ must explicitly set a validator chosen from this
+ list. If set to an empty string (the default), OAuth connections will be
+ refused. This parameter can only be set in the
+ postgresql.conf file.
+
+
+ Validator modules must be implemented/obtained separately;
+ PostgreSQL does not ship with any default
+ implementations. For more information on implementing OAuth validators,
+ see .
+
+
+
@@ -1340,6 +1390,28 @@ include_dir 'conf.d'
+
+ ssl_tls13_ciphers (string)
+
+ ssl_tls13_ciphers configuration parameter
+
+
+
+
+ Specifies a list of cipher suites that are allowed by connections using
+ TLS version 1.3. Multiple cipher suites can be
+ specified by using a colon separated list. If left blank, the default
+ set of cipher suites in OpenSSL will be used.
+
+
+
+ This parameter can only be set in the
+ postgresql.conf file or on the server command
+ line.
+
+
+
+
ssl_ciphers (string)
@@ -1348,15 +1420,13 @@ include_dir 'conf.d'
- Specifies a list of SSL cipher suites that are
- allowed to be used by SSL connections. See the
- ciphers
+ Specifies a list of SSL ciphers that are allowed by
+ connections using TLS version 1.2 and lower, see
+ for TLS version 1.3 connections. See
+ the ciphers
manual page in the OpenSSL 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
- HIGH:MEDIUM:+3DES:!aNULL. The default is usually a
+ syntax of this setting and a list of supported values. The default value
+ is HIGH:MEDIUM:+3DES:!aNULL. The default is usually a
reasonable choice unless you have specific security requirements.
@@ -1443,30 +1513,30 @@ include_dir 'conf.d'
- 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.
+ PostgreSQL versions before 9.4 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.
-
- ssl_ecdh_curve (string)
+
+ ssl_groups (string)
- ssl_ecdh_curve configuration parameter
+ ssl_groups configuration parameter
Specifies the name of the curve to use in ECDH key
exchange. It needs to be supported by all clients that connect.
+ Multiple curves can be specified by using a colon-separated list.
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 postgresql.conf
- file or on the server command line.
- The default is prime256v1.
+ Curve key. This parameter can only be set in the
+ postgresql.conf file or on the server command line.
+ The default is X25519:prime256v1.
@@ -1475,9 +1545,16 @@ include_dir 'conf.d'
prime256v1 (NIST P-256),
secp384r1 (NIST P-384),
secp521r1 (NIST P-521).
- The full list of available curves can be shown with the command
- openssl ecparam -list_curves. Not all of them
- are usable in TLS though.
+ An incomplete list of available groups can be shown with the command
+ openssl ecparam -list_curves. Not all of them are
+ usable with TLS though, and many supported group
+ names and aliases are omitted.
+
+
+
+ In PostgreSQL versions before 18.0 this
+ setting was named ssl_ecdh_curve and only accepted
+ a single value.
@@ -2286,6 +2363,44 @@ include_dir 'conf.d'
+
+ file_copy_method (enum)
+
+ file_copy_method configuration parameter
+
+
+
+
+ Specifies the method used to copy files.
+ Possible values are COPY (default) and
+ CLONE (if operating support is available).
+
+
+
+ This parameter affects:
+
+
+
+
+ CREATE DATABASE ... STRATEGY=FILE_COPY
+
+
+
+
+ ALTER DATABASE ... SET TABLESPACE ...
+
+
+
+
+
+ CLONE uses the copy_file_range()
+ (Linux, FreeBSD) or copyfile
+ (macOS) system calls, giving the kernel the opportunity to share disk
+ blocks or push work down to lower layers on some file systems.
+
+
+
+
max_notify_queue_pages (integer)
@@ -2317,8 +2432,13 @@ include_dir 'conf.d'
- Sets the maximum number of simultaneously open files allowed to each
- server subprocess. The default is one thousand files. If the kernel is enforcing
+ Sets the maximum number of open files each server subprocess is
+ allowed to open simultaneously; files already opened in the
+ postmaster are not counted toward this limit. 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
@@ -2332,149 +2452,6 @@ include_dir 'conf.d'
-
- Cost-based Vacuum Delay
-
-
- During the execution of
- and
- commands, the system maintains an
- internal counter that keeps track of the estimated cost of the
- various I/O operations that are performed. When the accumulated
- cost reaches a limit (specified by
- vacuum_cost_limit), the process performing
- the operation will sleep for a short period of time, as specified by
- vacuum_cost_delay. Then it will reset the
- counter and continue execution.
-
-
-
- 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
- VACUUM and ANALYZE 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.
-
-
-
- This feature is disabled by default for manually issued
- VACUUM commands. To enable it, set the
- vacuum_cost_delay variable to a nonzero
- value.
-
-
-
-
- vacuum_cost_delay (floating point)
-
- vacuum_cost_delay configuration parameter
-
-
-
-
- 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.
-
-
-
- When using cost-based vacuuming, appropriate values for
- vacuum_cost_delay are usually quite small, perhaps
- less than 1 millisecond. While vacuum_cost_delay
- can be set to fractional-millisecond values, such delays may not be
- measured accurately on older platforms. On such platforms,
- increasing VACUUM's throttled resource consumption
- above what you get at 1ms will require changing the other vacuum cost
- parameters. You should, nonetheless,
- keep vacuum_cost_delay as small as your platform
- will consistently measure; large delays are not helpful.
-
-
-
-
-
- vacuum_cost_page_hit (integer)
-
- vacuum_cost_page_hit configuration parameter
-
-
-
-
- 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.
-
-
-
-
-
- vacuum_cost_page_miss (integer)
-
- vacuum_cost_page_miss configuration parameter
-
-
-
-
- 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.
-
-
-
-
-
- vacuum_cost_page_dirty (integer)
-
- vacuum_cost_page_dirty configuration parameter
-
-
-
-
- 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.
-
-
-
-
-
- vacuum_cost_limit (integer)
-
- vacuum_cost_limit configuration parameter
-
-
-
-
- This is the accumulated cost that will cause the vacuuming process to sleep
- for vacuum_cost_delay. The default is 200.
-
-
-
-
-
-
-
- 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 vacuum_cost_delay *
- accumulated_balance /
- vacuum_cost_limit with a maximum of
- vacuum_cost_delay * 4.
-
-
- Background Writer
@@ -2614,8 +2591,8 @@ include_dir 'conf.d'
-
- Asynchronous Behavior
+
+ I/O
@@ -2656,41 +2633,33 @@ include_dir 'conf.d'
- Sets the number of concurrent disk I/O operations that
+ Sets the number of concurrent storage I/O operations that
PostgreSQL expects can be executed
simultaneously. Raising this value will increase the number of I/O
- operations that any individual PostgreSQL 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.
+ operations that any individual PostgreSQL
+ session attempts to initiate in parallel. The allowed range is
+ 1 to 1000, or
+ 0 to disable issuance of asynchronous I/O requests.
+ The default is 16.
- 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.
+ Higher values will have the most impact on higher latency storage
+ where queries otherwise experience noticeable I/O stalls and on
+ devices with high IOPs. Unnecessarily high values may increase I/O
+ latency for all queries on the system
- Asynchronous I/O depends on an effective posix_fadvise
- 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.
+ On systems with prefetch advice support,
+ effective_io_concurrency also controls the
+ prefetch distance.
- 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
- ).
+ This value can be overridden for tables in a particular tablespace by
+ setting the tablespace parameter of the same name (see ).
@@ -2707,10 +2676,30 @@ include_dir 'conf.d'
for maintenance work that is done on behalf of many client sessions.
- 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
- ).
+ The default is 16. This value can be overridden
+ for tables in a particular tablespace by setting the tablespace
+ parameter of the same name (see ).
+
+
+
+
+
+ io_max_combine_limit (integer)
+
+ io_max_combine_limit configuration parameter
+
+
+
+
+ Controls the largest I/O size in operations that combine I/O, and silently
+ limits the user-settable parameter io_combine_limit.
+ This parameter can only be set in
+ the postgresql.conf file or on the server
+ command line.
+ The maximum possible size depends on the operating system and block
+ size, but is typically 1MB on Unix and 128kB on Windows.
+ The default is 128kB.
@@ -2723,63 +2712,158 @@ include_dir 'conf.d'
- Controls the largest I/O size in operations that combine I/O.
+ Controls the largest I/O size in operations that combine I/O. If set
+ higher than the io_max_combine_limit parameter, the
+ lower value will silently be used instead, so both may need to be raised
+ to increase the I/O size.
+ The maximum possible size depends on the operating system and block
+ size, but is typically 1MB on Unix and 128kB on Windows.
The default is 128kB.
-
- max_worker_processes (integer)
+
+ io_max_concurrency (integer)
- max_worker_processes configuration parameter
+ io_max_concurrency configuration parameter
- Sets the maximum number of background processes that the cluster
- can support. This parameter can only be set at server start. The
- default is 8.
+ Controls the maximum number of I/O operations that one process can
+ execute simultaneously.
-
- 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.
+ The default setting of -1 selects a number based
+ on and the maximum number of
+ processes (, , and ), but not more than
+ 64.
-
- When changing this value, consider also adjusting
- ,
- , and
- .
+ This parameter can only be set at server start.
-
- max_parallel_workers_per_gather (integer)
+
+ io_method (enum)
- max_parallel_workers_per_gather configuration parameter
+ io_method configuration parameter
- Sets the maximum number of workers that can be started by a single
- Gather or Gather Merge node.
- Parallel workers are taken from the pool of processes established by
- , limited by
- . Note that the requested
- 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.
+ Selects the method for executing asynchronous I/O.
+ Possible values are:
+
+
+
+ worker (execute asynchronous I/O using worker processes)
+
+
+
+
+ io_uring (execute asynchronous I/O using
+ io_uring, requires a build with
+ /
+ )
+
+
+
+
+ sync (execute asynchronous-eligible I/O synchronously)
+
+
+
+ The default is worker.
-
- 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
+ This parameter can only be set at server start.
+
+
+
+
+
+ io_workers (integer)
+
+ io_workers configuration parameter
+
+
+
+
+ Selects the number of I/O worker processes to use. The default is
+ 3. This parameter can only be set in the
+ postgresql.conf file or on the server command
+ line.
+
+
+ Only has an effect if is set to
+ worker.
+
+
+
+
+
+
+
+ Worker Processes
+
+
+
+ max_worker_processes (integer)
+
+ max_worker_processes configuration parameter
+
+
+
+
+ Sets the maximum number of background processes that the cluster
+ can support. This parameter can only be set at server start. The
+ default is 8.
+
+
+
+ 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.
+
+
+
+ When changing this value, consider also adjusting
+ ,
+ , and
+ .
+
+
+
+
+
+ max_parallel_workers_per_gather (integer)
+
+ max_parallel_workers_per_gather configuration parameter
+
+
+
+
+ Sets the maximum number of workers that can be started by a single
+ Gather or Gather Merge node.
+ Parallel workers are taken from the pool of processes established by
+ , limited by
+ . Note that the requested
+ 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.
+
+
+
+ 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
@@ -2810,7 +2894,8 @@ include_dir 'conf.d'
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
- CREATE INDEX only when building a B-tree index,
+ CREATE INDEX when building a B-tree,
+ GIN, or BRIN index,
and VACUUM without FULL
option. Parallel workers are taken from the pool of processes
established by , limited
@@ -3314,8 +3399,9 @@ include_dir 'conf.d'
This parameter enables compression of WAL using the specified
compression method.
When enabled, the PostgreSQL
- server compresses full page images written to WAL when
- is on or during a base backup.
+ server compresses full page images written to WAL (e.g. when
+ is on, during a base backup,
+ etc.).
A compressed page image will be decompressed during WAL replay.
The supported methods are pglz,
lz4 (if PostgreSQL
@@ -3852,10 +3938,8 @@ include_dir 'conf.d'
off, on and
try (the default). The setting
try enables
- prefetching only if the operating system provides the
- posix_fadvise function, which is currently used
- to implement prefetching. Note that some operating systems provide the
- function, but it doesn't do anything.
+ prefetching only if the operating system provides support for issuing
+ read-ahead advice.
Prefetching blocks that will soon be needed can reduce I/O wait times
@@ -4318,11 +4402,17 @@ restore_command = 'copy "C:\\server\\archivedir\\%f" "%p"' # Windows
Enables the WAL summarizer process. Note that WAL summarization can
- be enabled either on a primary or on a standby. WAL summarization
- cannot be enabled when wal_level is set to
- minimal. This parameter can only be set in the
- postgresql.conf file or on the server command line.
- The default is off.
+ be enabled either on a primary or on a standby. This parameter can only
+ be set in the postgresql.conf file or on the server
+ command line. The default is off.
+
+
+ The server cannot be started with summarize_wal=on
+ if wal_level is set to minimal. If
+ summarize_wal=on is configured after server startup
+ while wal_level=minimal, the summarizer will run
+ but refuse to generate summary files for any WAL generated with
+ wal_level=minimal.
@@ -4441,7 +4531,6 @@ restore_command = 'copy "C:\\server\\archivedir\\%f" "%p"' # Windows
max_replication_slots (integer)
max_replication_slots configuration parameter
- in a sending server
@@ -4456,11 +4545,6 @@ restore_command = 'copy "C:\\server\\archivedir\\%f" "%p"' # Windows
to replica or higher to allow replication slots to
be used.
-
-
- Note that this parameter also applies on the subscriber side, but with
- a different meaning.
-
@@ -4527,6 +4611,48 @@ restore_command = 'copy "C:\\server\\archivedir\\%f" "%p"' # Windows
+
+ idle_replication_slot_timeout (integer)
+
+ idle_replication_slot_timeout configuration parameter
+
+
+
+
+ Invalidate replication slots that have remained inactive (not used by
+ a replication connection)
+ for longer than this duration.
+ If this value is specified without units, it is taken as seconds.
+ A value of zero (the default) disables the idle timeout
+ invalidation mechanism. This parameter can only be set in the
+ postgresql.conf file or on the server command
+ line.
+
+
+
+ Slot invalidation due to idle timeout occurs during checkpoint.
+ Because checkpoints happen at checkpoint_timeout
+ intervals, there can be some lag between when the
+ idle_replication_slot_timeout was exceeded and when
+ the slot invalidation is triggered at the next checkpoint.
+ To avoid such lags, users can force a checkpoint to promptly invalidate
+ inactive slots. The duration of slot inactivity is calculated using the
+ slot's pg_replication_slots.inactive_since
+ value.
+
+
+
+ Note that the idle timeout invalidation mechanism is not applicable
+ for slots that do not reserve WAL or for slots on the standby server
+ that are being synced from the primary server (i.e., standby slots
+ having pg_replication_slots.synced
+ value true). Synced slots are always considered to
+ be inactive because they don't perform logical decoding to produce
+ changes.
+
+
+
+
wal_sender_timeout (integer)
@@ -4569,10 +4695,10 @@ restore_command = 'copy "C:\\server\\archivedir\\%f" "%p"' # Windows
-
- standby_slot_names (string)
+
+ synchronized_standby_slots (string)
- standby_slot_names configuration parameter
+ synchronized_standby_slots configuration parameter
@@ -4587,7 +4713,7 @@ restore_command = 'copy "C:\\server\\archivedir\\%f" "%p"' # Windows
after the standby is promoted, the physical replication slot for the
standby should be listed here. Note that logical replication will not
proceed if the slots specified in the
- standby_slot_names do not exist or are invalidated.
+ synchronized_standby_slots do not exist or are invalidated.
Additionally, the replication management functions
pg_replication_slot_advance,
@@ -4596,12 +4722,12 @@ restore_command = 'copy "C:\\server\\archivedir\\%f" "%p"' # Windows
pg_logical_slot_peek_changes,
when used with logical failover slots, will block until all
- physical slots specified in standby_slot_names have
+ physical slots specified in synchronized_standby_slots have
confirmed WAL receipt.
The standbys corresponding to the physical replication slots in
- standby_slot_names must configure
+ synchronized_standby_slots must configure
sync_replication_slots = true so they can receive
logical failover slot changes from the primary.
@@ -4676,6 +4802,8 @@ ANY num_sync ( standby_name
is the name of a standby server.
+ num_sync
+ must be an integer value greater than zero.
FIRST and ANY specify the method to choose
synchronous standbys from the listed servers.
@@ -4838,6 +4966,8 @@ ANY num_sync ( num_sync ( num_sync ( num_sync (
- max_replication_slots (integer)
+
+ max_active_replication_origins (integer)
- max_replication_slots configuration parameter
- in a subscriber
+ max_active_replication_origins configuration parameter
@@ -5178,16 +5315,13 @@ ANY num_sync ( pg_replication_origin_status)
- will prevent the server from starting.
- max_replication_slots must be set to at least the
+ will prevent the server from starting. It defaults to 10. This parameter
+ can only be set at server start.
+
+ max_active_replication_origins must be set to at least the
number of subscriptions that will be added to the subscriber, plus some
reserve for table synchronization.
-
-
- Note that this parameter also applies on a sending server, but with
- a different meaning.
-
@@ -5327,6 +5461,20 @@ ANY num_sync (
+ enable_distinct_reordering (boolean)
+
+ enable_distinct_reordering configuration parameter
+
+
+
+
+ Enables or disables the query planner's ability to reorder DISTINCT
+ keys to match the input path's pathkeys. The default is on.
+
+
+
+
enable_gathermerge (boolean)
@@ -5341,6 +5489,25 @@ ANY num_sync (
+ enable_group_by_reordering (boolean)
+
+ enable_group_by_reordering configuration parameter
+
+
+
+
+ Controls if the query planner will produce a plan which will provide
+ GROUP BY keys sorted in the order of keys of
+ a child node of the plan, such as an index scan. When disabled, the
+ query planner will produce a plan with GROUP BY
+ keys only sorted to match the ORDER BY clause,
+ if any. When enabled, the planner will try to produce a more
+ efficient plan. The default value is on.
+
+
+
+
enable_hashagg (boolean)
@@ -5394,8 +5561,9 @@ ANY num_sync ( .
@@ -5410,7 +5578,9 @@ ANY num_sync ( ).
- The default is on.
+ The default is on. The
+ setting must also be
+ enabled to have the query planner consider index-only-scans.
@@ -5542,9 +5712,13 @@ ANY num_sync ( num_sync ( num_sync (
+ enable_self_join_elimination (boolean)
+
+ enable_self_join_elimination configuration parameter
+
+
+
+
+ Enables or disables the query planner's optimization which analyses
+ the query tree and replaces self joins with semantically equivalent
+ single scans. Takes into consideration only plain tables.
+ The default is on.
+
+
+
+
enable_seqscan (boolean)
@@ -6393,7 +6587,7 @@ SELECT * FROM parent WHERE key = 2400;
If csvlog is included in log_destination,
- log entries are output in comma separated
+ log entries are output in comma-separated
value (CSV) format, which is convenient for
loading logs into programs.
See for details.
@@ -7189,6 +7383,11 @@ local0.* /var/log/postgresql
+ debug_print_raw_parse (boolean)
+
+ debug_print_raw_parse configuration parameter
+
+ debug_print_parse (boolean)
debug_print_parse configuration parameter
@@ -7207,8 +7406,8 @@ local0.* /var/log/postgresql
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.
+ When set, they print the resulting raw parse tree, the parse tree, the query
+ rewriter output, or the execution plan for each executed query.
These messages are emitted at LOG message level, so by
default they will appear in the server log but will not be sent to the
client. You can change that by adjusting
@@ -7228,7 +7427,8 @@ local0.* /var/log/postgresql
When set, debug_pretty_print indents the messages
- produced by debug_print_parse,
+ produced by debug_print_raw_parse,
+ debug_print_parse,
debug_print_rewritten, or
debug_print_plan. This results in more readable
but much longer output than the compact format used when
@@ -7282,20 +7482,105 @@ local0.* /var/log/postgresql
- log_connections (boolean)
+ log_connections (string)
log_connections configuration parameter
- Causes each attempted connection to the server to be logged,
- as well as successful completion of both client authentication (if
- necessary) and authorization.
+ Causes aspects of each connection to the server to be logged.
+ The default is the empty string, '', which
+ disables all connection logging. The following options may be
+ specified alone or in a comma-separated list:
+
+
+
+ Log Connection Options
+
+
+
+
+
+ Name
+ Description
+
+
+
+
+ receipt
+ Logs receipt of a connection.
+
+
+
+ authentication
+
+ Logs the original identity used by an authentication method
+ to identify a user. In most cases, the identity string
+ matches the PostgreSQL username,
+ but some third-party authentication methods may alter the
+ original user identifier before the server stores it. Failed
+ authentication is always logged regardless of the value of
+ this setting.
+
+
+
+
+ authorization
+
+ Logs successful completion of authorization. At this point
+ the connection has been established but the backend is not
+ yet fully set up. The log message includes the authorized
+ username as well as the database name and application name,
+ if applicable.
+
+
+
+
+ setup_durations
+
+ Logs the time spent establishing the connection and setting up the
+ backend until the connection is ready to execute its first
+ query. The log message includes three durations: the total
+ setup duration (starting from the postmaster accepting the
+ incoming connection and ending when the connection is ready
+ for query), the time it took to fork the new backend, and
+ the time it took to authenticate the user.
+
+
+
+
+ all
+
+ A convenience alias equivalent to specifying all options. If
+ all is specified in a list of other
+ options, all connection aspects will be logged.
+
+
+
+
+
+
+
+
+ Disconnection logging is separately controlled by .
+
+
+
+ For the purposes of backwards compatibility, on,
+ off, true,
+ false, yes,
+ no, 1, and 0
+ are still supported. The positive values are equivalent to specifying
+ the receipt, authentication, and
+ authorization options.
+
+
+
Only superusers and users with the appropriate SET
privilege can change this parameter at session start,
and it cannot be changed at all within a session.
- The default is off.
@@ -7470,6 +7755,12 @@ local0.* /var/log/postgresql
Remote host name or IP addressyes
+
+ %L
+ Local address (the IP address on the server that the
+ client connected to)
+ yes
+ %bBackend type
@@ -7645,6 +7936,26 @@ log_line_prefix = '%m [%p] %q%u@%d/%a '
+
+ log_lock_failures (boolean)
+
+ log_lock_failures configuration parameter
+
+
+
+
+ Controls whether a detailed log message is produced
+ when a lock acquisition fails. This is useful for analyzing
+ the causes of lock failures. Currently, only lock failures
+ due to SELECT NOWAIT is supported.
+ The default is off. Only superusers and
+ users with the appropriate SET privilege
+ can change this setting.
+
+
+
+
+
log_recovery_conflict_waits (boolean)
@@ -8173,7 +8484,7 @@ COPY postgres_log FROM '/full/path/to/logfile.csv' WITH csv;
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 .)
+ linkend="guc-synchronous-standby-names"/>).
@@ -8285,6 +8596,34 @@ COPY postgres_log FROM '/full/path/to/logfile.csv' WITH csv;
+
+ track_cost_delay_timing (boolean)
+
+ track_cost_delay_timing configuration parameter
+
+
+
+
+ Enables timing of cost-based vacuum delay (see
+ ). 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 tool to
+ measure the overhead of timing on your system. Cost-based vacuum delay
+ timing information is displayed in
+ pg_stat_progress_vacuum,
+ pg_stat_progress_analyze,
+ in the output of and
+ when the
+ VERBOSE option is used, and by autovacuum for
+ auto-vacuums and auto-analyzes when
+ is set.
+ Only superusers and users with the appropriate SET
+ privilege can change this setting.
+
+
+
+
track_io_timing (boolean)
@@ -8293,16 +8632,22 @@ COPY postgres_log FROM '/full/path/to/logfile.csv' WITH csv;
- Enables timing of database I/O calls. This parameter is off by
+ Enables timing of database I/O waits. 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 tool to
measure the overhead of timing on your system.
I/O timing information is
displayed in
- pg_stat_database, in the output of
- when the BUFFERS option
- is used, in the output of when
+ pg_stat_database,
+
+ pg_stat_io (if object
+ is not wal), in the output of the
+
+ pg_stat_get_backend_io() function (if
+ object is not wal), in the
+ output of when the BUFFERS
+ option is used, in the output of when
the VERBOSE option is used, by autovacuum
for auto-vacuums and auto-analyzes, when is set and by
@@ -8321,14 +8666,18 @@ COPY postgres_log FROM '/full/path/to/logfile.csv' WITH csv;
- Enables timing of WAL I/O calls. This parameter is off by default,
+ Enables timing of WAL I/O waits. 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 pg_test_timing tool to
measure the overhead of timing on your system.
- I/O timing information is
- displayed in
- pg_stat_wal.
+ I/O timing information is displayed in
+
+ pg_stat_io for the
+ objectwal and in the output of
+ the
+ pg_stat_get_backend_io() function for the
+ objectwal.
Only superusers and users with the appropriate SET
privilege can change this setting.
@@ -8483,14 +8832,22 @@ COPY postgres_log FROM '/full/path/to/logfile.csv' WITH csv;
-
- Automatic Vacuuming
+
+ Vacuuming
- autovacuum
+ vacuumconfiguration parameters
+
+ These parameters control vacuuming behavior. For more information on the
+ purpose and responsibilities of vacuum, see .
+
+
+
+ Automatic Vacuuming
+
These settings control the behavior of the autovacuum
feature. Refer to for more information.
@@ -8498,298 +8855,747 @@ COPY postgres_log FROM '/full/path/to/logfile.csv' WITH csv;
basis; see .
-
+
-
- autovacuum (boolean)
-
- autovacuum configuration parameter
-
-
-
-
- Controls whether the server should run the
- autovacuum launcher daemon. This is on by default; however,
- must also be enabled for
- autovacuum to work.
- This parameter can only be set in the postgresql.conf
- file or on the server command line; however, autovacuuming can be
- disabled for individual tables by changing table storage parameters.
-
-
- Note that even when this parameter is disabled, the system
- will launch autovacuum processes if necessary to
- prevent transaction ID wraparound. See for more information.
-
-
-
+
+ autovacuum (boolean)
+
+ autovacuum configuration parameter
+
+
+
+
+ Controls whether the server should run the
+ autovacuum launcher daemon. This is on by default; however,
+ must also be enabled for
+ autovacuum to work.
+ This parameter can only be set in the postgresql.conf
+ file or on the server command line; however, autovacuuming can be
+ disabled for individual tables by changing table storage parameters.
+
+
+ Note that even when this parameter is disabled, the system
+ will launch autovacuum processes if necessary to
+ prevent transaction ID wraparound. See for more information.
+
+
+
-
- autovacuum_max_workers (integer)
-
- autovacuum_max_workers configuration parameter
-
-
-
-
- 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.
-
-
-
+
+ autovacuum_worker_slots (integer)
+
+ autovacuum_worker_slots configuration parameter
+
+
+
+
+ Specifies the number of backend slots to reserve for autovacuum worker
+ processes. The default is typically 16 slots, but might be less if
+ your kernel settings will not support it (as determined during initdb).
+ This parameter can only be set at server start.
+
+
+ When changing this value, consider also adjusting
+ .
+
+
+
-
- autovacuum_naptime (integer)
-
- autovacuum_naptime configuration parameter
-
-
-
-
- Specifies the minimum delay between autovacuum runs on any given
- database. In each round the daemon examines the
- database and issues VACUUM and ANALYZE 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 (1min).
- This parameter can only be set in the postgresql.conf
- file or on the server command line.
-
-
-
+
+ autovacuum_max_workers (integer)
+
+ autovacuum_max_workers configuration parameter
+
+
+
+
+ Specifies the maximum number of autovacuum processes (other than the
+ autovacuum launcher) that may be running at any one time. The default
+ is 3. This parameter can only be set in the
+ postgresql.conf file or on the server command line.
+
+
+ Note that a setting for this value which is higher than
+ will have no effect,
+ since autovacuum workers are taken from the pool of slots established
+ by that setting.
+
+
+
-
- autovacuum_vacuum_threshold (integer)
-
- autovacuum_vacuum_threshold
- configuration parameter
-
-
-
-
- Specifies the minimum number of updated or deleted tuples needed
- to trigger a VACUUM in any one table.
- The default is 50 tuples.
- This parameter can only be set in the postgresql.conf
- file or on the server command line;
- but the setting can be overridden for individual tables by
- changing table storage parameters.
-
-
-
+
+ autovacuum_naptime (integer)
+
+ autovacuum_naptime configuration parameter
+
+
+
+
+ Specifies the minimum delay between autovacuum runs on any given
+ database. In each round the daemon examines the
+ database and issues VACUUM and ANALYZE 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 (1min).
+ This parameter can only be set in the postgresql.conf
+ file or on the server command line.
+
+
+
-
- autovacuum_vacuum_insert_threshold (integer)
-
- autovacuum_vacuum_insert_threshold
- configuration parameter
-
-
-
-
- Specifies the number of inserted tuples needed to trigger a
- VACUUM in any one table.
- The default is 1000 tuples. If -1 is specified, autovacuum will not
- trigger a VACUUM operation on any tables based on
- the number of inserts.
- This parameter can only be set in the postgresql.conf
- file or on the server command line;
- but the setting can be overridden for individual tables by
- changing table storage parameters.
-
-
-
+
+ autovacuum_vacuum_threshold (integer)
+
+ autovacuum_vacuum_threshold
+ configuration parameter
+
+
+
+
+ Specifies the minimum number of updated or deleted tuples needed
+ to trigger a VACUUM in any one table.
+ The default is 50 tuples.
+ This parameter can only be set in the postgresql.conf
+ file or on the server command line;
+ but the setting can be overridden for individual tables by
+ changing table storage parameters.
+
+
+
-
- autovacuum_analyze_threshold (integer)
-
- autovacuum_analyze_threshold
- configuration parameter
-
-
-
-
- Specifies the minimum number of inserted, updated or deleted tuples
- needed to trigger an ANALYZE in any one table.
- The default is 50 tuples.
- This parameter can only be set in the postgresql.conf
- file or on the server command line;
- but the setting can be overridden for individual tables by
- changing table storage parameters.
-
-
-
+
+ autovacuum_vacuum_insert_threshold (integer)
+
+ autovacuum_vacuum_insert_threshold
+ configuration parameter
+
+
+
+
+ Specifies the number of inserted tuples needed to trigger a
+ VACUUM in any one table.
+ The default is 1000 tuples. If -1 is specified, autovacuum will not
+ trigger a VACUUM operation on any tables based on
+ the number of inserts.
+ This parameter can only be set in the postgresql.conf
+ file or on the server command line;
+ but the setting can be overridden for individual tables by
+ changing table storage parameters.
+
+
+
-
- autovacuum_vacuum_scale_factor (floating point)
-
- autovacuum_vacuum_scale_factor
- configuration parameter
-
-
-
-
- Specifies a fraction of the table size to add to
- autovacuum_vacuum_threshold
- when deciding whether to trigger a VACUUM.
- The default is 0.2 (20% of table size).
- This parameter can only be set in the postgresql.conf
- file or on the server command line;
- but the setting can be overridden for individual tables by
- changing table storage parameters.
-
-
-
+
+ autovacuum_analyze_threshold (integer)
+
+ autovacuum_analyze_threshold
+ configuration parameter
+
+
+
+
+ Specifies the minimum number of inserted, updated or deleted tuples
+ needed to trigger an ANALYZE in any one table.
+ The default is 50 tuples.
+ This parameter can only be set in the postgresql.conf
+ file or on the server command line;
+ but the setting can be overridden for individual tables by
+ changing table storage parameters.
+
+
+
-
- autovacuum_vacuum_insert_scale_factor (floating point)
-
- autovacuum_vacuum_insert_scale_factor
- configuration parameter
-
-
-
-
- Specifies a fraction of the table size to add to
- autovacuum_vacuum_insert_threshold
- when deciding whether to trigger a VACUUM.
- The default is 0.2 (20% of table size).
- This parameter can only be set in the postgresql.conf
- file or on the server command line;
- but the setting can be overridden for individual tables by
- changing table storage parameters.
-
-
-
+
+ autovacuum_vacuum_scale_factor (floating point)
+
+ autovacuum_vacuum_scale_factor
+ configuration parameter
+
+
+
+
+ Specifies a fraction of the table size to add to
+ autovacuum_vacuum_threshold
+ when deciding whether to trigger a VACUUM.
+ The default is 0.2 (20% of table size).
+ This parameter can only be set in the postgresql.conf
+ file or on the server command line;
+ but the setting can be overridden for individual tables by
+ changing table storage parameters.
+
+
+
+
+
+ autovacuum_vacuum_insert_scale_factor (floating point)
+
+ autovacuum_vacuum_insert_scale_factor
+ configuration parameter
+
+
+
+
+ Specifies a fraction of the unfrozen pages in the table to add to
+ autovacuum_vacuum_insert_threshold when deciding
+ whether to trigger a VACUUM. The default is
+ 0.2 (20% of unfrozen pages in table). This
+ parameter can only be set in the postgresql.conf
+ file or on the server command line; but the setting can be overridden
+ for individual tables by changing table storage parameters.
+
+
+
+
+
+ autovacuum_analyze_scale_factor (floating point)
+
+ autovacuum_analyze_scale_factor
+ configuration parameter
+
+
+
+
+ Specifies a fraction of the table size to add to
+ autovacuum_analyze_threshold
+ when deciding whether to trigger an ANALYZE.
+ The default is 0.1 (10% of table size).
+ This parameter can only be set in the postgresql.conf
+ file or on the server command line;
+ but the setting can be overridden for individual tables by
+ changing table storage parameters.
+
+
+
+
+
+ autovacuum_vacuum_max_threshold (integer)
+
+ autovacuum_vacuum_max_threshold
+ configuration parameter
+
+
+
+
+ Specifies the maximum number of updated or deleted tuples needed to
+ trigger a VACUUM in any one table, i.e., a limit on
+ the value calculated with
+ autovacuum_vacuum_threshold and
+ autovacuum_vacuum_scale_factor. The default is
+ 100,000,000 tuples. If -1 is specified, autovacuum will not enforce a
+ maximum number of updated or deleted tuples that will trigger a
+ VACUUM operation. This parameter can only be set
+ in the postgresql.conf file or on the server
+ command line; but the setting can be overridden for individual tables
+ by changing storage parameters.
+
+
+
+
+
+ autovacuum_freeze_max_age (integer)
+
+ autovacuum_freeze_max_age
+ configuration parameter
+
+
+
+
+ Specifies the maximum age (in transactions) that a table's
+ pg_class.relfrozenxid field can
+ attain before a VACUUM 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.
+
+
+
+ Vacuum also allows removal of old files from the
+ pg_xact subdirectory, which is why the default
+ is a relatively low 200 million transactions.
+ This parameter can only be set at server start, but the setting
+ can be reduced for individual tables by
+ changing table storage parameters.
+ For more information see .
+
+
+
+
+
+ autovacuum_multixact_freeze_max_age (integer)
+
+ autovacuum_multixact_freeze_max_age
+ configuration parameter
+
+
+
+
+ Specifies the maximum age (in multixacts) that a table's
+ pg_class.relminmxid field can
+ attain before a VACUUM 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.
+
+
+
+ Vacuuming multixacts also allows removal of old files from the
+ pg_multixact/members and pg_multixact/offsets
+ 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 .
+
+
+
+
+
+ autovacuum_vacuum_cost_delay (floating point)
+
+ autovacuum_vacuum_cost_delay
+ configuration parameter
+
+
+
+
+ Specifies the cost delay value that will be used in automatic
+ VACUUM operations. If -1 is specified, the regular
+ 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 postgresql.conf
+ file or on the server command line;
+ but the setting can be overridden for individual tables by
+ changing table storage parameters.
+
+
+
+
+
+ autovacuum_vacuum_cost_limit (integer)
+
+ autovacuum_vacuum_cost_limit
+ configuration parameter
+
+
+
+
+ Specifies the cost limit value that will be used in automatic
+ VACUUM operations. If -1
+ is specified (which is the default), the regular
+ value will be used. Note that
+ 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 postgresql.conf
+ file or on the server command line;
+ but the setting can be overridden for individual tables by
+ changing table storage parameters.
+
+
+
+
+
+
+
+
+ Cost-based Vacuum Delay
+
+
+ During the execution of
+ and
+ commands, the system maintains an
+ internal counter that keeps track of the estimated cost of the
+ various I/O operations that are performed. When the accumulated
+ cost reaches a limit (specified by
+ vacuum_cost_limit), the process performing
+ the operation will sleep for a short period of time, as specified by
+ vacuum_cost_delay. Then it will reset the
+ counter and continue execution.
+
+
+
+ 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
+ VACUUM and ANALYZE 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.
+
+
+
+ This feature is disabled by default for manually issued
+ VACUUM commands. To enable it, set the
+ vacuum_cost_delay variable to a nonzero
+ value.
+
+
+
+
+ vacuum_cost_delay (floating point)
+
+ vacuum_cost_delay configuration parameter
+
+
+
+
+ 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
+ 0, which disables the cost-based vacuum delay
+ feature. Positive values enable cost-based vacuuming.
+
+
+
+ When using cost-based vacuuming, appropriate values for
+ vacuum_cost_delay are usually quite small, perhaps
+ less than 1 millisecond. While vacuum_cost_delay
+ can be set to fractional-millisecond values, such delays may not be
+ measured accurately on older platforms. On such platforms,
+ increasing VACUUM's throttled resource consumption
+ above what you get at 1ms will require changing the other vacuum cost
+ parameters. You should, nonetheless,
+ keep vacuum_cost_delay as small as your platform
+ will consistently measure; large delays are not helpful.
+
+
+
+
+
+ vacuum_cost_page_hit (integer)
+
+ vacuum_cost_page_hit configuration parameter
+
+
+
+
+ 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 1.
+
+
+
+
+
+ vacuum_cost_page_miss (integer)
+
+ vacuum_cost_page_miss configuration parameter
+
+
+
+
+ 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.
+
+
+
+
+
+ vacuum_cost_page_dirty (integer)
+
+ vacuum_cost_page_dirty configuration parameter
+
+
+
+
+ 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.
+
+
+
+
+
+ vacuum_cost_limit (integer)
+
+ vacuum_cost_limit configuration parameter
+
+
+
+
+ This is the accumulated cost that will cause the vacuuming
+ process to sleep for vacuum_cost_delay. The
+ default is 200.
+
+
+
+
+
+
+
+ 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 vacuum_cost_delay *
+ accumulated_balance /
+ vacuum_cost_limit with a maximum of
+ vacuum_cost_delay * 4.
+
+
+
+
+
+ Default Behavior
+
+
+
+ vacuum_truncate (boolean)
+
+ vacuum_truncate
+ configuration parameter
+
+
+
+
+ Enables or disables vacuum to try to truncate off any empty pages at
+ the end of the table. The default value is true.
+ If true, VACUUM and autovacuum
+ do the truncation and the disk space for the truncated pages is
+ returned to the operating system. Note that the truncation requires
+ an ACCESS EXCLUSIVE lock on the table. The
+ TRUNCATE parameter of
+ VACUUM, if
+ specified, overrides the value of this parameter. The setting can
+ also be overridden for individual tables by changing table storage
+ parameters.
+
+
+
+
+
+
+
+ Freezing
+
+
+ To maintain correctness even after transaction IDs wrap around,
+ PostgreSQL marks rows that are sufficiently
+ old as frozen. These rows are visible to everyone;
+ other transactions do not need to examine their inserting XID to
+ determine visibility. VACUUM is responsible for
+ marking rows as frozen. The following settings control
+ VACUUM's freezing behavior and should be tuned based
+ on the XID consumption rate of the system and data access patterns of the
+ dominant workloads. See for more
+ information on transaction ID wraparound and tuning these parameters.
+
+
+
+
+ vacuum_freeze_table_age (integer)
+
+ vacuum_freeze_table_age configuration parameter
+
+
+
+
+ VACUUM performs an aggressive scan if the table's
+ pg_class.relfrozenxid field has reached
+ the age specified by this setting. An aggressive scan differs from
+ a regular VACUUM 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, VACUUM
+ will silently limit the effective value to 95% of
+ , so that a
+ periodic manual VACUUM has a chance to run before an
+ anti-wraparound autovacuum is launched for the table. For more
+ information see
+ .
+
+
+
+
+
+ vacuum_freeze_min_age (integer)
+
+ vacuum_freeze_min_age configuration parameter
+
+
+
+
+ Specifies the cutoff age (in transactions) that
+ VACUUM should use to decide whether to
+ trigger freezing of pages that have an older XID.
+ The default is 50 million transactions. Although
+ users can set this value anywhere from zero to one billion,
+ VACUUM will silently limit the effective value to half
+ the value of , so
+ that there is not an unreasonably short time between forced
+ autovacuums. For more information see .
+
+
+
-
- autovacuum_analyze_scale_factor (floating point)
-
- autovacuum_analyze_scale_factor
- configuration parameter
-
-
-
-
- Specifies a fraction of the table size to add to
- autovacuum_analyze_threshold
- when deciding whether to trigger an ANALYZE.
- The default is 0.1 (10% of table size).
- This parameter can only be set in the postgresql.conf
- file or on the server command line;
- but the setting can be overridden for individual tables by
- changing table storage parameters.
-
-
-
+
+ vacuum_failsafe_age (integer)
+
+ vacuum_failsafe_age configuration parameter
+
+
+
+
+ Specifies the maximum age (in transactions) that a table's
+ pg_class.relfrozenxid
+ field can attain before VACUUM takes
+ extraordinary measures to avoid system-wide transaction ID
+ wraparound failure. This is VACUUM'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 VACUUM.
+
+
+ When the failsafe is triggered, any cost-based delay that is
+ in effect will no longer be applied, further non-essential
+ maintenance tasks (such as index vacuuming) are bypassed, and any
+ Buffer Access Strategy
+ in use will be disabled resulting in VACUUM being
+ free to make use of all of
+ shared buffers.
+
+
+ The default is 1.6 billion transactions. Although users can
+ set this value anywhere from zero to 2.1 billion,
+ VACUUM will silently adjust the effective
+ value to no less than 105% of .
+
+
+
-
- autovacuum_freeze_max_age (integer)
-
- autovacuum_freeze_max_age
- configuration parameter
-
-
-
-
- Specifies the maximum age (in transactions) that a table's
- pg_class.relfrozenxid field can
- attain before a VACUUM 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.
-
+
+ vacuum_multixact_freeze_table_age (integer)
+
+ vacuum_multixact_freeze_table_age configuration parameter
+
+
+
+
+ VACUUM performs an aggressive scan if the table's
+ pg_class.relminmxid field has reached
+ the age specified by this setting. An aggressive scan differs from
+ a regular VACUUM 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,
+ VACUUM will silently limit the effective value to 95% of
+ , so that a
+ periodic manual VACUUM has a chance to run before an
+ anti-wraparound is launched for the table.
+ For more information see .
+
+
+
-
- Vacuum also allows removal of old files from the
- pg_xact subdirectory, which is why the default
- is a relatively low 200 million transactions.
- This parameter can only be set at server start, but the setting
- can be reduced for individual tables by
- changing table storage parameters.
- For more information see .
-
-
-
+
+ vacuum_multixact_freeze_min_age (integer)
+
+ vacuum_multixact_freeze_min_age configuration parameter
+
+
+
+
+ Specifies the cutoff age (in multixacts) that VACUUM
+ should use to decide whether to trigger freezing of pages with
+ an older multixact ID. The default is 5 million multixacts.
+ Although users can set this value anywhere from zero to one billion,
+ VACUUM will silently limit the effective value to half
+ the value of ,
+ so that there is not an unreasonably short time between forced
+ autovacuums.
+ For more information see .
+
+
+
+
+
+ vacuum_multixact_failsafe_age (integer)
+
+ vacuum_multixact_failsafe_age configuration parameter
+
+
+
+
+ Specifies the maximum age (in multixacts) that a table's
+ pg_class.relminmxid
+ field can attain before VACUUM takes
+ extraordinary measures to avoid system-wide multixact ID
+ wraparound failure. This is VACUUM'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 VACUUM.
+
+
+ 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.
+
+
+ The default is 1.6 billion multixacts. Although users can set
+ this value anywhere from zero to 2.1 billion,
+ VACUUM will silently adjust the effective
+ value to no less than 105% of .
+
+
+
-
- autovacuum_multixact_freeze_max_age (integer)
+
+ vacuum_max_eager_freeze_failure_rate (floating point)
- autovacuum_multixact_freeze_max_age
+ vacuum_max_eager_freeze_failure_rateconfiguration parameter
- Specifies the maximum age (in multixacts) that a table's
- pg_class.relminmxid field can
- attain before a VACUUM 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.
-
-
-
- Vacuuming multixacts also allows removal of old files from the
- pg_multixact/members and pg_multixact/offsets
- 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 .
+ Specifies the maximum number of pages (as a fraction of total pages in
+ the relation) that VACUUM may scan and
+ fail to set all-frozen in the visibility map
+ before disabling eager scanning. A value of 0
+ disables eager scanning altogether. The default is
+ 0.03 (3%).
-
-
-
- autovacuum_vacuum_cost_delay (floating point)
-
- autovacuum_vacuum_cost_delay
- configuration parameter
-
-
-
- Specifies the cost delay value that will be used in automatic
- VACUUM operations. If -1 is specified, the regular
- 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 postgresql.conf
- file or on the server command line;
- but the setting can be overridden for individual tables by
- changing table storage parameters.
+ Note that when eager scanning is enabled, only freeze failures
+ count against the cap, not successful freezing. Successful page
+ freezes are capped internally at 20% of the all-visible but not
+ all-frozen pages in the relation. Capping successful page freezes helps
+ amortize the overhead across multiple normal vacuums and limits the
+ potential downside of wasted eager freezes of pages that are modified
+ again before the next aggressive vacuum.
-
-
-
- autovacuum_vacuum_cost_limit (integer)
-
- autovacuum_vacuum_cost_limit
- configuration parameter
-
-
-
- Specifies the cost limit value that will be used in automatic
- VACUUM operations. If -1 is specified (which is the
- default), the regular
- value will be used. Note that
- 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 postgresql.conf
- file or on the server command line;
- but the setting can be overridden for individual tables by
- changing table storage parameters.
+ This parameter can only be set in the
+ postgresql.conf file or on the server command
+ line; but the setting can be overridden for individual tables by
+ changing the
+
+ corresponding table storage parameter.
+ For more information on tuning vacuum's freezing behavior,
+ see .
-
+
+
@@ -9349,7 +10155,7 @@ COPY postgres_log FROM '/full/path/to/logfile.csv' WITH csv;
If transaction_timeout is shorter or equal to
idle_in_transaction_session_timeout or statement_timeout
- then the longer timeout is ignored.
+ then the longer timeout is ignored.
@@ -9461,168 +10267,6 @@ COPY postgres_log FROM '/full/path/to/logfile.csv' WITH csv;
-
- vacuum_freeze_table_age (integer)
-
- vacuum_freeze_table_age configuration parameter
-
-
-
-
- VACUUM performs an aggressive scan if the table's
- pg_class.relfrozenxid field has reached
- the age specified by this setting. An aggressive scan differs from
- a regular VACUUM 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, VACUUM
- will silently limit the effective value to 95% of
- , so that a
- periodic manual VACUUM has a chance to run before an
- anti-wraparound autovacuum is launched for the table. For more
- information see
- .
-
-
-
-
-
- vacuum_freeze_min_age (integer)
-
- vacuum_freeze_min_age configuration parameter
-
-
-
-
- Specifies the cutoff age (in transactions) that
- VACUUM should use to decide whether to
- trigger freezing of pages that have an older XID.
- The default is 50 million transactions. Although
- users can set this value anywhere from zero to one billion,
- VACUUM will silently limit the effective value to half
- the value of , so
- that there is not an unreasonably short time between forced
- autovacuums. For more information see .
-
-
-
-
-
- vacuum_failsafe_age (integer)
-
- vacuum_failsafe_age configuration parameter
-
-
-
-
- Specifies the maximum age (in transactions) that a table's
- pg_class.relfrozenxid
- field can attain before VACUUM takes
- extraordinary measures to avoid system-wide transaction ID
- wraparound failure. This is VACUUM'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 VACUUM.
-
-
- When the failsafe is triggered, any cost-based delay that is
- in effect will no longer be applied, further non-essential
- maintenance tasks (such as index vacuuming) are bypassed, and any
- Buffer Access Strategy
- in use will be disabled resulting in VACUUM being
- free to make use of all of
- shared buffers.
-
-
- The default is 1.6 billion transactions. Although users can
- set this value anywhere from zero to 2.1 billion,
- VACUUM will silently adjust the effective
- value to no less than 105% of .
-
-
-
-
-
- vacuum_multixact_freeze_table_age (integer)
-
- vacuum_multixact_freeze_table_age configuration parameter
-
-
-
-
- VACUUM performs an aggressive scan if the table's
- pg_class.relminmxid field has reached
- the age specified by this setting. An aggressive scan differs from
- a regular VACUUM 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,
- VACUUM will silently limit the effective value to 95% of
- , so that a
- periodic manual VACUUM has a chance to run before an
- anti-wraparound is launched for the table.
- For more information see .
-
-
-
-
-
- vacuum_multixact_freeze_min_age (integer)
-
- vacuum_multixact_freeze_min_age configuration parameter
-
-
-
-
- Specifies the cutoff age (in multixacts) that VACUUM
- should use to decide whether to trigger freezing of pages with
- an older multixact ID. The default is 5 million multixacts.
- Although users can set this value anywhere from zero to one billion,
- VACUUM will silently limit the effective value to half
- the value of ,
- so that there is not an unreasonably short time between forced
- autovacuums.
- For more information see .
-
-
-
-
-
- vacuum_multixact_failsafe_age (integer)
-
- vacuum_multixact_failsafe_age configuration parameter
-
-
-
-
- Specifies the maximum age (in multixacts) that a table's
- pg_class.relminmxid
- field can attain before VACUUM takes
- extraordinary measures to avoid system-wide multixact ID
- wraparound failure. This is VACUUM'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 VACUUM.
-
-
- 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.
-
-
- The default is 1.6 billion multixacts. Although users can set
- this value anywhere from zero to 2.1 billion,
- VACUUM will silently adjust the effective
- value to no less than 105% of .
-
-
-
-
bytea_output (enum)
@@ -9778,6 +10422,23 @@ SET XML OPTION { DOCUMENT | CONTENT };
+
+ restrict_nonsystem_relation_kind (string)
+
+ restrict_nonsystem_relation_kind
+ configuration parameter
+
+
+
+
+ Set relation kinds for which access to non-system relations is prohibited.
+ The value takes the form of a comma-separated list of relation kinds.
+ Currently, the supported relation kinds are view and
+ foreign-table.
+
+
+
+
@@ -9871,8 +10532,10 @@ SET XML OPTION { DOCUMENT | CONTENT };
- Sets the collection of time zone abbreviations that will be accepted
- by the server for datetime input. The default is 'Default',
+ Sets the collection of additional time zone abbreviations that
+ will be accepted by the server for datetime input (beyond any
+ abbreviations defined by the current TimeZone
+ setting). The default is 'Default',
which is a collection that works in most of the world; there are
also 'Australia' and 'India',
and other collections can be defined for a particular installation.
@@ -10356,6 +11019,75 @@ dynamic_library_path = 'C:\tools\postgresql;H:\my_project\lib;$libdir'
+
+ extension_control_path (string)
+
+ extension_control_path configuration parameter
+
+
+
+
+ A path to search for extensions, specifically extension control files
+ (name.control). The
+ remaining extension script and secondary control files are then loaded
+ from the same directory where the primary control file was found.
+ See for details.
+
+
+
+ The value for extension_control_path 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 $system, the
+ compiled-in PostgreSQL extension
+ directory is substituted for $system; this
+ is where the extensions provided by the standard
+ PostgreSQL distribution are installed.
+ (Use pg_config --sharedir to find out the name of
+ this directory.) For example:
+
+extension_control_path = '/usr/local/share/postgresql:/home/my_project/share:$system'
+
+ or, in a Windows environment:
+
+extension_control_path = 'C:\tools\postgresql;H:\my_project\share;$system'
+
+ Note that the specified paths elements are expected to have a
+ subdirectory extension which will contain the
+ .control and .sql files; the
+ extension suffix is automatically appended to
+ each path element.
+
+
+
+ The default value for this parameter is
+ '$system'. If the value is set to an empty
+ string, the default '$system' is also assumed.
+
+
+
+ This parameter can be changed at run time by superusers and users
+ with the appropriate SET 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 postgresql.conf configuration
+ file.
+
+
+
+ Note that if you set this parameter to be able to load extensions from
+ nonstandard locations, you will most likely also need to set to a correspondent location, for
+ example,
+
+extension_control_path = '/usr/local/share/postgresql:$system'
+dynamic_library_path = '/usr/local/lib/postgresql:$libdir'
+
+
+
+
+
gin_fuzzy_search_limit (integer)
@@ -10790,7 +11522,7 @@ dynamic_library_path = 'C:\tools\postgresql;H:\my_project\lib;$libdir'
Turning this setting off is intended for environments where the
configuration of PostgreSQL is managed by
some external tool.
- In such environments, a well intentioned superuser might
+ In such environments, a well-intentioned superuser might
mistakenly use ALTER SYSTEM
to change the configuration instead of using the external tool.
This might result in unintended behavior, such as the external tool
@@ -10994,7 +11726,9 @@ dynamic_library_path = 'C:\tools\postgresql;H:\my_project\lib;$libdir'
had at server startup.
(On Microsoft Windows this parameter will always display
0700.) See
- for more information.
+ the
+ initdb option
+ for more information.
@@ -11118,6 +11852,24 @@ dynamic_library_path = 'C:\tools\postgresql;H:\my_project\lib;$libdir'
+
+ num_os_semaphores (integer)
+
+ num_os_semaphores configuration parameter
+
+
+
+
+ Reports the number of semaphores that are needed for the server based
+ on the configured number of allowed connections
+ (), allowed autovacuum worker
+ processes (), allowed WAL
+ sender processes (), allowed
+ background processes (), etc.
+
+
+
+
segment_size (integer)
@@ -11372,6 +12124,29 @@ dynamic_library_path = 'C:\tools\postgresql;H:\my_project\lib;$libdir'
+
+ debug_copy_parse_plan_trees (boolean)
+
+ debug_copy_parse_plan_trees configuration parameter
+
+
+
+
+ Enabling this forces all parse and plan trees to be passed through
+ copyObject(), to facilitate catching errors and
+ omissions in copyObject(). The default is off.
+
+
+
+ This parameter is only available when
+ DEBUG_NODE_TESTS_ENABLED was defined at compile time
+ (which happens automatically when using the
+ configure option
+ ).
+
+
+
+
debug_discard_caches (integer)
@@ -11487,6 +12262,54 @@ dynamic_library_path = 'C:\tools\postgresql;H:\my_project\lib;$libdir'
+
+ debug_raw_expression_coverage_test (boolean)
+
+ debug_raw_expression_coverage_test configuration parameter
+
+
+
+
+ Enabling this forces all raw parse trees for DML statements to be
+ scanned by raw_expression_tree_walker(), to
+ facilitate catching errors and omissions in that function. The
+ default is off.
+
+
+
+ This parameter is only available when
+ DEBUG_NODE_TESTS_ENABLED was defined at compile time
+ (which happens automatically when using the
+ configure option
+ ).
+
+
+
+
+
+ debug_write_read_parse_plan_trees (boolean)
+
+ debug_write_read_parse_plan_trees configuration parameter
+
+
+
+
+ Enabling this forces all parse and plan trees to be passed through
+ outfuncs.c/readfuncs.c, to
+ facilitate catching errors and omissions in those modules. The
+ default is off.
+
+
+
+ This parameter is only available when
+ DEBUG_NODE_TESTS_ENABLED was defined at compile time
+ (which happens automatically when using the
+ configure option
+ ).
+
+
+
+
ignore_system_indexes (boolean)
@@ -11570,9 +12393,6 @@ dynamic_library_path = 'C:\tools\postgresql;H:\my_project\lib;$libdir'
If on, emit information about resource usage during sort operations.
- This parameter is only available if the TRACE_SORT macro
- was defined when PostgreSQL was compiled.
- (However, TRACE_SORT is currently defined by default.)
diff --git a/doc/src/sgml/contrib-spi.sgml b/doc/src/sgml/contrib-spi.sgml
index e7cae4e38dcce..6fa9479d1b992 100644
--- a/doc/src/sgml/contrib-spi.sgml
+++ b/doc/src/sgml/contrib-spi.sgml
@@ -36,7 +36,7 @@
check_primary_key() checks the referencing table.
- To use, create a BEFORE INSERT OR UPDATE trigger using this
+ To use, create an AFTER INSERT OR UPDATE 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
@@ -46,7 +46,7 @@
check_foreign_key() checks the referenced table.
- To use, create a BEFORE DELETE OR UPDATE trigger using this
+ To use, create an AFTER DELETE OR UPDATE 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
@@ -60,6 +60,16 @@
unique index.
+
+ Note that if these triggers are executed from
+ another BEFORE trigger, they can fail unexpectedly. For
+ example, if a user inserts row1 and then the BEFORE
+ trigger inserts row2 and calls a trigger with the
+ check_foreign_key(),
+ the check_foreign_key()
+ function will not see row1 and will fail.
+
+
There are examples in refint.example.
@@ -71,10 +81,12 @@
autoinc() is a trigger that stores the next value of
a sequence into an integer field. This has some overlap with the
- built-in serial column feature, but it is not the same:
- autoinc() will override attempts to substitute a
- different field value during inserts, and optionally it can be
- used to increment the field during updates, too.
+ built-in serial column feature, but it is not the same.
+ The trigger will replace the field's value only if that value is
+ initially zero or null (after the action of the SQL statement that
+ inserted or updated the row). Also, if the sequence's next value is
+ zero, nextval() will be called a second time in
+ order to obtain a non-zero value.
diff --git a/doc/src/sgml/contrib.sgml b/doc/src/sgml/contrib.sgml
index 44639a8dcab90..24b706b29adc3 100644
--- a/doc/src/sgml/contrib.sgml
+++ b/doc/src/sgml/contrib.sgml
@@ -154,6 +154,8 @@ CREATE EXTENSION extension_name;
&pgbuffercache;
&pgcrypto;
&pgfreespacemap;
+ &pglogicalinspect;
+ &pgoverexplain;
&pgprewarm;
&pgrowlocks;
&pgstatstatements;
diff --git a/doc/src/sgml/datatype.sgml b/doc/src/sgml/datatype.sgml
index 6646820d6a0a9..b81d89e260809 100644
--- a/doc/src/sgml/datatype.sgml
+++ b/doc/src/sgml/datatype.sgml
@@ -117,7 +117,7 @@
double precision
- float8
+ float, float8double precision floating-point number (8 bytes)
@@ -2054,8 +2054,6 @@ MINUTE TO SECOND
Time Input
-
- Example
@@ -2245,24 +2243,27 @@ TIMESTAMP '2004-10-19 10:23:54+02'
TIMESTAMP WITH TIME ZONE '2004-10-19 10:23:54+02'
+
- In a literal that has been determined to be timestamp without time
+
+ In a value that has been determined to be timestamp without time
zone, PostgreSQL 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.
+ fields in the input string, and is not adjusted for time zone.
- For timestamp with time zone, the internally stored
- value is always in UTC (Universal
- Coordinated Time, traditionally known as Greenwich Mean Time,
- GMT). An input value that has an explicit
- time zone specified is converted to UTC using the appropriate offset
+ For timestamp with time zone values, an input string
+ that includes an explicit time zone will be converted to UTC
+ (Universal Coordinated
+ Time) using the appropriate offset
for that time zone. If no time zone is stated in the input string,
then it is assumed to be in the time zone indicated by the system's
parameter, and is converted to UTC using the
offset for the timezone zone.
+ In either case, the value is stored internally as UTC, and the
+ originally stated or assumed time zone is not retained.
@@ -2534,6 +2535,10 @@ TIMESTAMP WITH TIME ZONE '2004-10-19 10:23:54+02'
abbreviation if one is in common use in the current zone. Otherwise
it appears as a signed numeric offset in ISO 8601 basic format
(hh or hhmm).
+ The alphabetic abbreviations shown in these styles are taken from the
+ IANA time zone database entry currently selected by the
+ run-time parameter; they are not
+ affected by the setting.
@@ -2675,6 +2680,14 @@ TIMESTAMP WITH TIME ZONE '2004-10-19 10:23:54+02'
savings was nominally in effect on that date.
+
+
+ The sign in POSIX-style time zone specifications has the opposite meaning
+ of the sign in ISO-8601 datetime values. For example, the POSIX time zone
+ for 2014-06-04 12:00+04 would be UTC-4.
+
+
+
To complicate matters, some jurisdictions have used the same timezone
abbreviation to mean different UTC offsets at different times; for
@@ -3369,7 +3382,7 @@ SELECT person.name, holidays.num_weeks FROM person, holidays
line
- 32 bytes
+ 24 bytesInfinite line{A,B,C}
@@ -3413,6 +3426,11 @@ SELECT person.name, holidays.num_weeks FROM person, holidays
+
+ In all these types, the individual coordinates are stored as
+ double precision (float8) numbers.
+
+
A rich set of functions and operators is available to perform various geometric
operations such as scaling, translation, rotation, and determining
@@ -3603,8 +3621,16 @@ SELECT person.name, holidays.num_weeks FROM person, holidays
Polygons are represented by lists of points (the vertices 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.
+ semantic difference is that a polygon is considered to include the
+ area within it, while a path is not.
+
+
+
+ An important implementation difference between polygons and
+ paths is that the stored representation of a polygon includes its
+ smallest bounding box. This speeds up certain search operations,
+ although computing the bounding box adds overhead while constructing
+ new polygons.
@@ -4367,7 +4393,7 @@ SELECT to_tsvector( 'postgraduate' ), to_tsquery( 'postgres:*' );
The data type uuid stores Universally Unique Identifiers
- (UUID) as defined by RFC 4122,
+ (UUID) as defined by RFC 9562,
ISO/IEC 9834-8:2005, and related standards.
(Some systems refer to this data type as a globally unique identifier, or
GUID,GUID instead.) This
@@ -4379,6 +4405,15 @@ SELECT to_tsvector( 'postgraduate' ), to_tsquery( 'postgres:*' );
are only unique within a single database.
+
+ RFC 9562 defines 8 different UUID versions. Each version has specific requirements
+ for generating new UUID values, and each version provides distinct benefits and drawbacks.
+ PostgreSQL provides native support for generating UUIDs
+ using the UUIDv4 and UUIDv7 algorithms. Alternatively, UUID values can be generated
+ outside of the database using any algorithm. The data type uuid can be used
+ to store any UUID, regardless of the origin and the UUID version.
+
+
A UUID is written as a sequence of lower-case hexadecimal digits,
in several groups separated by hyphens, specifically a group of 8
@@ -4700,6 +4735,10 @@ INSERT INTO mytable VALUES(-1); -- fails
regconfig
+
+ regdatabase
+
+
regdictionary
@@ -4841,6 +4880,13 @@ SELECT * FROM pg_attribute
english
+
+ regdatabase
+ pg_database
+ database name
+ template1
+
+
regdictionarypg_ts_dict
@@ -5012,8 +5058,8 @@ WHERE ...
be dropped without first removing the default expression. The
alternative of nextval('my_seq'::text) does not
create a dependency.
- (regrole is an exception to this property. Constants of this
- type are not allowed in stored expressions.)
+ (regdatabase and regrole are exceptions to this
+ property. Constants of these types are not allowed in stored expressions.)
@@ -5073,7 +5119,7 @@ WHERE ...
+(pg_lsn,numeric) and
-(pg_lsn,numeric) operators, respectively. Note that
the calculated LSN should be in the range of pg_lsn type,
- i.e., between 0/0 and
+ i.e., between 0/00000000 and
FFFFFFFF/FFFFFFFF.
@@ -5197,8 +5243,8 @@ WHERE ...
Pseudo-Types
-
-
+
+ Name
diff --git a/doc/src/sgml/datetime.sgml b/doc/src/sgml/datetime.sgml
index e7035c7806538..3e24170acbfcc 100644
--- a/doc/src/sgml/datetime.sgml
+++ b/doc/src/sgml/datetime.sgml
@@ -80,7 +80,7 @@
See if the token matches any known time zone abbreviation.
- These abbreviations are supplied by the configuration file
+ These abbreviations are determined by the configuration settings
described in .
@@ -424,9 +424,43 @@
Since timezone abbreviations are not well standardized,
PostgreSQL provides a means to customize
- the set of abbreviations accepted by the server. The
- run-time parameter
- determines the active set of abbreviations. While this parameter
+ the set of abbreviations accepted in datetime input.
+ There are two sources for these abbreviations:
+
+
+
+
+ The run-time parameter is usually
+ set to the name of an entry in the IANA time zone database.
+ If that zone has widely-used zone abbreviations, they will appear
+ in the IANA data, and PostgreSQL will
+ preferentially recognize those abbreviations with the meanings
+ given in the IANA data.
+ For example, if timezone is set
+ to America/New_York then EST
+ will be understood as UTC-5 and EDT will be
+ understood as UTC-4. (These IANA abbreviations will also be used
+ in datetime output, if is set to a
+ style that prefers non-numeric zone abbreviations.)
+
+
+
+
+
+ If an abbreviation is not found in the current IANA time zone,
+ it is sought in the list specified by the
+ run-time parameter.
+ The timezone_abbreviations list is primarily
+ useful for allowing datetime input to recognize abbreviations for
+ time zones other than the current zone. (These abbreviations will
+ not be used in datetime output.)
+
+
+
+
+
+
+ While the timezone_abbreviations 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
diff --git a/doc/src/sgml/dblink.sgml b/doc/src/sgml/dblink.sgml
index 81f35986c8820..808c690985b73 100644
--- a/doc/src/sgml/dblink.sgml
+++ b/doc/src/sgml/dblink.sgml
@@ -150,9 +150,23 @@ dblink_connect(text connname, text connstr) returns text
executing arbitrary SQL commands.
+
+ The foreign-data wrapper dblink_fdw has an additional
+ Boolean option use_scram_passthrough that controls
+ whether dblink will use the SCRAM pass-through
+ authentication to connect to the remote database. With SCRAM pass-through
+ authentication, dblink uses SCRAM-hashed secrets
+ instead of plain-text user passwords to connect to the remote server. This
+ avoids storing plain-text user passwords in PostgreSQL system catalogs.
+ See the documentation of the equivalent use_scram_passthrough
+ option of postgres_fdw for further details and restrictions.
+
+
Only superusers may use dblink_connect to create
- non-password-authenticated and non-GSSAPI-authenticated connections.
+ connections that use neither password authentication, SCRAM pass-through,
+ nor GSSAPI-authentication.
If non-superusers need this capability, use
dblink_connect_u instead.
@@ -181,8 +195,9 @@ SELECT dblink_connect('myconn', 'dbname=postgres options=-csearch_path=');
(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():
+-- Note: local connections that don't use SCRAM pass-through 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.
diff --git a/doc/src/sgml/ddl.sgml b/doc/src/sgml/ddl.sgml
index 6aab79e901c80..65bc070d2e5fa 100644
--- a/doc/src/sgml/ddl.sgml
+++ b/doc/src/sgml/ddl.sgml
@@ -257,7 +257,7 @@ CREATE TABLE people (
or alternatively
CREATE TABLE people (
- id bigint GENERATED BY DEFAULT IDENTITY,
+ id bigint GENERATED BY DEFAULT AS IDENTITY,
...,
);
@@ -271,8 +271,8 @@ CREATE TABLE people (
example, with the above definitions and assuming additional appropriate
columns, writing
-INSERT INTO people (name, address) VALUE ('A', 'foo');
-INSERT INTO people (name, address) VALUE ('B', 'bar');
+INSERT INTO people (name, address) VALUES ('A', 'foo');
+INSERT INTO people (name, address) VALUES ('B', 'bar');
would generate values for the id column starting at 1
and result in the following table data:
@@ -285,7 +285,7 @@ INSERT INTO people (name, address) VALUE ('B', 'bar');
Alternatively, the keyword DEFAULT can be specified in
place of a value to explicitly request the sequence-generated value, like
-INSERT INTO people (id, name, address) VALUE (DEFAULT, 'C', 'baz');
+INSERT INTO people (id, name, address) VALUES (DEFAULT, 'C', 'baz');
Similarly, the keyword DEFAULT can be used in
UPDATE commands.
@@ -361,7 +361,6 @@ INSERT INTO people (id, name, address) VALUE (DEFAULT, 'C',
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.
@@ -371,12 +370,12 @@ INSERT INTO people (id, name, address) VALUE (DEFAULT, 'C',
CREATE TABLE people (
...,
height_cm numeric,
- height_in numeric GENERATED ALWAYS AS (height_cm / 2.54) STORED
+ height_in numeric GENERATED ALWAYS AS (height_cm / 2.54)
);
- The keyword STORED must be specified to choose the
- stored kind of generated column. See for
- more details.
+ A generated column is by default of the virtual kind. Use the keywords
+ VIRTUAL or STORED to make the choice
+ explicit. See for more details.
@@ -420,6 +419,16 @@ CREATE TABLE people (
tableoid.
+
+
+ A virtual generated column cannot have a user-defined type, and the
+ generation expression of a virtual generated column must not reference
+ user-defined functions or types, that is, it can only use built-in
+ functions or types. This applies also indirectly, such as for functions
+ or types that underlie operators or casts. (This restriction does not
+ exist for stored generated columns.)
+
+
A generated column cannot have a column default or an identity definition.
@@ -442,12 +451,18 @@ CREATE TABLE people (
If a parent column is a generated column, its child column must also
- be a generated column; however, the child column can have a
- different generation expression. The generation expression that is
+ be a generated column of the same kind (stored or virtual); however,
+ the child column can have a different generation expression.
+
+
+
+ For stored generated columns, the generation expression that is
actually applied during insert or update of a row is the one
- associated with the table that the row is physically in.
- (This is unlike the behavior for column defaults: for those, the
- default value associated with the table named in the query applies.)
+ associated with the table that the row is physically in. (This is
+ unlike the behavior for column defaults: for those, the default value
+ associated with the table named in the query applies.) For virtual
+ generated columns, the generation expression of the table named in the
+ query applies when a table is read.
@@ -502,6 +517,26 @@ CREATE TABLE people (
particular role can read from a generated column but not from the
underlying base columns.
+
+
+ For virtual generated columns, this is only fully secure if the
+ generation expression uses only leakproof functions (see ), but this is not enforced by the system.
+
+
+
+
+ Privileges of functions used in generation expressions are checked when
+ the expression is actually executed, on write or read respectively, as
+ if the generation expression had been called directly from the query
+ using the generated column. The user of a generated column must have
+ permissions to call all functions used by the generation expression.
+ Functions in the generation expression are executed with the privileges
+ of the user executing the query or the function owner, depending on
+ whether the functions are defined as SECURITY INVOKER
+ or SECURITY DEFINER.
+
+
@@ -512,6 +547,17 @@ CREATE TABLE people (
generated columns in BEFORE triggers.
+
+
+ Generated columns are allowed to be replicated during logical replication
+ according to the CREATE PUBLICATION parameter
+
+ publish_generated_columns or by including them
+ in the column list of the CREATE PUBLICATION command.
+ This is currently only supported for stored generated columns.
+ See for details.
+
+
@@ -763,17 +809,38 @@ CREATE TABLE products (
price numeric
);
+ An explicit constraint name can also be specified, for example:
+
+CREATE TABLE products (
+ product_no integer NOT NULL,
+ name text CONSTRAINT products_name_not_null NOT NULL,
+ price numeric
+);
+
+
+
+
+ A not-null constraint is usually written as a column constraint. The
+ syntax for writing it as a table constraint is
+
+CREATE TABLE products (
+ product_no integer,
+ name text,
+ price numeric,
+ NOT NULL product_no,
+ NOT NULL name
+);
+
+ But this syntax is not standard and mainly intended for use by
+ pg_dump.
- A not-null constraint is always written as a column constraint. A
- not-null constraint is functionally equivalent to creating a check
+ A not-null constraint is functionally equivalent to creating a check
constraint CHECK (column_name
IS NOT NULL), but in
PostgreSQL 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.
+ not-null constraint is more efficient.
@@ -790,6 +857,10 @@ CREATE TABLE products (
order the constraints are checked.
+
+ However, a column can have at most one explicit not-null constraint.
+
+
The NOT NULL constraint has an inverse: the
NULL constraint. This does not mean that the
@@ -983,7 +1054,7 @@ CREATE TABLE example (
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
+ of unique constraints, which combined with not-null constraints 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
@@ -1199,16 +1270,32 @@ CREATE TABLE order_items (
- Restricting and cascading deletes are the two most common options.
- RESTRICT prevents deletion of a
- referenced row. NO ACTION 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
- NO ACTION allows the check to be deferred until
- later in the transaction, whereas RESTRICT does not.)
+ The default ON DELETE action is ON DELETE NO
+ ACTION; this does not need to be specified. This means that the
+ deletion in the referenced table is allowed to proceed. But the
+ foreign-key constraint is still required to be satisfied, so this
+ operation will usually result in an error. But checking of foreign-key
+ constraints can also be deferred to later in the transaction (not covered
+ in this chapter). In that case, the NO ACTION setting
+ would allow other commands to fix the situation before the
+ constraint is checked, for example by inserting another suitable row into
+ the referenced table or by deleting the now-dangling rows from the
+ referencing table.
+
+
+
+ RESTRICT is a stricter setting than NO
+ ACTION. It prevents deletion of a referenced row.
+ RESTRICT does not allow the check to be deferred until
+ later in the transaction.
+
+
+ CASCADE specifies that when a referenced row is deleted,
row(s) referencing it should be automatically deleted as well.
+
+
+
There are two other options:
SET NULL and SET DEFAULT.
These cause the referencing column(s) in the referencing row(s)
@@ -1278,6 +1365,15 @@ CREATE TABLE posts (
NULL and SET DEFAULT.
In this case, CASCADE means that the updated values of the
referenced column(s) should be copied into the referencing row(s).
+ There is also a noticeable difference between ON UPDATE NO
+ ACTION (the default) and ON UPDATE RESTRICT.
+ The former will allow the update to proceed and the foreign-key constraint
+ will be checked against the state after the update. The latter will
+ prevent the update to run even if the state after the update would still
+ satisfy the constraint. This prevents updating a referenced row to a
+ value that is distinct but compares as equal (for example, a character
+ string with a different case variant, if a character string type with a
+ case-insensitive collation is used).
@@ -1564,17 +1660,15 @@ ALTER TABLE products ADD COLUMN description text;
- From PostgreSQL 11, adding a column with
- a constant default value no longer means that each row of the table
- needs to be updated when the ALTER TABLE statement
+ Adding a column with a constant default value does not require each row of
+ the table to be updated when the ALTER TABLE 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 ALTER TABLE very fast even on large tables.
- However, if the default value is volatile (e.g.,
- clock_timestamp())
+ If the default value is volatile (e.g., clock_timestamp())
each row will need to be updated with the value calculated at the time
ALTER TABLE is executed. To avoid a potentially
lengthy update operation, particularly if you intend to fill the column
@@ -1643,11 +1737,16 @@ ALTER TABLE products ADD CHECK (name <> '');
ALTER TABLE products ADD CONSTRAINT some_name UNIQUE (product_no);
ALTER TABLE products ADD FOREIGN KEY (product_group_id) REFERENCES product_groups;
- To add a not-null constraint, which cannot be written as a table
- constraint, use this syntax:
+
+
+
+ To add a not-null constraint, which is normally not written as a table
+ constraint, this special syntax is available:
ALTER TABLE products ALTER COLUMN product_no SET NOT NULL;
+ This command silently does nothing if the column already has a
+ not-null constraint.
@@ -1675,9 +1774,6 @@ ALTER TABLE products ALTER COLUMN product_no SET NOT NULL;
ALTER TABLE products DROP CONSTRAINT some_name;
- (If you are dealing with a generated constraint name like $2,
- don't forget that you'll need to double-quote it to make it a valid
- identifier.)
@@ -1688,12 +1784,15 @@ ALTER TABLE products DROP CONSTRAINT some_name;
- This works the same for all constraint types except not-null
- constraints. To drop a not-null constraint use:
+ Simplified syntax is available to drop a not-null constraint:
ALTER TABLE products ALTER COLUMN product_no DROP NOT NULL;
- (Recall that not-null constraints do not have names.)
+ This mirrors the SET NOT NULL syntax for adding a
+ not-null constraint. This command will silently do nothing if the column
+ does not have a not-null constraint. (Recall that a column can have at
+ most one not-null constraint, so it is never ambiguous which constraint
+ this command acts on.)
@@ -1813,7 +1912,7 @@ ALTER TABLE products RENAME TO items;
- ACL
+ ACL
@@ -2134,8 +2233,9 @@ REVOKE ALL ON accounts FROM PUBLIC;
Allows VACUUM, ANALYZE,
CLUSTER, REFRESH MATERIALIZED VIEW,
- REINDEX, and LOCK TABLE on a
- relation.
+ REINDEX, LOCK TABLE,
+ and database object statistics manipulation functions
+ (see ) on a relation.
@@ -2177,13 +2277,14 @@ REVOKE ALL ON accounts FROM PUBLIC;
shows the one-letter
abbreviations that are used for these privilege types in
- ACL (Access Control List) values.
+ ACL values.
You will see these letters in the output of the
- commands listed below, or when looking at ACL columns of system catalogs.
+ commands listed below, or when looking at ACL columns
+ of system catalogs.
- ACL Privilege Abbreviations
+ <acronym>ACL</acronym> Privilege Abbreviations
@@ -2585,7 +2686,8 @@ GRANT SELECT (col1), UPDATE (col1) ON mytable TO miriam_rw;
When multiple policies apply to a given query, they are combined using
either OR (for permissive policies, which are the
default) or using AND (for restrictive policies).
- This is similar to the rule that a given role has the privileges
+ The OR behavior 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.
@@ -3771,12 +3873,14 @@ VALUES ('Albany', NULL, NULL, 'NY');
not INSERT or ALTER TABLE ...
RENAME) typically default to including child tables and
support the ONLY notation to exclude them.
- Commands that do database maintenance and tuning
- (e.g., REINDEX, VACUUM)
- 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 ().
+ The majority of commands that do database maintenance and tuning
+ (e.g., REINDEX) only work on individual, physical
+ tables and do not support recursing over inheritance hierarchies.
+ However, both VACUUM and ANALYZE
+ commands default to including child tables and the ONLY
+ notation is supported to allow them to be excluded. The respective
+ behavior of each individual command is documented in its reference page
+ ().
@@ -4348,44 +4452,6 @@ ALTER INDEX measurement_city_id_logdate_key
...
-
-
- There is also an option for merging multiple table partitions into
- a single partition using the
- ALTER TABLE ... MERGE PARTITIONS.
- This feature simplifies the management of partitioned tables by allowing
- users to combine partitions that are no longer needed as
- separate entities. It's important to note that this operation is not
- supported for hash-partitioned tables and acquires an
- ACCESS EXCLUSIVE lock, which could impact high-load
- systems due to the lock's restrictive nature. For example, we can
- merge three monthly partitions into one quarter partition:
-
-ALTER TABLE measurement
- MERGE PARTITIONS (measurement_y2006m01,
- measurement_y2006m02,
- measurement_y2006m03) INTO measurement_y2006q1;
-
-
-
-
- Similarly to merging multiple table partitions, there is an option for
- splitting a single partition into multiple using the
- ALTER TABLE ... SPLIT PARTITION.
- This feature could come in handy when one partition grows too big
- and needs to be split into multiple. It's important to note that
- this operation is not supported for hash-partitioned tables and acquires
- an ACCESS EXCLUSIVE lock, which could impact high-load
- systems due to the lock's restrictive nature. For example, we can split
- the quarter partition back to monthly partitions:
-
-ALTER TABLE measurement SPLIT PARTITION measurement_y2006q1 INTO
- (PARTITION measurement_y2006m01 FOR VALUES FROM ('2006-01-01') TO ('2006-02-01'),
- PARTITION measurement_y2006m02 FOR VALUES FROM ('2006-02-01') TO ('2006-03-01'),
- PARTITION measurement_y2006m03 FOR VALUES FROM ('2006-03-01') TO ('2006-04-01'));
-
-
-
@@ -4472,12 +4538,10 @@ ALTER TABLE measurement SPLIT PARTITION measurement_y2006q1 INTO
Both CHECK and NOT NULL
constraints of a partitioned table are always inherited by all its
- partitions. CHECK constraints that are marked
- NO INHERIT are not allowed to be created on
- partitioned tables.
- You cannot drop a NOT NULL constraint on a
- partition's column if the same constraint is present in the parent
- table.
+ partitions; it is not allowed to create NO INHERIT
+ constraints of those types.
+ You cannot drop a constraint of those types if the same constraint
+ is present in the parent table.
@@ -4885,11 +4949,12 @@ ALTER TABLE measurement_y2008m02 INHERIT measurement;
- If you are using manual VACUUM or
- ANALYZE commands, don't forget that
- you need to run them on each child table individually. A command like:
+ Manual VACUUM and ANALYZE
+ commands will automatically process all inheritance child tables. If
+ this is undesirable, you can use the ONLY keyword.
+ A command like:
-ANALYZE measurement;
+ANALYZE ONLY measurement;
will only process the root table.
@@ -5018,7 +5083,13 @@ EXPLAIN SELECT count(*) FROM measurement WHERE logdate >= DATE '2008-01-01';
It is possible to determine the number of partitions which were
removed during this phase by observing the
Subplans Removed property in the
- EXPLAIN output.
+ EXPLAIN output. The query planner obtains locks for
+ all partitions which are part of the plan. However, when the executor
+ uses a cached plan, locks are only obtained on the partitions which
+ remain after partition pruning done during the initialization phase of
+ execution, i.e., the ones shown in the EXPLAIN
+ output and not the ones referred to by the
+ Subplans Removed property.
diff --git a/doc/src/sgml/dml.sgml b/doc/src/sgml/dml.sgml
index 3d95bdb94e79d..458aee788b7fb 100644
--- a/doc/src/sgml/dml.sgml
+++ b/doc/src/sgml/dml.sgml
@@ -308,7 +308,8 @@ DELETE FROM products;
- In an INSERT, the data available to RETURNING is
+ In an INSERT, the default data available to
+ RETURNING is
the row as it was inserted. This is not so useful in trivial inserts,
since it would just repeat the data provided by the client. But it can
be very handy when relying on computed default values. For example,
@@ -325,7 +326,8 @@ INSERT INTO users (firstname, lastname) VALUES ('Joe', 'Cool') RETURNING id;
- In an UPDATE, the data available to RETURNING is
+ In an UPDATE, the default data available to
+ RETURNING is
the new content of the modified row. For example:
UPDATE products SET price = price * 1.10
@@ -335,7 +337,8 @@ UPDATE products SET price = price * 1.10
- In a DELETE, the data available to RETURNING is
+ In a DELETE, the default data available to
+ RETURNING is
the content of the deleted row. For example:
DELETE FROM products
@@ -345,7 +348,8 @@ DELETE FROM products
- In a MERGE, the data available to RETURNING is
+ In a MERGE, the default data available to
+ RETURNING is
the content of the source row plus the content of the inserted, updated, or
deleted target row. Since it is quite common for the source and target to
have many of the same columns, specifying RETURNING *
@@ -359,6 +363,35 @@ MERGE INTO products p USING new_products n ON p.product_no = n.product_no
+
+ In each of these commands, it is also possible to explicitly return the
+ old and new content of the modified row. For example:
+
+UPDATE products SET price = price * 1.10
+ WHERE price <= 99.99
+ RETURNING name, old.price AS old_price, new.price AS new_price,
+ new.price - old.price AS price_change;
+
+ In this example, writing new.price is the same as
+ just writing price, but it makes the meaning clearer.
+
+
+
+ This syntax for returning old and new values is available in
+ INSERT, UPDATE,
+ DELETE, and MERGE commands, but
+ typically old values will be NULL for an
+ INSERT, and new values will be NULL
+ for a DELETE. However, there are situations where it
+ can still be useful for those commands. For example, in an
+ INSERT with an
+ ON CONFLICT DO UPDATE
+ clause, the old values will be non-NULL for conflicting
+ rows. Similarly, if a DELETE is turned into an
+ UPDATE by a rewrite rule,
+ the new values may be non-NULL.
+
+
If there are triggers () on the target table,
the data available to RETURNING is the row as modified by
diff --git a/doc/src/sgml/docguide.sgml b/doc/src/sgml/docguide.sgml
index db4bcce56eac6..7b61b4841aa03 100644
--- a/doc/src/sgml/docguide.sgml
+++ b/doc/src/sgml/docguide.sgml
@@ -60,9 +60,7 @@
maintained by the
OASIS group. The
official DocBook site has good introductory and reference documentation and
- a complete O'Reilly book for your online reading pleasure. The
-
- NewbieDoc Docbook Guide is very helpful for beginners.
+ a complete O'Reilly book for your online reading pleasure.
The
FreeBSD Documentation Project also uses DocBook and has some good
information, including a number of style guidelines that might be
diff --git a/doc/src/sgml/event-trigger.sgml b/doc/src/sgml/event-trigger.sgml
index 8e009cca050f2..1bd9abb667650 100644
--- a/doc/src/sgml/event-trigger.sgml
+++ b/doc/src/sgml/event-trigger.sgml
@@ -26,7 +26,7 @@
An event trigger fires whenever the event with which it is associated
- occurs in the database in which it is defined. Currently, the only
+ occurs in the database in which it is defined. Currently, the
supported events are
login,
ddl_command_start,
@@ -36,6 +36,9 @@
Support for additional events may be added in future releases.
+
+ login
+
The login event occurs when an authenticated user logs
into the system. Any bug in a trigger procedure for this event may
@@ -54,25 +57,62 @@
the in-progress login trigger.
+
+ For an example on how to use the login event trigger,
+ see .
+
+
+
+
+ ddl_command_start
+
The ddl_command_start event occurs just before the
- execution of a CREATE, ALTER, DROP,
- SECURITY LABEL,
- COMMENT, GRANT or REVOKE
- 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.
- ddl_command_start also occurs just before the execution of a
- SELECT INTO command, since this is equivalent to
- CREATE TABLE AS.
+ execution of a DDL command. DDL commands in this context are:
+
+ CREATE
+ ALTER
+ DROP
+ COMMENT
+ GRANT
+ IMPORT FOREIGN SCHEMA
+ REINDEX
+ REFRESH MATERIALIZED VIEW
+ REVOKE
+ SECURITY LABEL
+
+ ddl_command_start also occurs just before the
+ execution of a SELECT INTO command, since this is
+ equivalent to CREATE TABLE AS.
+
+ As an exception, this event does not occur for DDL commands targeting
+ shared objects:
+
+ databases
+ roles (role definitions and role memberships)
+ tablespaces
+ parameter privileges
+ ALTER SYSTEM
+
+ This event also does not occur for commands targeting event triggers
+ themselves.
+
+
+
+ No check whether the affected object exists or doesn't exist is performed
+ before the event trigger fires.
+
+
+
+
+ ddl_command_end
+
The ddl_command_end event occurs just after the execution of
- this same set of commands. To obtain more details on the DDL
+ the same set of commands as ddl_command_start. To
+ obtain more details on the DDL
operations that took place, use the set-returning function
pg_event_trigger_ddl_commands() from the
ddl_command_end event trigger code (see
@@ -80,17 +120,31 @@
after the actions have taken place (but before the transaction commits),
and thus the system catalogs can be read as already changed.
+
+
+
+ sql_drop
The sql_drop event occurs just before the
ddl_command_end event trigger for any operation that drops
- database objects. To list the objects that have been dropped, use the
+ database objects. Note that besides the obvious DROP
+ commands, some ALTER commands can also trigger an
+ sql_drop event.
+
+
+
+ To list the objects that have been dropped, use the
set-returning function pg_event_trigger_dropped_objects() from the
sql_drop event trigger code (see
). Note that
the trigger is executed after the objects have been deleted from the
system catalogs, so it's not possible to look them up anymore.
+
+
+
+ table_rewrite
The table_rewrite event occurs just before a table is
@@ -99,7 +153,16 @@
control statements are available to rewrite a table,
like CLUSTER and VACUUM,
the table_rewrite event is not triggered by them.
+ To find the OID of the table that was rewritten, use the function
+ pg_event_trigger_table_rewrite_oid(), to discover the
+ reason(s) for the rewrite, use the function
+ pg_event_trigger_table_rewrite_reason() (see ).
+
+
+
+ Event Triggers in Aborted Transactions
Event triggers (like other functions) cannot be executed in an aborted
@@ -112,11 +175,10 @@
back, just as they would be in any other case where the containing
transaction aborts.
+
-
- For a complete list of commands supported by the event trigger mechanism,
- see .
-
+
+ Creating Event Triggers
Event triggers are created using the command .
@@ -138,935 +200,7 @@
to intercept. A common use of such triggers is to restrict the range of
DDL operations which users may perform.
-
-
-
- Event Trigger Firing Matrix
-
-
- lists all commands
- for which event triggers are supported.
-
-
-
- Event Trigger Support by Command Tag
-
-
-
-
-
-
-
-
-
- Command Tag
- ddl_&zwsp;command_&zwsp;start
- ddl_&zwsp;command_&zwsp;end
- sql_&zwsp;drop
- table_&zwsp;rewrite
- Notes
-
-
-
-
- ALTER AGGREGATE
- X
- X
- -
- -
-
-
-
- ALTER COLLATION
- X
- X
- -
- -
-
-
-
- ALTER CONVERSION
- X
- X
- -
- -
-
-
-
- ALTER DOMAIN
- X
- X
- -
- -
-
-
-
- ALTER DEFAULT PRIVILEGES
- X
- X
- -
- -
-
-
-
- ALTER EXTENSION
- X
- X
- -
- -
-
-
-
- ALTER FOREIGN DATA WRAPPER
- X
- X
- -
- -
-
-
-
- ALTER FOREIGN TABLE
- X
- X
- X
- -
-
-
-
- ALTER FUNCTION
- X
- X
- -
- -
-
-
-
- ALTER LANGUAGE
- X
- X
- -
- -
-
-
-
- ALTER LARGE OBJECT
- X
- X
- -
- -
-
-
-
- ALTER MATERIALIZED VIEW
- X
- X
- -
- X
-
-
-
- ALTER OPERATOR
- X
- X
- -
- -
-
-
-
- ALTER OPERATOR CLASS
- X
- X
- -
- -
-
-
-
- ALTER OPERATOR FAMILY
- X
- X
- -
- -
-
-
-
- ALTER POLICY
- X
- X
- -
- -
-
-
-
- ALTER PROCEDURE
- X
- X
- -
- -
-
-
-
- ALTER PUBLICATION
- X
- X
- -
- -
-
-
-
- ALTER ROUTINE
- X
- X
- -
- -
-
-
-
- ALTER SCHEMA
- X
- X
- -
- -
-
-
-
- ALTER SEQUENCE
- X
- X
- -
- -
-
-
-
- ALTER SERVER
- X
- X
- -
- -
-
-
-
- ALTER STATISTICS
- X
- X
- -
- -
-
-
-
- ALTER SUBSCRIPTION
- X
- X
- -
- -
-
-
-
- ALTER TABLE
- X
- X
- X
- X
-
-
-
- ALTER TEXT SEARCH CONFIGURATION
- X
- X
- -
- -
-
-
-
- ALTER TEXT SEARCH DICTIONARY
- X
- X
- -
- -
-
-
-
- ALTER TEXT SEARCH PARSER
- X
- X
- -
- -
-
-
-
- ALTER TEXT SEARCH TEMPLATE
- X
- X
- -
- -
-
-
-
- ALTER TRIGGER
- X
- X
- -
- -
-
-
-
- ALTER TYPE
- X
- X
- -
- X
-
-
-
- ALTER USER MAPPING
- X
- X
- -
- -
-
-
-
- ALTER VIEW
- X
- X
- -
- -
-
-
-
- COMMENT
- X
- X
- -
- -
- Only for local objects
-
-
- CREATE ACCESS METHOD
- X
- X
- -
- -
-
-
-
- CREATE AGGREGATE
- X
- X
- -
- -
-
-
-
- CREATE CAST
- X
- X
- -
- -
-
-
-
- CREATE COLLATION
- X
- X
- -
- -
-
-
-
- CREATE CONVERSION
- X
- X
- -
- -
-
-
-
- CREATE DOMAIN
- X
- X
- -
- -
-
-
-
- CREATE EXTENSION
- X
- X
- -
- -
-
-
-
- CREATE FOREIGN DATA WRAPPER
- X
- X
- -
- -
-
-
-
- CREATE FOREIGN TABLE
- X
- X
- -
- -
-
-
-
- CREATE FUNCTION
- X
- X
- -
- -
-
-
-
- CREATE INDEX
- X
- X
- -
- -
-
-
-
- CREATE LANGUAGE
- X
- X
- -
- -
-
-
-
- CREATE MATERIALIZED VIEW
- X
- X
- -
- -
-
-
-
- CREATE OPERATOR
- X
- X
- -
- -
-
-
-
- CREATE OPERATOR CLASS
- X
- X
- -
- -
-
-
-
- CREATE OPERATOR FAMILY
- X
- X
- -
- -
-
-
-
- CREATE POLICY
- X
- X
- -
- -
-
-
-
- CREATE PROCEDURE
- X
- X
- -
- -
-
-
-
- CREATE PUBLICATION
- X
- X
- -
- -
-
-
-
- CREATE RULE
- X
- X
- -
- -
-
-
-
- CREATE SCHEMA
- X
- X
- -
- -
-
-
-
- CREATE SEQUENCE
- X
- X
- -
- -
-
-
-
- CREATE SERVER
- X
- X
- -
- -
-
-
-
- CREATE STATISTICS
- X
- X
- -
- -
-
-
-
- CREATE SUBSCRIPTION
- X
- X
- -
- -
-
-
-
- CREATE TABLE
- X
- X
- -
- -
-
-
-
- CREATE TABLE AS
- X
- X
- -
- -
-
-
-
- CREATE TEXT SEARCH CONFIGURATION
- X
- X
- -
- -
-
-
-
- CREATE TEXT SEARCH DICTIONARY
- X
- X
- -
- -
-
-
-
- CREATE TEXT SEARCH PARSER
- X
- X
- -
- -
-
-
-
- CREATE TEXT SEARCH TEMPLATE
- X
- X
- -
- -
-
-
-
- CREATE TRIGGER
- X
- X
- -
- -
-
-
-
- CREATE TYPE
- X
- X
- -
- -
-
-
-
- CREATE USER MAPPING
- X
- X
- -
- -
-
-
-
- CREATE VIEW
- X
- X
- -
- -
-
-
-
- DROP ACCESS METHOD
- X
- X
- X
- -
-
-
-
- DROP AGGREGATE
- X
- X
- X
- -
-
-
-
- DROP CAST
- X
- X
- X
- -
-
-
-
- DROP COLLATION
- X
- X
- X
- -
-
-
-
- DROP CONVERSION
- X
- X
- X
- -
-
-
-
- DROP DOMAIN
- X
- X
- X
- -
-
-
-
- DROP EXTENSION
- X
- X
- X
- -
-
-
-
- DROP FOREIGN DATA WRAPPER
- X
- X
- X
- -
-
-
-
- DROP FOREIGN TABLE
- X
- X
- X
- -
-
-
-
- DROP FUNCTION
- X
- X
- X
- -
-
-
-
- DROP INDEX
- X
- X
- X
- -
-
-
-
- DROP LANGUAGE
- X
- X
- X
- -
-
-
-
- DROP MATERIALIZED VIEW
- X
- X
- X
- -
-
-
-
- DROP OPERATOR
- X
- X
- X
- -
-
-
-
- DROP OPERATOR CLASS
- X
- X
- X
- -
-
-
-
- DROP OPERATOR FAMILY
- X
- X
- X
- -
-
-
-
- DROP OWNED
- X
- X
- X
- -
-
-
-
- DROP POLICY
- X
- X
- X
- -
-
-
-
- DROP PROCEDURE
- X
- X
- X
- -
-
-
-
- DROP PUBLICATION
- X
- X
- X
- -
-
-
-
- DROP ROUTINE
- X
- X
- X
- -
-
-
-
- DROP RULE
- X
- X
- X
- -
-
-
-
- DROP SCHEMA
- X
- X
- X
- -
-
-
-
- DROP SEQUENCE
- X
- X
- X
- -
-
-
-
- DROP SERVER
- X
- X
- X
- -
-
-
-
- DROP STATISTICS
- X
- X
- X
- -
-
-
-
- DROP SUBSCRIPTION
- X
- X
- X
- -
-
-
-
- DROP TABLE
- X
- X
- X
- -
-
-
-
- DROP TEXT SEARCH CONFIGURATION
- X
- X
- X
- -
-
-
-
- DROP TEXT SEARCH DICTIONARY
- X
- X
- X
- -
-
-
-
- DROP TEXT SEARCH PARSER
- X
- X
- X
- -
-
-
-
- DROP TEXT SEARCH TEMPLATE
- X
- X
- X
- -
-
-
-
- DROP TRIGGER
- X
- X
- X
- -
-
-
-
- DROP TYPE
- X
- X
- X
- -
-
-
-
- DROP USER MAPPING
- X
- X
- X
- -
-
-
-
- DROP VIEW
- X
- X
- X
- -
-
-
-
- GRANT
- X
- X
- -
- -
- Only for local objects
-
-
- IMPORT FOREIGN SCHEMA
- X
- X
- -
- -
-
-
-
- REFRESH MATERIALIZED VIEW
- X
- X
- -
- -
-
-
-
- REINDEX
- X
- X
- -
- -
-
-
-
- REVOKE
- X
- X
- -
- -
- Only for local objects
-
-
- SECURITY LABEL
- X
- X
- -
- -
- Only for local objects
-
-
- SELECT INTO
- X
- X
- -
- -
-
-
-
-
-
+
diff --git a/doc/src/sgml/extend.sgml b/doc/src/sgml/extend.sgml
index 218940ee5ce19..63c5ec6d1eb99 100644
--- a/doc/src/sgml/extend.sgml
+++ b/doc/src/sgml/extend.sgml
@@ -649,6 +649,11 @@ RETURNS anycompatible AS ...
control file can specify a different directory for the script file(s).
+
+ Additional locations for extension control files can be configured using
+ the parameter .
+
+
The file format for an extension control file is the same as for the
postgresql.conf file, namely a list of
@@ -669,9 +674,9 @@ RETURNS anycompatible AS ...
The directory containing the extension's SQL script
file(s). Unless an absolute path is given, the name is relative to
- the installation's SHAREDIR directory. The
- default behavior is equivalent to specifying
- directory = 'extension'.
+ the directory where the control file was found. By default,
+ the script files are looked for in the same directory where the
+ control file was found.
@@ -719,8 +724,8 @@ RETURNS anycompatible AS ...
The value of this parameter will be substituted for each occurrence
of MODULE_PATHNAME in the script file(s). If it is not
- set, no substitution is made. Typically, this is set to
- $libdir/shared_library_name and
+ set, no substitution is made. Typically, this is set to just
+ shared_library_name and
then MODULE_PATHNAME is used in CREATE
FUNCTION commands for C-language functions, so that the script
files do not need to hard-wire the name of the shared library.
@@ -1339,8 +1344,8 @@ SELECT * FROM pg_extension_update_paths('extension_namesearch_path; do not
trust the path provided by CREATE/ALTER EXTENSION
to be secure. Best practice is to temporarily
- set search_path to 'pg_catalog,
- pg_temp' and insert references to the extension's
+ set search_path to pg_catalog,
+ pg_temp 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 contrib modules in
@@ -1348,15 +1353,11 @@ SELECT * FROM pg_extension_update_paths('extension_name
- 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
- search_path. 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 pg_catalog.
+ Secure cross-extension references typically require schema-qualification
+ of the names of the other extension's objects, using the
+ @extschema:name@
+ syntax, in addition to careful matching of argument types for functions
+ and operators.
@@ -1810,6 +1811,36 @@ include $(PGXS)
or on the make command line.
+
+ You can select a separate directory prefix in which to install your
+ extension's files, by setting the make variable
+ prefix when executing make install
+ like so:
+
+make install prefix=/usr/local/postgresql
+
+ This will install the extension control and SQL files into
+ /usr/local/postgresql/share and the shared modules into
+ /usr/local/postgresql/lib. If the prefix does not
+ include the strings postgres or
+ pgsql, such as
+
+make install prefix=/usr/local/extras
+
+ then postgresql will be appended to the directory
+ names, installing the control and SQL files into
+ /usr/local/extras/share/postgresql/extension and the
+ shared modules into /usr/local/extras/lib/postgresql.
+ Either way, you'll need to set and to enable the
+ PostgreSQL server to find the files:
+
+extension_control_path = '/usr/local/extras/share/postgresql:$system'
+dynamic_library_path = '/usr/local/extras/lib/postgresql:$libdir'
+
+
+
You can also run make in a directory outside the source
tree of your extension, if you want to keep the build directory separate.
diff --git a/doc/src/sgml/file-fdw.sgml b/doc/src/sgml/file-fdw.sgml
index b7f64930f06f7..882d9a76d2169 100644
--- a/doc/src/sgml/file-fdw.sgml
+++ b/doc/src/sgml/file-fdw.sgml
@@ -126,6 +126,41 @@
+
+ on_error
+
+
+
+ Specifies how to behave when encountering an error converting a column's
+ input value into its data type,
+ the same as COPY's ON_ERROR option.
+
+
+
+
+
+ reject_limit
+
+
+
+ Specifies the maximum number of errors tolerated while converting a column's
+ input value to its data type, the same as COPY's
+ REJECT_LIMIT option.
+
+
+
+
+
+ log_verbosity
+
+
+
+ Specifies the amount of messages emitted by file_fdw,
+ the same as COPY's LOG_VERBOSITY option.
+
+
+
+
@@ -280,7 +315,7 @@ OPTIONS ( filename 'log/pglog.csv', format 'csv' );
- Create a Foreign Table with an option on a column
+ Create a Foreign Table with an Option on a Column
To set the force_null option for a column, use the
OPTIONS keyword.
diff --git a/doc/src/sgml/filelist.sgml b/doc/src/sgml/filelist.sgml
index 38ec362d8f469..ac66fcbdb5727 100644
--- a/doc/src/sgml/filelist.sgml
+++ b/doc/src/sgml/filelist.sgml
@@ -17,7 +17,10 @@
-
+
+
+%allfiles_func;
+
@@ -111,6 +114,7 @@
+
@@ -143,6 +147,8 @@
+
+
@@ -177,7 +183,7 @@
-
+
diff --git a/doc/src/sgml/func.sgml b/doc/src/sgml/func.sgml
deleted file mode 100644
index 17c44bc338464..0000000000000
--- a/doc/src/sgml/func.sgml
+++ /dev/null
@@ -1,31128 +0,0 @@
-
-
-
- Functions and Operators
-
-
- function
-
-
-
- operator
-
-
-
- PostgreSQL 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
- . The
- psql commands \df and
- \do can be used to list all
- available functions and operators, respectively.
-
-
-
- The notation used throughout this chapter to describe the argument and
- result data types of a function or operator is like this:
-
-repeat ( text, integer ) text
-
- which says that the function repeat 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:
-
-repeat('Pg', 4) PgPgPgPg
-
-
-
-
- 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
- SQL standard. Some of this extended functionality
- is present in other SQL database management
- systems, and in many cases this functionality is compatible and
- consistent between the various implementations.
-
-
-
-
- Logical Operators
-
-
- operator
- logical
-
-
-
- Boolean
- operators
- operators, logical
-
-
-
- The usual logical operators are available:
-
-
- AND (operator)
-
-
-
- OR (operator)
-
-
-
- NOT (operator)
-
-
-
- conjunction
-
-
-
- disjunction
-
-
-
- negation
-
-
-
-booleanANDbooleanboolean
-booleanORbooleanboolean
-NOTbooleanboolean
-
-
- SQL uses a three-valued logic system with true,
- false, and null, which represents unknown.
- Observe the following truth tables:
-
-
-
-
-
- a
- b
- a AND b
- a OR b
-
-
-
-
-
- TRUE
- TRUE
- TRUE
- TRUE
-
-
-
- TRUE
- FALSE
- FALSE
- TRUE
-
-
-
- TRUE
- NULL
- NULL
- TRUE
-
-
-
- FALSE
- FALSE
- FALSE
- FALSE
-
-
-
- FALSE
- NULL
- FALSE
- NULL
-
-
-
- NULL
- NULL
- NULL
- NULL
-
-
-
-
-
-
-
-
-
- a
- NOT a
-
-
-
-
-
- TRUE
- FALSE
-
-
-
- FALSE
- TRUE
-
-
-
- NULL
- NULL
-
-
-
-
-
-
-
- The operators AND and OR 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 for more information about the
- order of evaluation of subexpressions.)
-
-
-
-
- Comparison Functions and Operators
-
-
- comparison
- operators
-
-
-
- The usual comparison operators are available, as shown in .
-
-
-
- Comparison Operators
-
-
-
- Operator
- Description
-
-
-
-
-
-
- datatype<datatype
- boolean
-
- Less than
-
-
-
-
- datatype>datatype
- boolean
-
- Greater than
-
-
-
-
- datatype<=datatype
- boolean
-
- Less than or equal to
-
-
-
-
- datatype>=datatype
- boolean
-
- Greater than or equal to
-
-
-
-
- datatype=datatype
- boolean
-
- Equal
-
-
-
-
- datatype<>datatype
- boolean
-
- Not equal
-
-
-
-
- datatype!=datatype
- boolean
-
- Not equal
-
-
-
-
-
-
-
- <> is the standard SQL notation for not
- equal. != is an alias, which is converted
- to <> at a very early stage of parsing.
- Hence, it is not possible to implement !=
- and <> operators that do different things.
-
-
-
-
- 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.
-
-
-
- It is usually possible to compare values of related data
- types as well; for example integer>
- bigint will work. Some cases of this sort are implemented
- directly by cross-type 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.
-
-
-
- As shown above, all comparison operators are binary operators that
- return values of type boolean. Thus, expressions like
- 1 < 2 < 3 are not valid (because there is
- no < operator to compare a Boolean value with
- 3). Use the BETWEEN predicates
- shown below to perform range tests.
-
-
-
- There are also some comparison predicates, as shown in . These behave much like
- operators, but have special syntax mandated by the SQL standard.
-
-
-
- Comparison Predicates
-
-
-
-
- Predicate
-
-
- Description
-
-
- Example(s)
-
-
-
-
-
-
-
- datatypeBETWEENdatatypeANDdatatype
- boolean
-
-
- Between (inclusive of the range endpoints).
-
-
- 2 BETWEEN 1 AND 3
- t
-
-
- 2 BETWEEN 3 AND 1
- f
-
-
-
-
-
- datatypeNOT BETWEENdatatypeANDdatatype
- boolean
-
-
- Not between (the negation of BETWEEN).
-
-
- 2 NOT BETWEEN 1 AND 3
- f
-
-
-
-
-
- datatypeBETWEEN SYMMETRICdatatypeANDdatatype
- boolean
-
-
- Between, after sorting the two endpoint values.
-
-
- 2 BETWEEN SYMMETRIC 3 AND 1
- t
-
-
-
-
-
- datatypeNOT BETWEEN SYMMETRICdatatypeANDdatatype
- boolean
-
-
- Not between, after sorting the two endpoint values.
-
-
- 2 NOT BETWEEN SYMMETRIC 3 AND 1
- f
-
-
-
-
-
- datatypeIS DISTINCT FROMdatatype
- boolean
-
-
- Not equal, treating null as a comparable value.
-
-
- 1 IS DISTINCT FROM NULL
- t (rather than NULL)
-
-
- NULL IS DISTINCT FROM NULL
- f (rather than NULL)
-
-
-
-
-
- datatypeIS NOT DISTINCT FROMdatatype
- boolean
-
-
- Equal, treating null as a comparable value.
-
-
- 1 IS NOT DISTINCT FROM NULL
- f (rather than NULL)
-
-
- NULL IS NOT DISTINCT FROM NULL
- t (rather than NULL)
-
-
-
-
-
- datatypeIS NULL
- boolean
-
-
- Test whether value is null.
-
-
- 1.5 IS NULL
- f
-
-
-
-
-
- datatypeIS NOT NULL
- boolean
-
-
- Test whether value is not null.
-
-
- 'null' IS NOT NULL
- t
-
-
-
-
-
- datatypeISNULL
- boolean
-
-
- Test whether value is null (nonstandard syntax).
-
-
-
-
-
- datatypeNOTNULL
- boolean
-
-
- Test whether value is not null (nonstandard syntax).
-
-
-
-
-
- booleanIS TRUE
- boolean
-
-
- Test whether boolean expression yields true.
-
-
- true IS TRUE
- t
-
-
- NULL::boolean IS TRUE
- f (rather than NULL)
-
-
-
-
-
- booleanIS NOT TRUE
- boolean
-
-
- Test whether boolean expression yields false or unknown.
-
-
- true IS NOT TRUE
- f
-
-
- NULL::boolean IS NOT TRUE
- t (rather than NULL)
-
-
-
-
-
- booleanIS FALSE
- boolean
-
-
- Test whether boolean expression yields false.
-
-
- true IS FALSE
- f
-
-
- NULL::boolean IS FALSE
- f (rather than NULL)
-
-
-
-
-
- booleanIS NOT FALSE
- boolean
-
-
- Test whether boolean expression yields true or unknown.
-
-
- true IS NOT FALSE
- t
-
-
- NULL::boolean IS NOT FALSE
- t (rather than NULL)
-
-
-
-
-
- booleanIS UNKNOWN
- boolean
-
-
- Test whether boolean expression yields unknown.
-
-
- true IS UNKNOWN
- f
-
-
- NULL::boolean IS UNKNOWN
- t (rather than NULL)
-
-
-
-
-
- booleanIS NOT UNKNOWN
- boolean
-
-
- Test whether boolean expression yields true or false.
-
-
- true IS NOT UNKNOWN
- t
-
-
- NULL::boolean IS NOT UNKNOWN
- f (rather than NULL)
-
-
-
-
-
-
-
-
- BETWEEN
-
-
- BETWEEN SYMMETRIC
-
- The BETWEEN predicate simplifies range tests:
-
-a BETWEEN x AND y
-
- is equivalent to
-
-a >= x AND a <= y
-
- Notice that BETWEEN treats the endpoint values as included
- in the range.
- BETWEEN SYMMETRIC is like BETWEEN
- except there is no requirement that the argument to the left of
- AND 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.
-
-
-
- The various variants of BETWEEN are implemented in
- terms of the ordinary comparison operators, and therefore will work for
- any data type(s) that can be compared.
-
-
-
-
- The use of AND in the BETWEEN
- syntax creates an ambiguity with the use of AND as a
- logical operator. To resolve this, only a limited set of expression
- types are allowed as the second argument of a BETWEEN
- clause. If you need to write a more complex sub-expression
- in BETWEEN, write parentheses around the
- sub-expression.
-
-
-
-
-
- IS DISTINCT FROM
-
-
- IS NOT DISTINCT FROM
-
- Ordinary comparison operators yield null (signifying unknown),
- not true or false, when either input is null. For example,
- 7 = NULL yields null, as does 7 <> NULL. When
- this behavior is not suitable, use the
- IS NOT DISTINCT FROM predicates:
-
-a IS DISTINCT FROM b
-a IS NOT DISTINCT FROM b
-
- For non-null inputs, IS DISTINCT FROM is
- the same as the <> operator. However, if both
- inputs are null it returns false, and if only one input is
- null it returns true. Similarly, IS NOT DISTINCT
- FROM is identical to = 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 unknown.
-
-
-
-
- IS NULL
-
-
- IS NOT NULL
-
-
- ISNULL
-
-
- NOTNULL
-
- To check whether a value is or is not null, use the predicates:
-
-expression IS NULL
-expression IS NOT NULL
-
- or the equivalent, but nonstandard, predicates:
-
-expression ISNULL
-expression NOTNULL
-
- null valuecomparing
-
-
-
- Do not write
- expression = NULL
- because NULL is not equal to
- NULL. (The null value represents an unknown value,
- and it is not known whether two unknown values are equal.)
-
-
-
-
- Some applications might expect that
- expression = NULL
- returns true if expression evaluates to
- the null value. It is highly recommended that these applications
- be modified to comply with the SQL standard. However, if that
- cannot be done the
- configuration variable is available. If it is enabled,
- PostgreSQL will convert x =
- NULL clauses to x IS NULL.
-
-
-
-
- If the expression is row-valued, then
- IS NULL is true when the row expression itself is null
- or when all the row's fields are null, while
- IS NOT NULL is true when the row expression itself is non-null
- and all the row's fields are non-null. Because of this behavior,
- IS NULL and IS NOT NULL 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. For example:
-
-
-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
-
-SELECT ROW(table.*) IS NOT NULL FROM table; -- detect all-non-null rows
-
-SELECT NOT(ROW(table.*) IS NOT NULL) FROM TABLE; -- detect at least one null in rows
-
-
- In some cases, it may be preferable to
- write rowIS DISTINCT FROM NULL
- or rowIS NOT DISTINCT FROM NULL,
- which will simply check whether the overall row value is null without any
- additional tests on the row fields.
-
-
-
-
- IS TRUE
-
-
- IS NOT TRUE
-
-
- IS FALSE
-
-
- IS NOT FALSE
-
-
- IS UNKNOWN
-
-
- IS NOT UNKNOWN
-
- Boolean values can also be tested using the predicates
-
-boolean_expression IS TRUE
-boolean_expression IS NOT TRUE
-boolean_expression IS FALSE
-boolean_expression IS NOT FALSE
-boolean_expression IS UNKNOWN
-boolean_expression IS NOT UNKNOWN
-
- 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 unknown.
- Notice that IS UNKNOWN and IS NOT UNKNOWN are
- effectively the same as IS NULL and
- IS NOT NULL, respectively, except that the input
- expression must be of Boolean type.
-
-
-
- Some comparison-related functions are also available, as shown in .
-
-
-
-
-
-
-
- Mathematical Functions and Operators
-
-
- Mathematical operators are provided for many
- PostgreSQL types. For types without
- standard mathematical conventions
- (e.g., date/time types) we
- describe the actual behavior in subsequent sections.
-
-
-
- shows the mathematical
- operators that are available for the standard numeric types.
- Unless otherwise noted, operators shown as
- accepting numeric_type are available for all
- the types smallint, integer,
- bigint, numeric, real,
- and double precision.
- Operators shown as accepting integral_type
- are available for the types smallint, integer,
- and bigint.
- 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 integer+numeric,
- are resolved by using the type appearing later in these lists.
-
-
-
-
-
- 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 double precision 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.
-
-
-
- Mathematical Functions
-
-
-
-
- Function
-
-
- Description
-
-
- Example(s)
-
-
-
-
-
-
-
-
- abs
-
- abs ( numeric_type )
- numeric_type
-
-
- Absolute value
-
-
- abs(-17.4)
- 17.4
-
-
-
-
-
-
- cbrt
-
- cbrt ( double precision )
- double precision
-
-
- Cube root
-
-
- cbrt(64.0)
- 4
-
-
-
-
-
-
- ceil
-
- ceil ( numeric )
- numeric
-
-
- ceil ( double precision )
- double precision
-
-
- Nearest integer greater than or equal to argument
-
-
- ceil(42.2)
- 43
-
-
- ceil(-42.8)
- -42
-
-
-
-
-
-
- ceiling
-
- ceiling ( numeric )
- numeric
-
-
- ceiling ( double precision )
- double precision
-
-
- Nearest integer greater than or equal to argument (same
- as ceil)
-
-
- ceiling(95.3)
- 96
-
-
-
-
-
-
- degrees
-
- degrees ( double precision )
- double precision
-
-
- Converts radians to degrees
-
-
- degrees(0.5)
- 28.64788975654116
-
-
-
-
-
-
- div
-
- div ( ynumeric,
- xnumeric )
- numeric
-
-
- Integer quotient of y/x
- (truncates towards zero)
-
-
- div(9, 4)
- 2
-
-
-
-
-
-
- erf
-
- erf ( double precision )
- double precision
-
-
- Error function
-
-
- erf(1.0)
- 0.8427007929497149
-
-
-
-
-
-
- erfc
-
- erfc ( double precision )
- double precision
-
-
- Complementary error function (1 - erf(x), without
- loss of precision for large inputs)
-
-
- erfc(1.0)
- 0.15729920705028513
-
-
-
-
-
-
- exp
-
- exp ( numeric )
- numeric
-
-
- exp ( double precision )
- double precision
-
-
- Exponential (e raised to the given power)
-
-
- exp(1.0)
- 2.7182818284590452
-
-
-
-
-
-
- factorial
-
- factorial ( bigint )
- numeric
-
-
- Factorial
-
-
- factorial(5)
- 120
-
-
-
-
-
-
- floor
-
- floor ( numeric )
- numeric
-
-
- floor ( double precision )
- double precision
-
-
- Nearest integer less than or equal to argument
-
-
- floor(42.8)
- 42
-
-
- floor(-42.8)
- -43
-
-
-
-
-
-
- gcd
-
- gcd ( numeric_type, numeric_type )
- numeric_type
-
-
- Greatest common divisor (the largest positive number that divides both
- inputs with no remainder); returns 0 if both inputs
- are zero; available for integer, bigint,
- and numeric
-
-
- gcd(1071, 462)
- 21
-
-
-
-
-
-
- lcm
-
- lcm ( numeric_type, numeric_type )
- numeric_type
-
-
- Least common multiple (the smallest strictly positive number that is
- an integral multiple of both inputs); returns 0 if
- either input is zero; available for integer,
- bigint, and numeric
-
-
- lcm(1071, 462)
- 23562
-
-
-
-
-
-
- ln
-
- ln ( numeric )
- numeric
-
-
- ln ( double precision )
- double precision
-
-
- Natural logarithm
-
-
- ln(2.0)
- 0.6931471805599453
-
-
-
-
-
-
- log
-
- log ( numeric )
- numeric
-
-
- log ( double precision )
- double precision
-
-
- Base 10 logarithm
-
-
- log(100)
- 2
-
-
-
-
-
-
- log10
-
- log10 ( numeric )
- numeric
-
-
- log10 ( double precision )
- double precision
-
-
- Base 10 logarithm (same as log)
-
-
- log10(1000)
- 3
-
-
-
-
-
- log ( bnumeric,
- xnumeric )
- numeric
-
-
- Logarithm of x to base b
-
-
- log(2.0, 64.0)
- 6.0000000000000000
-
-
-
-
-
-
- min_scale
-
- min_scale ( numeric )
- integer
-
-
- Minimum scale (number of fractional decimal digits) needed
- to represent the supplied value precisely
-
-
- min_scale(8.4100)
- 2
-
-
-
-
-
-
- mod
-
- mod ( ynumeric_type,
- xnumeric_type )
- numeric_type
-
-
- Remainder of y/x;
- available for smallint, integer,
- bigint, and numeric
-
-
- mod(9, 4)
- 1
-
-
-
-
-
-
- pi
-
- pi ( )
- double precision
-
-
- Approximate value of π
-
-
- pi()
- 3.141592653589793
-
-
-
-
-
-
- power
-
- power ( anumeric,
- bnumeric )
- numeric
-
-
- power ( adouble precision,
- bdouble precision )
- double precision
-
-
- a raised to the power of b
-
-
- power(9, 3)
- 729
-
-
-
-
-
-
- radians
-
- radians ( double precision )
- double precision
-
-
- Converts degrees to radians
-
-
- radians(45.0)
- 0.7853981633974483
-
-
-
-
-
-
- round
-
- round ( numeric )
- numeric
-
-
- round ( double precision )
- double precision
-
-
- Rounds to nearest integer. For numeric, ties are
- broken by rounding away from zero. For double precision,
- the tie-breaking behavior is platform dependent, but
- round to nearest even is the most common rule.
-
-
- round(42.4)
- 42
-
-
-
-
-
- round ( vnumeric, sinteger )
- numeric
-
-
- Rounds v to s decimal
- places. Ties are broken by rounding away from zero.
-
-
- round(42.4382, 2)
- 42.44
-
-
- round(1234.56, -1)
- 1230
-
-
-
-
-
-
- scale
-
- scale ( numeric )
- integer
-
-
- Scale of the argument (the number of decimal digits in the fractional part)
-
-
- scale(8.4100)
- 4
-
-
-
-
-
-
- sign
-
- sign ( numeric )
- numeric
-
-
- sign ( double precision )
- double precision
-
-
- Sign of the argument (-1, 0, or +1)
-
-
- sign(-8.4)
- -1
-
-
-
-
-
-
- sqrt
-
- sqrt ( numeric )
- numeric
-
-
- sqrt ( double precision )
- double precision
-
-
- Square root
-
-
- sqrt(2)
- 1.4142135623730951
-
-
-
-
-
-
- trim_scale
-
- trim_scale ( numeric )
- numeric
-
-
- Reduces the value's scale (number of fractional decimal digits) by
- removing trailing zeroes
-
-
- trim_scale(8.4100)
- 8.41
-
-
-
-
-
-
- trunc
-
- trunc ( numeric )
- numeric
-
-
- trunc ( double precision )
- double precision
-
-
- Truncates to integer (towards zero)
-
-
- trunc(42.8)
- 42
-
-
- trunc(-42.8)
- -42
-
-
-
-
-
- trunc ( vnumeric, sinteger )
- numeric
-
-
- Truncates v to s
- decimal places
-
-
- trunc(42.4382, 2)
- 42.43
-
-
-
-
-
-
- width_bucket
-
- width_bucket ( operandnumeric, lownumeric, highnumeric, countinteger )
- integer
-
-
- width_bucket ( operanddouble precision, lowdouble precision, highdouble precision, countinteger )
- integer
-
-
- Returns the number of the bucket in
- which operand falls in a histogram
- having count equal-width buckets spanning the
- range low to high.
- Returns 0
- or count+1 for an input
- outside that range.
-
-
- width_bucket(5.35, 0.024, 10.06, 5)
- 3
-
-
-
-
-
- width_bucket ( operandanycompatible, thresholdsanycompatiblearray )
- integer
-
-
- Returns the number of the bucket in
- which operand falls given an array listing the
- lower bounds of the buckets. Returns 0 for an
- input less than the first lower
- bound. operand and the array elements can be
- of any type having standard comparison operators.
- The thresholds array must be
- sorted, smallest first, or unexpected results will be
- obtained.
-
-
- width_bucket(now(), array['yesterday', 'today', 'tomorrow']::timestamptz[])
- 2
-
-
-
-
-
-
-
- shows functions for
- generating random numbers.
-
-
-
- Random Functions
-
-
-
-
-
- Function
-
-
- Description
-
-
- Example(s)
-
-
-
-
-
-
-
-
- random
-
- random ( )
- double precision
-
-
- Returns a random value in the range 0.0 <= x < 1.0
-
-
- random()
- 0.897124072839091
-
-
-
-
-
-
- random
-
- random ( mininteger, maxinteger )
- integer
-
-
- random ( minbigint, maxbigint )
- bigint
-
-
- random ( minnumeric, maxnumeric )
- numeric
-
-
- Returns a random value in the range
- min <= x <= max.
- For type numeric, the result will have the same number of
- fractional decimal digits as min or
- max, whichever has more.
-
-
- random(1, 10)
- 7
-
-
- random(-0.499, 0.499)
- 0.347
-
-
-
-
-
-
- random_normal
-
-
- random_normal (
- meandouble precision
- , stddevdouble precision )
- double precision
-
-
- Returns a random value from the normal distribution with the given
- parameters; mean defaults to 0.0
- and stddev defaults to 1.0
-
-
- random_normal(0.0, 1.0)
- 0.051285419
-
-
-
-
-
-
- setseed
-
- setseed ( double precision )
- void
-
-
- Sets the seed for subsequent random() and
- random_normal() calls;
- argument must be between -1.0 and 1.0, inclusive
-
-
- setseed(0.12345)
-
-
-
-
-
-
-
- The random() and random_normal()
- functions listed in use a
- deterministic pseudo-random number generator.
- It is fast but not suitable for cryptographic
- applications; see the module for a more
- secure alternative.
- If setseed() is called, the series of results of
- subsequent calls to these functions in the current session
- can be repeated by re-issuing setseed() with the same
- argument.
- Without any prior setseed() call in the same
- session, the first call to any of these functions obtains a seed
- from a platform-dependent source of random bits.
-
-
-
- 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.
-
-
-
-
-
-
- Another way to work with angles measured in degrees is to use the unit
- transformation functions radians()
- and degrees() shown earlier.
- However, using the degree-based trigonometric functions is preferred,
- as that way avoids round-off error for special cases such
- as sind(30).
-
-
-
-
- shows the
- available hyperbolic functions.
-
-
-
-
-
-
-
-
- String Functions and Operators
-
-
- This section describes functions and operators for examining and
- manipulating string values. Strings in this context include values
- of the types character, character varying,
- and text. Except where noted, these functions and operators
- are declared to accept and return type text. They will
- interchangeably accept character varying arguments.
- Values of type character will be converted
- to text before the function or operator is applied, resulting
- in stripping any trailing spaces in the character value.
-
-
-
- SQL defines some string functions that use
- key words, rather than commas, to separate
- arguments. Details are in
- .
- PostgreSQL also provides versions of these functions
- that use the regular function invocation syntax
- (see ).
-
-
-
-
- The string concatenation operator (||) will accept
- non-string input, so long as at least one input is of string type, as shown
- in . For other cases, inserting an
- explicit coercion to text can be used to have non-string input
- accepted.
-
-
-
-
- <acronym>SQL</acronym> String Functions and Operators
-
-
-
-
- Function/Operator
-
-
- Description
-
-
- Example(s)
-
-
-
-
-
-
-
-
- character string
- concatenation
-
- text||text
- text
-
-
- Concatenates the two strings.
-
-
- 'Post' || 'greSQL'
- PostgreSQL
-
-
-
-
-
- text||anynonarray
- text
-
-
- anynonarray||text
- text
-
-
- 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 ||
- operators. If you want to concatenate an array's text equivalent,
- cast it to text explicitly.)
-
-
- 'Value: ' || 42
- Value: 42
-
-
-
-
-
-
- btrim
-
- btrim ( stringtext
- , characterstext )
- text
-
-
- Removes the longest string containing only characters
- in characters (a space by default)
- from the start and end of string.
-
-
- btrim('xyxtrimyyx', 'xyz')
- trim
-
-
-
-
-
-
- normalized
-
-
- Unicode normalization
-
- textISNOTformNORMALIZED
- boolean
-
-
- Checks whether the string is in the specified Unicode normalization
- form. The optional form key word specifies the
- form: NFC (the default), NFD,
- NFKC, or NFKD. This expression can
- only be used when the server encoding is UTF8. Note
- that checking for normalization using this expression is often faster
- than normalizing possibly already normalized strings.
-
-
- U&'\0061\0308bc' IS NFD NORMALIZED
- t
-
-
-
-
-
-
- bit_length
-
- bit_length ( text )
- integer
-
-
- Returns number of bits in the string (8
- times the octet_length).
-
-
- bit_length('jose')
- 32
-
-
-
-
-
-
- char_length
-
-
- character string
- length
-
-
- length
- of a character string
- character string, length
-
- char_length ( text )
- integer
-
-
-
- character_length
-
- character_length ( text )
- integer
-
-
- Returns number of characters in the string.
-
-
- char_length('josé')
- 4
-
-
-
-
-
-
- lower
-
- lower ( text )
- text
-
-
- Converts the string to all lower case, according to the rules of the
- database's locale.
-
-
- lower('TOM')
- tom
-
-
-
-
-
-
- lpad
-
- lpad ( stringtext,
- lengthinteger
- , filltext )
- text
-
-
- Extends the string to length
- length by prepending the characters
- fill (a space by default). If the
- string is already longer than
- length then it is truncated (on the right).
-
-
- lpad('hi', 5, 'xy')
- xyxhi
-
-
-
-
-
-
- ltrim
-
- ltrim ( stringtext
- , characterstext )
- text
-
-
- Removes the longest string containing only characters in
- characters (a space by default) from the start of
- string.
-
-
- ltrim('zzzytest', 'xyz')
- test
-
-
-
-
-
-
- normalize
-
-
- Unicode normalization
-
- normalize ( text
- , form )
- text
-
-
- Converts the string to the specified Unicode
- normalization form. The optional form key word
- specifies the form: NFC (the default),
- NFD, NFKC, or
- NFKD. This function can only be used when the
- server encoding is UTF8.
-
-
- normalize(U&'\0061\0308bc', NFC)
- U&'\00E4bc'
-
-
-
-
-
-
- octet_length
-
- octet_length ( text )
- integer
-
-
- Returns number of bytes in the string.
-
-
- octet_length('josé')
- 5 (if server encoding is UTF8)
-
-
-
-
-
-
- octet_length
-
- octet_length ( character )
- integer
-
-
- Returns number of bytes in the string. Since this version of the
- function accepts type character directly, it will not
- strip trailing spaces.
-
-
- octet_length('abc '::character(4))
- 4
-
-
-
-
-
-
- overlay
-
- overlay ( stringtextPLACINGnewsubstringtextFROMstartintegerFORcountinteger )
- text
-
-
- Replaces the substring of string that starts at
- the start'th character and extends
- for count characters
- with newsubstring.
- If count is omitted, it defaults to the length
- of newsubstring.
-
-
- overlay('Txxxxas' placing 'hom' from 2 for 4)
- Thomas
-
-
-
-
-
-
- position
-
- position ( substringtextINstringtext )
- integer
-
-
- Returns first starting index of the specified
- substring within
- string, or zero if it's not present.
-
-
- position('om' in 'Thomas')
- 3
-
-
-
-
-
-
- rpad
-
- rpad ( stringtext,
- lengthinteger
- , filltext )
- text
-
-
- Extends the string to length
- length by appending the characters
- fill (a space by default). If the
- string is already longer than
- length then it is truncated.
-
-
- rpad('hi', 5, 'xy')
- hixyx
-
-
-
-
-
-
- rtrim
-
- rtrim ( stringtext
- , characterstext )
- text
-
-
- Removes the longest string containing only characters in
- characters (a space by default) from the end of
- string.
-
-
- rtrim('testxxzx', 'xyz')
- test
-
-
-
-
-
-
- substring
-
- substring ( stringtextFROMstartintegerFORcountinteger )
- text
-
-
- Extracts the substring of string starting at
- the start'th character if that is specified,
- and stopping after count characters if that is
- specified. Provide at least one of start
- and count.
-
-
- substring('Thomas' from 2 for 3)
- hom
-
-
- substring('Thomas' from 3)
- omas
-
-
- substring('Thomas' for 2)
- Th
-
-
-
-
-
- substring ( stringtextFROMpatterntext )
- text
-
-
- Extracts the first substring matching POSIX regular expression; see
- .
-
-
- substring('Thomas' from '...$')
- mas
-
-
-
-
-
- substring ( stringtextSIMILARpatterntextESCAPEescapetext )
- text
-
-
- substring ( stringtextFROMpatterntextFORescapetext )
- text
-
-
- Extracts the first substring matching SQL regular expression;
- see . The first form has
- been specified since SQL:2003; the second form was only in SQL:1999
- and should be considered obsolete.
-
-
- substring('Thomas' similar '%#"o_a#"_' escape '#')
- oma
-
-
-
-
-
-
- trim
-
- trim ( LEADING | TRAILING | BOTH
- characterstextFROM
- stringtext )
- text
-
-
- Removes the longest string containing only characters in
- characters (a space by default) from the
- start, end, or both ends (BOTH is the default)
- of string.
-
-
- trim(both 'xyz' from 'yxTomxx')
- Tom
-
-
-
-
-
- trim ( LEADING | TRAILING | BOTHFROM
- stringtext,
- characterstext )
- text
-
-
- This is a non-standard syntax for trim().
-
-
- trim(both from 'yxTomxx', 'xyz')
- Tom
-
-
-
-
-
-
- unicode_assigned
-
- unicode_assigned ( text )
- text
-
-
- Returns true if all characters in the string are
- assigned Unicode codepoints; false otherwise. This
- function can only be used when the server encoding is
- UTF8.
-
-
-
-
-
-
- upper
-
- upper ( text )
- text
-
-
- Converts the string to all upper case, according to the rules of the
- database's locale.
-
-
- upper('tom')
- TOM
-
-
-
-
-
-
-
- Additional string manipulation functions and operators are available
- and are listed in . (Some of
- these are used internally to implement
- the SQL-standard string functions listed in
- .)
- There are also pattern-matching operators, which are described in
- , and operators for full-text
- search, which are described in .
-
-
-
- Other String Functions and Operators
-
-
-
-
- Function/Operator
-
-
- Description
-
-
- Example(s)
-
-
-
-
-
-
-
-
- character string
- prefix test
-
- text^@text
- boolean
-
-
- Returns true if the first string starts with the second string
- (equivalent to the starts_with() function).
-
-
- 'alphabet' ^@ 'alph'
- t
-
-
-
-
-
-
- ascii
-
- ascii ( text )
- integer
-
-
- Returns the numeric code of the first character of the argument.
- In UTF8 encoding, returns the Unicode code point
- of the character. In other multibyte encodings, the argument must
- be an ASCII character.
-
-
- ascii('x')
- 120
-
-
-
-
-
-
- chr
-
- chr ( integer )
- text
-
-
- Returns the character with the given code. In UTF8
- encoding the argument is treated as a Unicode code point. In other
- multibyte encodings the argument must designate
- an ASCII character. chr(0) is
- disallowed because text data types cannot store that character.
-
-
- chr(65)
- A
-
-
-
-
-
-
- concat
-
- concat ( val1"any"
- [, val2"any" [, ...] ] )
- text
-
-
- Concatenates the text representations of all the arguments.
- NULL arguments are ignored.
-
-
- concat('abcde', 2, NULL, 22)
- abcde222
-
-
-
-
-
-
- concat_ws
-
- concat_ws ( septext,
- val1"any"
- [, val2"any" [, ...] ] )
- text
-
-
- 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.
-
-
- concat_ws(',', 'abcde', 2, NULL, 22)
- abcde,2,22
-
-
-
-
-
-
- format
-
- format ( formatstrtext
- [, formatarg"any" [, ...] ] )
- text
-
-
- Formats arguments according to a format string;
- see .
- This function is similar to the C function sprintf.
-
-
- format('Hello %s, %1$s', 'World')
- Hello World, World
-
-
-
-
-
-
- initcap
-
- initcap ( text )
- text
-
-
- 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.
-
-
- initcap('hi THOMAS')
- Hi Thomas
-
-
-
-
-
-
- left
-
- left ( stringtext,
- ninteger )
- text
-
-
- Returns first n characters in the
- string, or when n is negative, returns
- all but last |n| characters.
-
-
- left('abcde', 2)
- ab
-
-
-
-
-
-
- length
-
- length ( text )
- integer
-
-
- Returns the number of characters in the string.
-
-
- length('jose')
- 4
-
-
-
-
-
-
- md5
-
- md5 ( text )
- text
-
-
- Computes the MD5 hash of
- the argument, with the result written in hexadecimal.
-
-
- md5('abc')
- 900150983cd24fb0&zwsp;d6963f7d28e17f72
-
-
-
-
-
-
- parse_ident
-
- parse_ident ( qualified_identifiertext
- [, strict_modebooleanDEFAULTtrue ] )
- text[]
-
-
- Splits qualified_identifier 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 false, 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 name[].
-
-
- parse_ident('"SomeSchema".someTable')
- {SomeSchema,sometable}
-
-
-
-
-
-
- pg_client_encoding
-
- pg_client_encoding ( )
- name
-
-
- Returns current client encoding name.
-
-
- pg_client_encoding()
- UTF8
-
-
-
-
-
-
- quote_ident
-
- quote_ident ( text )
- text
-
-
- Returns 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.
- See also .
-
-
- quote_ident('Foo bar')
- "Foo bar"
-
-
-
-
-
-
- quote_literal
-
- quote_literal ( text )
- text
-
-
- Returns 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 quote_literal returns null on null
- input; if the argument might be null,
- quote_nullable is often more suitable.
- See also .
-
-
- quote_literal(E'O\'Reilly')
- 'O''Reilly'
-
-
-
-
-
- quote_literal ( anyelement )
- text
-
-
- Converts the given value to text and then quotes it as a literal.
- Embedded single-quotes and backslashes are properly doubled.
-
-
- quote_literal(42.5)
- '42.5'
-
-
-
-
-
-
- quote_nullable
-
- quote_nullable ( text )
- text
-
-
- Returns the given string suitably quoted to be used as a string literal
- in an SQL statement string; or, if the argument
- is null, returns NULL.
- Embedded single-quotes and backslashes are properly doubled.
- See also .
-
-
- quote_nullable(NULL)
- NULL
-
-
-
-
-
- quote_nullable ( anyelement )
- text
-
-
- Converts the given value to text and then quotes it as a literal;
- or, if the argument is null, returns NULL.
- Embedded single-quotes and backslashes are properly doubled.
-
-
- quote_nullable(42.5)
- '42.5'
-
-
-
-
-
-
- regexp_count
-
- regexp_count ( stringtext, patterntext
- [, startinteger
- [, flagstext ] ] )
- integer
-
-
- Returns the number of times the POSIX regular
- expression pattern matches in
- the string; see
- .
-
-
- regexp_count('123456789012', '\d\d\d', 2)
- 3
-
-
-
-
-
-
- regexp_instr
-
- regexp_instr ( stringtext, patterntext
- [, startinteger
- [, Ninteger
- [, endoptioninteger
- [, flagstext
- [, subexprinteger ] ] ] ] ] )
- integer
-
-
- Returns the position within string where
- the N'th match of the POSIX regular
- expression pattern occurs, or zero if there is
- no such match; see .
-
-
- regexp_instr('ABCDEF', 'c(.)(..)', 1, 1, 0, 'i')
- 3
-
-
- regexp_instr('ABCDEF', 'c(.)(..)', 1, 1, 0, 'i', 2)
- 5
-
-
-
-
-
-
- regexp_like
-
- regexp_like ( stringtext, patterntext
- [, flagstext ] )
- boolean
-
-
- Checks whether a match of the POSIX regular
- expression pattern occurs
- within string; see
- .
-
-
- regexp_like('Hello World', 'world$', 'i')
- t
-
-
-
-
-
-
- regexp_match
-
- regexp_match ( stringtext, patterntext [, flagstext ] )
- text[]
-
-
- Returns substrings within the first match of the POSIX regular
- expression pattern to
- the string; see
- .
-
-
- regexp_match('foobarbequebaz', '(bar)(beque)')
- {bar,beque}
-
-
-
-
-
-
- regexp_matches
-
- regexp_matches ( stringtext, patterntext [, flagstext ] )
- setof text[]
-
-
- Returns substrings within the first match of the POSIX regular
- expression pattern to
- the string, or substrings within all
- such matches if the g flag is used;
- see .
-
-
- regexp_matches('foobarbequebaz', 'ba.', 'g')
-
-
- {bar}
- {baz}
-
-
-
-
-
-
-
- regexp_replace
-
- regexp_replace ( stringtext, patterntext, replacementtext
- [, startinteger ]
- [, flagstext ] )
- text
-
-
- Replaces the substring that is the first match to the POSIX
- regular expression pattern, or all such
- matches if the g flag is used; see
- .
-
-
- regexp_replace('Thomas', '.[mN]a.', 'M')
- ThM
-
-
-
-
-
- regexp_replace ( stringtext, patterntext, replacementtext,
- startinteger,
- Ninteger
- [, flagstext ] )
- text
-
-
- Replaces the substring that is the N'th
- match to the POSIX regular expression pattern,
- or all such matches if N is zero; see
- .
-
-
- regexp_replace('Thomas', '.', 'X', 3, 2)
- ThoXas
-
-
-
-
-
-
- regexp_split_to_array
-
- regexp_split_to_array ( stringtext, patterntext [, flagstext ] )
- text[]
-
-
- Splits string using a POSIX regular
- expression as the delimiter, producing an array of results; see
- .
-
-
- regexp_split_to_array('hello world', '\s+')
- {hello,world}
-
-
-
-
-
-
- regexp_split_to_table
-
- regexp_split_to_table ( stringtext, patterntext [, flagstext ] )
- setof text
-
-
- Splits string using a POSIX regular
- expression as the delimiter, producing a set of results; see
- .
-
-
- regexp_split_to_table('hello world', '\s+')
-
-
- hello
- world
-
-
-
-
-
-
-
- regexp_substr
-
- regexp_substr ( stringtext, patterntext
- [, startinteger
- [, Ninteger
- [, flagstext
- [, subexprinteger ] ] ] ] )
- text
-
-
- Returns the substring within string that
- matches the N'th occurrence of the POSIX
- regular expression pattern,
- or NULL if there is no such match; see
- .
-
-
- regexp_substr('ABCDEF', 'c(.)(..)', 1, 1, 'i')
- CDEF
-
-
- regexp_substr('ABCDEF', 'c(.)(..)', 1, 1, 'i', 2)
- EF
-
-
-
-
-
-
- repeat
-
- repeat ( stringtext, numberinteger )
- text
-
-
- Repeats string the specified
- number of times.
-
-
- repeat('Pg', 4)
- PgPgPgPg
-
-
-
-
-
-
- replace
-
- replace ( stringtext,
- fromtext,
- totext )
- text
-
-
- Replaces all occurrences in string of
- substring from with
- substring to.
-
-
- replace('abcdefabcdef', 'cd', 'XX')
- abXXefabXXef
-
-
-
-
-
-
- reverse
-
- reverse ( text )
- text
-
-
- Reverses the order of the characters in the string.
-
-
- reverse('abcde')
- edcba
-
-
-
-
-
-
- right
-
- right ( stringtext,
- ninteger )
- text
-
-
- Returns last n characters in the string,
- or when n is negative, returns all but
- first |n| characters.
-
-
- right('abcde', 2)
- de
-
-
-
-
-
-
- split_part
-
- split_part ( stringtext,
- delimitertext,
- ninteger )
- text
-
-
- Splits string at occurrences
- of delimiter and returns
- the n'th field (counting from one),
- or when n is negative, returns
- the |n|'th-from-last field.
-
-
- split_part('abc~@~def~@~ghi', '~@~', 2)
- def
-
-
- split_part('abc,def,ghi,jkl', ',', -2)
- ghi
-
-
-
-
-
-
- starts_with
-
- starts_with ( stringtext, prefixtext )
- boolean
-
-
- Returns true if string starts
- with prefix.
-
-
- starts_with('alphabet', 'alph')
- t
-
-
-
-
-
-
- string_to_array
-
- string_to_array ( stringtext, delimitertext, null_stringtext )
- text[]
-
-
- Splits the string at occurrences
- of delimiter and forms the resulting fields
- into a text array.
- If delimiter is NULL,
- each character in the string will become a
- separate element in the array.
- If delimiter is an empty string, then
- the string is treated as a single field.
- If null_string is supplied and is
- not NULL, fields matching that string are
- replaced by NULL.
- See also array_to_string.
-
-
- string_to_array('xx~~yy~~zz', '~~', 'yy')
- {xx,NULL,zz}
-
-
-
-
-
-
- string_to_table
-
- string_to_table ( stringtext, delimitertext, null_stringtext )
- setof text
-
-
- Splits the string at occurrences
- of delimiter and returns the resulting fields
- as a set of text rows.
- If delimiter is NULL,
- each character in the string will become a
- separate row of the result.
- If delimiter is an empty string, then
- the string is treated as a single field.
- If null_string is supplied and is
- not NULL, fields matching that string are
- replaced by NULL.
-
-
- string_to_table('xx~^~yy~^~zz', '~^~', 'yy')
-
-
- xx
- NULL
- zz
-
-
-
-
-
-
-
- strpos
-
- strpos ( stringtext, substringtext )
- integer
-
-
- Returns first starting index of the specified substring
- within string, or zero if it's not present.
- (Same as position(substring in
- string), but note the reversed
- argument order.)
-
-
- strpos('high', 'ig')
- 2
-
-
-
-
-
-
- substr
-
- substr ( stringtext, startinteger, countinteger )
- text
-
-
- Extracts the substring of string starting at
- the start'th character,
- and extending for count characters if that is
- specified. (Same
- as substring(string
- from start
- for count).)
-
-
- substr('alphabet', 3)
- phabet
-
-
- substr('alphabet', 3, 2)
- ph
-
-
-
-
-
-
- to_ascii
-
- to_ascii ( stringtext )
- text
-
-
- to_ascii ( stringtext,
- encodingname )
- text
-
-
- to_ascii ( stringtext,
- encodinginteger )
- text
-
-
- Converts string to ASCII
- from another encoding, which may be identified by name or number.
- If encoding 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 LATIN1, LATIN2,
- LATIN9, and WIN1250 encodings.
- (See the module for another, more flexible
- solution.)
-
-
- to_ascii('Karél')
- Karel
-
-
-
-
-
-
- to_bin
-
- to_bin ( integer )
- text
-
-
- to_bin ( bigint )
- text
-
-
- Converts the number to its equivalent two's complement binary
- representation.
-
-
- to_bin(2147483647)
- 1111111111111111111111111111111
-
-
- to_bin(-1234)
- 11111111111111111111101100101110
-
-
-
-
-
-
- to_hex
-
- to_hex ( integer )
- text
-
-
- to_hex ( bigint )
- text
-
-
- Converts the number to its equivalent two's complement hexadecimal
- representation.
-
-
- to_hex(2147483647)
- 7fffffff
-
-
- to_hex(-1234)
- fffffb2e
-
-
-
-
-
-
- to_oct
-
- to_oct ( integer )
- text
-
-
- to_oct ( bigint )
- text
-
-
- Converts the number to its equivalent two's complement octal
- representation.
-
-
- to_oct(2147483647)
- 17777777777
-
-
- to_oct(-1234)
- 37777775456
-
-
-
-
-
-
- translate
-
- translate ( stringtext,
- fromtext,
- totext )
- text
-
-
- Replaces each character in string that
- matches a character in the from set with the
- corresponding character in the to
- set. If from is longer than
- to, occurrences of the extra characters in
- from are deleted.
-
-
- translate('12345', '143', 'ax')
- a2x5
-
-
-
-
-
-
- unistr
-
- unistr ( text )
- text
-
-
- Evaluate escaped Unicode characters in the argument. Unicode characters
- can be specified as
- \XXXX (4 hexadecimal
- digits), \+XXXXXX (6
- hexadecimal digits),
- \uXXXX (4 hexadecimal
- digits), or \UXXXXXXXX
- (8 hexadecimal digits). To specify a backslash, write two
- backslashes. All other characters are taken literally.
-
-
-
- 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.
-
-
-
- This function provides a (non-standard) alternative to string
- constants with Unicode escapes (see ).
-
-
-
- unistr('d\0061t\+000061')
- data
-
-
- unistr('d\u0061t\U00000061')
- data
-
-
-
-
-
-
-
-
- The concat, concat_ws and
- format functions are variadic, so it is possible to
- pass the values to be concatenated or formatted as an array marked with
- the VARIADIC keyword (see ). The array's elements are
- treated as if they were separate ordinary arguments to the function.
- If the variadic array argument is NULL, concat
- and concat_ws return NULL, but
- format treats a NULL as a zero-element array.
-
-
-
- See also the aggregate function string_agg in
- , and the functions for
- converting between strings and the bytea type in
- .
-
-
-
- <function>format</function>
-
-
- format
-
-
-
- The function format produces output formatted according to
- a format string, in a style similar to the C function
- sprintf.
-
-
-
-
-format(formatstrtext [, formatarg"any" [, ...] ])
-
- formatstr 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 format specifiers are
- used. Format specifiers act as placeholders in the string, defining how
- subsequent function arguments should be formatted and inserted into the
- result. Each formatarg 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).
-
-
-
- Format specifiers are introduced by a % character and have
- the form
-
-%[position][flags][width]type
-
- where the component fields are:
-
-
-
- position (optional)
-
-
- A string of the form n$ where
- n is the index of the argument to print.
- Index 1 means the first argument after
- formatstr. If the position is
- omitted, the default is to use the next argument in sequence.
-
-
-
-
-
- flags (optional)
-
-
- Additional options controlling how the format specifier's output is
- formatted. Currently the only supported flag is a minus sign
- (-) which will cause the format specifier's output to be
- left-justified. This has no effect unless the width
- field is also specified.
-
-
-
-
-
- width (optional)
-
-
- Specifies the minimum number of characters to use to
- display the format specifier's output. The output is padded on the
- left or right (depending on the - 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 (*) to use the next function argument as the
- width; or a string of the form *n$ to
- use the nth function argument as the width.
-
-
-
- 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 - flag had been specified) within a
- field of length abs(width).
-
-
-
-
-
- type (required)
-
-
- The type of format conversion to use to produce the format
- specifier's output. The following types are supported:
-
-
-
- s formats the argument value as a simple
- string. A null value is treated as an empty string.
-
-
-
-
- I 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
- quote_ident).
-
-
-
-
- L quotes the argument value as an SQL literal.
- A null value is displayed as the string NULL, without
- quotes (equivalent to quote_nullable).
-
-
-
-
-
-
-
-
-
-
- In addition to the format specifiers described above, the special sequence
- %% may be used to output a literal % character.
-
-
-
- Here are some examples of the basic format conversions:
-
-
-SELECT format('Hello %s', 'World');
-Result: Hello World
-
-SELECT format('Testing %s, %s, %s, %%', 'one', 'two', 'three');
-Result: Testing one, two, three, %
-
-SELECT format('INSERT INTO %I VALUES(%L)', 'Foo bar', E'O\'Reilly');
-Result: INSERT INTO "Foo bar" VALUES('O''Reilly')
-
-SELECT format('INSERT INTO %I VALUES(%L)', 'locations', 'C:\Program Files');
-Result: INSERT INTO locations VALUES('C:\Program Files')
-
-
-
-
- Here are examples using width fields
- and the - flag:
-
-
-SELECT format('|%10s|', 'foo');
-Result: | foo|
-
-SELECT format('|%-10s|', 'foo');
-Result: |foo |
-
-SELECT format('|%*s|', 10, 'foo');
-Result: | foo|
-
-SELECT format('|%*s|', -10, 'foo');
-Result: |foo |
-
-SELECT format('|%-*s|', 10, 'foo');
-Result: |foo |
-
-SELECT format('|%-*s|', -10, 'foo');
-Result: |foo |
-
-
-
-
- These examples show use of position fields:
-
-
-SELECT format('Testing %3$s, %2$s, %1$s', 'one', 'two', 'three');
-Result: Testing three, two, one
-
-SELECT format('|%*2$s|', 'foo', 10, 'bar');
-Result: | bar|
-
-SELECT format('|%1$*2$s|', 'foo', 10, 'bar');
-Result: | foo|
-
-
-
-
- Unlike the standard C function sprintf,
- PostgreSQL's format function allows format
- specifiers with and without position fields to be mixed
- in the same format string. A format specifier without a
- position field always uses the next argument after the
- last argument consumed.
- In addition, the format function does not require all
- function arguments to be used in the format string.
- For example:
-
-
-SELECT format('Testing %3$s, %2$s, %s', 'one', 'two', 'three');
-Result: Testing three, two, three
-
-
-
-
- The %I and %L format specifiers are particularly
- useful for safely constructing dynamic SQL statements. See
- .
-
-
-
-
-
-
-
- Binary String Functions and Operators
-
-
- binary data
- functions
-
-
-
- This section describes functions and operators for examining and
- manipulating binary strings, that is values of type bytea.
- Many of these are equivalent, in purpose and syntax, to the
- text-string functions described in the previous section.
-
-
-
- SQL defines some string functions that use
- key words, rather than commas, to separate
- arguments. Details are in
- .
- PostgreSQL also provides versions of these functions
- that use the regular function invocation syntax
- (see ).
-
-
-
- <acronym>SQL</acronym> Binary String Functions and Operators
-
-
-
-
- Function/Operator
-
-
- Description
-
-
- Example(s)
-
-
-
-
-
-
-
-
- binary string
- concatenation
-
- bytea||bytea
- bytea
-
-
- Concatenates the two binary strings.
-
-
- '\x123456'::bytea || '\x789a00bcde'::bytea
- \x123456789a00bcde
-
-
-
-
-
-
- bit_length
-
- bit_length ( bytea )
- integer
-
-
- Returns number of bits in the binary string (8
- times the octet_length).
-
-
- bit_length('\x123456'::bytea)
- 24
-
-
-
-
-
-
- btrim
-
- btrim ( bytesbytea,
- bytesremovedbytea )
- bytea
-
-
- Removes the longest string containing only bytes appearing in
- bytesremoved from the start and end of
- bytes.
-
-
- btrim('\x1234567890'::bytea, '\x9012'::bytea)
- \x345678
-
-
-
-
-
-
- ltrim
-
- ltrim ( bytesbytea,
- bytesremovedbytea )
- bytea
-
-
- Removes the longest string containing only bytes appearing in
- bytesremoved from the start of
- bytes.
-
-
- ltrim('\x1234567890'::bytea, '\x9012'::bytea)
- \x34567890
-
-
-
-
-
-
- octet_length
-
- octet_length ( bytea )
- integer
-
-
- Returns number of bytes in the binary string.
-
-
- octet_length('\x123456'::bytea)
- 3
-
-
-
-
-
-
- overlay
-
- overlay ( bytesbyteaPLACINGnewsubstringbyteaFROMstartintegerFORcountinteger )
- bytea
-
-
- Replaces the substring of bytes that starts at
- the start'th byte and extends
- for count bytes
- with newsubstring.
- If count is omitted, it defaults to the length
- of newsubstring.
-
-
- overlay('\x1234567890'::bytea placing '\002\003'::bytea from 2 for 3)
- \x12020390
-
-
-
-
-
-
- position
-
- position ( substringbyteaINbytesbytea )
- integer
-
-
- Returns first starting index of the specified
- substring within
- bytes, or zero if it's not present.
-
-
- position('\x5678'::bytea in '\x1234567890'::bytea)
- 3
-
-
-
-
-
-
- rtrim
-
- rtrim ( bytesbytea,
- bytesremovedbytea )
- bytea
-
-
- Removes the longest string containing only bytes appearing in
- bytesremoved from the end of
- bytes.
-
-
- rtrim('\x1234567890'::bytea, '\x9012'::bytea)
- \x12345678
-
-
-
-
-
-
- substring
-
- substring ( bytesbyteaFROMstartintegerFORcountinteger )
- bytea
-
-
- Extracts the substring of bytes starting at
- the start'th byte if that is specified,
- and stopping after count bytes if that is
- specified. Provide at least one of start
- and count.
-
-
- substring('\x1234567890'::bytea from 3 for 2)
- \x5678
-
-
-
-
-
-
- trim
-
- trim ( LEADING | TRAILING | BOTH
- bytesremovedbyteaFROM
- bytesbytea )
- bytea
-
-
- Removes the longest string containing only bytes appearing in
- bytesremoved from the start,
- end, or both ends (BOTH is the default)
- of bytes.
-
-
- trim('\x9012'::bytea from '\x1234567890'::bytea)
- \x345678
-
-
-
-
-
- trim ( LEADING | TRAILING | BOTHFROM
- bytesbytea,
- bytesremovedbytea )
- bytea
-
-
- This is a non-standard syntax for trim().
-
-
- trim(both from '\x1234567890'::bytea, '\x9012'::bytea)
- \x345678
-
-
-
-
-
-
-
- Additional binary string manipulation functions are available and
- are listed in . Some
- of them are used internally to implement the
- SQL-standard string functions listed in .
-
-
-
- Other Binary String Functions
-
-
-
-
- Function
-
-
- Description
-
-
- Example(s)
-
-
-
-
-
-
-
-
- bit_count
-
-
- popcount
- bit_count
-
- bit_count ( bytesbytea )
- bigint
-
-
- Returns the number of bits set in the binary string (also known as
- popcount).
-
-
- bit_count('\x1234567890'::bytea)
- 15
-
-
-
-
-
-
- get_bit
-
- get_bit ( bytesbytea,
- nbigint )
- integer
-
-
- Extracts n'th bit
- from binary string.
-
-
- get_bit('\x1234567890'::bytea, 30)
- 1
-
-
-
-
-
-
- get_byte
-
- get_byte ( bytesbytea,
- ninteger )
- integer
-
-
- Extracts n'th byte
- from binary string.
-
-
- get_byte('\x1234567890'::bytea, 4)
- 144
-
-
-
-
-
-
- length
-
-
- binary string
- length
-
-
- length
- of a binary string
- binary strings, length
-
- length ( bytea )
- integer
-
-
- Returns the number of bytes in the binary string.
-
-
- length('\x1234567890'::bytea)
- 5
-
-
-
-
-
- length ( bytesbytea,
- encodingname )
- integer
-
-
- Returns the number of characters in the binary string, assuming
- that it is text in the given encoding.
-
-
- length('jose'::bytea, 'UTF8')
- 4
-
-
-
-
-
-
- md5
-
- md5 ( bytea )
- text
-
-
- Computes the MD5 hash of
- the binary string, with the result written in hexadecimal.
-
-
- md5('Th\000omas'::bytea)
- 8ab2d3c9689aaf18&zwsp;b4958c334c82d8b1
-
-
-
-
-
-
- set_bit
-
- set_bit ( bytesbytea,
- nbigint,
- newvalueinteger )
- bytea
-
-
- Sets n'th bit in
- binary string to newvalue.
-
-
- set_bit('\x1234567890'::bytea, 30, 0)
- \x1234563890
-
-
-
-
-
-
- set_byte
-
- set_byte ( bytesbytea,
- ninteger,
- newvalueinteger )
- bytea
-
-
- Sets n'th byte in
- binary string to newvalue.
-
-
- set_byte('\x1234567890'::bytea, 4, 64)
- \x1234567840
-
-
-
-
-
-
- sha224
-
- sha224 ( bytea )
- bytea
-
-
- Computes the SHA-224 hash
- of the binary string.
-
-
- sha224('abc'::bytea)
- \x23097d223405d8228642a477bda2&zwsp;55b32aadbce4bda0b3f7e36c9da7
-
-
-
-
-
-
- sha256
-
- sha256 ( bytea )
- bytea
-
-
- Computes the SHA-256 hash
- of the binary string.
-
-
- sha256('abc'::bytea)
- \xba7816bf8f01cfea414140de5dae2223&zwsp;b00361a396177a9cb410ff61f20015ad
-
-
-
-
-
-
- sha384
-
- sha384 ( bytea )
- bytea
-
-
- Computes the SHA-384 hash
- of the binary string.
-
-
- sha384('abc'::bytea)
- \xcb00753f45a35e8bb5a03d699ac65007&zwsp;272c32ab0eded1631a8b605a43ff5bed&zwsp;8086072ba1e7cc2358baeca134c825a7
-
-
-
-
-
-
- sha512
-
- sha512 ( bytea )
- bytea
-
-
- Computes the SHA-512 hash
- of the binary string.
-
-
- sha512('abc'::bytea)
- \xddaf35a193617abacc417349ae204131&zwsp;12e6fa4e89a97ea20a9eeee64b55d39a&zwsp;2192992a274fc1a836ba3c23a3feebbd&zwsp;454d4423643ce80e2a9ac94fa54ca49f
-
-
-
-
-
-
- substr
-
- substr ( bytesbytea, startinteger, countinteger )
- bytea
-
-
- Extracts the substring of bytes starting at
- the start'th byte,
- and extending for count bytes if that is
- specified. (Same
- as substring(bytes
- from start
- for count).)
-
-
- substr('\x1234567890'::bytea, 3, 2)
- \x5678
-
-
-
-
-
-
-
- Functions get_byte and set_byte
- number the first byte of a binary string as byte 0.
- Functions get_bit and set_bit
- 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.
-
-
-
- For historical reasons, the function md5
- returns a hex-encoded value of type text whereas the SHA-2
- functions return type bytea. Use the functions
- encode
- and decode to
- convert between the two. For example write encode(sha256('abc'),
- 'hex') to get a hex-encoded text representation,
- or decode(md5('abc'), 'hex') to get
- a bytea value.
-
-
-
-
- character string
- converting to binary string
-
-
- binary string
- converting to character string
-
- Functions for converting strings between different character sets
- (encodings), and for representing arbitrary binary data in textual
- form, are shown in
- . For these
- functions, an argument or result of type text is expressed
- in the database's default encoding, while arguments or results of
- type bytea are in an encoding named by another argument.
-
-
-
- Text/Binary String Conversion Functions
-
-
-
-
- Function
-
-
- Description
-
-
- Example(s)
-
-
-
-
-
-
-
-
- convert
-
- convert ( bytesbytea,
- src_encodingname,
- dest_encodingname )
- bytea
-
-
- Converts a binary string representing text in
- encoding src_encoding
- to a binary string in encoding dest_encoding
- (see for
- available conversions).
-
-
- convert('text_in_utf8', 'UTF8', 'LATIN1')
- \x746578745f696e5f75746638
-
-
-
-
-
-
- convert_from
-
- convert_from ( bytesbytea,
- src_encodingname )
- text
-
-
- Converts a binary string representing text in
- encoding src_encoding
- to text in the database encoding
- (see for
- available conversions).
-
-
- convert_from('text_in_utf8', 'UTF8')
- text_in_utf8
-
-
-
-
-
-
- convert_to
-
- convert_to ( stringtext,
- dest_encodingname )
- bytea
-
-
- Converts a text string (in the database encoding) to a
- binary string encoded in encoding dest_encoding
- (see for
- available conversions).
-
-
- convert_to('some_text', 'UTF8')
- \x736f6d655f74657874
-
-
-
-
-
-
- encode
-
- encode ( bytesbytea,
- formattext )
- text
-
-
- Encodes binary data into a textual representation; supported
- format values are:
- base64,
- escape,
- hex.
-
-
- encode('123\000\001', 'base64')
- MTIzAAE=
-
-
-
-
-
-
- decode
-
- decode ( stringtext,
- formattext )
- bytea
-
-
- Decodes binary data from a textual representation; supported
- format values are the same as
- for encode.
-
-
- decode('MTIzAAE=', 'base64')
- \x3132330001
-
-
-
-
-
-
-
- The encode and decode
- functions support the following textual formats:
-
-
-
- base64
-
- base64 format
-
-
-
- The base64 format is that
- of RFC
- 2045 Section 6.8. As per the RFC, 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 decode function ignores carriage-return,
- newline, space, and tab characters. Otherwise, an error is
- raised when decode is supplied invalid
- base64 data — including when trailing padding is incorrect.
-
-
-
-
-
- escape
-
- escape format
-
-
-
- The escape format converts zero bytes and
- bytes with the high bit set into octal escape sequences
- (\nnn), and it doubles
- backslashes. Other byte values are represented literally.
- The decode 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.
-
-
-
-
-
- hex
-
- hex format
-
-
-
- The hex format represents each 4 bits of
- data as one hexadecimal digit, 0
- through f, writing the higher-order digit of
- each byte first. The encode function outputs
- the a-f hex digits in lower
- case. Because the smallest unit of data is 8 bits, there are
- always an even number of characters returned
- by encode.
- The decode function
- accepts the a-f characters in
- either upper or lower case. An error is raised
- when decode is given invalid hex data
- — including when given an odd number of characters.
-
-
-
-
-
-
-
- See also the aggregate function string_agg in
- and the large object functions
- in .
-
-
-
-
-
- Bit String Functions and Operators
-
-
- bit strings
- functions
-
-
-
- This section describes functions and operators for examining and
- manipulating bit strings, that is values of the types
- bit and bit varying. (While only
- type bit is mentioned in these tables, values of
- type bit varying can be used interchangeably.)
- Bit strings support the usual comparison operators shown in
- , as well as the
- operators shown in .
-
-
-
- Bit String Operators
-
-
-
-
- Operator
-
-
- Description
-
-
- Example(s)
-
-
-
-
-
-
-
- bit||bit
- bit
-
-
- Concatenation
-
-
- B'10001' || B'011'
- 10001011
-
-
-
-
-
- bit&bit
- bit
-
-
- Bitwise AND (inputs must be of equal length)
-
-
- B'10001' & B'01101'
- 00001
-
-
-
-
-
- bit|bit
- bit
-
-
- Bitwise OR (inputs must be of equal length)
-
-
- B'10001' | B'01101'
- 11101
-
-
-
-
-
- bit#bit
- bit
-
-
- Bitwise exclusive OR (inputs must be of equal length)
-
-
- B'10001' # B'01101'
- 11100
-
-
-
-
-
- ~bit
- bit
-
-
- Bitwise NOT
-
-
- ~ B'10001'
- 01110
-
-
-
-
-
- bit<<integer
- bit
-
-
- Bitwise shift left
- (string length is preserved)
-
-
- B'10001' << 3
- 01000
-
-
-
-
-
- bit>>integer
- bit
-
-
- Bitwise shift right
- (string length is preserved)
-
-
- B'10001' >> 2
- 00100
-
-
-
-
-
-
-
- Some of the functions available for binary strings are also available
- for bit strings, as shown in .
-
-
-
- Bit String Functions
-
-
-
-
- Function
-
-
- Description
-
-
- Example(s)
-
-
-
-
-
-
-
-
- bit_count
-
- bit_count ( bit )
- bigint
-
-
- Returns the number of bits set in the bit string (also known as
- popcount).
-
-
- bit_count(B'10111')
- 4
-
-
-
-
-
-
- bit_length
-
- bit_length ( bit )
- integer
-
-
- Returns number of bits in the bit string.
-
-
- bit_length(B'10111')
- 5
-
-
-
-
-
-
- length
-
-
- bit string
- length
-
- length ( bit )
- integer
-
-
- Returns number of bits in the bit string.
-
-
- length(B'10111')
- 5
-
-
-
-
-
-
- octet_length
-
- octet_length ( bit )
- integer
-
-
- Returns number of bytes in the bit string.
-
-
- octet_length(B'1011111011')
- 2
-
-
-
-
-
-
- overlay
-
- overlay ( bitsbitPLACINGnewsubstringbitFROMstartintegerFORcountinteger )
- bit
-
-
- Replaces the substring of bits that starts at
- the start'th bit and extends
- for count bits
- with newsubstring.
- If count is omitted, it defaults to the length
- of newsubstring.
-
-
- overlay(B'01010101010101010' placing B'11111' from 2 for 3)
- 0111110101010101010
-
-
-
-
-
-
- position
-
- position ( substringbitINbitsbit )
- integer
-
-
- Returns first starting index of the specified substring
- within bits, or zero if it's not present.
-
-
- position(B'010' in B'000001101011')
- 8
-
-
-
-
-
-
- substring
-
- substring ( bitsbitFROMstartintegerFORcountinteger )
- bit
-
-
- Extracts the substring of bits starting at
- the start'th bit if that is specified,
- and stopping after count bits if that is
- specified. Provide at least one of start
- and count.
-
-
- substring(B'110010111111' from 3 for 2)
- 00
-
-
-
-
-
-
- get_bit
-
- get_bit ( bitsbit,
- ninteger )
- integer
-
-
- Extracts n'th bit
- from bit string; the first (leftmost) bit is bit 0.
-
-
- get_bit(B'101010101010101010', 6)
- 1
-
-
-
-
-
-
- set_bit
-
- set_bit ( bitsbit,
- ninteger,
- newvalueinteger )
- bit
-
-
- Sets n'th bit in
- bit string to newvalue;
- the first (leftmost) bit is bit 0.
-
-
- set_bit(B'101010101010101010', 6, 0)
- 101010001010101010
-
-
-
-
-
-
-
- In addition, it is possible to cast integral values to and from type
- bit.
- Casting an integer to bit(n) copies the rightmost
- n bits. Casting an integer to a bit string width wider
- than the integer itself will sign-extend on the left.
- Some examples:
-
-44::bit(10) 0000101100
-44::bit(3) 100
-cast(-44 as bit(12)) 111111010100
-'1110'::bit(4)::integer 14
-
- Note that casting to just bit means casting to
- bit(1), and so will deliver only the least significant
- bit of the integer.
-
-
-
-
-
- Pattern Matching
-
-
- pattern matching
-
-
-
- There are three separate approaches to pattern matching provided
- by PostgreSQL: the traditional
- SQL LIKE operator, the
- more recent SIMILAR TO operator (added in
- SQL:1999), and POSIX-style regular
- expressions. Aside from the basic does this string match
- this pattern? operators, functions are available to extract
- or replace matching substrings and to split a string at matching
- locations.
-
-
-
-
- If you have pattern matching needs that go beyond this,
- consider writing a user-defined function in Perl or Tcl.
-
-
-
-
-
- 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.
-
-
-
- Searches using SIMILAR TO patterns have the same
- security hazards, since SIMILAR TO provides many
- of the same capabilities as POSIX-style regular
- expressions.
-
-
-
- LIKE searches, being much simpler than the other
- two options, are safer to use with possibly-hostile pattern sources.
-
-
-
-
- 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.
-
-
-
- <function>LIKE</function>
-
-
- LIKE
-
-
-
-string LIKE patternESCAPE escape-character
-string NOT LIKE patternESCAPE escape-character
-
-
-
- The LIKE expression returns true if the
- string matches the supplied
- pattern. (As
- expected, the NOT LIKE expression returns
- false if LIKE returns true, and vice versa.
- An equivalent expression is
- NOT (string LIKE
- pattern).)
-
-
-
- If pattern does not contain percent
- signs or underscores, then the pattern only represents the string
- itself; in that case LIKE acts like the
- equals operator. An underscore (_) in
- pattern stands for (matches) any single
- character; a percent sign (%) matches any sequence
- of zero or more characters.
-
-
-
- Some examples:
-
-'abc' LIKE 'abc' true
-'abc' LIKE 'a%' true
-'abc' LIKE '_b_' true
-'abc' LIKE 'c' false
-
-
-
-
- LIKE 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.
-
-
-
- To match a literal underscore or percent sign without matching
- other characters, the respective character in
- pattern must be
- preceded by the escape character. The default escape
- character is the backslash but a different one can be selected by
- using the ESCAPE clause. To match the escape
- character itself, write two escape characters.
-
-
-
-
- If you have turned off,
- any backslashes you write in literal string constants will need to be
- doubled. See for more information.
-
-
-
-
- It's also possible to select no escape character by writing
- ESCAPE ''. This effectively disables the
- escape mechanism, which makes it impossible to turn off the
- special meaning of underscore and percent signs in the pattern.
-
-
-
- According to the SQL standard, omitting ESCAPE
- means there is no escape character (rather than defaulting to a
- backslash), and a zero-length ESCAPE value is
- disallowed. PostgreSQL's behavior in
- this regard is therefore slightly nonstandard.
-
-
-
- The key word ILIKE can be used instead of
- LIKE to make the match case-insensitive according
- to the active locale. This is not in the SQL standard but is a
- PostgreSQL extension.
-
-
-
- The operator ~~ is equivalent to
- LIKE, and ~~* corresponds to
- ILIKE. There are also
- !~~ and !~~* operators that
- represent NOT LIKE and NOT
- ILIKE, respectively. All of these operators are
- PostgreSQL-specific. You may see these
- operator names in EXPLAIN output and similar
- places, since the parser actually translates LIKE
- et al. to these operators.
-
-
-
- The phrases LIKE, ILIKE,
- NOT LIKE, and NOT ILIKE are
- generally treated as operators
- in PostgreSQL syntax; for example they can
- be used in expression
- operator ANY
- (subquery) constructs, although
- an ESCAPE clause cannot be included there. In some
- obscure cases it may be necessary to use the underlying operator names
- instead.
-
-
-
- Also see the starts-with operator ^@ and the
- corresponding starts_with() function, which are
- useful in cases where simply matching the beginning of a string is
- needed.
-
-
-
-
-
- <function>SIMILAR TO</function> Regular Expressions
-
-
- regular expression
-
-
-
-
- SIMILAR TO
-
-
- substring
-
-
-
-string SIMILAR TO patternESCAPE escape-character
-string NOT SIMILAR TO patternESCAPE escape-character
-
-
-
- The SIMILAR TO operator returns true or
- false depending on whether its pattern matches the given string.
- It is similar to LIKE, except that it
- interprets the pattern using the SQL standard's definition of a
- regular expression. SQL regular expressions are a curious cross
- between LIKE notation and common (POSIX) regular
- expression notation.
-
-
-
- Like LIKE, the SIMILAR TO
- 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
- LIKE, SIMILAR TO uses
- _ and % as wildcard characters denoting
- any single character and any string, respectively (these are
- comparable to . and .* in POSIX regular
- expressions).
-
-
-
- In addition to these facilities borrowed from LIKE,
- SIMILAR TO supports these pattern-matching
- metacharacters borrowed from POSIX regular expressions:
-
-
-
-
- | denotes alternation (either of two alternatives).
-
-
-
-
- * denotes repetition of the previous item zero
- or more times.
-
-
-
-
- + denotes repetition of the previous item one
- or more times.
-
-
-
-
- ? denotes repetition of the previous item zero
- or one time.
-
-
-
-
- {m} denotes repetition
- of the previous item exactly m times.
-
-
-
-
- {m,} denotes repetition
- of the previous item m or more times.
-
-
-
-
- {m,n}
- denotes repetition of the previous item at least m and
- not more than n times.
-
-
-
-
- Parentheses () can be used to group items into
- a single logical item.
-
-
-
-
- A bracket expression [...] specifies a character
- class, just as in POSIX regular expressions.
-
-
-
-
- Notice that the period (.) is not a metacharacter
- for SIMILAR TO.
-
-
-
- As with LIKE, a backslash disables the special
- meaning of any of these metacharacters. A different escape character
- can be specified with ESCAPE, or the escape
- capability can be disabled by writing ESCAPE ''.
-
-
-
- According to the SQL standard, omitting ESCAPE
- means there is no escape character (rather than defaulting to a
- backslash), and a zero-length ESCAPE value is
- disallowed. PostgreSQL's behavior in
- this regard is therefore slightly nonstandard.
-
-
-
- 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
- ,
- , and
- below.
-
-
-
- Some examples:
-
-'abc' SIMILAR TO 'abc' true
-'abc' SIMILAR TO 'a' false
-'abc' SIMILAR TO '%(b|d)%' true
-'abc' SIMILAR TO '(b|c)%' false
-'-abc-' SIMILAR TO '%\mabc\M%' true
-'xabcy' SIMILAR TO '%\mabc\M%' false
-
-
-
-
- The substring 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:
-
-substring(string similar pattern escape escape-character)
-
- or using the now obsolete SQL:1999 syntax:
-
-substring(string from pattern for escape-character)
-
- or as a plain three-argument function:
-
-substring(string, pattern, escape-character)
-
- As with SIMILAR TO, 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
- (").
- The text matching the portion of the pattern
- between these separators is returned when the match is successful.
-
-
-
- The escape-double-quote separators actually
- divide substring's pattern into three independent
- regular expressions; for example, a vertical bar (|)
- 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.)
-
-
-
- As an extension to the SQL standard, PostgreSQL
- 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.
-
-
-
- Some examples, with #" delimiting the return string:
-
-substring('foobar' similar '%#"o_b#"%' escape '#') oob
-substring('foobar' similar '#"o_b#"%' escape '#') NULL
-
-
-
-
-
- <acronym>POSIX</acronym> Regular Expressions
-
-
- regular expression
- pattern matching
-
-
- substring
-
-
- regexp_count
-
-
- regexp_instr
-
-
- regexp_like
-
-
- regexp_match
-
-
- regexp_matches
-
-
- regexp_replace
-
-
- regexp_split_to_table
-
-
- regexp_split_to_array
-
-
- regexp_substr
-
-
-
- lists the available
- operators for pattern matching using POSIX regular expressions.
-
-
-
-
-
- POSIX regular expressions provide a more
- powerful means for pattern matching than the LIKE and
- SIMILAR TO operators.
- Many Unix tools such as egrep,
- sed, or awk use a pattern
- matching language that is similar to the one described here.
-
-
-
- A regular expression is a character sequence that is an
- abbreviated definition of a set of strings (a regular
- set). 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 LIKE, pattern characters
- match string characters exactly unless they are special characters
- in the regular expression language — but regular expressions use
- different special characters than LIKE does.
- Unlike LIKE 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.
-
-
-
- Some examples:
-
-'abcd' ~ 'bc' true
-'abcd' ~ 'a.c' true — dot matches any character
-'abcd' ~ 'a.*d' true — * repeats the preceding pattern item
-'abcd' ~ '(b|x)' true — | means OR, parentheses group
-'abcd' ~ '^a' true — ^ anchors to start of string
-'abcd' ~ '^(b|c)' false — would match except for anchoring
-
-
-
-
- The POSIX pattern language is described in much
- greater detail below.
-
-
-
- The substring function with two parameters,
- substring(string from
- pattern), 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.
-
-
-
- Some examples:
-
-substring('foobar' from 'o.b') oob
-substring('foobar' from 'o(.)b') o
-
-
-
-
- The regexp_count function counts the number of
- places where a POSIX regular expression pattern matches a string.
- It has the syntax
- regexp_count(string,
- pattern
- , start
- , flags
- ).
- pattern is searched for
- in string, normally from the beginning of
- the string, but if the start parameter is
- provided then beginning from that character index.
- The flags parameter is an optional text
- string containing zero or more single-letter flags that change the
- function's behavior. For example, including i in
- flags specifies case-insensitive matching.
- Supported flags are described in
- .
-
-
-
- Some examples:
-
-regexp_count('ABCABCAXYaxy', 'A.') 3
-regexp_count('ABCABCAXYaxy', 'A.', 1, 'i') 4
-
-
-
-
- The regexp_instr function returns the starting or
- ending position of the N'th match of a
- POSIX regular expression pattern to a string, or zero if there is no
- such match. It has the syntax
- regexp_instr(string,
- pattern
- , start
- , N
- , endoption
- , flags
- , subexpr
- ).
- pattern is searched for
- in string, normally from the beginning of
- the string, but if the start parameter is
- provided then beginning from that character index.
- If N is specified
- then the N'th match of the pattern
- is located, otherwise the first match is located.
- If the endoption parameter is omitted or
- specified as zero, the function returns the position of the first
- character of the match. Otherwise, endoption
- must be one, and the function returns the position of the character
- following the match.
- The flags parameter is an optional text
- string containing zero or more single-letter flags that change the
- function's behavior. Supported flags are described
- in .
- For a pattern containing parenthesized
- subexpressions, subexpr 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 subexpr is omitted or zero, the result
- identifies the position of the whole match regardless of
- parenthesized subexpressions.
-
-
-
- Some examples:
-
-regexp_instr('number of your street, town zip, FR', '[^,]+', 1, 2)
- 23
-regexp_instr('ABCDEFGHI', '(c..)(...)', 1, 1, 0, 'i', 2)
- 6
-
-
-
-
- The regexp_like function checks whether a match
- of a POSIX regular expression pattern occurs within a string,
- returning boolean true or false. It has the syntax
- regexp_like(string,
- pattern
- , flags).
- The flags parameter is an optional text
- string containing zero or more single-letter flags that change the
- function's behavior. Supported flags are described
- in .
- This function has the same results as the ~
- operator if no flags are specified. If only the i
- flag is specified, it has the same results as
- the ~* operator.
-
-
-
- Some examples:
-
-regexp_like('Hello World', 'world') false
-regexp_like('Hello World', 'world', 'i') true
-
-
-
-
- The regexp_match 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
- regexp_match(string,
- pattern, flags).
- If there is no match, the result is NULL.
- If a match is found, and the pattern contains no
- parenthesized subexpressions, then the result is a single-element text
- array containing the substring matching the whole pattern.
- If a match is found, and the pattern contains
- parenthesized subexpressions, then the result is a text array
- whose n'th element is the substring matching
- the n'th parenthesized subexpression of
- the pattern (not counting non-capturing
- parentheses; see below for details).
- The flags parameter is an optional text string
- containing zero or more single-letter flags that change the function's
- behavior. Supported flags are described
- in .
-
-
-
- Some examples:
-
-SELECT regexp_match('foobarbequebaz', 'bar.*que');
- regexp_match
---------------
- {barbeque}
-(1 row)
-
-SELECT regexp_match('foobarbequebaz', '(bar)(beque)');
- regexp_match
---------------
- {bar,beque}
-(1 row)
-
-
-
-
-
- In the common case where you just want the whole matching substring
- or NULL for no match, the best solution is to
- use regexp_substr().
- However, regexp_substr() only exists
- in PostgreSQL version 15 and up. When
- working in older versions, you can extract the first element
- of regexp_match()'s result, for example:
-
-SELECT (regexp_match('foobarbequebaz', 'bar.*que'))[1];
- regexp_match
---------------
- barbeque
-(1 row)
-
-
-
-
-
- The regexp_matches 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
- regexp_match.
- This function returns no rows if there is no match, one row if there is
- a match and the g flag is not given, or N
- rows if there are N matches and the g flag
- is given. Each returned row is a text array containing the whole
- matched substring or the substrings matching parenthesized
- subexpressions of the pattern, just as described above
- for regexp_match.
- regexp_matches accepts all the flags shown
- in , plus
- the g flag which commands it to return all matches, not
- just the first one.
-
-
-
- Some examples:
-
-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)
-
-
-
-
-
- In most cases regexp_matches() should be used with
- the g flag, since if you only want the first match, it's
- easier and more efficient to use regexp_match().
- However, regexp_match() only exists
- in PostgreSQL version 10 and up. When working in older
- versions, a common trick is to place a regexp_matches()
- call in a sub-select, for example:
-
-SELECT col1, (SELECT regexp_matches(col2, '(bar)(beque)')) FROM tab;
-
- This produces a text array if there's a match, or NULL if
- not, the same as regexp_match() would do. Without the
- sub-select, this query would produce no output at all for table rows
- without a match, which is typically not the desired behavior.
-
-
-
-
- The regexp_replace function provides substitution of
- new text for substrings that match POSIX regular expression patterns.
- It has the syntax
- regexp_replace(source,
- pattern, replacement
- , start
- , N
-
- , flags).
- (Notice that N cannot be specified
- unless start is,
- but flags can be given in any case.)
- The source string is returned unchanged if
- there is no match to the pattern. If there is a
- match, the source string is returned with the
- replacement string substituted for the matching
- substring. The replacement string can contain
- \n, where n is 1
- through 9, to indicate that the source substring matching the
- n'th parenthesized subexpression of the pattern should be
- inserted, and it can contain \& to indicate that the
- substring matching the entire pattern should be inserted. Write
- \\ if you need to put a literal backslash in the replacement
- text.
- pattern is searched for
- in string, normally from the beginning of
- the string, but if the start parameter is
- provided then beginning from that character index.
- By default, only the first match of the pattern is replaced.
- If N is specified and is greater than zero,
- then the N'th match of the pattern
- is replaced.
- If the g flag is given, or
- if N is specified and is zero, then all
- matches at or after the start position are
- replaced. (The g flag is ignored
- when N is specified.)
- The flags parameter is an optional text
- string containing zero or more single-letter flags that change the
- function's behavior. Supported flags (though
- not g) are
- described in .
-
-
-
- Some examples:
-
-regexp_replace('foobarbaz', 'b..', 'X')
- fooXbaz
-regexp_replace('foobarbaz', 'b..', 'X', 'g')
- fooXX
-regexp_replace('foobarbaz', 'b(..)', 'X\1Y', 'g')
- fooXarYXazY
-regexp_replace('A PostgreSQL function', 'a|e|i|o|u', 'X', 1, 0, 'i')
- X PXstgrXSQL fXnctXXn
-regexp_replace('A PostgreSQL function', 'a|e|i|o|u', 'X', 1, 3, 'i')
- A PostgrXSQL function
-
-
-
-
- The regexp_split_to_table function splits a string using a POSIX
- regular expression pattern as a delimiter. It has the syntax
- regexp_split_to_table(string, pattern
- , flags).
- If there is no match to the pattern, the function returns the
- string. 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 flags parameter is an optional text string containing
- zero or more single-letter flags that change the function's behavior.
- regexp_split_to_table supports the flags described in
- .
-
-
-
- The regexp_split_to_array function behaves the same as
- regexp_split_to_table, except that regexp_split_to_array
- returns its result as an array of text. It has the syntax
- regexp_split_to_array(string, pattern
- , flags).
- The parameters are the same as for regexp_split_to_table.
-
-
-
- Some examples:
-
-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)
-
-
-
-
- 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.
-
-
-
- The regexp_substr function returns the substring
- that matches a POSIX regular expression pattern,
- or NULL if there is no match. It has the syntax
- regexp_substr(string,
- pattern
- , start
- , N
- , flags
- , subexpr
- ).
- pattern is searched for
- in string, normally from the beginning of
- the string, but if the start parameter is
- provided then beginning from that character index.
- If N is specified
- then the N'th match of the pattern
- is returned, otherwise the first match is returned.
- The flags parameter is an optional text
- string containing zero or more single-letter flags that change the
- function's behavior. Supported flags are described
- in .
- For a pattern containing parenthesized
- subexpressions, subexpr 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 subexpr is omitted or zero, the result
- is the whole match regardless of parenthesized subexpressions.
-
-
-
- Some examples:
-
-regexp_substr('number of your street, town zip, FR', '[^,]+', 1, 2)
- town zip
-regexp_substr('ABCDEFGHI', '(c..)(...)', 1, 1, 'i', 2)
- FGH
-
-
-
-
-
-
- Regular Expression Details
-
-
- PostgreSQL'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.
-
-
-
- Regular expressions (REs), as defined in
- POSIX 1003.2, come in two forms:
- extended REs or EREs
- (roughly those of egrep), and
- basic REs or BREs
- (roughly those of ed).
- PostgreSQL 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.
- REs using these non-POSIX extensions are called
- advanced REs or AREs
- 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.
-
-
-
-
- PostgreSQL always initially presumes that a regular
- expression follows the ARE rules. However, the more limited ERE or
- BRE rules can be chosen by prepending an embedded option
- to the RE pattern, as described in .
- This can be useful for compatibility with applications that expect
- exactly the POSIX 1003.2 rules.
-
-
-
-
- A regular expression is defined as one or more
- branches, separated by
- |. It matches anything that matches one of the
- branches.
-
-
-
- A branch is zero or more quantified atoms or
- constraints, concatenated.
- It matches a match for the first, followed by a match for the second, etc.;
- an empty branch matches the empty string.
-
-
-
- A quantified atom is an atom possibly followed
- by a single quantifier.
- Without a quantifier, it matches a match for the atom.
- With a quantifier, it can match some number of matches of the atom.
- An atom can be any of the possibilities
- shown in .
- The possible quantifiers and their meanings are shown in
- .
-
-
-
- A constraint 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
- ;
- some more constraints are described later.
-
-
-
-
- Regular Expression Atoms
-
-
-
-
- Atom
- Description
-
-
-
-
-
- (re)
- (where re is any regular expression)
- matches a match for
- re, with the match noted for possible reporting
-
-
-
- (?:re)
- as above, but the match is not noted for reporting
- (a non-capturing set of parentheses)
- (AREs only)
-
-
-
- .
- matches any single character
-
-
-
- [chars]
- a bracket expression,
- matching any one of the chars (see
- for more detail)
-
-
-
- \k
- (where k is a non-alphanumeric character)
- matches that character taken as an ordinary character,
- e.g., \\ matches a backslash character
-
-
-
- \c
- where c is alphanumeric
- (possibly followed by other characters)
- is an escape, see
- (AREs only; in EREs and BREs, this matches c)
-
-
-
- {
- when followed by a character other than a digit,
- matches the left-brace character {;
- when followed by a digit, it is the beginning of a
- bound (see below)
-
-
-
- x
- where x is a single character with no other
- significance, matches that character
-
-
-
-
-
-
- An RE cannot end with a backslash (\).
-
-
-
-
- If you have turned off,
- any backslashes you write in literal string constants will need to be
- doubled. See for more information.
-
-
-
-
- Regular Expression Quantifiers
-
-
-
-
- Quantifier
- Matches
-
-
-
-
-
- *
- a sequence of 0 or more matches of the atom
-
-
-
- +
- a sequence of 1 or more matches of the atom
-
-
-
- ?
- a sequence of 0 or 1 matches of the atom
-
-
-
- {m}
- a sequence of exactly m matches of the atom
-
-
-
- {m,}
- a sequence of m or more matches of the atom
-
-
-
-
- {m,n}
- a sequence of m through n
- (inclusive) matches of the atom; m cannot exceed
- n
-
-
-
- *?
- non-greedy version of *
-
-
-
- +?
- non-greedy version of +
-
-
-
- ??
- non-greedy version of ?
-
-
-
- {m}?
- non-greedy version of {m}
-
-
-
- {m,}?
- non-greedy version of {m,}
-
-
-
-
- {m,n}?
- non-greedy version of {m,n}
-
-
-
-
-
-
- The forms using {...}
- are known as bounds.
- The numbers m and n within a bound are
- unsigned decimal integers with permissible values from 0 to 255 inclusive.
-
-
-
- Non-greedy quantifiers (available in AREs only) match the
- same possibilities as their corresponding normal (greedy)
- counterparts, but prefer the smallest number rather than the largest
- number of matches.
- See for more detail.
-
-
-
-
- A quantifier cannot immediately follow another quantifier, e.g.,
- ** is invalid.
- A quantifier cannot
- begin an expression or subexpression or follow
- ^ or |.
-
-
-
-
- Regular Expression Constraints
-
-
-
-
- Constraint
- Description
-
-
-
-
-
- ^
- matches at the beginning of the string
-
-
-
- $
- matches at the end of the string
-
-
-
- (?=re)
- positive lookahead matches at any point
- where a substring matching re begins
- (AREs only)
-
-
-
- (?!re)
- negative lookahead matches at any point
- where no substring matching re begins
- (AREs only)
-
-
-
- (?<=re)
- positive lookbehind matches at any point
- where a substring matching re ends
- (AREs only)
-
-
-
- (?<!re)
- negative lookbehind matches at any point
- where no substring matching re ends
- (AREs only)
-
-
-
-
-
-
- Lookahead and lookbehind constraints cannot contain back
- references (see ),
- and all parentheses within them are considered non-capturing.
-
-
-
-
- Bracket Expressions
-
-
- A bracket expression is a list of
- characters enclosed in []. It normally matches
- any single character from the list (but see below). If the list
- begins with ^, it matches any single character
- not from the rest of the list.
- If two characters
- in the list are separated by -, this is
- shorthand for the full range of characters between those two
- (inclusive) in the collating sequence,
- e.g., [0-9] in ASCII matches
- any decimal digit. It is illegal for two ranges to share an
- endpoint, e.g., a-c-e. Ranges are very
- collating-sequence-dependent, so portable programs should avoid
- relying on them.
-
-
-
- To include a literal ] in the list, make it the
- first character (after ^, if that is used). To
- include a literal -, make it the first or last
- character, or the second endpoint of a range. To use a literal
- - as the first endpoint of a range, enclose it
- in [. and .] to make it a
- collating element (see below). With the exception of these characters,
- some combinations using [
- (see next paragraphs), and escapes (AREs only), all other special
- characters lose their special significance within a bracket expression.
- In particular, \ is not special when following
- ERE or BRE rules, though it is special (as introducing an escape)
- in AREs.
-
-
-
- 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
- [. and .] 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 ch collating element, then the RE
- [[.ch.]]*c matches the first five characters of
- chchcc.
-
-
-
-
- PostgreSQL currently does not support multi-character collating
- elements. This information describes possible future behavior.
-
-
-
-
- Within a bracket expression, a collating element enclosed in
- [= and =] is an equivalence
- class, 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 [. and
- .].) For example, if o and
- ^ are the members of an equivalence class, then
- [[=o=]], [[=^=]], and
- [o^] are all synonymous. An equivalence class
- cannot be an endpoint of a range.
-
-
-
- Within a bracket expression, the name of a character class
- enclosed in [: and :] stands
- for the list of all characters belonging to that class. A character
- class cannot be used as an endpoint of a range.
- The POSIX standard defines these character class
- names:
- alnum (letters and numeric digits),
- alpha (letters),
- blank (space and tab),
- cntrl (control characters),
- digit (numeric digits),
- graph (printable characters except space),
- lower (lower-case letters),
- print (printable characters including space),
- punct (punctuation),
- space (any white space),
- upper (upper-case letters),
- and xdigit (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 collation
- that is used for the regular-expression function or operator
- (see ), or by default on the
- database's LC_CTYPE locale setting (see
- ). The classification of non-ASCII
- characters can vary across platforms even in similarly-named
- locales. (But the C locale never considers any
- non-ASCII characters to belong to any of these classes.)
- In addition to these standard character
- classes, PostgreSQL defines
- the word character class, which is the same as
- alnum plus the underscore (_)
- character, and
- the ascii character class, which contains exactly
- the 7-bit ASCII set.
-
-
-
- There are two special cases of bracket expressions: the bracket
- expressions [[:<:]] and
- [[:>:]] 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
- word character class, that is, any letter, digit,
- or underscore. This is an extension, compatible with but not
- specified by POSIX 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.
-
-
-
-
- Regular Expression Escapes
-
-
- Escapes are special sequences beginning with \
- followed by an alphanumeric character. Escapes come in several varieties:
- character entry, class shorthands, constraint escapes, and back references.
- A \ 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 \ followed by an alphanumeric character merely stands for
- that character as an ordinary character, and inside a bracket expression,
- \ is an ordinary character.
- (The latter is the one actual incompatibility between EREs and AREs.)
-
-
-
- Character-entry escapes exist to make it easier to specify
- non-printing and other inconvenient characters in REs. They are
- shown in .
-
-
-
- Class-shorthand escapes provide shorthands for certain
- commonly-used character classes. They are
- shown in .
-
-
-
- A constraint escape is a constraint,
- matching the empty string if specific conditions are met,
- written as an escape. They are
- shown in .
-
-
-
- A back reference (\n) matches the
- same string matched by the previous parenthesized subexpression specified
- by the number n
- (see ). For example,
- ([bc])\1 matches bb or cc
- but not bc or cb.
- The subexpression must entirely precede the back reference in the RE.
- 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, (^\d)\1 will match 22.
-
-
-
- Regular Expression Character-Entry Escapes
-
-
-
-
- Escape
- Description
-
-
-
-
-
- \a
- alert (bell) character, as in C
-
-
-
- \b
- backspace, as in C
-
-
-
- \B
- synonym for backslash (\) to help reduce the need for backslash
- doubling
-
-
-
- \cX
- (where X is any character) the character whose
- low-order 5 bits are the same as those of
- X, and whose other bits are all zero
-
-
-
- \e
- the character whose collating-sequence name
- is ESC,
- or failing that, the character with octal value 033
-
-
-
- \f
- form feed, as in C
-
-
-
- \n
- newline, as in C
-
-
-
- \r
- carriage return, as in C
-
-
-
- \t
- horizontal tab, as in C
-
-
-
- \uwxyz
- (where wxyz is exactly four hexadecimal digits)
- the character whose hexadecimal value is
- 0xwxyz
-
-
-
-
- \Ustuvwxyz
- (where stuvwxyz is exactly eight hexadecimal
- digits)
- the character whose hexadecimal value is
- 0xstuvwxyz
-
-
-
-
- \v
- vertical tab, as in C
-
-
-
- \xhhh
- (where hhh is any sequence of hexadecimal
- digits)
- the character whose hexadecimal value is
- 0xhhh
- (a single character no matter how many hexadecimal digits are used)
-
-
-
-
- \0
- the character whose value is 0 (the null byte)
-
-
-
- \xy
- (where xy is exactly two octal digits,
- and is not a back reference)
- the character whose octal value is
- 0xy
-
-
-
- \xyz
- (where xyz is exactly three octal digits,
- and is not a back reference)
- the character whose octal value is
- 0xyz
-
-
-
-
-
-
- Hexadecimal digits are 0-9,
- a-f, and A-F.
- Octal digits are 0-7.
-
-
-
- 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 \u1234 means the character U+1234.
- 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.
-
-
-
- The character-entry escapes are always taken as ordinary characters.
- For example, \135 is ] in ASCII, but
- \135 does not terminate a bracket expression.
-
-
-
- Regular Expression Class-Shorthand Escapes
-
-
-
-
- Escape
- Description
-
-
-
-
-
- \d
- matches any digit, like
- [[:digit:]]
-
-
-
- \s
- matches any whitespace character, like
- [[:space:]]
-
-
-
- \w
- matches any word character, like
- [[:word:]]
-
-
-
- \D
- matches any non-digit, like
- [^[:digit:]]
-
-
-
- \S
- matches any non-whitespace character, like
- [^[:space:]]
-
-
-
- \W
- matches any non-word character, like
- [^[:word:]]
-
-
-
-
-
-
- The class-shorthand escapes also work within bracket expressions,
- although the definitions shown above are not quite syntactically
- valid in that context.
- For example, [a-c\d] is equivalent to
- [a-c[:digit:]].
-
-
-
- Regular Expression Constraint Escapes
-
-
-
-
- Escape
- Description
-
-
-
-
-
- \A
- matches only at the beginning of the string
- (see for how this differs from
- ^)
-
-
-
- \m
- matches only at the beginning of a word
-
-
-
- \M
- matches only at the end of a word
-
-
-
- \y
- matches only at the beginning or end of a word
-
-
-
- \Y
- matches only at a point that is not the beginning or end of a
- word
-
-
-
- \Z
- matches only at the end of the string
- (see for how this differs from
- $)
-
-
-
-
-
-
- A word is defined as in the specification of
- [[:<:]] and [[:>:]] above.
- Constraint escapes are illegal within bracket expressions.
-
-
-
- Regular Expression Back References
-
-
-
-
- Escape
- Description
-
-
-
-
-
- \m
- (where m is a nonzero digit)
- a back reference to the m'th subexpression
-
-
-
- \mnn
- (where m is a nonzero digit, and
- nn is some more digits, and the decimal value
- mnn is not greater than the number of closing capturing
- parentheses seen so far)
- a back reference to the mnn'th subexpression
-
-
-
-
-
-
-
- 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.
-
-
-
-
-
- Regular Expression Metasyntax
-
-
- In addition to the main syntax described above, there are some special
- forms and miscellaneous syntactic facilities available.
-
-
-
- An RE can begin with one of two special director prefixes.
- If an RE begins with ***:,
- the rest of the RE is taken as an ARE. (This normally has no effect in
- PostgreSQL, since REs are assumed to be AREs;
- but it does have an effect if ERE or BRE mode had been specified by
- the flags parameter to a regex function.)
- If an RE begins with ***=,
- the rest of the RE is taken to be a literal string,
- with all characters considered ordinary characters.
-
-
-
- An ARE can begin with embedded options:
- a sequence (?xyz)
- (where xyz 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 flags parameter to a regex
- function.
- The available option letters are
- shown in .
- Note that these same option letters are used in the flags
- parameters of regex functions.
-
-
-
- ARE Embedded-Option Letters
-
-
-
-
- Option
- Description
-
-
-
-
-
- b
- rest of RE is a BRE
-
-
-
- c
- case-sensitive matching (overrides operator type)
-
-
-
- e
- rest of RE is an ERE
-
-
-
- i
- case-insensitive matching (see
- ) (overrides operator type)
-
-
-
- m
- historical synonym for n
-
-
-
- n
- newline-sensitive matching (see
- )
-
-
-
- p
- partial newline-sensitive matching (see
- )
-
-
-
- q
- rest of RE is a literal (quoted) string, all ordinary
- characters
-
-
-
- s
- non-newline-sensitive matching (default)
-
-
-
- t
- tight syntax (default; see below)
-
-
-
- w
- inverse partial newline-sensitive (weird) matching
- (see )
-
-
-
- x
- expanded syntax (see below)
-
-
-
-
-
-
- Embedded options take effect at the ) terminating the sequence.
- They can appear only at the start of an ARE (after the
- ***: director if any).
-
-
-
- In addition to the usual (tight) RE syntax, in which all
- characters are significant, there is an expanded syntax,
- available by specifying the embedded x option.
- In the expanded syntax,
- white-space characters in the RE are ignored, as are
- all characters between a #
- 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:
-
-
-
-
- a white-space character or # preceded by \ is
- retained
-
-
-
-
- white space or # within a bracket expression is retained
-
-
-
-
- white space and comments cannot appear within multi-character symbols,
- such as (?:
-
-
-
-
- For this purpose, white-space characters are blank, tab, newline, and
- any character that belongs to the space character class.
-
-
-
- Finally, in an ARE, outside bracket expressions, the sequence
- (?#ttt)
- (where ttt is any text not containing a ))
- is a comment, completely ignored.
- Again, this is not allowed between the characters of
- multi-character symbols, like (?:.
- Such comments are more a historical artifact than a useful facility,
- and their use is deprecated; use the expanded syntax instead.
-
-
-
- None of these metasyntax extensions is available if
- an initial ***= director
- has specified that the user's input be treated as a literal string
- rather than as an RE.
-
-
-
-
- Regular Expression Matching Rules
-
-
- 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 greedy or
- non-greedy.
-
-
-
- Whether an RE is greedy or not is determined by the following rules:
-
-
-
- Most atoms, and all constraints, have no greediness attribute (because
- they cannot match variable amounts of text anyway).
-
-
-
-
- Adding parentheses around an RE does not change its greediness.
-
-
-
-
- A quantified atom with a fixed-repetition quantifier
- ({m}
- or
- {m}?)
- has the same greediness (possibly none) as the atom itself.
-
-
-
-
- A quantified atom with other normal quantifiers (including
- {m,n}
- with m equal to n)
- is greedy (prefers longest match).
-
-
-
-
- A quantified atom with a non-greedy quantifier (including
- {m,n}?
- with m equal to n)
- is non-greedy (prefers shortest match).
-
-
-
-
- A branch — that is, an RE that has no top-level
- | operator — has the same greediness as the first
- quantified atom in it that has a greediness attribute.
-
-
-
-
- An RE consisting of two or more branches connected by the
- | operator is always greedy.
-
-
-
-
-
-
- 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 as a whole. 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.
-
-
-
- An example of what this means:
-
-SELECT SUBSTRING('XY1234Z', 'Y*([0-9]{1,3})');
-Result: 123
-SELECT SUBSTRING('XY1234Z', 'Y*?([0-9]{1,3})');
-Result: 1
-
- In the first case, the RE as a whole is greedy because Y*
- is greedy. It can match beginning at the Y, and it matches
- the longest possible string starting there, i.e., Y123.
- The output is the parenthesized part of that, or 123.
- In the second case, the RE as a whole is non-greedy because Y*?
- is non-greedy. It can match beginning at the Y, and it matches
- the shortest possible string starting there, i.e., Y1.
- The subexpression [0-9]{1,3} is greedy but it cannot change
- the decision as to the overall match length; so it is forced to match
- just 1.
-
-
-
- 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 eat relative to each other.
-
-
-
- The quantifiers {1,1} and {1,1}?
- 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:
-
-SELECT regexp_match('abc01234xyz', '(.*)(\d+)(.*)');
-Result: {abc0123,4,xyz}
-
- That didn't work: the first .* is greedy so
- it eats as much as it can, leaving the \d+ to
- match at the last possible place, the last digit. We might try to fix
- that by making it non-greedy:
-
-SELECT regexp_match('abc01234xyz', '(.*?)(\d+)(.*)');
-Result: {abc,0,""}
-
- 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:
-
-SELECT regexp_match('abc01234xyz', '(?:(.*?)(\d+)(.*)){1,1}');
-Result: {abc,01234,xyz}
-
- Controlling the RE's overall greediness separately from its components'
- greediness allows great flexibility in handling variable-length patterns.
-
-
-
- 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:
- bb*
- matches the three middle characters of abbbc;
- (week|wee)(night|knights)
- matches all ten characters of weeknights;
- when (.*).*
- is matched against abc the parenthesized subexpression
- matches all three characters; and when
- (a*)* is matched against bc
- both the whole RE and the parenthesized
- subexpression match an empty string.
-
-
-
- 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., x becomes [xX].
- When it appears inside a bracket expression, all case counterparts
- of it are added to the bracket expression, e.g.,
- [x] becomes [xX]
- and [^x] becomes [^xX].
-
-
-
- If newline-sensitive matching is specified, .
- and bracket expressions using ^
- will never match the newline character
- (so that matches will not cross lines unless the RE
- explicitly includes a newline)
- and ^ and $
- 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 \A and \Z
- continue to match beginning or end of string only.
- Also, the character class shorthands \D
- and \W will match a newline regardless of this mode.
- (Before PostgreSQL 14, they did not match
- newlines when in newline-sensitive mode.
- Write [^[:digit:]]
- or [^[:word:]] to get the old behavior.)
-
-
-
- If partial newline-sensitive matching is specified,
- this affects . and bracket expressions
- as with newline-sensitive matching, but not ^
- and $.
-
-
-
- If inverse partial newline-sensitive matching is specified,
- this affects ^ and $
- as with newline-sensitive matching, but not .
- and bracket expressions.
- This isn't very useful but is provided for symmetry.
-
-
-
-
- Limits and Compatibility
-
-
- 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.
-
-
-
- The only feature of AREs that is actually incompatible with
- POSIX EREs is that \ 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 *** syntax of directors likewise is outside the POSIX
- syntax for both BREs and EREs.
-
-
-
- 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 \b, \B,
- 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.
-
-
-
-
- Basic Regular Expressions
-
-
- BREs differ from EREs in several respects.
- In BREs, |, +, and ?
- are ordinary characters and there is no equivalent
- for their functionality.
- The delimiters for bounds are
- \{ and \},
- with { and }
- by themselves ordinary characters.
- The parentheses for nested subexpressions are
- \( and \),
- with ( and ) by themselves ordinary characters.
- ^ is an ordinary character except at the beginning of the
- RE or the beginning of a parenthesized subexpression,
- $ is an ordinary character except at the end of the
- RE or the end of a parenthesized subexpression,
- and * is an ordinary character if it appears at the beginning
- of the RE or the beginning of a parenthesized subexpression
- (after a possible leading ^).
- Finally, single-digit back references are available, and
- \< and \>
- are synonyms for
- [[:<:]] and [[:>:]]
- respectively; no other escapes are available in BREs.
-
-
-
-
-
-
- Differences from SQL Standard and XQuery
-
-
- LIKE_REGEX
-
-
-
- OCCURRENCES_REGEX
-
-
-
- POSITION_REGEX
-
-
-
- SUBSTRING_REGEX
-
-
-
- TRANSLATE_REGEX
-
-
-
- XQuery regular expressions
-
-
-
- Since SQL:2008, the SQL standard includes regular expression operators
- and functions that performs pattern
- matching according to the XQuery regular expression
- standard:
-
- LIKE_REGEX
- OCCURRENCES_REGEX
- POSITION_REGEX
- SUBSTRING_REGEX
- TRANSLATE_REGEX
-
- PostgreSQL does not currently implement these
- operators and functions. You can get approximately equivalent
- functionality in each case as shown in . (Various optional clauses on
- both sides have been omitted in this table.)
-
-
-
-
-
- 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.
-
-
-
- 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:
-
-
-
-
- XQuery character class subtraction is not supported. An example of
- this feature is using the following to match only English
- consonants: [a-z-[aeiou]].
-
-
-
-
- XQuery character class shorthands \c,
- \C, \i,
- and \I are not supported.
-
-
-
-
- XQuery character class elements
- using \p{UnicodeProperty} or the
- inverse \P{UnicodeProperty} are not supported.
-
-
-
-
- POSIX interprets character classes such as \w
- (see )
- according to the prevailing locale (which you can control by
- attaching a COLLATE 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.
-
-
-
-
- The SQL standard (not XQuery itself) attempts to cater for more
- variants of newline than POSIX does. The
- newline-sensitive matching options described above consider only
- ASCII NL (\n) to be a newline, but SQL would have
- us treat CR (\r), CRLF (\r\n)
- (a Windows-style newline), and some Unicode-only characters like
- LINE SEPARATOR (U+2028) as newlines as well.
- Notably, . and \s should
- count \r\n as one character not two according to
- SQL.
-
-
-
-
- Of the character-entry escapes described in
- ,
- XQuery supports only \n, \r,
- and \t.
-
-
-
-
- XQuery does not support
- the [:name:] syntax
- for character classes within bracket expressions.
-
-
-
-
- XQuery does not have lookahead or lookbehind constraints,
- nor any of the constraint escapes described in
- .
-
-
-
-
- The metasyntax forms described in
- do not exist in XQuery.
-
-
-
-
- The regular expression flag letters defined by XQuery are
- related to but not the same as the option letters for POSIX
- (). While the
- i and q options behave the
- same, others do not:
-
-
-
- XQuery's s (allow dot to match newline)
- and m (allow ^
- and $ to match at newlines) flags provide
- access to the same behaviors as
- POSIX's n, p
- and w flags, but they
- do not match the behavior of
- POSIX's s and m flags.
- Note in particular that dot-matches-newline is the default
- behavior in POSIX but not XQuery.
-
-
-
-
- XQuery's x (ignore whitespace in pattern) flag
- is noticeably different from POSIX's expanded-mode flag.
- POSIX's x flag also
- allows # to begin a comment in the pattern,
- and POSIX will not ignore a whitespace character after a
- backslash.
-
-
-
-
-
-
-
-
-
-
-
-
-
-
- Data Type Formatting Functions
-
-
- formatting
-
-
-
- The PostgreSQL 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.
- 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.
-
-
-
- Formatting Functions
-
-
-
-
- Function
-
-
- Description
-
-
- Example(s)
-
-
-
-
-
-
-
-
- to_char
-
- to_char ( timestamp, text )
- text
-
-
- to_char ( timestamp with time zone, text )
- text
-
-
- Converts time stamp to string according to the given format.
-
-
- to_char(timestamp '2002-04-20 17:31:12.66', 'HH12:MI:SS')
- 05:31:12
-
-
-
-
-
- to_char ( interval, text )
- text
-
-
- Converts interval to string according to the given format.
-
-
- to_char(interval '15h 2m 12s', 'HH24:MI:SS')
- 15:02:12
-
-
-
-
-
- to_char ( numeric_type, text )
- text
-
-
- Converts number to string according to the given format; available
- for integer, bigint, numeric,
- real, double precision.
-
-
- to_char(125, '999')
- 125
-
-
- to_char(125.8::real, '999D9')
- 125.8
-
-
- to_char(-125.8, '999D99S')
- 125.80-
-
-
-
-
-
-
- to_date
-
- to_date ( text, text )
- date
-
-
- Converts string to date according to the given format.
-
-
- to_date('05 Dec 2000', 'DD Mon YYYY')
- 2000-12-05
-
-
-
-
-
-
- to_number
-
- to_number ( text, text )
- numeric
-
-
- Converts string to numeric according to the given format.
-
-
- to_number('12,454.8-', '99G999D9S')
- -12454.8
-
-
-
-
-
-
- to_timestamp
-
- to_timestamp ( text, text )
- timestamp with time zone
-
-
- Converts string to time stamp according to the given format.
- (See also to_timestamp(double precision) in
- .)
-
-
- to_timestamp('05 Dec 2000', 'DD Mon YYYY')
- 2000-12-05 00:00:00-05
-
-
-
-
-
-
-
-
- to_timestamp and to_date
- 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, to_number is unnecessary for standard numeric
- representations.
-
-
-
-
- In a to_char 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).
-
-
-
- shows the
- template patterns available for formatting date and time values.
-
-
-
- Template Patterns for Date/Time Formatting
-
-
-
- Pattern
- Description
-
-
-
-
- HH
- hour of day (01–12)
-
-
- HH12
- hour of day (01–12)
-
-
- HH24
- hour of day (00–23)
-
-
- MI
- minute (00–59)
-
-
- SS
- second (00–59)
-
-
- MS
- millisecond (000–999)
-
-
- US
- microsecond (000000–999999)
-
-
- FF1
- tenth of second (0–9)
-
-
- FF2
- hundredth of second (00–99)
-
-
- FF3
- millisecond (000–999)
-
-
- FF4
- tenth of a millisecond (0000–9999)
-
-
- FF5
- hundredth of a millisecond (00000–99999)
-
-
- FF6
- microsecond (000000–999999)
-
-
- SSSS, SSSSS
- seconds past midnight (0–86399)
-
-
- AM, am,
- PM or pm
- meridiem indicator (without periods)
-
-
- A.M., a.m.,
- P.M. or p.m.
- meridiem indicator (with periods)
-
-
- Y,YYY
- year (4 or more digits) with comma
-
-
- YYYY
- year (4 or more digits)
-
-
- YYY
- last 3 digits of year
-
-
- YY
- last 2 digits of year
-
-
- Y
- last digit of year
-
-
- IYYY
- ISO 8601 week-numbering year (4 or more digits)
-
-
- IYY
- last 3 digits of ISO 8601 week-numbering year
-
-
- IY
- last 2 digits of ISO 8601 week-numbering year
-
-
- I
- last digit of ISO 8601 week-numbering year
-
-
- BC, bc,
- AD or ad
- era indicator (without periods)
-
-
- B.C., b.c.,
- A.D. or a.d.
- era indicator (with periods)
-
-
- MONTH
- full upper case month name (blank-padded to 9 chars)
-
-
- Month
- full capitalized month name (blank-padded to 9 chars)
-
-
- month
- full lower case month name (blank-padded to 9 chars)
-
-
- MON
- abbreviated upper case month name (3 chars in English, localized lengths vary)
-
-
- Mon
- abbreviated capitalized month name (3 chars in English, localized lengths vary)
-
-
- mon
- abbreviated lower case month name (3 chars in English, localized lengths vary)
-
-
- MM
- month number (01–12)
-
-
- DAY
- full upper case day name (blank-padded to 9 chars)
-
-
- Day
- full capitalized day name (blank-padded to 9 chars)
-
-
- day
- full lower case day name (blank-padded to 9 chars)
-
-
- DY
- abbreviated upper case day name (3 chars in English, localized lengths vary)
-
-
- Dy
- abbreviated capitalized day name (3 chars in English, localized lengths vary)
-
-
- dy
- abbreviated lower case day name (3 chars in English, localized lengths vary)
-
-
- DDD
- day of year (001–366)
-
-
- IDDD
- day of ISO 8601 week-numbering year (001–371; day 1 of the year is Monday of the first ISO week)
-
-
- DD
- day of month (01–31)
-
-
- D
- day of the week, Sunday (1) to Saturday (7)
-
-
- ID
- ISO 8601 day of the week, Monday (1) to Sunday (7)
-
-
- W
- week of month (1–5) (the first week starts on the first day of the month)
-
-
- WW
- week number of year (1–53) (the first week starts on the first day of the year)
-
-
- IW
- week number of ISO 8601 week-numbering year (01–53; the first Thursday of the year is in week 1)
-
-
- CC
- century (2 digits) (the twenty-first century starts on 2001-01-01)
-
-
- J
- Julian Date (integer days since November 24, 4714 BC at local
- midnight; see )
-
-
- Q
- quarter
-
-
- RM
- month in upper case Roman numerals (I–XII; I=January)
-
-
- rm
- month in lower case Roman numerals (i–xii; i=January)
-
-
- TZ
- upper case time-zone abbreviation
-
-
- tz
- lower case time-zone abbreviation
-
-
- TZH
- time-zone hours
-
-
- TZM
- time-zone minutes
-
-
- OF
- time-zone offset from UTC (HH
- or HH:MM)
-
-
-
-
-
-
- Modifiers can be applied to any template pattern to alter its
- behavior. For example, FMMonth
- is the Month pattern with the
- FM modifier.
- shows the
- modifier patterns for date/time formatting.
-
-
-
- Template Pattern Modifiers for Date/Time Formatting
-
-
-
- Modifier
- Description
- Example
-
-
-
-
- FM prefix
- fill mode (suppress leading zeroes and padding blanks)
- FMMonth
-
-
- TH suffix
- upper case ordinal number suffix
- DDTH, e.g., 12TH
-
-
- th suffix
- lower case ordinal number suffix
- DDth, e.g., 12th
-
-
- FX prefix
- fixed format global option (see usage notes)
- FX Month DD Day
-
-
- TM prefix
- translation mode (use localized day and month names based on
- )
- TMMonth
-
-
- SP suffix
- spell mode (not implemented)
- DDSP
-
-
-
-
-
-
- Usage notes for date/time formatting:
-
-
-
-
- FM suppresses leading zeroes and trailing blanks
- that would otherwise be added to make the output of a pattern be
- fixed-width. In PostgreSQL,
- FM modifies only the next specification, while in
- Oracle FM affects all subsequent
- specifications, and repeated FM modifiers
- toggle fill mode on and off.
-
-
-
-
-
- TM suppresses trailing blanks whether or
- not FM is specified.
-
-
-
-
-
- to_timestamp and to_date
- ignore letter case in the input; so for
- example MON, Mon,
- and mon all accept the same strings. When using
- the TM modifier, case-folding is done according to
- the rules of the function's input collation (see
- ).
-
-
-
-
-
- to_timestamp and to_date
- skip multiple blank spaces at the beginning of the input string and
- around date and time values unless the FX option is used. For example,
- to_timestamp(' 2000 JUN', 'YYYY MON') and
- to_timestamp('2000 - JUN', 'YYYY-MON') work, but
- to_timestamp('2000 JUN', 'FXYYYY MON') returns an error
- because to_timestamp expects only a single space.
- FX must be specified as the first item in
- the template.
-
-
-
-
-
- A separator (a space or non-letter/non-digit character) in the template string of
- to_timestamp and to_date
- matches any single separator in the input string or is skipped,
- unless the FX option is used.
- For example, to_timestamp('2000JUN', 'YYYY///MON') and
- to_timestamp('2000/JUN', 'YYYY MON') work, but
- to_timestamp('2000//JUN', 'YYYY/MON')
- returns an error because the number of separators in the input string
- exceeds the number of separators in the template.
-
-
- If FX 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, to_timestamp('2000/JUN', 'FXYYYY MON')
- works, but to_timestamp('2000/JUN', 'FXYYYY MON')
- returns an error because the second space in the template string consumes
- the letter J from the input string.
-
-
-
-
-
- A TZH template pattern can match a signed number.
- Without the FX 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
- TZH 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 TZH.
- Otherwise, the minus sign is considered to be a separator between values.
- For example, to_timestamp('2000 -10', 'YYYY TZH') matches
- -10 to TZH, but
- to_timestamp('2000 -10', 'YYYY TZH')
- matches 10 to TZH.
-
-
-
-
-
- Ordinary text is allowed in to_char
- 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
- '"Hello Year "YYYY', the YYYY
- will be replaced by the year data, but the single Y in Year
- will not be.
- In to_date, to_number,
- and to_timestamp, literal text and double-quoted
- strings result in skipping the number of characters contained in the
- string; for example "XX" skips two input characters
- (whether or not they are XX).
-
-
-
- Prior to PostgreSQL 12, it was possible to
- skip arbitrary text in the input string using non-letter or non-digit
- characters. For example,
- to_timestamp('2000y6m1d', 'yyyy-MM-DD') used to
- work. Now you can only use letter characters for this purpose. For example,
- to_timestamp('2000y6m1d', 'yyyytMMtDDt') and
- to_timestamp('2000y6m1d', 'yyyy"y"MM"m"DD"d"')
- skip y, m, and
- d.
-
-
-
-
-
-
- If you want to have a double quote in the output you must
- precede it with a backslash, for example '\"YYYY
- Month\"'.
- 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).
-
-
-
-
-
- In to_timestamp and to_date,
- if the year format specification is less than four digits, e.g.,
- YYY, and the supplied year is less than four digits,
- the year will be adjusted to be nearest to the year 2020, e.g.,
- 95 becomes 1995.
-
-
-
-
-
- In to_timestamp and to_date,
- negative years are treated as signifying BC. If you write both a
- negative year and an explicit BC field, you get AD
- again. An input of year zero is treated as 1 BC.
-
-
-
-
-
- In to_timestamp and to_date,
- the YYYY conversion has a restriction when
- processing years with more than 4 digits. You must
- use some non-digit character or template after YYYY,
- otherwise the year is always interpreted as 4 digits. For example
- (with the year 20000):
- to_date('200001130', 'YYYYMMDD') will be
- interpreted as a 4-digit year; instead use a non-digit
- separator after the year, like
- to_date('20000-1130', 'YYYY-MMDD') or
- to_date('20000Nov30', 'YYYYMonDD').
-
-
-
-
-
- In to_timestamp and to_date,
- the CC (century) field is accepted but ignored
- if there is a YYY, YYYY or
- Y,YYY field. If CC is used with
- YY or Y 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.
-
-
-
-
-
- In to_timestamp and to_date,
- weekday names or numbers (DAY, D,
- and related field types) are accepted but are ignored for purposes of
- computing the result. The same is true for quarter
- (Q) fields.
-
-
-
-
-
- In to_timestamp and to_date,
- an ISO 8601 week-numbering date (as distinct from a Gregorian date)
- can be specified in one of two ways:
-
-
-
- Year, week number, and weekday: for
- example to_date('2006-42-4', 'IYYY-IW-ID')
- returns the date 2006-10-19.
- If you omit the weekday it is assumed to be 1 (Monday).
-
-
-
-
- Year and day of year: for example to_date('2006-291',
- 'IYYY-IDDD') also returns 2006-10-19.
-
-
-
-
-
- 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 month or day of month has no
- meaning. In the context of a Gregorian year, the ISO week has no
- meaning.
-
-
-
- While to_date will reject a mixture of
- Gregorian and ISO week-numbering date
- fields, to_char will not, since output format
- specifications like YYYY-MM-DD (IYYY-IDDD) can be
- useful. But avoid writing something like IYYY-MM-DD;
- that would yield surprising results near the start of the year.
- (See for more
- information.)
-
-
-
-
-
-
- In to_timestamp, millisecond
- (MS) or microsecond (US)
- fields are used as the
- seconds digits after the decimal point. For example
- to_timestamp('12.3', 'SS.MS') is not 3 milliseconds,
- but 300, because the conversion treats it as 12 + 0.3 seconds.
- So, for the format SS.MS, the input values
- 12.3, 12.30,
- and 12.300 specify the
- same number of milliseconds. To get three milliseconds, one must write
- 12.003, which the conversion treats as
- 12 + 0.003 = 12.003 seconds.
-
-
-
- Here is a more
- complex example:
- to_timestamp('15:12:02.020.001230', 'HH24:MI:SS.MS.US')
- is 15 hours, 12 minutes, and 2 seconds + 20 milliseconds +
- 1230 microseconds = 2.021230 seconds.
-
-
-
-
-
- to_char(..., 'ID')'s day of the week numbering
- matches the extract(isodow from ...) function, but
- to_char(..., 'D')'s does not match
- extract(dow from ...)'s day numbering.
-
-
-
-
-
- to_char(interval) formats HH and
- HH12 as shown on a 12-hour clock, for example zero hours
- and 36 hours both output as 12, while HH24
- outputs the full hour value, which can exceed 23 in
- an interval value.
-
-
-
-
-
-
-
- shows the
- template patterns available for formatting numeric values.
-
-
-
- Template Patterns for Numeric Formatting
-
-
-
- Pattern
- Description
-
-
-
-
- 9
- digit position (can be dropped if insignificant)
-
-
- 0
- digit position (will not be dropped, even if insignificant)
-
-
- . (period)
- decimal point
-
-
- , (comma)
- group (thousands) separator
-
-
- PR
- negative value in angle brackets
-
-
- S
- sign anchored to number (uses locale)
-
-
- L
- currency symbol (uses locale)
-
-
- D
- decimal point (uses locale)
-
-
- G
- group separator (uses locale)
-
-
- MI
- minus sign in specified position (if number < 0)
-
-
- PL
- plus sign in specified position (if number > 0)
-
-
- SG
- plus/minus sign in specified position
-
-
- RN
- Roman numeral (input between 1 and 3999)
-
-
- TH or th
- ordinal number suffix
-
-
- V
- shift specified number of digits (see notes)
-
-
- EEEE
- exponent for scientific notation
-
-
-
-
-
-
- Usage notes for numeric formatting:
-
-
-
-
- 0 specifies a digit position that will always be printed,
- even if it contains a leading/trailing zero. 9 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 to_number(),
- these two pattern characters are equivalent.)
-
-
-
-
-
- If the format provides fewer fractional digits than the number being
- formatted, to_char() will round the number to
- the specified number of fractional digits.
-
-
-
-
-
- The pattern characters S, L, D,
- and G represent the sign, currency symbol, decimal point,
- and thousands separator characters defined by the current locale
- (see
- and ). The pattern characters period
- and comma represent those exact characters, with the meanings of
- decimal point and thousands separator, regardless of locale.
-
-
-
-
-
- If no explicit provision is made for a sign
- in to_char()'s pattern, one column will be reserved for
- the sign, and it will be anchored to (appear just left of) the
- number. If S appears just left of some 9's,
- it will likewise be anchored to the number.
-
-
-
-
-
- A sign formatted using SG, PL, or
- MI is not anchored to
- the number; for example,
- to_char(-12, 'MI9999') produces '- 12'
- but to_char(-12, 'S9999') produces ' -12'.
- (The Oracle implementation does not allow the use of
- MI before 9, but rather
- requires that 9 precede
- MI.)
-
-
-
-
-
- TH does not convert values less than zero
- and does not convert fractional numbers.
-
-
-
-
-
- PL, SG, and
- TH are PostgreSQL
- extensions.
-
-
-
-
-
- In to_number, if non-data template patterns such
- as L or TH 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, TH would skip two non-data characters.
-
-
-
-
-
- V with to_char
- multiplies the input values by
- 10^n, where
- n is the number of digits following
- V. V with
- to_number divides in a similar manner.
- to_char and to_number
- do not support the use of
- V combined with a decimal point
- (e.g., 99.9V99 is not allowed).
-
-
-
-
-
- EEEE (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., 9.99EEEE is a valid pattern).
-
-
-
-
-
-
- Certain modifiers can be applied to any template pattern to alter its
- behavior. For example, FM99.99
- is the 99.99 pattern with the
- FM modifier.
- shows the
- modifier patterns for numeric formatting.
-
-
-
- Template Pattern Modifiers for Numeric Formatting
-
-
-
- Modifier
- Description
- Example
-
-
-
-
- FM prefix
- fill mode (suppress trailing zeroes and padding blanks)
- FM99.99
-
-
- TH suffix
- upper case ordinal number suffix
- 999TH
-
-
- th suffix
- lower case ordinal number suffix
- 999th
-
-
-
-
-
-
- shows some
- examples of the use of the to_char function.
-
-
-
-
-
-
-
-
- Date/Time Functions and Operators
-
-
- shows the available
- functions for date/time value processing, with details appearing in
- the following subsections. illustrates the behaviors of
- the basic arithmetic operators (+,
- *, etc.). For formatting functions, refer to
- . You should be familiar with
- the background information on date/time data types from .
-
-
-
- In addition, the usual comparison operators shown in
- 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 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 TimeZone zone when comparing it
- to a timestamp.
-
-
-
- All the functions and operators described below that take time or timestamp
- inputs actually come in two variants: one that takes time with time zone or timestamp
- with time zone, and one that takes time without time zone or timestamp without time zone.
- For brevity, these variants are not shown separately. Also, the
- + and * operators come in commutative pairs (for
- example both date+integer
- and integer+date); we show
- only one of each such pair.
-
-
-
- Date/Time Operators
-
-
-
-
-
- Operator
-
-
- Description
-
-
- Example(s)
-
-
-
-
-
-
-
- date+integer
- date
-
-
- Add a number of days to a date
-
-
- date '2001-09-28' + 7
- 2001-10-05
-
-
-
-
-
- date+interval
- timestamp
-
-
- Add an interval to a date
-
-
- date '2001-09-28' + interval '1 hour'
- 2001-09-28 01:00:00
-
-
-
-
-
- date+time
- timestamp
-
-
- Add a time-of-day to a date
-
-
- date '2001-09-28' + time '03:00'
- 2001-09-28 03:00:00
-
-
-
-
-
- interval+interval
- interval
-
-
- Add intervals
-
-
- interval '1 day' + interval '1 hour'
- 1 day 01:00:00
-
-
-
-
-
- timestamp+interval
- timestamp
-
-
- Add an interval to a timestamp
-
-
- timestamp '2001-09-28 01:00' + interval '23 hours'
- 2001-09-29 00:00:00
-
-
-
-
-
- time+interval
- time
-
-
- Add an interval to a time
-
-
- time '01:00' + interval '3 hours'
- 04:00:00
-
-
-
-
-
- -interval
- interval
-
-
- Negate an interval
-
-
- - interval '23 hours'
- -23:00:00
-
-
-
-
-
- date-date
- integer
-
-
- Subtract dates, producing the number of days elapsed
-
-
- date '2001-10-01' - date '2001-09-28'
- 3
-
-
-
-
-
- date-integer
- date
-
-
- Subtract a number of days from a date
-
-
- date '2001-10-01' - 7
- 2001-09-24
-
-
-
-
-
- date-interval
- timestamp
-
-
- Subtract an interval from a date
-
-
- date '2001-09-28' - interval '1 hour'
- 2001-09-27 23:00:00
-
-
-
-
-
- time-time
- interval
-
-
- Subtract times
-
-
- time '05:00' - time '03:00'
- 02:00:00
-
-
-
-
-
- time-interval
- time
-
-
- Subtract an interval from a time
-
-
- time '05:00' - interval '2 hours'
- 03:00:00
-
-
-
-
-
- timestamp-interval
- timestamp
-
-
- Subtract an interval from a timestamp
-
-
- timestamp '2001-09-28 23:00' - interval '23 hours'
- 2001-09-28 00:00:00
-
-
-
-
-
- interval-interval
- interval
-
-
- Subtract intervals
-
-
- interval '1 day' - interval '1 hour'
- 1 day -01:00:00
-
-
-
-
-
- timestamp-timestamp
- interval
-
-
- Subtract timestamps (converting 24-hour intervals into days,
- similarly to justify_hours())
-
-
- timestamp '2001-09-29 03:00' - timestamp '2001-07-27 12:00'
- 63 days 15:00:00
-
-
-
-
-
- interval*double precision
- interval
-
-
- Multiply an interval by a scalar
-
-
- interval '1 second' * 900
- 00:15:00
-
-
- interval '1 day' * 21
- 21 days
-
-
- interval '1 hour' * 3.5
- 03:30:00
-
-
-
-
-
- interval/double precision
- interval
-
-
- Divide an interval by a scalar
-
-
- interval '1 hour' / 1.5
- 00:40:00
-
-
-
-
-
-
-
- Date/Time Functions
-
-
-
-
- Function
-
-
- Description
-
-
- Example(s)
-
-
-
-
-
-
-
-
- age
-
- age ( timestamp, timestamp )
- interval
-
-
- Subtract arguments, producing a symbolic result that
- uses years and months, rather than just days
-
-
- age(timestamp '2001-04-10', timestamp '1957-06-13')
- 43 years 9 mons 27 days
-
-
-
-
-
- age ( timestamp )
- interval
-
-
- Subtract argument from current_date (at midnight)
-
-
- age(timestamp '1957-06-13')
- 62 years 6 mons 10 days
-
-
-
-
-
-
- clock_timestamp
-
- clock_timestamp ( )
- timestamp with time zone
-
-
- Current date and time (changes during statement execution);
- see
-
-
- clock_timestamp()
- 2019-12-23 14:39:53.662522-05
-
-
-
-
-
-
- current_date
-
- current_date
- date
-
-
- Current date; see
-
-
- current_date
- 2019-12-23
-
-
-
-
-
-
- current_time
-
- current_time
- time with time zone
-
-
- Current time of day; see
-
-
- current_time
- 14:39:53.662522-05
-
-
-
-
-
- current_time ( integer )
- time with time zone
-
-
- Current time of day, with limited precision;
- see
-
-
- current_time(2)
- 14:39:53.66-05
-
-
-
-
-
-
- current_timestamp
-
- current_timestamp
- timestamp with time zone
-
-
- Current date and time (start of current transaction);
- see
-
-
- current_timestamp
- 2019-12-23 14:39:53.662522-05
-
-
-
-
-
- current_timestamp ( integer )
- timestamp with time zone
-
-
- Current date and time (start of current transaction), with limited precision;
- see
-
-
- current_timestamp(0)
- 2019-12-23 14:39:53-05
-
-
-
-
-
-
- date_add
-
- date_add ( timestamp with time zone, interval, text )
- timestamp with time zone
-
-
- Add an interval to a timestamp with time
- zone, computing times of day and daylight-savings adjustments
- according to the time zone named by the third argument, or the
- current setting if that is omitted.
- The form with two arguments is equivalent to the timestamp with
- time zone+interval operator.
-
-
- date_add('2021-10-31 00:00:00+02'::timestamptz, '1 day'::interval, 'Europe/Warsaw')
- 2021-10-31 23:00:00+00
-
-
-
-
-
- date_bin ( interval, timestamp, timestamp )
- timestamp
-
-
- Bin input into specified interval aligned with specified origin; see
-
-
- date_bin('15 minutes', timestamp '2001-02-16 20:38:40', timestamp '2001-02-16 20:05:00')
- 2001-02-16 20:35:00
-
-
-
-
-
-
- date_part
-
- date_part ( text, timestamp )
- double precision
-
-
- Get timestamp subfield (equivalent to extract);
- see
-
-
- date_part('hour', timestamp '2001-02-16 20:38:40')
- 20
-
-
-
-
-
- date_part ( text, interval )
- double precision
-
-
- Get interval subfield (equivalent to extract);
- see
-
-
- date_part('month', interval '2 years 3 months')
- 3
-
-
-
-
-
-
- date_subtract
-
- date_subtract ( timestamp with time zone, interval, text )
- timestamp with time zone
-
-
- Subtract an interval from a timestamp with time
- zone, computing times of day and daylight-savings adjustments
- according to the time zone named by the third argument, or the
- current setting if that is omitted.
- The form with two arguments is equivalent to the timestamp with
- time zone-interval operator.
-
-
- date_subtract('2021-11-01 00:00:00+01'::timestamptz, '1 day'::interval, 'Europe/Warsaw')
- 2021-10-30 22:00:00+00
-
-
-
-
-
-
- date_trunc
-
- date_trunc ( text, timestamp )
- timestamp
-
-
- Truncate to specified precision; see
-
-
- date_trunc('hour', timestamp '2001-02-16 20:38:40')
- 2001-02-16 20:00:00
-
-
-
-
-
- date_trunc ( text, timestamp with time zone, text )
- timestamp with time zone
-
-
- Truncate to specified precision in the specified time zone; see
-
-
-
- date_trunc('day', timestamptz '2001-02-16 20:38:40+00', 'Australia/Sydney')
- 2001-02-16 13:00:00+00
-
-
-
-
-
- date_trunc ( text, interval )
- interval
-
-
- Truncate to specified precision; see
-
-
-
- date_trunc('hour', interval '2 days 3 hours 40 minutes')
- 2 days 03:00:00
-
-
-
-
-
-
- extract
-
- extract ( fieldfromtimestamp )
- numeric
-
-
- Get timestamp subfield; see
-
-
- extract(hour from timestamp '2001-02-16 20:38:40')
- 20
-
-
-
-
-
- extract ( fieldfrominterval )
- numeric
-
-
- Get interval subfield; see
-
-
- extract(month from interval '2 years 3 months')
- 3
-
-
-
-
-
-
- isfinite
-
- isfinite ( date )
- boolean
-
-
- Test for finite date (not +/-infinity)
-
-
- isfinite(date '2001-02-16')
- true
-
-
-
-
-
- isfinite ( timestamp )
- boolean
-
-
- Test for finite timestamp (not +/-infinity)
-
-
- isfinite(timestamp 'infinity')
- false
-
-
-
-
-
- isfinite ( interval )
- boolean
-
-
- Test for finite interval (not +/-infinity)
-
-
- isfinite(interval '4 hours')
- true
-
-
-
-
-
-
- justify_days
-
- justify_days ( interval )
- interval
-
-
- Adjust interval, converting 30-day time periods to months
-
-
- justify_days(interval '1 year 65 days')
- 1 year 2 mons 5 days
-
-
-
-
-
-
- justify_hours
-
- justify_hours ( interval )
- interval
-
-
- Adjust interval, converting 24-hour time periods to days
-
-
- justify_hours(interval '50 hours 10 minutes')
- 2 days 02:10:00
-
-
-
-
-
-
- justify_interval
-
- justify_interval ( interval )
- interval
-
-
- Adjust interval using justify_days
- and justify_hours, with additional sign
- adjustments
-
-
- justify_interval(interval '1 mon -1 hour')
- 29 days 23:00:00
-
-
-
-
-
-
- localtime
-
- localtime
- time
-
-
- Current time of day;
- see
-
-
- localtime
- 14:39:53.662522
-
-
-
-
-
- localtime ( integer )
- time
-
-
- Current time of day, with limited precision;
- see
-
-
- localtime(0)
- 14:39:53
-
-
-
-
-
-
- localtimestamp
-
- localtimestamp
- timestamp
-
-
- Current date and time (start of current transaction);
- see
-
-
- localtimestamp
- 2019-12-23 14:39:53.662522
-
-
-
-
-
- localtimestamp ( integer )
- timestamp
-
-
- Current date and time (start of current
- transaction), with limited precision;
- see
-
-
- localtimestamp(2)
- 2019-12-23 14:39:53.66
-
-
-
-
-
-
- make_date
-
- make_date ( yearint,
- monthint,
- dayint )
- date
-
-
- Create date from year, month and day fields
- (negative years signify BC)
-
-
- make_date(2013, 7, 15)
- 2013-07-15
-
-
-
-
-
- make_interval
-
- make_interval ( yearsint
- , monthsint
- , weeksint
- , daysint
- , hoursint
- , minsint
- , secsdouble precision
- )
- interval
-
-
- Create interval from years, months, weeks, days, hours, minutes and
- seconds fields, each of which can default to zero
-
-
- make_interval(days => 10)
- 10 days
-
-
-
-
-
-
- make_time
-
- make_time ( hourint,
- minint,
- secdouble precision )
- time
-
-
- Create time from hour, minute and seconds fields
-
-
- make_time(8, 15, 23.5)
- 08:15:23.5
-
-
-
-
-
-
- make_timestamp
-
- make_timestamp ( yearint,
- monthint,
- dayint,
- hourint,
- minint,
- secdouble precision )
- timestamp
-
-
- Create timestamp from year, month, day, hour, minute and seconds fields
- (negative years signify BC)
-
-
- make_timestamp(2013, 7, 15, 8, 15, 23.5)
- 2013-07-15 08:15:23.5
-
-
-
-
-
-
- make_timestamptz
-
- make_timestamptz ( yearint,
- monthint,
- dayint,
- hourint,
- minint,
- secdouble precision
- , timezonetext )
- timestamp with time zone
-
-
- Create timestamp with time zone from year, month, day, hour, minute
- and seconds fields (negative years signify BC).
- If timezone is not
- specified, the current time zone is used; the examples assume the
- session time zone is Europe/London
-
-
- make_timestamptz(2013, 7, 15, 8, 15, 23.5)
- 2013-07-15 08:15:23.5+01
-
-
- make_timestamptz(2013, 7, 15, 8, 15, 23.5, 'America/New_York')
- 2013-07-15 13:15:23.5+01
-
-
-
-
-
-
- now
-
- now ( )
- timestamp with time zone
-
-
- Current date and time (start of current transaction);
- see
-
-
- now()
- 2019-12-23 14:39:53.662522-05
-
-
-
-
-
-
- statement_timestamp
-
- statement_timestamp ( )
- timestamp with time zone
-
-
- Current date and time (start of current statement);
- see
-
-
- statement_timestamp()
- 2019-12-23 14:39:53.662522-05
-
-
-
-
-
-
- timeofday
-
- timeofday ( )
- text
-
-
- Current date and time
- (like clock_timestamp, but as a text string);
- see
-
-
- timeofday()
- Mon Dec 23 14:39:53.662522 2019 EST
-
-
-
-
-
-
- transaction_timestamp
-
- transaction_timestamp ( )
- timestamp with time zone
-
-
- Current date and time (start of current transaction);
- see
-
-
- transaction_timestamp()
- 2019-12-23 14:39:53.662522-05
-
-
-
-
-
-
- to_timestamp
-
- to_timestamp ( double precision )
- timestamp with time zone
-
-
- Convert Unix epoch (seconds since 1970-01-01 00:00:00+00) to
- timestamp with time zone
-
-
- to_timestamp(1284352323)
- 2010-09-13 04:32:03+00
-
-
-
-
-
-
-
-
- OVERLAPS
-
- In addition to these functions, the SQL OVERLAPS operator is
- supported:
-
-(start1, end1) OVERLAPS (start2, end2)
-(start1, length1) OVERLAPS (start2, length2)
-
- 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; OVERLAPS automatically takes the earlier value
- of the pair as the start. Each time period is considered to
- represent the half-open interval start<=
- time<end, unless
- start and end 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.
-
-
-
-SELECT (DATE '2001-02-16', DATE '2001-12-21') OVERLAPS
- (DATE '2001-10-30', DATE '2002-10-30');
-Result: true
-SELECT (DATE '2001-02-16', INTERVAL '100 days') OVERLAPS
- (DATE '2001-10-30', DATE '2002-10-30');
-Result: false
-SELECT (DATE '2001-10-29', DATE '2001-10-30') OVERLAPS
- (DATE '2001-10-30', DATE '2001-10-31');
-Result: false
-SELECT (DATE '2001-10-30', DATE '2001-10-30') OVERLAPS
- (DATE '2001-10-30', DATE '2001-10-31');
-Result: true
-
-
-
- When adding an interval value to (or subtracting an
- interval value from) a timestamp
- or timestamp with time zone value, the months, days, and
- microseconds fields of the interval value are handled in turn.
- First, a nonzero months field advances or decrements the date of the
- timestamp by the indicated number of months, keeping the day of month the
- same unless it would be past the end of the new month, in which case the
- last day of that month is used. (For example, March 31 plus 1 month
- becomes April 30, but March 31 plus 2 months becomes May 31.)
- Then the days field advances or decrements the date of the timestamp by
- the indicated number of days. In both these steps the local time of day
- is kept the same. Finally, if there is a nonzero microseconds field, it
- is added or subtracted literally.
- When doing arithmetic on a timestamp with time zone value in
- a time zone that recognizes DST, this means that adding or subtracting
- (say) interval '1 day' does not necessarily have the
- same result as adding or subtracting interval '24
- hours'.
- For example, with the session time zone set
- to America/Denver:
-
-SELECT timestamp with time zone '2005-04-02 12:00:00-07' + interval '1 day';
-Result: 2005-04-03 12:00:00-06
-SELECT timestamp with time zone '2005-04-02 12:00:00-07' + interval '24 hours';
-Result: 2005-04-03 13:00:00-06
-
- This happens because an hour was skipped due to a change in daylight saving
- time at 2005-04-03 02:00:00 in time zone
- America/Denver.
-
-
-
- Note there can be ambiguity in the months field returned by
- age because different months have different numbers of
- days. PostgreSQL's approach uses the month from the
- earlier of the two dates when calculating partial months. For example,
- age('2004-06-01', '2004-04-30') uses April to yield
- 1 mon 1 day, while using May would yield 1 mon 2
- days because May has 31 days, while April has only 30.
-
-
-
- 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 EXTRACT(EPOCH FROM ...), then subtract the
- results; this produces the
- number of seconds 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 - operator
- returns the number of days (24-hours) and hours/minutes/seconds
- between the values, making the same adjustments. The age
- 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 timezone
- = 'US/Eastern'; there is a daylight saving time change between the
- two dates used:
-
-
-
-SELECT EXTRACT(EPOCH FROM timestamptz '2013-07-01 12:00:00') -
- EXTRACT(EPOCH FROM timestamptz '2013-03-01 12:00:00');
-Result: 10537200.000000
-SELECT (EXTRACT(EPOCH FROM timestamptz '2013-07-01 12:00:00') -
- EXTRACT(EPOCH FROM timestamptz '2013-03-01 12:00:00'))
- / 60 / 60 / 24;
-Result: 121.9583333333333333
-SELECT timestamptz '2013-07-01 12:00:00' - timestamptz '2013-03-01 12:00:00';
-Result: 121 days 23:00:00
-SELECT age(timestamptz '2013-07-01 12:00:00', timestamptz '2013-03-01 12:00:00');
-Result: 4 mons
-
-
-
- <function>EXTRACT</function>, <function>date_part</function>
-
-
- date_part
-
-
- extract
-
-
-
-EXTRACT(field FROM source)
-
-
-
- The extract function retrieves subfields
- such as year or hour from date/time values.
- source must be a value expression of
- type timestamp, date, time,
- or interval. (Timestamps and times can be with or
- without time zone.)
- field is an identifier or
- string that selects what field to extract from the source value.
- Not all fields are valid for every input data type; for example, fields
- smaller than a day cannot be extracted from a date, while
- fields of a day or more cannot be extracted from a time.
- The extract function returns values of type
- numeric.
-
-
-
- The following are valid field names:
-
-
-
-
- century
-
-
- The century; for interval values, the year field
- divided by 100
-
-
-
-SELECT EXTRACT(CENTURY FROM TIMESTAMP '2000-12-16 12:21:13');
-Result: 20
-SELECT EXTRACT(CENTURY FROM TIMESTAMP '2001-02-16 20:38:40');
-Result: 21
-SELECT EXTRACT(CENTURY FROM DATE '0001-01-01 AD');
-Result: 1
-SELECT EXTRACT(CENTURY FROM DATE '0001-12-31 BC');
-Result: -1
-SELECT EXTRACT(CENTURY FROM INTERVAL '2001 years');
-Result: 20
-
-
-
-
-
- day
-
-
- The day of the month (1–31); for interval
- values, the number of days
-
-
-
-SELECT EXTRACT(DAY FROM TIMESTAMP '2001-02-16 20:38:40');
-Result: 16
-SELECT EXTRACT(DAY FROM INTERVAL '40 days 1 minute');
-Result: 40
-
-
-
-
-
-
- decade
-
-
- The year field divided by 10
-
-
-
-SELECT EXTRACT(DECADE FROM TIMESTAMP '2001-02-16 20:38:40');
-Result: 200
-
-
-
-
-
- dow
-
-
- The day of the week as Sunday (0) to
- Saturday (6)
-
-
-
-SELECT EXTRACT(DOW FROM TIMESTAMP '2001-02-16 20:38:40');
-Result: 5
-
-
- Note that extract's day of the week numbering
- differs from that of the to_char(...,
- 'D') function.
-
-
-
-
-
-
- doy
-
-
- The day of the year (1–365/366)
-
-
-
-SELECT EXTRACT(DOY FROM TIMESTAMP '2001-02-16 20:38:40');
-Result: 47
-
-
-
-
-
- epoch
-
-
- For timestamp with time zone values, the
- number of seconds since 1970-01-01 00:00:00 UTC (negative for
- timestamps before that);
- for date and timestamp values, the
- nominal number of seconds since 1970-01-01 00:00:00,
- without regard to timezone or daylight-savings rules;
- for interval values, the total number
- of seconds in the interval
-
-
-
-SELECT EXTRACT(EPOCH FROM TIMESTAMP WITH TIME ZONE '2001-02-16 20:38:40.12-08');
-Result: 982384720.120000
-SELECT EXTRACT(EPOCH FROM TIMESTAMP '2001-02-16 20:38:40.12');
-Result: 982355920.120000
-SELECT EXTRACT(EPOCH FROM INTERVAL '5 days 3 hours');
-Result: 442800.000000
-
-
-
- You can convert an epoch value back to a timestamp with time zone
- with to_timestamp:
-
-
-SELECT to_timestamp(982384720.12);
-Result: 2001-02-17 04:38:40.12+00
-
-
-
- Beware that applying to_timestamp to an epoch
- extracted from a date or timestamp 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.
-
-
-
-
-
- hour
-
-
- The hour field (0–23 in timestamps, unrestricted in
- intervals)
-
-
-
-SELECT EXTRACT(HOUR FROM TIMESTAMP '2001-02-16 20:38:40');
-Result: 20
-
-
-
-
-
- isodow
-
-
- The day of the week as Monday (1) to
- Sunday (7)
-
-
-
-SELECT EXTRACT(ISODOW FROM TIMESTAMP '2001-02-18 20:38:40');
-Result: 7
-
-
- This is identical to dow except for Sunday. This
- matches the ISO 8601 day of the week numbering.
-
-
-
-
-
-
- isoyear
-
-
- The ISO 8601 week-numbering year that the date
- falls in
-
-
-
-SELECT EXTRACT(ISOYEAR FROM DATE '2006-01-01');
-Result: 2005
-SELECT EXTRACT(ISOYEAR FROM DATE '2006-01-02');
-Result: 2006
-
-
-
- Each ISO 8601 week-numbering year begins with the
- Monday of the week containing the 4th of January, so in early
- January or late December the ISO year may be
- different from the Gregorian year. See the week
- field for more information.
-
-
-
-
-
- julian
-
-
- The Julian Date corresponding to the
- date or timestamp. Timestamps
- that are not local midnight result in a fractional value. See
- for more information.
-
-
-
-SELECT EXTRACT(JULIAN FROM DATE '2006-01-01');
-Result: 2453737
-SELECT EXTRACT(JULIAN FROM TIMESTAMP '2006-01-01 12:00');
-Result: 2453737.50000000000000000000
-
-
-
-
-
- microseconds
-
-
- The seconds field, including fractional parts, multiplied by 1
- 000 000; note that this includes full seconds
-
-
-
-SELECT EXTRACT(MICROSECONDS FROM TIME '17:12:28.5');
-Result: 28500000
-
-
-
-
-
- millennium
-
-
- The millennium; for interval values, the year field
- divided by 1000
-
-
-
-SELECT EXTRACT(MILLENNIUM FROM TIMESTAMP '2001-02-16 20:38:40');
-Result: 3
-SELECT EXTRACT(MILLENNIUM FROM INTERVAL '2001 years');
-Result: 2
-
-
-
- Years in the 1900s are in the second millennium.
- The third millennium started January 1, 2001.
-
-
-
-
-
- milliseconds
-
-
- The seconds field, including fractional parts, multiplied by
- 1000. Note that this includes full seconds.
-
-
-
-SELECT EXTRACT(MILLISECONDS FROM TIME '17:12:28.5');
-Result: 28500.000
-
-
-
-
-
- minute
-
-
- The minutes field (0–59)
-
-
-
-SELECT EXTRACT(MINUTE FROM TIMESTAMP '2001-02-16 20:38:40');
-Result: 38
-
-
-
-
-
- month
-
-
- The number of the month within the year (1–12);
- for interval values, the number of months modulo 12
- (0–11)
-
-
-
-SELECT EXTRACT(MONTH FROM TIMESTAMP '2001-02-16 20:38:40');
-Result: 2
-SELECT EXTRACT(MONTH FROM INTERVAL '2 years 3 months');
-Result: 3
-SELECT EXTRACT(MONTH FROM INTERVAL '2 years 13 months');
-Result: 1
-
-
-
-
-
- quarter
-
-
- The quarter of the year (1–4) that the date is in
-
-
-
-SELECT EXTRACT(QUARTER FROM TIMESTAMP '2001-02-16 20:38:40');
-Result: 1
-
-
-
-
-
- second
-
-
- The seconds field, including any fractional seconds
-
-
-
-SELECT EXTRACT(SECOND FROM TIMESTAMP '2001-02-16 20:38:40');
-Result: 40.000000
-SELECT EXTRACT(SECOND FROM TIME '17:12:28.5');
-Result: 28.500000
-
-
-
-
- timezone
-
-
- 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,
- PostgreSQL does not use UTC because
- leap seconds are not handled.)
-
-
-
-
-
- timezone_hour
-
-
- The hour component of the time zone offset
-
-
-
-
-
- timezone_minute
-
-
- The minute component of the time zone offset
-
-
-
-
-
- week
-
-
- The number of the ISO 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.
-
-
- 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, 2005-01-01 is part of the 53rd week of year
- 2004, and 2006-01-01 is part of the 52nd week of year
- 2005, while 2012-12-31 is part of the first week of 2013.
- It's recommended to use the isoyear field together with
- week to get consistent results.
-
-
-
-SELECT EXTRACT(WEEK FROM TIMESTAMP '2001-02-16 20:38:40');
-Result: 7
-
-
-
-
-
- year
-
-
- The year field. Keep in mind there is no 0 AD, so subtracting
- BC years from AD years should be done with care.
-
-
-
-SELECT EXTRACT(YEAR FROM TIMESTAMP '2001-02-16 20:38:40');
-Result: 2001
-
-
-
-
-
-
-
-
- When processing an interval value,
- the extract function produces field values that
- match the interpretation used by the interval output function. This
- can produce surprising results if one starts with a non-normalized
- interval representation, for example:
-
-SELECT INTERVAL '80 minutes';
-Result: 01:20:00
-SELECT EXTRACT(MINUTES FROM INTERVAL '80 minutes');
-Result: 20
-
-
-
-
-
- When the input value is +/-Infinity, extract returns
- +/-Infinity for monotonically-increasing fields (epoch,
- julian, year, isoyear,
- decade, century, and millennium
- for timestamp inputs; epoch, hour,
- day, year, decade,
- century, and millennium for
- interval inputs).
- For other fields, NULL is returned. PostgreSQL
- versions before 9.6 returned zero for all cases of infinite input.
-
-
-
-
- The extract function is primarily intended
- for computational processing. For formatting date/time values for
- display, see .
-
-
-
- The date_part function is modeled on the traditional
- Ingres equivalent to the
- SQL-standard function extract:
-
-date_part('field', source)
-
- Note that here the field parameter needs to
- be a string value, not a name. The valid field names for
- date_part are the same as for
- extract.
- For historical reasons, the date_part function
- returns values of type double precision. This can result in
- a loss of precision in certain uses. Using extract
- is recommended instead.
-
-
-
-SELECT date_part('day', TIMESTAMP '2001-02-16 20:38:40');
-Result: 16
-SELECT date_part('hour', INTERVAL '4 hours 3 minutes');
-Result: 4
-
-
-
-
-
- <function>date_trunc</function>
-
-
- date_trunc
-
-
-
- The function date_trunc is conceptually
- similar to the trunc function for numbers.
-
-
-
-
-date_trunc(field, source [, time_zone ])
-
- source is a value expression of type
- timestamp, timestamp with time zone,
- or interval.
- (Values of type date and
- time are cast automatically to timestamp or
- interval, respectively.)
- field selects to which precision to
- truncate the input value. The return value is likewise of type
- timestamp, timestamp with time zone,
- or interval,
- and it has all fields that are less significant than the
- selected one set to zero (or one, for day and month).
-
-
-
- Valid values for field are:
-
- microseconds
- milliseconds
- second
- minute
- hour
- day
- week
- month
- quarter
- year
- decade
- century
- millennium
-
-
-
-
- When the input value is of type timestamp with time zone,
- the truncation is performed with respect to a particular time zone;
- for example, truncation to day produces a value that
- is midnight in that zone. By default, truncation is done with respect
- to the current setting, but the
- optional time_zone 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 time zone cannot be specified when processing timestamp without
- time zone or interval inputs. These are always
- taken at face value.
-
-
-
- Examples (assuming the local time zone is America/New_York):
-
-SELECT date_trunc('hour', TIMESTAMP '2001-02-16 20:38:40');
-Result: 2001-02-16 20:00:00
-SELECT date_trunc('year', TIMESTAMP '2001-02-16 20:38:40');
-Result: 2001-01-01 00:00:00
-SELECT date_trunc('day', TIMESTAMP WITH TIME ZONE '2001-02-16 20:38:40+00');
-Result: 2001-02-16 00:00:00-05
-SELECT date_trunc('day', TIMESTAMP WITH TIME ZONE '2001-02-16 20:38:40+00', 'Australia/Sydney');
-Result: 2001-02-16 08:00:00-05
-SELECT date_trunc('hour', INTERVAL '3 days 02:47:33');
-Result: 3 days 02:00:00
-
-
-
-
-
- <function>date_bin</function>
-
-
- date_bin
-
-
-
- The function date_binbins the input
- timestamp into the specified interval (the stride)
- aligned with a specified origin.
-
-
-
-
-date_bin(stride, source, origin)
-
- source is a value expression of type
- timestamp or timestamp with time zone. (Values
- of type date are cast automatically to
- timestamp.) stride is a value
- expression of type interval. The return value is likewise
- of type timestamp or timestamp with time zone,
- and it marks the beginning of the bin into which the
- source is placed.
-
-
-
- Examples:
-
-SELECT date_bin('15 minutes', TIMESTAMP '2020-02-11 15:44:17', TIMESTAMP '2001-01-01');
-Result: 2020-02-11 15:30:00
-SELECT date_bin('15 minutes', TIMESTAMP '2020-02-11 15:44:17', TIMESTAMP '2001-01-01 00:02:30');
-Result: 2020-02-11 15:32:30
-
-
-
-
- In the case of full units (1 minute, 1 hour, etc.), it gives the same result as
- the analogous date_trunc call, but the difference is
- that date_bin can truncate to an arbitrary interval.
-
-
-
- The stride interval must be greater than zero and
- cannot contain units of month or larger.
-
-
-
-
- <literal>AT TIME ZONE and AT LOCAL</literal>
-
-
- time zone
- conversion
-
-
-
- AT TIME ZONE
-
-
-
- AT LOCAL
-
-
-
- The AT TIME ZONE operator converts time
- stamp without time zone to/from
- time stamp with time zone, and
- time with time zone values to different time
- zones. shows its
- variants.
-
-
-
- <literal>AT TIME ZONE</literal> and <literal>AT LOCAL</literal> Variants
-
-
-
-
- Operator
-
-
- Description
-
-
- Example(s)
-
-
-
-
-
-
-
- timestamp without time zoneAT TIME ZONEzone
- timestamp with time zone
-
-
- Converts given time stamp without time zone to
- time stamp with time zone, assuming the given
- value is in the named time zone.
-
-
- timestamp '2001-02-16 20:38:40' at time zone 'America/Denver'
- 2001-02-17 03:38:40+00
-
-
-
-
-
- timestamp without time zoneAT LOCAL
- timestamp with time zone
-
-
- Converts given time stamp without time zone to
- time stamp with the session's
- TimeZone value as time zone.
-
-
- timestamp '2001-02-16 20:38:40' at local
- 2001-02-17 03:38:40+00
-
-
-
-
-
- timestamp with time zoneAT TIME ZONEzone
- timestamp without time zone
-
-
- Converts given time stamp with time zone to
- time stamp without time zone, as the time would
- appear in that zone.
-
-
- timestamp with time zone '2001-02-16 20:38:40-05' at time zone 'America/Denver'
- 2001-02-16 18:38:40
-
-
-
-
-
- timestamp with time zoneAT LOCAL
- timestamp without time zone
-
-
- Converts given time stamp with time zone to
- time stamp without time zone, as the time would
- appear with the session's TimeZone value as time zone.
-
-
- timestamp with time zone '2001-02-16 20:38:40-05' at local
- 2001-02-16 18:38:40
-
-
-
-
-
- time with time zoneAT TIME ZONEzone
- time with time zone
-
-
- Converts given time with time zone to a new time
- zone. Since no date is supplied, this uses the currently active UTC
- offset for the named destination zone.
-
-
- time with time zone '05:34:17-05' at time zone 'UTC'
- 10:34:17+00
-
-
-
-
-
- time with time zoneAT LOCAL
- time with time zone
-
-
- Converts given time with time zone to a new time
- zone. Since no date is supplied, this uses the currently active UTC
- offset for the session's TimeZone value.
-
-
- Assuming the session's TimeZone is set to UTC:
-
-
- time with time zone '05:34:17-05' at local
- 10:34:17+00
-
-
-
-
-
-
-
- In these expressions, the desired time zone zone can be
- specified either as a text value (e.g., 'America/Los_Angeles')
- or as an interval (e.g., INTERVAL '-08:00').
- In the text case, a time zone name can be specified in any of the ways
- described in .
- The interval case is only useful for zones that have fixed offsets from
- UTC, so it is not very common in practice.
-
-
-
- The syntax AT LOCAL may be used as shorthand for
- AT TIME ZONE local, where
- local is the session's
- TimeZone value.
-
-
-
- Examples (assuming the current setting
- is America/Los_Angeles):
-
-SELECT TIMESTAMP '2001-02-16 20:38:40' AT TIME ZONE 'America/Denver';
-Result: 2001-02-16 19:38:40-08
-SELECT TIMESTAMP WITH TIME ZONE '2001-02-16 20:38:40-05' AT TIME ZONE 'America/Denver';
-Result: 2001-02-16 18:38:40
-SELECT TIMESTAMP '2001-02-16 20:38:40' AT TIME ZONE 'Asia/Tokyo' AT TIME ZONE 'America/Chicago';
-Result: 2001-02-16 05:38:40
-SELECT TIMESTAMP WITH TIME ZONE '2001-02-16 20:38:40-05' AT LOCAL;
-Result: 2001-02-16 17:38:40
-SELECT TIME WITH TIME ZONE '20:38:40-05' AT LOCAL;
-Result: 17:38:40
-
- The first example adds a time zone to a value that lacks it, and
- displays the value using the current TimeZone
- 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
- TimeZone setting. The third example converts
- Tokyo time to Chicago time. The fourth example shifts the time stamp
- with time zone value to the time zone currently specified by the
- TimeZone setting and returns the value without a
- time zone.
-
-
-
- The fifth example is a cautionary tale. Due to the fact that there is no
- date associated with the input value, the conversion is made using the
- current date of the session. Therefore, this static example may show a wrong
- result depending on the time of the year it is viewed because
- 'America/Los_Angeles' observes Daylight Savings Time.
-
-
-
- The function timezone(zone,
- timestamp) is equivalent to the SQL-conforming construct
- timestamp AT TIME ZONE
- zone.
-
-
-
- The function timezone(zone,
- time) is equivalent to the SQL-conforming construct
- time AT TIME ZONE
- zone.
-
-
-
- The function timezone(timestamp)
- is equivalent to the SQL-conforming construct timestamp
- AT LOCAL.
-
-
-
- The function timezone(time)
- is equivalent to the SQL-conforming construct time
- AT LOCAL.
-
-
-
-
- Current Date/Time
-
-
- date
- current
-
-
-
- time
- current
-
-
-
- PostgreSQL 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:
-
-CURRENT_DATE
-CURRENT_TIME
-CURRENT_TIMESTAMP
-CURRENT_TIME(precision)
-CURRENT_TIMESTAMP(precision)
-LOCALTIME
-LOCALTIMESTAMP
-LOCALTIME(precision)
-LOCALTIMESTAMP(precision)
-
-
-
-
- CURRENT_TIME and
- CURRENT_TIMESTAMP deliver values with time zone;
- LOCALTIME and
- LOCALTIMESTAMP deliver values without time zone.
-
-
-
- CURRENT_TIME,
- CURRENT_TIMESTAMP,
- LOCALTIME, and
- LOCALTIMESTAMP
- 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.
-
-
-
- Some examples:
-
-SELECT CURRENT_TIME;
-Result: 14:39:53.662522-05
-SELECT CURRENT_DATE;
-Result: 2019-12-23
-SELECT CURRENT_TIMESTAMP;
-Result: 2019-12-23 14:39:53.662522-05
-SELECT CURRENT_TIMESTAMP(2);
-Result: 2019-12-23 14:39:53.66-05
-SELECT LOCALTIMESTAMP;
-Result: 2019-12-23 14:39:53.662522
-
-
-
-
- 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 current time, so that multiple
- modifications within the same transaction bear the same
- time stamp.
-
-
-
-
- Other database systems might advance these values more
- frequently.
-
-
-
-
- PostgreSQL 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:
-
-transaction_timestamp()
-statement_timestamp()
-clock_timestamp()
-timeofday()
-now()
-
-
-
-
- transaction_timestamp() is equivalent to
- CURRENT_TIMESTAMP, but is named to clearly reflect
- what it returns.
- statement_timestamp() returns the start time of the current
- statement (more specifically, the time of receipt of the latest command
- message from the client).
- statement_timestamp() and transaction_timestamp()
- return the same value during the first command of a transaction, but might
- differ during subsequent commands.
- clock_timestamp() returns the actual current time, and
- therefore its value changes even within a single SQL command.
- timeofday() is a historical
- PostgreSQL function. Like
- clock_timestamp(), it returns the actual current time,
- but as a formatted text string rather than a timestamp
- with time zone value.
- now() is a traditional PostgreSQL
- equivalent to transaction_timestamp().
-
-
-
- All the date/time data types also accept the special literal value
- now to specify the current date and time (again,
- interpreted as the transaction start time). Thus,
- the following three all return the same result:
-
-SELECT CURRENT_TIMESTAMP;
-SELECT now();
-SELECT TIMESTAMP 'now'; -- but see tip below
-
-
-
-
-
- Do not use the third form when specifying a value to be evaluated later,
- for example in a DEFAULT clause for a table column.
- The system will convert now
- to a timestamp 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 .)
-
-
-
-
-
- Delaying Execution
-
-
- pg_sleep
-
-
- pg_sleep_for
-
-
- pg_sleep_until
-
-
- sleep
-
-
- delay
-
-
-
- The following functions are available to delay execution of the server
- process:
-
-pg_sleep ( double precision )
-pg_sleep_for ( interval )
-pg_sleep_until ( timestamp with time zone )
-
-
- pg_sleep makes the current session's process
- sleep until the given number of seconds have
- elapsed. Fractional-second delays can be specified.
- pg_sleep_for is a convenience function to
- allow the sleep time to be specified as an interval.
- pg_sleep_until is a convenience function for when
- a specific wake-up time is desired.
- For example:
-
-
-SELECT pg_sleep(1.5);
-SELECT pg_sleep_for('5 minutes');
-SELECT pg_sleep_until('tomorrow 03:00');
-
-
-
-
-
- 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, pg_sleep_until is not guaranteed to
- wake up exactly at the specified time, but it will not wake up any earlier.
-
-
-
-
-
- Make sure that your session does not hold more locks than necessary
- when calling pg_sleep or its variants. Otherwise
- other sessions might have to wait for your sleeping process, slowing down
- the entire system.
-
-
-
-
-
-
-
-
- Enum Support Functions
-
-
- For enum types (described in ),
- there are several functions that allow cleaner programming without
- hard-coding particular values of an enum type.
- These are listed in . The examples
- assume an enum type created as:
-
-
-CREATE TYPE rainbow AS ENUM ('red', 'orange', 'yellow', 'green', 'blue', 'purple');
-
-
-
-
-
- Enum Support Functions
-
-
-
-
- Function
-
-
- Description
-
-
- Example(s)
-
-
-
-
-
-
-
-
- enum_first
-
- enum_first ( anyenum )
- anyenum
-
-
- Returns the first value of the input enum type.
-
-
- enum_first(null::rainbow)
- red
-
-
-
-
-
- enum_last
-
- enum_last ( anyenum )
- anyenum
-
-
- Returns the last value of the input enum type.
-
-
- enum_last(null::rainbow)
- purple
-
-
-
-
-
- enum_range
-
- enum_range ( anyenum )
- anyarray
-
-
- Returns all values of the input enum type in an ordered array.
-
-
- enum_range(null::rainbow)
- {red,orange,yellow,&zwsp;green,blue,purple}
-
-
-
-
- enum_range ( anyenum, anyenum )
- anyarray
-
-
- 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.
-
-
- enum_range('orange'::rainbow, 'green'::rainbow)
- {orange,yellow,green}
-
-
- enum_range(NULL, 'green'::rainbow)
- {red,orange,&zwsp;yellow,green}
-
-
- enum_range('orange'::rainbow, NULL)
- {orange,yellow,green,&zwsp;blue,purple}
-
-
-
-
-
-
-
- Notice that except for the two-argument form of enum_range,
- 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.
-
-
-
-
- Geometric Functions and Operators
-
-
- The geometric types point, box,
- lseg, line, path,
- polygon, and circle have a large set of
- native support functions and operators, shown in , , and .
-
-
-
- Geometric Operators
-
-
-
-
- Operator
-
-
- Description
-
-
- Example(s)
-
-
-
-
-
-
-
- geometric_type+point
- geometric_type
-
-
- Adds the coordinates of the second point to those of each
- point of the first argument, thus performing translation.
- Available for point, box, path,
- circle.
-
-
- box '(1,1),(0,0)' + point '(2,0)'
- (3,1),(2,0)
-
-
-
-
-
- path+path
- path
-
-
- Concatenates two open paths (returns NULL if either path is closed).
-
-
- path '[(0,0),(1,1)]' + path '[(2,2),(3,3),(4,4)]'
- [(0,0),(1,1),(2,2),(3,3),(4,4)]
-
-
-
-
-
- geometric_type-point
- geometric_type
-
-
- Subtracts the coordinates of the second point from those
- of each point of the first argument, thus performing translation.
- Available for point, box, path,
- circle.
-
-
- box '(1,1),(0,0)' - point '(2,0)'
- (-1,1),(-2,0)
-
-
-
-
-
- geometric_type*point
- geometric_type
-
-
- Multiplies each point of the first argument by the second
- point (treating a point as being a complex number
- represented by real and imaginary parts, and performing standard
- complex multiplication). If one interprets
- the second point 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 x axis.
- Available for point, box,Rotating 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.
- path, circle.
-
-
- path '((0,0),(1,0),(1,1))' * point '(3.0,0)'
- ((0,0),(3,0),(3,3))
-
-
- path '((0,0),(1,0),(1,1))' * point(cosd(45), sind(45))
- ((0,0),&zwsp;(0.7071067811865475,0.7071067811865475),&zwsp;(0,1.414213562373095))
-
-
-
-
-
- geometric_type/point
- geometric_type
-
-
- Divides each point of the first argument by the second
- point (treating a point as being a complex number
- represented by real and imaginary parts, and performing standard
- complex division). If one interprets
- the second point 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 x axis.
- Available for point, box,path,
- circle.
-
-
- path '((0,0),(1,0),(1,1))' / point '(2.0,0)'
- ((0,0),(0.5,0),(0.5,0.5))
-
-
- path '((0,0),(1,0),(1,1))' / point(cosd(45), sind(45))
- ((0,0),&zwsp;(0.7071067811865476,-0.7071067811865476),&zwsp;(1.4142135623730951,0))
-
-
-
-
-
- @-@geometric_type
- double precision
-
-
- Computes the total length.
- Available for lseg, path.
-
-
- @-@ path '[(0,0),(1,0),(1,1)]'
- 2
-
-
-
-
-
- @@geometric_type
- point
-
-
- Computes the center point.
- Available for box, lseg,
- polygon, circle.
-
-
- @@ box '(2,2),(0,0)'
- (1,1)
-
-
-
-
-
- #geometric_type
- integer
-
-
- Returns the number of points.
- Available for path, polygon.
-
-
- # path '((1,0),(0,1),(-1,0))'
- 3
-
-
-
-
-
- geometric_type#geometric_type
- point
-
-
- Computes the point of intersection, or NULL if there is none.
- Available for lseg, line.
-
-
- lseg '[(0,0),(1,1)]' # lseg '[(1,0),(0,1)]'
- (0.5,0.5)
-
-
-
-
-
- box#box
- box
-
-
- Computes the intersection of two boxes, or NULL if there is none.
-
-
- box '(2,2),(-1,-1)' # box '(1,1),(-2,-2)'
- (1,1),(-1,-1)
-
-
-
-
-
- geometric_type##geometric_type
- point
-
-
- Computes the closest point to the first object on the second object.
- Available for these pairs of types:
- (point, box),
- (point, lseg),
- (point, line),
- (lseg, box),
- (lseg, lseg),
- (line, lseg).
-
-
- point '(0,0)' ## lseg '[(2,0),(0,2)]'
- (1,1)
-
-
-
-
-
- geometric_type<->geometric_type
- double precision
-
-
- Computes the distance between the objects.
- Available for all seven geometric types, for all combinations
- of point with another geometric type, and for
- these additional pairs of types:
- (box, lseg),
- (lseg, line),
- (polygon, circle)
- (and the commutator cases).
-
-
- circle '<(0,0),1>' <-> circle '<(5,0),1>'
- 3
-
-
-
-
-
- geometric_type@>geometric_type
- boolean
-
-
- Does first object contain second?
- Available for these pairs of types:
- (box, point),
- (box, box),
- (path, point),
- (polygon, point),
- (polygon, polygon),
- (circle, point),
- (circle, circle).
-
-
- circle '<(0,0),2>' @> point '(1,1)'
- t
-
-
-
-
-
- geometric_type<@geometric_type
- boolean
-
-
- Is first object contained in or on second?
- Available for these pairs of types:
- (point, box),
- (point, lseg),
- (point, line),
- (point, path),
- (point, polygon),
- (point, circle),
- (box, box),
- (lseg, box),
- (lseg, line),
- (polygon, polygon),
- (circle, circle).
-
-
- point '(1,1)' <@ circle '<(0,0),2>'
- t
-
-
-
-
-
- geometric_type&&geometric_type
- boolean
-
-
- Do these objects overlap? (One point in common makes this true.)
- Available for box, polygon,
- circle.
-
-
- box '(1,1),(0,0)' && box '(2,2),(0,0)'
- t
-
-
-
-
-
- geometric_type<<geometric_type
- boolean
-
-
- Is first object strictly left of second?
- Available for point, box,
- polygon, circle.
-
-
- circle '<(0,0),1>' << circle '<(5,0),1>'
- t
-
-
-
-
-
- geometric_type>>geometric_type
- boolean
-
-
- Is first object strictly right of second?
- Available for point, box,
- polygon, circle.
-
-
- circle '<(5,0),1>' >> circle '<(0,0),1>'
- t
-
-
-
-
-
- geometric_type&<geometric_type
- boolean
-
-
- Does first object not extend to the right of second?
- Available for box, polygon,
- circle.
-
-
- box '(1,1),(0,0)' &< box '(2,2),(0,0)'
- t
-
-
-
-
-
- geometric_type&>geometric_type
- boolean
-
-
- Does first object not extend to the left of second?
- Available for box, polygon,
- circle.
-
-
- box '(3,3),(0,0)' &> box '(2,2),(0,0)'
- t
-
-
-
-
-
- geometric_type<<|geometric_type
- boolean
-
-
- Is first object strictly below second?
- Available for point, box, polygon,
- circle.
-
-
- box '(3,3),(0,0)' <<| box '(5,5),(3,4)'
- t
-
-
-
-
-
- geometric_type|>>geometric_type
- boolean
-
-
- Is first object strictly above second?
- Available for point, box, polygon,
- circle.
-
-
- box '(5,5),(3,4)' |>> box '(3,3),(0,0)'
- t
-
-
-
-
-
- geometric_type&<|geometric_type
- boolean
-
-
- Does first object not extend above second?
- Available for box, polygon,
- circle.
-
-
- box '(1,1),(0,0)' &<| box '(2,2),(0,0)'
- t
-
-
-
-
-
- geometric_type|&>geometric_type
- boolean
-
-
- Does first object not extend below second?
- Available for box, polygon,
- circle.
-
-
- box '(3,3),(0,0)' |&> box '(2,2),(0,0)'
- t
-
-
-
-
-
- box<^box
- boolean
-
-
- Is first object below second (allows edges to touch)?
-
-
- box '((1,1),(0,0))' <^ box '((2,2),(1,1))'
- t
-
-
-
-
-
- box>^box
- boolean
-
-
- Is first object above second (allows edges to touch)?
-
-
- box '((2,2),(1,1))' >^ box '((1,1),(0,0))'
- t
-
-
-
-
-
- geometric_type?#geometric_type
- boolean
-
-
- Do these objects intersect?
- Available for these pairs of types:
- (box, box),
- (lseg, box),
- (lseg, lseg),
- (lseg, line),
- (line, box),
- (line, line),
- (path, path).
-
-
- lseg '[(-1,0),(1,0)]' ?# box '(2,2),(-2,-2)'
- t
-
-
-
-
-
- ?-line
- boolean
-
-
- ?-lseg
- boolean
-
-
- Is line horizontal?
-
-
- ?- lseg '[(-1,0),(1,0)]'
- t
-
-
-
-
-
- point?-point
- boolean
-
-
- Are points horizontally aligned (that is, have same y coordinate)?
-
-
- point '(1,0)' ?- point '(0,0)'
- t
-
-
-
-
-
- ?|line
- boolean
-
-
- ?|lseg
- boolean
-
-
- Is line vertical?
-
-
- ?| lseg '[(-1,0),(1,0)]'
- f
-
-
-
-
-
- point?|point
- boolean
-
-
- Are points vertically aligned (that is, have same x coordinate)?
-
-
- point '(0,1)' ?| point '(0,0)'
- t
-
-
-
-
-
- line?-|line
- boolean
-
-
- lseg?-|lseg
- boolean
-
-
- Are lines perpendicular?
-
-
- lseg '[(0,0),(0,1)]' ?-| lseg '[(0,0),(1,0)]'
- t
-
-
-
-
-
- line?||line
- boolean
-
-
- lseg?||lseg
- boolean
-
-
- Are lines parallel?
-
-
- lseg '[(-1,0),(1,0)]' ?|| lseg '[(-1,2),(1,2)]'
- t
-
-
-
-
-
- geometric_type~=geometric_type
- boolean
-
-
- Are these objects the same?
- Available for point, box,
- polygon, circle.
-
-
- polygon '((0,0),(1,1))' ~= polygon '((1,1),(0,0))'
- t
-
-
-
-
-
-
-
-
- Note that the same as operator, ~=,
- represents the usual notion of equality for the point,
- box, polygon, and circle types.
- Some of the geometric types also have an = operator, but
- = compares for equal areas only.
- The other scalar comparison operators (<= and so
- on), where available for these types, likewise compare areas.
-
-
-
-
-
- Before PostgreSQL 14, the point
- is strictly below/above comparison operators point
- <<|point and point
- |>>point were respectively
- called <^ and >^. These
- names are still available, but are deprecated and will eventually be
- removed.
-
-
-
-
- Geometric Functions
-
-
-
-
- Function
-
-
- Description
-
-
- Example(s)
-
-
-
-
-
-
-
-
- area
-
- area ( geometric_type )
- double precision
-
-
- Computes area.
- Available for box, path, circle.
- A path input must be closed, else NULL is returned.
- Also, if the path is self-intersecting, the result may be
- meaningless.
-
-
- area(box '(2,2),(0,0)')
- 4
-
-
-
-
-
-
- center
-
- center ( geometric_type )
- point
-
-
- Computes center point.
- Available for box, circle.
-
-
- center(box '(1,2),(0,0)')
- (0.5,1)
-
-
-
-
-
-
- diagonal
-
- diagonal ( box )
- lseg
-
-
- Extracts box's diagonal as a line segment
- (same as lseg(box)).
-
-
- diagonal(box '(1,2),(0,0)')
- [(1,2),(0,0)]
-
-
-
-
-
-
- diameter
-
- diameter ( circle )
- double precision
-
-
- Computes diameter of circle.
-
-
- diameter(circle '<(0,0),2>')
- 4
-
-
-
-
-
-
- height
-
- height ( box )
- double precision
-
-
- Computes vertical size of box.
-
-
- height(box '(1,2),(0,0)')
- 2
-
-
-
-
-
-
- isclosed
-
- isclosed ( path )
- boolean
-
-
- Is path closed?
-
-
- isclosed(path '((0,0),(1,1),(2,0))')
- t
-
-
-
-
-
-
- isopen
-
- isopen ( path )
- boolean
-
-
- Is path open?
-
-
- isopen(path '[(0,0),(1,1),(2,0)]')
- t
-
-
-
-
-
-
- length
-
- length ( geometric_type )
- double precision
-
-
- Computes the total length.
- Available for lseg, path.
-
-
- length(path '((-1,0),(1,0))')
- 4
-
-
-
-
-
-
- npoints
-
- npoints ( geometric_type )
- integer
-
-
- Returns the number of points.
- Available for path, polygon.
-
-
- npoints(path '[(0,0),(1,1),(2,0)]')
- 3
-
-
-
-
-
-
- pclose
-
- pclose ( path )
- path
-
-
- Converts path to closed form.
-
-
- pclose(path '[(0,0),(1,1),(2,0)]')
- ((0,0),(1,1),(2,0))
-
-
-
-
-
-
- popen
-
- popen ( path )
- path
-
-
- Converts path to open form.
-
-
- popen(path '((0,0),(1,1),(2,0))')
- [(0,0),(1,1),(2,0)]
-
-
-
-
-
-
- radius
-
- radius ( circle )
- double precision
-
-
- Computes radius of circle.
-
-
- radius(circle '<(0,0),2>')
- 2
-
-
-
-
-
-
- slope
-
- slope ( point, point )
- double precision
-
-
- Computes slope of a line drawn through the two points.
-
-
- slope(point '(0,0)', point '(2,1)')
- 0.5
-
-
-
-
-
-
- width
-
- width ( box )
- double precision
-
-
- Computes horizontal size of box.
-
-
- width(box '(1,2),(0,0)')
- 1
-
-
-
-
-
-
-
- Geometric Type Conversion Functions
-
-
-
-
- Function
-
-
- Description
-
-
- Example(s)
-
-
-
-
-
-
-
-
- box
-
- box ( circle )
- box
-
-
- Computes box inscribed within the circle.
-
-
- box(circle '<(0,0),2>')
- (1.414213562373095,1.414213562373095),&zwsp;(-1.414213562373095,-1.414213562373095)
-
-
-
-
-
- box ( point )
- box
-
-
- Converts point to empty box.
-
-
- box(point '(1,0)')
- (1,0),(1,0)
-
-
-
-
-
- box ( point, point )
- box
-
-
- Converts any two corner points to box.
-
-
- box(point '(0,1)', point '(1,0)')
- (1,1),(0,0)
-
-
-
-
-
- box ( polygon )
- box
-
-
- Computes bounding box of polygon.
-
-
- box(polygon '((0,0),(1,1),(2,0))')
- (2,1),(0,0)
-
-
-
-
-
-
- bound_box
-
- bound_box ( box, box )
- box
-
-
- Computes bounding box of two boxes.
-
-
- bound_box(box '(1,1),(0,0)', box '(4,4),(3,3)')
- (4,4),(0,0)
-
-
-
-
-
-
- circle
-
- circle ( box )
- circle
-
-
- Computes smallest circle enclosing box.
-
-
- circle(box '(1,1),(0,0)')
- <(0.5,0.5),0.7071067811865476>
-
-
-
-
-
- circle ( point, double precision )
- circle
-
-
- Constructs circle from center and radius.
-
-
- circle(point '(0,0)', 2.0)
- <(0,0),2>
-
-
-
-
-
- circle ( polygon )
- circle
-
-
- 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.
-
-
- circle(polygon '((0,0),(1,3),(2,0))')
- <(1,1),1.6094757082487299>
-
-
-
-
-
-
- line
-
- line ( point, point )
- line
-
-
- Converts two points to the line through them.
-
-
- line(point '(-1,0)', point '(1,0)')
- {0,-1,0}
-
-
-
-
-
-
- lseg
-
- lseg ( box )
- lseg
-
-
- Extracts box's diagonal as a line segment.
-
-
- lseg(box '(1,0),(-1,0)')
- [(1,0),(-1,0)]
-
-
-
-
-
- lseg ( point, point )
- lseg
-
-
- Constructs line segment from two endpoints.
-
-
- lseg(point '(-1,0)', point '(1,0)')
- [(-1,0),(1,0)]
-
-
-
-
-
-
- path
-
- path ( polygon )
- path
-
-
- Converts polygon to a closed path with the same list of points.
-
-
- path(polygon '((0,0),(1,1),(2,0))')
- ((0,0),(1,1),(2,0))
-
-
-
-
-
-
- point
-
- point ( double precision, double precision )
- point
-
-
- Constructs point from its coordinates.
-
-
- point(23.4, -44.5)
- (23.4,-44.5)
-
-
-
-
-
- point ( box )
- point
-
-
- Computes center of box.
-
-
- point(box '(1,0),(-1,0)')
- (0,0)
-
-
-
-
-
- point ( circle )
- point
-
-
- Computes center of circle.
-
-
- point(circle '<(0,0),2>')
- (0,0)
-
-
-
-
-
- point ( lseg )
- point
-
-
- Computes center of line segment.
-
-
- point(lseg '[(-1,0),(1,0)]')
- (0,0)
-
-
-
-
-
- point ( polygon )
- point
-
-
- Computes center of polygon (the mean of the
- positions of the polygon's points).
-
-
- point(polygon '((0,0),(1,1),(2,0))')
- (1,0.3333333333333333)
-
-
-
-
-
-
- polygon
-
- polygon ( box )
- polygon
-
-
- Converts box to a 4-point polygon.
-
-
- polygon(box '(1,1),(0,0)')
- ((0,0),(0,1),(1,1),(1,0))
-
-
-
-
-
- polygon ( circle )
- polygon
-
-
- Converts circle to a 12-point polygon.
-
-
- polygon(circle '<(0,0),2>')
- ((-2,0),&zwsp;(-1.7320508075688774,0.9999999999999999),&zwsp;(-1.0000000000000002,1.7320508075688772),&zwsp;(-1.2246063538223773e-16,2),&zwsp;(0.9999999999999996,1.7320508075688774),&zwsp;(1.732050807568877,1.0000000000000007),&zwsp;(2,2.4492127076447545e-16),&zwsp;(1.7320508075688776,-0.9999999999999994),&zwsp;(1.0000000000000009,-1.7320508075688767),&zwsp;(3.673819061467132e-16,-2),&zwsp;(-0.9999999999999987,-1.732050807568878),&zwsp;(-1.7320508075688767,-1.0000000000000009))
-
-
-
-
-
- polygon ( integer, circle )
- polygon
-
-
- Converts circle to an n-point polygon.
-
-
- polygon(4, circle '<(3,0),1>')
- ((2,0),&zwsp;(3,1),&zwsp;(4,1.2246063538223773e-16),&zwsp;(3,-1))
-
-
-
-
-
- polygon ( path )
- polygon
-
-
- Converts closed path to a polygon with the same list of points.
-
-
- polygon(path '((0,0),(1,1),(2,0))')
- ((0,0),(1,1),(2,0))
-
-
-
-
-
-
-
-
- It is possible to access the two component numbers of a point
- as though the point were an array with indexes 0 and 1. For example, if
- t.p is a point column then
- SELECT p[0] FROM t retrieves the X coordinate and
- UPDATE t SET p[1] = ... changes the Y coordinate.
- In the same way, a value of type box or lseg can be treated
- as an array of two point values.
-
-
-
-
-
-
- Network Address Functions and Operators
-
-
- The IP network address types, cidr and inet,
- support the usual comparison operators shown in
-
- as well as the specialized operators and functions shown in
- and
- .
-
-
-
- Any cidr value can be cast to inet implicitly;
- therefore, the operators and functions shown below as operating on
- inet also work on cidr values. (Where there are
- separate functions for inet and cidr, it is
- because the behavior should be different for the two cases.)
- Also, it is permitted to cast an inet value
- to cidr. When this is done, any bits to the right of the
- netmask are silently zeroed to create a valid cidr value.
-
-
-
- IP Address Operators
-
-
-
-
- Operator
-
-
- Description
-
-
- Example(s)
-
-
-
-
-
-
-
- inet<<inet
- boolean
-
-
- 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.
-
-
- inet '192.168.1.5' << inet '192.168.1/24'
- t
-
-
- inet '192.168.0.5' << inet '192.168.1/24'
- f
-
-
- inet '192.168.1/24' << inet '192.168.1/24'
- f
-
-
-
-
-
- inet<<=inet
- boolean
-
-
- Is subnet contained by or equal to subnet?
-
-
- inet '192.168.1/24' <<= inet '192.168.1/24'
- t
-
-
-
-
-
- inet>>inet
- boolean
-
-
- Does subnet strictly contain subnet?
-
-
- inet '192.168.1/24' >> inet '192.168.1.5'
- t
-
-
-
-
-
- inet>>=inet
- boolean
-
-
- Does subnet contain or equal subnet?
-
-
- inet '192.168.1/24' >>= inet '192.168.1/24'
- t
-
-
-
-
-
- inet&&inet
- boolean
-
-
- Does either subnet contain or equal the other?
-
-
- inet '192.168.1/24' && inet '192.168.1.80/28'
- t
-
-
- inet '192.168.1/24' && inet '192.168.2.0/28'
- f
-
-
-
-
-
- ~inet
- inet
-
-
- Computes bitwise NOT.
-
-
- ~ inet '192.168.1.6'
- 63.87.254.249
-
-
-
-
-
- inet&inet
- inet
-
-
- Computes bitwise AND.
-
-
- inet '192.168.1.6' & inet '0.0.0.255'
- 0.0.0.6
-
-
-
-
-
- inet|inet
- inet
-
-
- Computes bitwise OR.
-
-
- inet '192.168.1.6' | inet '0.0.0.255'
- 192.168.1.255
-
-
-
-
-
- inet+bigint
- inet
-
-
- Adds an offset to an address.
-
-
- inet '192.168.1.6' + 25
- 192.168.1.31
-
-
-
-
-
- bigint+inet
- inet
-
-
- Adds an offset to an address.
-
-
- 200 + inet '::ffff:fff0:1'
- ::ffff:255.240.0.201
-
-
-
-
-
- inet-bigint
- inet
-
-
- Subtracts an offset from an address.
-
-
- inet '192.168.1.43' - 36
- 192.168.1.7
-
-
-
-
-
- inet-inet
- bigint
-
-
- Computes the difference of two addresses.
-
-
- inet '192.168.1.43' - inet '192.168.1.19'
- 24
-
-
- inet '::1' - inet '::ffff:1'
- -4294901760
-
-
-
-
-
-
-
- IP Address Functions
-
-
-
-
- Function
-
-
- Description
-
-
- Example(s)
-
-
-
-
-
-
-
-
- abbrev
-
- abbrev ( inet )
- text
-
-
- Creates an abbreviated display format as text.
- (The result is the same as the inet output function
- produces; it is abbreviated only in comparison to the
- result of an explicit cast to text, which for historical
- reasons will never suppress the netmask part.)
-
-
- abbrev(inet '10.1.0.0/32')
- 10.1.0.0
-
-
-
-
-
- abbrev ( cidr )
- text
-
-
- 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
- .)
-
-
- abbrev(cidr '10.1.0.0/16')
- 10.1/16
-
-
-
-
-
-
- broadcast
-
- broadcast ( inet )
- inet
-
-
- Computes the broadcast address for the address's network.
-
-
- broadcast(inet '192.168.1.5/24')
- 192.168.1.255/24
-
-
-
-
-
-
- family
-
- family ( inet )
- integer
-
-
- Returns the address's family: 4 for IPv4,
- 6 for IPv6.
-
-
- family(inet '::1')
- 6
-
-
-
-
-
-
- host
-
- host ( inet )
- text
-
-
- Returns the IP address as text, ignoring the netmask.
-
-
- host(inet '192.168.1.0/24')
- 192.168.1.0
-
-
-
-
-
-
- hostmask
-
- hostmask ( inet )
- inet
-
-
- Computes the host mask for the address's network.
-
-
- hostmask(inet '192.168.23.20/30')
- 0.0.0.3
-
-
-
-
-
-
- inet_merge
-
- inet_merge ( inet, inet )
- cidr
-
-
- Computes the smallest network that includes both of the given networks.
-
-
- inet_merge(inet '192.168.1.5/24', inet '192.168.2.5/24')
- 192.168.0.0/22
-
-
-
-
-
-
- inet_same_family
-
- inet_same_family ( inet, inet )
- boolean
-
-
- Tests whether the addresses belong to the same IP family.
-
-
- inet_same_family(inet '192.168.1.5/24', inet '::1')
- f
-
-
-
-
-
-
- masklen
-
- masklen ( inet )
- integer
-
-
- Returns the netmask length in bits.
-
-
- masklen(inet '192.168.1.5/24')
- 24
-
-
-
-
-
-
- netmask
-
- netmask ( inet )
- inet
-
-
- Computes the network mask for the address's network.
-
-
- netmask(inet '192.168.1.5/24')
- 255.255.255.0
-
-
-
-
-
-
- network
-
- network ( inet )
- cidr
-
-
- 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 cidr.)
-
-
- network(inet '192.168.1.5/24')
- 192.168.1.0/24
-
-
-
-
-
-
- set_masklen
-
- set_masklen ( inet, integer )
- inet
-
-
- Sets the netmask length for an inet value.
- The address part does not change.
-
-
- set_masklen(inet '192.168.1.5/24', 16)
- 192.168.1.5/16
-
-
-
-
-
- set_masklen ( cidr, integer )
- cidr
-
-
- Sets the netmask length for a cidr value.
- Address bits to the right of the new netmask are set to zero.
-
-
- set_masklen(cidr '192.168.1.0/24', 16)
- 192.168.0.0/16
-
-
-
-
-
-
- text
-
- text ( inet )
- text
-
-
- Returns the unabbreviated IP address and netmask length as text.
- (This has the same result as an explicit cast to text.)
-
-
- text(inet '192.168.1.5')
- 192.168.1.5/32
-
-
-
-
-
-
-
-
- The abbrev, host,
- and text functions are primarily intended to offer
- alternative display formats for IP addresses.
-
-
-
-
- The MAC address types, macaddr and macaddr8,
- support the usual comparison operators shown in
-
- as well as the specialized functions shown in
- .
- In addition, they support the bitwise logical operators
- ~, & and |
- (NOT, AND and OR), just as shown above for IP addresses.
-
-
-
- MAC Address Functions
-
-
-
-
- Function
-
-
- Description
-
-
- Example(s)
-
-
-
-
-
-
-
-
- trunc
-
- trunc ( macaddr )
- macaddr
-
-
- 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 PostgreSQL).
-
-
- trunc(macaddr '12:34:56:78:90:ab')
- 12:34:56:00:00:00
-
-
-
-
-
- trunc ( macaddr8 )
- macaddr8
-
-
- 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 PostgreSQL).
-
-
- trunc(macaddr8 '12:34:56:78:90:ab:cd:ef')
- 12:34:56:00:00:00:00:00
-
-
-
-
-
-
- macaddr8_set7bit
-
- macaddr8_set7bit ( macaddr8 )
- macaddr8
-
-
- Sets the 7th bit of the address to one, creating what is known as
- modified EUI-64, for inclusion in an IPv6 address.
-
-
- macaddr8_set7bit(macaddr8 '00:34:56:ab:cd:ef')
- 02:34:56:ff:fe:ab:cd:ef
-
-
-
-
-
-
-
-
-
-
- Text Search Functions and Operators
-
-
- full text search
- functions and operators
-
-
-
- text search
- functions and operators
-
-
-
- ,
- and
-
- summarize the functions and operators that are provided
- for full text searching. See for a detailed
- explanation of PostgreSQL's text search
- facility.
-
-
-
- Text Search Operators
-
-
-
-
- Operator
-
-
- Description
-
-
- Example(s)
-
-
-
-
-
-
-
- tsvector@@tsquery
- boolean
-
-
- tsquery@@tsvector
- boolean
-
-
- Does tsvector match tsquery?
- (The arguments can be given in either order.)
-
-
- to_tsvector('fat cats ate rats') @@ to_tsquery('cat & rat')
- t
-
-
-
-
-
- text@@tsquery
- boolean
-
-
- Does text string, after implicit invocation
- of to_tsvector(), match tsquery?
-
-
- 'fat cats ate rats' @@ to_tsquery('cat & rat')
- t
-
-
-
-
-
- tsvector||tsvector
- tsvector
-
-
- Concatenates two tsvectors. If both inputs contain
- lexeme positions, the second input's positions are adjusted
- accordingly.
-
-
- 'a:1 b:2'::tsvector || 'c:1 d:2 b:3'::tsvector
- 'a':1 'b':2,5 'c':3 'd':4
-
-
-
-
-
- tsquery&&tsquery
- tsquery
-
-
- ANDs two tsquerys together, producing a query that
- matches documents that match both input queries.
-
-
- 'fat | rat'::tsquery && 'cat'::tsquery
- ( 'fat' | 'rat' ) & 'cat'
-
-
-
-
-
- tsquery||tsquery
- tsquery
-
-
- ORs two tsquerys together, producing a query that
- matches documents that match either input query.
-
-
- 'fat | rat'::tsquery || 'cat'::tsquery
- 'fat' | 'rat' | 'cat'
-
-
-
-
-
- !!tsquery
- tsquery
-
-
- Negates a tsquery, producing a query that matches
- documents that do not match the input query.
-
-
- !! 'cat'::tsquery
- !'cat'
-
-
-
-
-
- tsquery<->tsquery
- tsquery
-
-
- Constructs a phrase query, which matches if the two input queries
- match at successive lexemes.
-
-
- to_tsquery('fat') <-> to_tsquery('rat')
- 'fat' <-> 'rat'
-
-
-
-
-
- tsquery@>tsquery
- boolean
-
-
- Does first tsquery contain the second? (This considers
- only whether all the lexemes appearing in one query appear in the
- other, ignoring the combining operators.)
-
-
- 'cat'::tsquery @> 'cat & rat'::tsquery
- f
-
-
-
-
-
- tsquery<@tsquery
- boolean
-
-
- Is first tsquery contained in the second? (This
- considers only whether all the lexemes appearing in one query appear
- in the other, ignoring the combining operators.)
-
-
- 'cat'::tsquery <@ 'cat & rat'::tsquery
- t
-
-
- 'cat'::tsquery <@ '!cat & rat'::tsquery
- t
-
-
-
-
-
-
-
- In addition to these specialized operators, the usual comparison
- operators shown in are
- available for types tsvector and tsquery.
- These are not very
- useful for text searching but allow, for example, unique indexes to be
- built on columns of these types.
-
-
-
- Text Search Functions
-
-
-
-
- Function
-
-
- Description
-
-
- Example(s)
-
-
-
-
-
-
-
-
- array_to_tsvector
-
- array_to_tsvector ( text[] )
- tsvector
-
-
- Converts an array of text strings to a tsvector.
- The given strings are used as lexemes as-is, without further
- processing. Array elements must not be empty strings
- or NULL.
-
-
- array_to_tsvector('{fat,cat,rat}'::text[])
- 'cat' 'fat' 'rat'
-
-
-
-
-
-
- get_current_ts_config
-
- get_current_ts_config ( )
- regconfig
-
-
- Returns the OID of the current default text search configuration
- (as set by ).
-
-
- get_current_ts_config()
- english
-
-
-
-
-
-
- length
-
- length ( tsvector )
- integer
-
-
- Returns the number of lexemes in the tsvector.
-
-
- length('fat:2,4 cat:3 rat:5A'::tsvector)
- 3
-
-
-
-
-
-
- numnode
-
- numnode ( tsquery )
- integer
-
-
- Returns the number of lexemes plus operators in
- the tsquery.
-
-
- numnode('(fat & rat) | cat'::tsquery)
- 5
-
-
-
-
-
-
- plainto_tsquery
-
- plainto_tsquery (
- configregconfig,
- querytext )
- tsquery
-
-
- Converts text to a tsquery, 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.
-
-
- plainto_tsquery('english', 'The Fat Rats')
- 'fat' & 'rat'
-
-
-
-
-
-
- phraseto_tsquery
-
- phraseto_tsquery (
- configregconfig,
- querytext )
- tsquery
-
-
- Converts text to a tsquery, 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.
-
-
- phraseto_tsquery('english', 'The Fat Rats')
- 'fat' <-> 'rat'
-
-
- phraseto_tsquery('english', 'The Cat and Rats')
- 'cat' <2> 'rat'
-
-
-
-
-
-
- websearch_to_tsquery
-
- websearch_to_tsquery (
- configregconfig,
- querytext )
- tsquery
-
-
- Converts text to a tsquery, normalizing words according
- to the specified or default configuration. Quoted word sequences are
- converted to phrase tests. The word or 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.
-
-
- websearch_to_tsquery('english', '"fat rat" or cat dog')
- 'fat' <-> 'rat' | 'cat' & 'dog'
-
-
-
-
-
-
- querytree
-
- querytree ( tsquery )
- text
-
-
- Produces a representation of the indexable portion of
- a tsquery. A result that is empty or
- just T indicates a non-indexable query.
-
-
- querytree('foo & ! bar'::tsquery)
- 'foo'
-
-
-
-
-
-
- setweight
-
- setweight ( vectortsvector, weight"char" )
- tsvector
-
-
- Assigns the specified weight to each element
- of the vector.
-
-
- setweight('fat:2,4 cat:3 rat:5B'::tsvector, 'A')
- 'cat':3A 'fat':2A,4A 'rat':5A
-
-
-
-
-
-
- setweight
- setweight for specific lexeme(s)
-
- setweight ( vectortsvector, weight"char", lexemestext[] )
- tsvector
-
-
- Assigns the specified weight to elements
- of the vector that are listed
- in lexemes.
- The strings in lexemes are taken as lexemes
- as-is, without further processing. Strings that do not match any
- lexeme in vector are ignored.
-
-
- setweight('fat:2,4 cat:3 rat:5,6B'::tsvector, 'A', '{cat,rat}')
- 'cat':3A 'fat':2,4 'rat':5A,6A
-
-
-
-
-
-
- strip
-
- strip ( tsvector )
- tsvector
-
-
- Removes positions and weights from the tsvector.
-
-
- strip('fat:2,4 cat:3 rat:5A'::tsvector)
- 'cat' 'fat' 'rat'
-
-
-
-
-
-
- to_tsquery
-
- to_tsquery (
- configregconfig,
- querytext )
- tsquery
-
-
- Converts text to a tsquery, normalizing words according to
- the specified or default configuration. The words must be combined
- by valid tsquery operators.
-
-
- to_tsquery('english', 'The & Fat & Rats')
- 'fat' & 'rat'
-
-
-
-
-
-
- to_tsvector
-
- to_tsvector (
- configregconfig,
- documenttext )
- tsvector
-
-
- Converts text to a tsvector, normalizing words according
- to the specified or default configuration. Position information is
- included in the result.
-
-
- to_tsvector('english', 'The Fat Rats')
- 'fat':2 'rat':3
-
-
-
-
-
- to_tsvector (
- configregconfig,
- documentjson )
- tsvector
-
-
- to_tsvector (
- configregconfig,
- documentjsonb )
- tsvector
-
-
- Converts each string value in the JSON document to
- a tsvector, 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 document order of the fields of a
- JSON object is implementation-dependent when the input
- is jsonb; observe the difference in the examples.)
-
-
- to_tsvector('english', '{"aa": "The Fat Rats", "b": "dog"}'::json)
- 'dog':5 'fat':2 'rat':3
-
-
- to_tsvector('english', '{"aa": "The Fat Rats", "b": "dog"}'::jsonb)
- 'dog':1 'fat':4 'rat':5
-
-
-
-
-
-
- json_to_tsvector
-
- json_to_tsvector (
- configregconfig,
- documentjson,
- filterjsonb )
- tsvector
-
-
-
- jsonb_to_tsvector
-
- jsonb_to_tsvector (
- configregconfig,
- documentjsonb,
- filterjsonb )
- tsvector
-
-
- Selects each item in the JSON document that is requested by
- the filter and converts each one to
- a tsvector, 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 document order of the fields of a
- JSON object is implementation-dependent when the input
- is jsonb.)
- The filter must be a jsonb
- array containing zero or more of these keywords:
- "string" (to include all string values),
- "numeric" (to include all numeric values),
- "boolean" (to include all boolean values),
- "key" (to include all keys), or
- "all" (to include all the above).
- As a special case, the filter can also be a
- simple JSON value that is one of these keywords.
-
-
- json_to_tsvector('english', '{"a": "The Fat Rats", "b": 123}'::json, '["string", "numeric"]')
- '123':5 'fat':2 'rat':3
-
-
- json_to_tsvector('english', '{"cat": "The Fat Rats", "dog": 123}'::json, '"all"')
- '123':9 'cat':1 'dog':7 'fat':4 'rat':5
-
-
-
-
-
-
- ts_delete
-
- ts_delete ( vectortsvector, lexemetext )
- tsvector
-
-
- Removes any occurrence of the given lexeme
- from the vector.
- The lexeme string is treated as a lexeme as-is,
- without further processing.
-
-
- ts_delete('fat:2,4 cat:3 rat:5A'::tsvector, 'fat')
- 'cat':3 'rat':5A
-
-
-
-
-
- ts_delete ( vectortsvector, lexemestext[] )
- tsvector
-
-
- Removes any occurrences of the lexemes
- in lexemes
- from the vector.
- The strings in lexemes are taken as lexemes
- as-is, without further processing. Strings that do not match any
- lexeme in vector are ignored.
-
-
- ts_delete('fat:2,4 cat:3 rat:5A'::tsvector, ARRAY['fat','rat'])
- 'cat':3
-
-
-
-
-
-
- ts_filter
-
- ts_filter ( vectortsvector, weights"char"[] )
- tsvector
-
-
- Selects only elements with the given weights
- from the vector.
-
-
- ts_filter('fat:2,4 cat:3b,7c rat:5A'::tsvector, '{a,b}')
- 'cat':3B 'rat':5A
-
-
-
-
-
-
- ts_headline
-
- ts_headline (
- configregconfig,
- documenttext,
- querytsquery
- , optionstext )
- text
-
-
- Displays, in an abbreviated form, the match(es) for
- the query in
- the document, which must be raw text not
- a tsvector. 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
- , which also describes the
- available options.
-
-
- ts_headline('The fat cat ate the rat.', 'cat')
- The fat <b>cat</b> ate the rat.
-
-
-
-
-
- ts_headline (
- configregconfig,
- documentjson,
- querytsquery
- , optionstext )
- text
-
-
- ts_headline (
- configregconfig,
- documentjsonb,
- querytsquery
- , optionstext )
- text
-
-
- Displays, in an abbreviated form, match(es) for
- the query that occur in string values
- within the JSON document.
- See for more details.
-
-
- ts_headline('{"cat":"raining cats and dogs"}'::jsonb, 'cat')
- {"cat": "raining <b>cats</b> and dogs"}
-
-
-
-
-
-
- ts_rank
-
- ts_rank (
- weightsreal[],
- vectortsvector,
- querytsquery
- , normalizationinteger )
- real
-
-
- Computes a score showing how well
- the vector matches
- the query. See
- for details.
-
-
- ts_rank(to_tsvector('raining cats and dogs'), 'cat')
- 0.06079271
-
-
-
-
-
-
- ts_rank_cd
-
- ts_rank_cd (
- weightsreal[],
- vectortsvector,
- querytsquery
- , normalizationinteger )
- real
-
-
- Computes a score showing how well
- the vector matches
- the query, using a cover density
- algorithm. See for details.
-
-
- ts_rank_cd(to_tsvector('raining cats and dogs'), 'cat')
- 0.1
-
-
-
-
-
-
- ts_rewrite
-
- ts_rewrite ( querytsquery,
- targettsquery,
- substitutetsquery )
- tsquery
-
-
- Replaces occurrences of target
- with substitute
- within the query.
- See for details.
-
-
- ts_rewrite('a & b'::tsquery, 'a'::tsquery, 'foo|bar'::tsquery)
- 'b' & ( 'foo' | 'bar' )
-
-
-
-
-
- ts_rewrite ( querytsquery,
- selecttext )
- tsquery
-
-
- Replaces portions of the query according to
- target(s) and substitute(s) obtained by executing
- a SELECT command.
- See for details.
-
-
- SELECT ts_rewrite('a & b'::tsquery, 'SELECT t,s FROM aliases')
- 'b' & ( 'foo' | 'bar' )
-
-
-
-
-
-
- tsquery_phrase
-
- tsquery_phrase ( query1tsquery, query2tsquery )
- tsquery
-
-
- Constructs a phrase query that searches
- for matches of query1
- and query2 at successive lexemes (same
- as <-> operator).
-
-
- tsquery_phrase(to_tsquery('fat'), to_tsquery('cat'))
- 'fat' <-> 'cat'
-
-
-
-
-
- tsquery_phrase ( query1tsquery, query2tsquery, distanceinteger )
- tsquery
-
-
- Constructs a phrase query that searches
- for matches of query1 and
- query2 that occur exactly
- distance lexemes apart.
-
-
- tsquery_phrase(to_tsquery('fat'), to_tsquery('cat'), 10)
- 'fat' <10> 'cat'
-
-
-
-
-
-
- tsvector_to_array
-
- tsvector_to_array ( tsvector )
- text[]
-
-
- Converts a tsvector to an array of lexemes.
-
-
- tsvector_to_array('fat:2,4 cat:3 rat:5A'::tsvector)
- {cat,fat,rat}
-
-
-
-
-
-
- unnest
- for tsvector
-
- unnest ( tsvector )
- setof record
- ( lexemetext,
- positionssmallint[],
- weightstext )
-
-
- Expands a tsvector into a set of rows, one per lexeme.
-
-
- select * from unnest('cat:3 fat:2,4 rat:5A'::tsvector)
-
-
- lexeme | positions | weights
---------+-----------+---------
- cat | {3} | {D}
- fat | {2,4} | {D,D}
- rat | {5} | {A}
-
-
-
-
-
-
-
-
-
- All the text search functions that accept an optional regconfig
- argument will use the configuration specified by
-
- when that argument is omitted.
-
-
-
-
- The functions in
-
- are listed separately because they are not usually used in everyday text
- searching operations. They are primarily helpful for development and
- debugging of new text search configurations.
-
-
-
- Text Search Debugging Functions
-
-
-
-
- Function
-
-
- Description
-
-
- Example(s)
-
-
-
-
-
-
-
-
- ts_debug
-
- ts_debug (
- configregconfig,
- documenttext )
- setof record
- ( aliastext,
- descriptiontext,
- tokentext,
- dictionariesregdictionary[],
- dictionaryregdictionary,
- lexemestext[] )
-
-
- Extracts and normalizes tokens from
- the document according to the specified or
- default text search configuration, and returns information about how
- each token was processed.
- See for details.
-
-
- ts_debug('english', 'The Brightest supernovaes')
- (asciiword,"Word, all ASCII",The,{english_stem},english_stem,{}) ...
-
-
-
-
-
-
- ts_lexize
-
- ts_lexize ( dictregdictionary, tokentext )
- text[]
-
-
- 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 for details.
-
-
- ts_lexize('english_stem', 'stars')
- {star}
-
-
-
-
-
-
- ts_parse
-
- ts_parse ( parser_nametext,
- documenttext )
- setof record
- ( tokidinteger,
- tokentext )
-
-
- Extracts tokens from the document using the
- named parser.
- See for details.
-
-
- ts_parse('default', 'foo - bar')
- (1,foo) ...
-
-
-
-
-
- ts_parse ( parser_oidoid,
- documenttext )
- setof record
- ( tokidinteger,
- tokentext )
-
-
- Extracts tokens from the document using a
- parser specified by OID.
- See for details.
-
-
- ts_parse(3722, 'foo - bar')
- (1,foo) ...
-
-
-
-
-
-
- ts_token_type
-
- ts_token_type ( parser_nametext )
- setof record
- ( tokidinteger,
- aliastext,
- descriptiontext )
-
-
- Returns a table that describes each type of token the named parser can
- recognize.
- See for details.
-
-
- ts_token_type('default')
- (1,asciiword,"Word, all ASCII") ...
-
-
-
-
-
- ts_token_type ( parser_oidoid )
- setof record
- ( tokidinteger,
- aliastext,
- descriptiontext )
-
-
- Returns a table that describes each type of token a parser specified
- by OID can recognize.
- See for details.
-
-
- ts_token_type(3722)
- (1,asciiword,"Word, all ASCII") ...
-
-
-
-
-
-
- ts_stat
-
- ts_stat ( sqlquerytext
- , weightstext )
- setof record
- ( wordtext,
- ndocinteger,
- nentryinteger )
-
-
- Executes the sqlquery, which must return a
- single tsvector column, and returns statistics about each
- distinct lexeme contained in the data.
- See for details.
-
-
- ts_stat('SELECT vector FROM apod')
- (foo,10,15) ...
-
-
-
-
-
-
-
-
-
- UUID Functions
-
-
- UUID
- generating
-
-
-
- gen_random_uuid
-
-
-
- uuid_extract_timestamp
-
-
-
- uuid_extract_version
-
-
-
- PostgreSQL includes one function to generate a UUID:
-
-gen_random_uuid () uuid
-
- This function returns a version 4 (random) UUID. This is the most commonly
- used type of UUID and is appropriate for most applications.
-
-
-
- The module provides additional functions that
- implement other standard algorithms for generating UUIDs.
-
-
-
- There are also functions to extract data from UUIDs:
-
-uuid_extract_timestamp (uuid) timestamp with time zone
-
- This function extracts a timestamp with time zone from UUID
- version 1. For other versions, this function returns null. Note that the
- extracted timestamp is not necessarily exactly equal to the time the UUID
- was generated; this depends on the implementation that generated the UUID.
-
-
-
-
-uuid_extract_version (uuid) smallint
-
- This function extracts the version from a UUID of the variant described by
- RFC 4122. For
- other variants, this function returns null. For example, for a UUID
- generated by gen_random_uuid, this function will
- return 4.
-
-
-
- PostgreSQL also provides the usual comparison
- operators shown in for
- UUIDs.
-
-
-
-
-
- XML Functions
-
-
- XML Functions
-
-
-
- The functions and function-like expressions described in this
- section operate on values of type xml. See for information about the xml
- type. The function-like expressions xmlparse
- and xmlserialize for converting to and from
- type xml are documented there, not in this section.
-
-
-
- Use of most of these functions
- requires PostgreSQL to have been built
- with configure --with-libxml.
-
-
-
- Producing XML Content
-
-
- 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.
-
-
-
- <literal>xmltext</literal>
-
-
- xmltext
-
-
-
-xmltext ( text ) xml
-
-
-
- The function xmltext returns an XML value with a single
- text node containing the input argument as its content. Predefined entities
- like ampersand (), left and right angle brackets
- (]]>), and quotation marks ()
- are escaped.
-
-
-
- Example:
-');
- xmltext
--------------------------
- < foo & bar >
-]]>
-
-
-
-
- <literal>xmlcomment</literal>
-
-
- xmlcomment
-
-
-
-xmlcomment ( text ) xml
-
-
-
- The function xmlcomment creates an XML value
- containing an XML comment with the specified text as content.
- The text cannot contain -- or end with a
- -, otherwise the resulting construct
- would not be a valid XML comment.
- If the argument is null, the result is null.
-
-
-
- Example:
-
-]]>
-
-
-
-
- <literal>xmlconcat</literal>
-
-
- xmlconcat
-
-
-
-xmlconcat ( xml, ... ) xml
-
-
-
- The function xmlconcat 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.
-
-
-
- Example:
-', 'foo');
-
- xmlconcat
-----------------------
- foo
-]]>
-
-
-
- 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
- yes, then that value is used in the result. If
- all argument values have a standalone declaration value and at
- least one is no, 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.
-
-
-
- Example:
-', '');
-
- xmlconcat
------------------------------------
-
-]]>
-
-
-
-
- <literal>xmlelement</literal>
-
-
- xmlelement
-
-
-
-xmlelement ( NAMEname, XMLATTRIBUTES ( attvalueASattname, ... ) , content, ... ) xml
-
-
-
- The xmlelement expression produces an XML
- element with the given name, attributes, and content.
- The name
- and attname items shown in the syntax are
- simple identifiers, not values. The attvalue
- and content items are expressions, which can
- yield any PostgreSQL data type. The
- argument(s) within XMLATTRIBUTES generate attributes
- of the XML element; the content value(s) are
- concatenated to form its content.
-
-
-
- Examples:
-
-
-SELECT xmlelement(name foo, xmlattributes('xyz' as bar));
-
- xmlelement
-------------------
-
-
-SELECT xmlelement(name foo, xmlattributes(current_date as bar), 'cont', 'ent');
-
- xmlelement
--------------------------------------
- content
-]]>
-
-
-
- Element and attribute names that are not valid XML names are
- escaped by replacing the offending characters by the sequence
- _xHHHH_, where
- HHHH is the character's Unicode
- codepoint in hexadecimal notation. For example:
-
-]]>
-
-
-
- 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:
-
-CREATE TABLE test (a xml, b xml);
-SELECT xmlelement(name test, xmlattributes(a, b)) FROM test;
-
- But these are not:
-
-SELECT xmlelement(name test, xmlattributes('constant'), a, b) FROM test;
-SELECT xmlelement(name test, xmlattributes(func(a, b))) FROM test;
-
-
-
-
- Element content, if specified, will be formatted according to
- its data type. If the content is itself of type xml,
- complex XML documents can be constructed. For example:
-
-]]>
-
- Content of other types will be formatted into valid XML character
- data. This means in particular that the characters <, >,
- and & will be converted to entities. Binary data (data type
- bytea) will be represented in base64 or hex
- encoding, depending on the setting of the configuration parameter
- . The particular behavior for
- 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 .
-
-
-
-
- <literal>xmlforest</literal>
-
-
- xmlforest
-
-
-
-xmlforest ( contentASname, ... ) xml
-
-
-
- The xmlforest expression produces an XML
- forest (sequence) of elements using the given names and content.
- As for xmlelement,
- each name must be a simple identifier, while
- the content expressions can have any data
- type.
-
-
-
- Examples:
-
-SELECT xmlforest('abc' AS foo, 123 AS bar);
-
- xmlforest
-------------------------------
- <foo>abc</foo><bar>123</bar>
-
-
-SELECT xmlforest(table_name, column_name)
-FROM information_schema.columns
-WHERE table_schema = 'pg_catalog';
-
- xmlforest
-------------------------------------&zwsp;-----------------------------------
- <table_name>pg_authid</table_name>&zwsp;<column_name>rolname</column_name>
- <table_name>pg_authid</table_name>&zwsp;<column_name>rolsuper</column_name>
- ...
-
-
- 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.
-
-
-
- Element names that are not valid XML names are escaped as shown
- for xmlelement above. Similarly, content
- data is escaped to make valid XML content, unless it is already
- of type xml.
-
-
-
- Note that XML forests are not valid XML documents if they consist
- of more than one element, so it might be useful to wrap
- xmlforest expressions in
- xmlelement.
-
-
-
-
- <literal>xmlpi</literal>
-
-
- xmlpi
-
-
-
-xmlpi ( NAMEname, content ) xml
-
-
-
- The xmlpi expression creates an XML
- processing instruction.
- As for xmlelement,
- the name must be a simple identifier, while
- the content expression can have any data type.
- The content, if present, must not contain the
- character sequence ?>.
-
-
-
- Example:
-
-]]>
-
-
-
-
- <literal>xmlroot</literal>
-
-
- xmlroot
-
-
-
-xmlroot ( xml, VERSION {text|NO VALUE} , STANDALONE {YES|NO|NO VALUE} ) xml
-
-
-
- The xmlroot 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.
-
-
-
-abc'),
- version '1.0', standalone yes);
-
- xmlroot
-----------------------------------------
-
- abc
-]]>
-
-
-
-
- <literal>xmlagg</literal>
-
-
- xmlagg
-
-
-
-xmlagg ( xml ) xml
-
-
-
- The function xmlagg is, unlike the other
- functions described here, an aggregate function. It concatenates the
- input values to the aggregate function call,
- much like xmlconcat does, except that concatenation
- occurs across rows rather than across expressions in a single row.
- See for additional information
- about aggregate functions.
-
-
-
- Example:
-abc');
-INSERT INTO test VALUES (2, '');
-SELECT xmlagg(x) FROM test;
- xmlagg
-----------------------
- abc
-]]>
-
-
-
- To determine the order of the concatenation, an ORDER BY
- clause may be added to the aggregate call as described in
- . For example:
-
-abc
-]]>
-
-
-
- The following non-standard approach used to be recommended
- in previous versions, and may still be useful in specific
- cases:
-
-abc
-]]>
-
-
-
-
-
- XML Predicates
-
-
- The expressions described in this section check properties
- of xml values.
-
-
-
- <literal>IS DOCUMENT</literal>
-
-
- IS DOCUMENT
-
-
-
-xmlIS DOCUMENTboolean
-
-
-
- The expression IS DOCUMENT returns true if the
- argument XML value is a proper XML document, false if it is not
- (that is, it is a content fragment), or null if the argument is
- null. See about the difference
- between documents and content fragments.
-
-
-
-
- <literal>IS NOT DOCUMENT</literal>
-
-
- IS NOT DOCUMENT
-
-
-
-xmlIS NOT DOCUMENTboolean
-
-
-
- The expression IS NOT DOCUMENT 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.
-
-
-
-
- <literal>XMLEXISTS</literal>
-
-
- XMLEXISTS
-
-
-
-XMLEXISTS ( textPASSINGBY {REF|VALUE}xmlBY {REF|VALUE} ) boolean
-
-
-
- The function xmlexists 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.
-
-
-
- Example:
- TorontoOttawa');
-
- xmlexists
-------------
- t
-(1 row)
-]]>
-
-
-
- The BY REF and BY VALUE clauses
- are accepted in PostgreSQL, but are ignored,
- as discussed in .
-
-
-
- In the SQL standard, the xmlexists function
- evaluates an expression in the XML Query language,
- but PostgreSQL allows only an XPath 1.0
- expression, as discussed in
- .
-
-
-
-
- <literal>xml_is_well_formed</literal>
-
-
- xml_is_well_formed
-
-
-
- xml_is_well_formed_document
-
-
-
- xml_is_well_formed_content
-
-
-
-xml_is_well_formed ( text ) boolean
-xml_is_well_formed_document ( text ) boolean
-xml_is_well_formed_content ( text ) boolean
-
-
-
- These functions check whether a text string represents
- well-formed XML, returning a Boolean result.
- xml_is_well_formed_document checks for a well-formed
- document, while xml_is_well_formed_content checks
- for well-formed content. xml_is_well_formed does
- the former if the configuration
- parameter is set to DOCUMENT, or the latter if it is set to
- CONTENT. This means that
- xml_is_well_formed is useful for seeing whether
- a simple cast to type xml will succeed, whereas the other two
- functions are useful for seeing whether the corresponding variants of
- XMLPARSE will succeed.
-
-
-
- Examples:
-
-');
- xml_is_well_formed
---------------------
- f
-(1 row)
-
-SELECT xml_is_well_formed('');
- 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('bar');
- xml_is_well_formed_document
------------------------------
- t
-(1 row)
-
-SELECT xml_is_well_formed_document('bar');
- xml_is_well_formed_document
------------------------------
- f
-(1 row)
-]]>
-
- The last example shows that the checks include whether
- namespaces are correctly matched.
-
-
-
-
-
- Processing XML
-
-
- To process values of data type xml, PostgreSQL offers
- the functions xpath and
- xpath_exists, which evaluate XPath 1.0
- expressions, and the XMLTABLE
- table function.
-
-
-
- <literal>xpath</literal>
-
-
- XPath
-
-
-
-xpath ( xpathtext, xmlxml, nsarraytext[] ) xml[]
-
-
-
- The function xpath evaluates the XPath 1.0
- expression xpath (given as text)
- against the XML value
- xml. 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.
-
-
-
- The second argument must be a well formed XML document. In particular,
- it must have a single root node element.
-
-
-
- The optional third argument of the function is an array of namespace
- mappings. This array should be a two-dimensional text array with
- the length of the second axis being equal to 2 (i.e., it should be an
- array of arrays, each of which consists of exactly 2 elements).
- The first element of each array entry is the namespace name (alias), the
- second the namespace URI. It is not required that aliases provided in
- this array be the same as those being used in the XML document itself (in
- other words, both in the XML document and in the xpath
- function context, aliases are local).
-
-
-
- Example:
-test',
- ARRAY[ARRAY['my', 'http://example.com']]);
-
- xpath
---------
- {test}
-(1 row)
-]]>
-
-
-
- To deal with default (anonymous) namespaces, do something like this:
-test',
- ARRAY[ARRAY['mydefns', 'http://example.com']]);
-
- xpath
---------
- {test}
-(1 row)
-]]>
-
-
-
-
- <literal>xpath_exists</literal>
-
-
- xpath_exists
-
-
-
-xpath_exists ( xpathtext, xmlxml, nsarraytext[] ) boolean
-
-
-
- The function xpath_exists is a specialized form
- of the xpath 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 XMLEXISTS predicate,
- except that it also offers support for a namespace mapping argument.
-
-
-
- Example:
-test',
- ARRAY[ARRAY['my', 'http://example.com']]);
-
- xpath_exists
---------------
- t
-(1 row)
-]]>
-
-
-
-
- <literal>xmltable</literal>
-
-
- xmltable
-
-
-
- table function
- XMLTABLE
-
-
-
-XMLTABLE (
- XMLNAMESPACES ( namespace_uriASnamespace_name, ... ),
- row_expressionPASSINGBY {REF|VALUE}document_expressionBY {REF|VALUE}
- COLUMNSname { typePATHcolumn_expressionDEFAULTdefault_expressionNOT NULL | NULL
- | FOR ORDINALITY }
- , ...
-) setof record
-
-
-
- The xmltable 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 FROM clause.
-
-
-
- The optional XMLNAMESPACES clause gives a
- comma-separated list of namespace definitions, where
- each namespace_uri is a text
- expression and each namespace_name is a simple
- identifier. It specifies the XML namespaces used in the document and
- their aliases. A default namespace specification is not currently
- supported.
-
-
-
- The required row_expression argument is an
- XPath 1.0 expression (given as text) that is evaluated,
- passing the XML value document_expression as
- its context item, to obtain a set of XML nodes. These nodes are what
- xmltable transforms into output rows. No rows
- will be produced if the document_expression
- is null, nor if the row_expression produces
- an empty node-set or any value other than a node-set.
-
-
-
- document_expression provides the context
- item for the row_expression. It must be a
- well-formed XML document; fragments/forests are not accepted.
- The BY REF and BY VALUE clauses
- are accepted but ignored, as discussed in
- .
-
-
-
- In the SQL standard, the xmltable function
- evaluates expressions in the XML Query language,
- but PostgreSQL allows only XPath 1.0
- expressions, as discussed in
- .
-
-
-
- The required COLUMNS 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 FOR ORDINALITY is specified, in which case
- type integer is implicit). The path, default and
- nullability clauses are optional.
-
-
-
- A column marked FOR ORDINALITY will be populated
- with row numbers, starting with 1, in the order of nodes retrieved from
- the row_expression's result node-set.
- At most one column may be marked FOR ORDINALITY.
-
-
-
-
- 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
- .
-
-
-
-
- The column_expression for a column is an
- XPath 1.0 expression that is evaluated for each row, with the current
- node from the row_expression result as its
- context item, to find the value of the column. If
- no column_expression is given, then the
- column name is used as an implicit path.
-
-
-
- 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 xml, 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 1 or 0 if the output
- column's type category is numeric, otherwise true or
- false.)
-
-
-
- If a column's XPath expression returns a non-empty set of XML nodes
- and the column's PostgreSQL type is xml, the column will
- be assigned the expression result exactly, if it is of document or
- content form.
-
-
- 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
- string function.
-
-
-
-
-
- A non-XML result assigned to an xml 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 string function)
- to the PostgreSQL type.
-
-
-
- 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 NULL).
- Any xsi:nil attributes are ignored.
- Note that the whitespace-only text() node between two non-text
- elements is preserved, and that leading whitespace on a text()
- node is not flattened.
- The XPath 1.0 string function may be consulted for the
- rules defining the string value of other XML node types and non-XML values.
-
-
-
- The conversion rules presented here are not exactly those of the SQL
- standard, as discussed in .
-
-
-
- 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 NULL, unless
- a default_expression is specified; then the
- value resulting from evaluating that expression is used.
-
-
-
- A default_expression, rather than being
- evaluated immediately when xmltable 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
- nextval in
- default_expression.
-
-
-
- Columns may be marked NOT NULL. If the
- column_expression for a NOT
- NULL column does not match anything and there is
- no DEFAULT or
- the default_expression also evaluates to null,
- an error is reported.
-
-
-
- Examples:
-
-
- AU
- Australia
-
-
- JP
- Japan
- Shinzo Abe
- 145935
-
-
- SG
- Singapore
- 697
-
-
-$$ 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
-]]>
-
- 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:
-
-
- Hello2a2 bbbxxxCC
-
-$$ AS data;
-
-SELECT xmltable.*
- FROM xmlelements, XMLTABLE('/root' PASSING data COLUMNS element text);
- element
--------------------------
- Hello2a2 bbbxxxCC
-]]>
-
-
-
- The following example illustrates how
- the XMLNAMESPACES clause can be used to specify
- a list of namespaces
- used in the XML document as well as in the XPath expressions:
-
-
-
-
-
-'::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)
-]]>
-
-
-
-
-
- Mapping Tables to XML
-
-
- XML export
-
-
-
- The following functions map the contents of relational tables to
- XML values. They can be thought of as XML export functionality:
-
-table_to_xml ( tableregclass, nullsboolean,
- tableforestboolean, targetnstext ) xml
-query_to_xml ( querytext, nullsboolean,
- tableforestboolean, targetnstext ) xml
-cursor_to_xml ( cursorrefcursor, countinteger, nullsboolean,
- tableforestboolean, targetnstext ) xml
-
-
-
-
- table_to_xml maps the content of the named
- table, passed as parameter table. The
- regclass type accepts strings identifying tables using the
- usual notation, including optional schema qualification and
- double quotes (see for details).
- query_to_xml executes the
- query whose text is passed as parameter
- query and maps the result set.
- cursor_to_xml fetches the indicated number of
- rows from the cursor specified by the parameter
- cursor. This variant is recommended if
- large tables have to be mapped, because the result value is built
- up in memory by each function.
-
-
-
- If tableforest is false, then the resulting
- XML document looks like this:
-
-
- data
- data
-
-
-
- ...
-
-
- ...
-
-]]>
-
- If tableforest is true, the result is an
- XML content fragment that looks like this:
-
- data
- data
-
-
-
- ...
-
-
-...
-]]>
-
- If no table name is available, that is, when mapping a query or a
- cursor, the string table is used in the first
- format, row in the second format.
-
-
-
- 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
- cursor_to_xml function if the result values are to be
- reassembled into one document later on. The functions for
- producing XML content discussed above, in particular
- xmlelement, can be used to alter the results
- to taste.
-
-
-
- The data values are mapped in the same way as described for the
- function xmlelement above.
-
-
-
- The parameter nulls determines whether null
- values should be included in the output. If true, null values in
- columns are represented as:
-
-]]>
- where xsi 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.
-
-
-
- The parameter targetns specifies the
- desired XML namespace of the result. If no particular namespace
- is wanted, an empty string should be passed.
-
-
-
- The following functions return XML Schema documents describing the
- mappings performed by the corresponding functions above:
-
-table_to_xmlschema ( tableregclass, nullsboolean,
- tableforestboolean, targetnstext ) xml
-query_to_xmlschema ( querytext, nullsboolean,
- tableforestboolean, targetnstext ) xml
-cursor_to_xmlschema ( cursorrefcursor, nullsboolean,
- tableforestboolean, targetnstext ) xml
-
- It is essential that the same parameters are passed in order to
- obtain matching XML data mappings and XML Schema documents.
-
-
-
- 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:
-
-table_to_xml_and_xmlschema ( tableregclass, nullsboolean,
- tableforestboolean, targetnstext ) xml
-query_to_xml_and_xmlschema ( querytext, nullsboolean,
- tableforestboolean, targetnstext ) xml
-
-
-
-
- In addition, the following functions are available to produce
- analogous mappings of entire schemas or the entire current
- database:
-
-schema_to_xml ( schemaname, nullsboolean,
- tableforestboolean, targetnstext ) xml
-schema_to_xmlschema ( schemaname, nullsboolean,
- tableforestboolean, targetnstext ) xml
-schema_to_xml_and_xmlschema ( schemaname, nullsboolean,
- tableforestboolean, targetnstext ) xml
-
-database_to_xml ( nullsboolean,
- tableforestboolean, targetnstext ) xml
-database_to_xmlschema ( nullsboolean,
- tableforestboolean, targetnstext ) xml
-database_to_xml_and_xmlschema ( nullsboolean,
- tableforestboolean, targetnstext ) xml
-
-
- 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 USAGE (lookup) privilege for.
-
-
-
- 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.
-
-
-
- The result of a schema content mapping looks like this:
-
-
-
-table1-mapping
-
-table2-mapping
-
-...
-
-]]>
-
- where the format of a table mapping depends on the
- tableforest parameter as explained above.
-
-
-
- The result of a database content mapping looks like this:
-
-
-
-
- ...
-
-
-
- ...
-
-
-...
-
-]]>
-
- where the schema mapping is as above.
-
-
-
- As an example of using the output produced by these functions,
- shows an XSLT stylesheet that
- converts the output of
- table_to_xml_and_xmlschema to an HTML
- document containing a tabular rendition of the table data. In a
- similar manner, the results from these functions can be
- converted into other XML-based formats.
-
-
-
- XSLT Stylesheet for Converting SQL/XML Output to HTML
-
-
-
-
-
-
-
-
-
-
-
-
- <xsl:value-of select="name(current())"/>
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-]]>
-
-
-
-
-
- JSON Functions and Operators
-
-
- JSON
- functions and operators
-
-
- SQL/JSON
- functions and expressions
-
-
-
- This section describes:
-
-
-
-
- functions and operators for processing and creating JSON data
-
-
-
-
- the SQL/JSON path language
-
-
-
-
- the SQL/JSON query functions
-
-
-
-
-
-
- To provide native support for JSON data types within the SQL environment,
- PostgreSQL implements the
- SQL/JSON data model.
- This model comprises sequences of items. Each item can hold SQL scalar
- values, with an additional SQL/JSON null value, and composite data structures
- that use JSON arrays and objects. The model is a formalization of the implied
- data model in the JSON specification
- RFC 7159.
-
-
-
- SQL/JSON allows you to handle JSON data alongside regular SQL data,
- with transaction support, including:
-
-
-
-
- Uploading JSON data into the database and storing it in
- regular SQL columns as character or binary strings.
-
-
-
-
- Generating JSON objects and arrays from relational data.
-
-
-
-
- Querying JSON data using SQL/JSON query functions and
- SQL/JSON path language expressions.
-
-
-
-
-
-
- To learn more about the SQL/JSON standard, see
- . For details on JSON types
- supported in PostgreSQL,
- see .
-
-
-
- Processing and Creating JSON Data
-
-
- shows the operators that
- are available for use with JSON data types (see ).
- In addition, the usual comparison operators shown in are available for
- jsonb, though not for json. The comparison
- operators follow the ordering rules for B-tree operations outlined in
- .
- See also for the aggregate
- function json_agg which aggregates record
- values as JSON, the aggregate function
- json_object_agg which aggregates pairs of values
- into a JSON object, and their jsonb equivalents,
- jsonb_agg and jsonb_object_agg.
-
-
-
- <type>json</type> and <type>jsonb</type> Operators
-
-
-
-
- Operator
-
-
- Description
-
-
- Example(s)
-
-
-
-
-
-
-
- json->integer
- json
-
-
- jsonb->integer
- jsonb
-
-
- Extracts n'th element of JSON array
- (array elements are indexed from zero, but negative integers count
- from the end).
-
-
- '[{"a":"foo"},{"b":"bar"},{"c":"baz"}]'::json -> 2
- {"c":"baz"}
-
-
- '[{"a":"foo"},{"b":"bar"},{"c":"baz"}]'::json -> -3
- {"a":"foo"}
-
-
-
-
-
- json->text
- json
-
-
- jsonb->text
- jsonb
-
-
- Extracts JSON object field with the given key.
-
-
- '{"a": {"b":"foo"}}'::json -> 'a'
- {"b":"foo"}
-
-
-
-
-
- json->>integer
- text
-
-
- jsonb->>integer
- text
-
-
- Extracts n'th element of JSON array,
- as text.
-
-
- '[1,2,3]'::json ->> 2
- 3
-
-
-
-
-
- json->>text
- text
-
-
- jsonb->>text
- text
-
-
- Extracts JSON object field with the given key, as text.
-
-
- '{"a":1,"b":2}'::json ->> 'b'
- 2
-
-
-
-
-
- json#>text[]
- json
-
-
- jsonb#>text[]
- jsonb
-
-
- Extracts JSON sub-object at the specified path, where path elements
- can be either field keys or array indexes.
-
-
- '{"a": {"b": ["foo","bar"]}}'::json #> '{a,b,1}'
- "bar"
-
-
-
-
-
- json#>>text[]
- text
-
-
- jsonb#>>text[]
- text
-
-
- Extracts JSON sub-object at the specified path as text.
-
-
- '{"a": {"b": ["foo","bar"]}}'::json #>> '{a,b,1}'
- bar
-
-
-
-
-
-
-
-
- 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.
-
-
-
-
- Some further operators exist only for jsonb, as shown
- in .
-
- describes how these operators can be used to effectively search indexed
- jsonb data.
-
-
-
- Additional <type>jsonb</type> Operators
-
-
-
-
- Operator
-
-
- Description
-
-
- Example(s)
-
-
-
-
-
-
-
- jsonb@>jsonb
- boolean
-
-
- Does the first JSON value contain the second?
- (See for details about containment.)
-
-
- '{"a":1, "b":2}'::jsonb @> '{"b":2}'::jsonb
- t
-
-
-
-
-
- jsonb<@jsonb
- boolean
-
-
- Is the first JSON value contained in the second?
-
-
- '{"b":2}'::jsonb <@ '{"a":1, "b":2}'::jsonb
- t
-
-
-
-
-
- jsonb?text
- boolean
-
-
- Does the text string exist as a top-level key or array element within
- the JSON value?
-
-
- '{"a":1, "b":2}'::jsonb ? 'b'
- t
-
-
- '["a", "b", "c"]'::jsonb ? 'b'
- t
-
-
-
-
-
- jsonb?|text[]
- boolean
-
-
- Do any of the strings in the text array exist as top-level keys or
- array elements?
-
-
- '{"a":1, "b":2, "c":3}'::jsonb ?| array['b', 'd']
- t
-
-
-
-
-
- jsonb?&text[]
- boolean
-
-
- Do all of the strings in the text array exist as top-level keys or
- array elements?
-
-
- '["a", "b", "c"]'::jsonb ?& array['a', 'b']
- t
-
-
-
-
-
- jsonb||jsonb
- jsonb
-
-
- Concatenates two jsonb 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.
-
-
- '["a", "b"]'::jsonb || '["a", "d"]'::jsonb
- ["a", "b", "a", "d"]
-
-
- '{"a": "b"}'::jsonb || '{"c": "d"}'::jsonb
- {"a": "b", "c": "d"}
-
-
- '[1, 2]'::jsonb || '3'::jsonb
- [1, 2, 3]
-
-
- '{"a": "b"}'::jsonb || '42'::jsonb
- [{"a": "b"}, 42]
-
-
- To append an array to another array as a single entry, wrap it
- in an additional layer of array, for example:
-
-
- '[1, 2]'::jsonb || jsonb_build_array('[3, 4]'::jsonb)
- [1, 2, [3, 4]]
-
-
-
-
-
- jsonb-text
- jsonb
-
-
- Deletes a key (and its value) from a JSON object, or matching string
- value(s) from a JSON array.
-
-
- '{"a": "b", "c": "d"}'::jsonb - 'a'
- {"c": "d"}
-
-
- '["a", "b", "c", "b"]'::jsonb - 'b'
- ["a", "c"]
-
-
-
-
-
- jsonb-text[]
- jsonb
-
-
- Deletes all matching keys or array elements from the left operand.
-
-
- '{"a": "b", "c": "d"}'::jsonb - '{a,c}'::text[]
- {}
-
-
-
-
-
- jsonb-integer
- jsonb
-
-
- Deletes the array element with specified index (negative
- integers count from the end). Throws an error if JSON value
- is not an array.
-
-
- '["a", "b"]'::jsonb - 1
- ["a"]
-
-
-
-
-
- jsonb#-text[]
- jsonb
-
-
- Deletes the field or array element at the specified path, where path
- elements can be either field keys or array indexes.
-
-
- '["a", {"b":1}]'::jsonb #- '{1,b}'
- ["a", {}]
-
-
-
-
-
- jsonb@?jsonpath
- boolean
-
-
- Does JSON path return any item for the specified JSON value?
- (This is useful only with SQL-standard JSON path expressions, not
- predicate check
- expressions, since those always return a value.)
-
-
- '{"a":[1,2,3,4,5]}'::jsonb @? '$.a[*] ? (@ > 2)'
- t
-
-
-
-
-
- jsonb@@jsonpath
- boolean
-
-
- Returns the result of a JSON path predicate check for the
- specified JSON value.
- (This is useful only
- with predicate
- check expressions, not SQL-standard JSON path expressions,
- since it will return NULL if the path result is
- not a single boolean value.)
-
-
- '{"a":[1,2,3,4,5]}'::jsonb @@ '$.a[*] > 2'
- t
-
-
-
-
-
-
-
-
- The jsonpath operators @?
- and @@ suppress the following errors: missing object
- field or array element, unexpected JSON item type, datetime and numeric
- errors. The jsonpath-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.
-
-
-
-
- shows the functions that are
- available for constructing json and jsonb values.
- Some functions in this table have a RETURNING clause,
- which specifies the data type returned. It must be one of json,
- jsonb, bytea, a character string type (text,
- char, or varchar), or a type
- for which there is a cast from json to that type.
- By default, the json type is returned.
-
-
-
- JSON Creation Functions
-
-
-
-
- Function
-
-
- Description
-
-
- Example(s)
-
-
-
-
-
-
-
-
- to_json
-
- to_json ( anyelement )
- json
-
-
-
- to_jsonb
-
- to_jsonb ( anyelement )
- jsonb
-
-
- Converts any SQL value to json or jsonb.
- 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 json, the cast function will be used to perform the
- conversion;
-
- For example, the extension has a cast
- from hstore to json, so that
- hstore values converted via the JSON creation functions
- will be represented as JSON objects, not as primitive string values.
-
-
- 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.
-
-
- to_json('Fred said "Hi."'::text)
- "Fred said \"Hi.\""
-
-
- to_jsonb(row(42, 'Fred said "Hi."'::text))
- {"f1": 42, "f2": "Fred said \"Hi.\""}
-
-
-
-
-
-
- array_to_json
-
- array_to_json ( anyarray, boolean )
- json
-
-
- Converts an SQL array to a JSON array. The behavior is the same
- as to_json except that line feeds will be added
- between top-level array elements if the optional boolean parameter is
- true.
-
-
- array_to_json('{{1,5},{99,100}}'::int[])
- [[1,5],[99,100]]
-
-
-
-
-
-
- json_array
- json_array (
- { value_expressionFORMAT JSON } , ...
- { NULL | ABSENT } ON NULL
- RETURNINGdata_typeFORMAT JSONENCODING UTF8)
-
-
- json_array (
- query_expression
- RETURNINGdata_typeFORMAT JSONENCODING UTF8)
-
-
- Constructs a JSON array from either a series of
- value_expression parameters or from the results
- of query_expression,
- which must be a SELECT query returning a single column. If
- ABSENT ON NULL is specified, NULL values are ignored.
- This is always the case if a
- query_expression is used.
-
-
- json_array(1,true,json '{"a":null}')
- [1, true, {"a":null}]
-
-
- json_array(SELECT * FROM (VALUES(1),(2)) t)
- [1, 2]
-
-
-
-
-
-
- row_to_json
-
- row_to_json ( record, boolean )
- json
-
-
- Converts an SQL composite value to a JSON object. The behavior is the
- same as to_json except that line feeds will be
- added between top-level elements if the optional boolean parameter is
- true.
-
-
- row_to_json(row(1,'foo'))
- {"f1":1,"f2":"foo"}
-
-
-
-
-
-
- json_build_array
-
- json_build_array ( VARIADIC"any" )
- json
-
-
-
- jsonb_build_array
-
- jsonb_build_array ( VARIADIC"any" )
- jsonb
-
-
- Builds a possibly-heterogeneously-typed JSON array out of a variadic
- argument list. Each argument is converted as
- per to_json or to_jsonb.
-
-
- json_build_array(1, 2, 'foo', 4, 5)
- [1, 2, "foo", 4, 5]
-
-
-
-
-
-
- json_build_object
-
- json_build_object ( VARIADIC"any" )
- json
-
-
-
- jsonb_build_object
-
- jsonb_build_object ( VARIADIC"any" )
- jsonb
-
-
- 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 to_json or to_jsonb.
-
-
- json_build_object('foo', 1, 2, row(3,'bar'))
- {"foo" : 1, "2" : {"f1":3,"f2":"bar"}}
-
-
-
-
-
- json_object
- json_object (
- { key_expression { VALUE | ':' }
- value_expressionFORMAT JSONENCODING UTF8 }, ...
- { NULL | ABSENT } ON NULL
- { WITH | WITHOUT } UNIQUEKEYS
- RETURNINGdata_typeFORMAT JSONENCODING UTF8)
-
-
- Constructs a JSON object of all the key/value pairs given,
- or an empty object if none are given.
- key_expression is a scalar expression
- defining the JSON key, which is
- converted to the text type.
- It cannot be NULL nor can it
- belong to a type that has a cast to the json type.
- If WITH UNIQUE KEYS is specified, there must not
- be any duplicate key_expression.
- Any pair for which the value_expression
- evaluates to NULL is omitted from the output
- if ABSENT ON NULL is specified;
- if NULL ON NULL is specified or the clause
- omitted, the key is included with value NULL.
-
-
- json_object('code' VALUE 'P123', 'title': 'Jaws')
- {"code" : "P123", "title" : "Jaws"}
-
-
-
-
-
-
- json_object
-
- json_object ( text[] )
- json
-
-
-
- jsonb_object
-
- jsonb_object ( text[] )
- jsonb
-
-
- 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.
-
-
- json_object('{a, 1, b, "def", c, 3.5}')
- {"a" : "1", "b" : "def", "c" : "3.5"}
-
- json_object('{{a, 1}, {b, "def"}, {c, 3.5}}')
- {"a" : "1", "b" : "def", "c" : "3.5"}
-
-
-
-
-
- json_object ( keystext[], valuestext[] )
- json
-
-
- jsonb_object ( keystext[], valuestext[] )
- jsonb
-
-
- This form of json_object takes keys and values
- pairwise from separate text arrays. Otherwise it is identical to
- the one-argument form.
-
-
- json_object('{a,b}', '{1,2}')
- {"a": "1", "b": "2"}
-
-
-
-
-
- json constructor
- json (
- expression
- FORMAT JSONENCODING UTF8
- { WITH | WITHOUT } UNIQUEKEYS )
- json
-
-
- Converts a given expression specified as text or
- bytea string (in UTF8 encoding) into a JSON
- value. If expression is NULL, an
- SQL null value is returned.
- If WITH UNIQUE is specified, the
- expression must not contain any duplicate
- object keys.
-
-
- json('{"a":123, "b":[true,"foo"], "a":"bar"}')
- {"a":123, "b":[true,"foo"], "a":"bar"}
-
-
-
-
-
-
- json_scalar
- json_scalar ( expression )
-
-
- Converts a given SQL scalar value into a JSON scalar value.
- If the input is NULL, an SQL null is returned. If
- the input is number or a boolean value, a corresponding JSON number
- or boolean value is returned. For any other value, a JSON string is
- returned.
-
-
- json_scalar(123.45)
- 123.45
-
-
- json_scalar(CURRENT_TIMESTAMP)
- "2022-05-10T10:51:04.62128-04:00"
-
-
-
-
-
- json_serialize (
- expressionFORMAT JSONENCODING UTF8
- RETURNINGdata_typeFORMAT JSONENCODING UTF8 )
-
-
- Converts an SQL/JSON expression into a character or binary string. The
- expression can be of any JSON type, any
- character string type, or bytea in UTF8 encoding.
- The returned type used in RETURNING can be any
- character string type or bytea. The default is
- text.
-
-
- json_serialize('{ "a" : 1 } ' RETURNING bytea)
- \x7b20226122203a2031207d20
-
-
-
-
-
- SQL/JSON Testing Functions
-
-
-
-
- Function signature
-
-
- Description
-
-
- Example(s)
-
-
-
-
-
-
- IS JSON
- expressionISNOTJSON
- { VALUE | SCALAR | ARRAY | OBJECT }
- { WITH | WITHOUT } UNIQUEKEYS
-
-
- This predicate tests whether expression can be
- parsed as JSON, possibly of a specified type.
- If SCALAR or ARRAY or
- OBJECT is specified, the
- test is whether or not the JSON is of that particular type. If
- WITH UNIQUE KEYS is specified, then any object in the
- expression is also tested to see if it
- has duplicate keys.
-
-
-
-SELECT js,
- js IS JSON "json?",
- js IS JSON SCALAR "scalar?",
- js IS JSON OBJECT "object?",
- js IS JSON ARRAY "array?"
-FROM (VALUES
- ('123'), ('"abc"'), ('{"a": "b"}'), ('[1,2]'),('abc')) foo(js);
- js | json? | scalar? | object? | array?
-------------+-------+---------+---------+--------
- 123 | t | t | f | f
- "abc" | t | t | f | f
- {"a": "b"} | t | f | t | f
- [1,2] | t | f | f | t
- abc | f | f | f | f
-
-
-
-
-SELECT js,
- js IS JSON OBJECT "object?",
- js IS JSON ARRAY "array?",
- js IS JSON ARRAY WITH UNIQUE KEYS "array w. UK?",
- js IS JSON ARRAY WITHOUT UNIQUE KEYS "array w/o UK?"
-FROM (VALUES ('[{"a":"1"},
- {"b":"2","b":"3"}]')) foo(js);
--[ RECORD 1 ]-+--------------------
-js | [{"a":"1"}, +
- | {"b":"2","b":"3"}]
-object? | f
-array? | t
-array w. UK? | f
-array w/o UK? | t
-
-
-
-
-
-
-
-
- shows the functions that
- are available for processing json and jsonb values.
-
-
-
- JSON Processing Functions
-
-
-
-
- Function
-
-
- Description
-
-
- Example(s)
-
-
-
-
-
-
-
-
- json_array_elements
-
- json_array_elements ( json )
- setof json
-
-
-
- jsonb_array_elements
-
- jsonb_array_elements ( jsonb )
- setof jsonb
-
-
- Expands the top-level JSON array into a set of JSON values.
-
-
- select * from json_array_elements('[1,true, [2,false]]')
-
-
- value
------------
- 1
- true
- [2,false]
-
-
-
-
-
-
-
- json_array_elements_text
-
- json_array_elements_text ( json )
- setof text
-
-
-
- jsonb_array_elements_text
-
- jsonb_array_elements_text ( jsonb )
- setof text
-
-
- Expands the top-level JSON array into a set of text values.
-
-
- select * from json_array_elements_text('["foo", "bar"]')
-
-
- value
------------
- foo
- bar
-
-
-
-
-
-
-
- json_array_length
-
- json_array_length ( json )
- integer
-
-
-
- jsonb_array_length
-
- jsonb_array_length ( jsonb )
- integer
-
-
- Returns the number of elements in the top-level JSON array.
-
-
- json_array_length('[1,2,3,{"f1":1,"f2":[5,6]},4]')
- 5
-
-
- jsonb_array_length('[]')
- 0
-
-
-
-
-
-
- json_each
-
- json_each ( json )
- setof record
- ( keytext,
- valuejson )
-
-
-
- jsonb_each
-
- jsonb_each ( jsonb )
- setof record
- ( keytext,
- valuejsonb )
-
-
- Expands the top-level JSON object into a set of key/value pairs.
-
-
- select * from json_each('{"a":"foo", "b":"bar"}')
-
-
- key | value
------+-------
- a | "foo"
- b | "bar"
-
-
-
-
-
-
-
- json_each_text
-
- json_each_text ( json )
- setof record
- ( keytext,
- valuetext )
-
-
-
- jsonb_each_text
-
- jsonb_each_text ( jsonb )
- setof record
- ( keytext,
- valuetext )
-
-
- Expands the top-level JSON object into a set of key/value pairs.
- The returned values will be of
- type text.
-
-
- select * from json_each_text('{"a":"foo", "b":"bar"}')
-
-
- key | value
------+-------
- a | foo
- b | bar
-
-
-
-
-
-
-
- json_extract_path
-
- json_extract_path ( from_jsonjson, VARIADICpath_elemstext[] )
- json
-
-
-
- jsonb_extract_path
-
- jsonb_extract_path ( from_jsonjsonb, VARIADICpath_elemstext[] )
- jsonb
-
-
- Extracts JSON sub-object at the specified path.
- (This is functionally equivalent to the #>
- operator, but writing the path out as a variadic list can be more
- convenient in some cases.)
-
-
- json_extract_path('{"f2":{"f3":1},"f4":{"f5":99,"f6":"foo"}}', 'f4', 'f6')
- "foo"
-
-
-
-
-
-
- json_extract_path_text
-
- json_extract_path_text ( from_jsonjson, VARIADICpath_elemstext[] )
- text
-
-
-
- jsonb_extract_path_text
-
- jsonb_extract_path_text ( from_jsonjsonb, VARIADICpath_elemstext[] )
- text
-
-
- Extracts JSON sub-object at the specified path as text.
- (This is functionally equivalent to the #>>
- operator.)
-
-
- json_extract_path_text('{"f2":{"f3":1},"f4":{"f5":99,"f6":"foo"}}', 'f4', 'f6')
- foo
-
-
-
-
-
-
- json_object_keys
-
- json_object_keys ( json )
- setof text
-
-
-
- jsonb_object_keys
-
- jsonb_object_keys ( jsonb )
- setof text
-
-
- Returns the set of keys in the top-level JSON object.
-
-
- select * from json_object_keys('{"f1":"abc","f2":{"f3":"a", "f4":"b"}}')
-
-
- json_object_keys
-------------------
- f1
- f2
-
-
-
-
-
-
-
- json_populate_record
-
- json_populate_record ( baseanyelement, from_jsonjson )
- anyelement
-
-
-
- jsonb_populate_record
-
- jsonb_populate_record ( baseanyelement, from_jsonjsonb )
- anyelement
-
-
- Expands the top-level JSON object to a row having the composite type
- of the base 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 base is just
- NULL, which means that any output columns that do
- not match any object field will be filled with nulls. However,
- if base isn't NULL then
- the values it contains will be used for unmatched columns.
-
-
- To convert a JSON value to the SQL type of an output column, the
- following rules are applied in sequence:
-
-
-
- A JSON null value is converted to an SQL null in all cases.
-
-
-
-
- If the output column is of type json
- or jsonb, the JSON value is just reproduced exactly.
-
-
-
-
- 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.
-
-
-
-
- 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.
-
-
-
-
- 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.
-
-
-
-
- Otherwise, the ordinary text representation of the JSON value is
- fed to the input conversion function for the column's data type.
-
-
-
-
-
- While the example below uses a constant JSON value, typical use would
- be to reference a json or jsonb column
- laterally from another table in the query's FROM
- clause. Writing json_populate_record in
- the FROM clause is good practice, since all of the
- extracted columns are available for use without duplicate function
- calls.
-
-
- create type subrowtype as (d int, e text);
- create type myrowtype as (a int, b text[], c subrowtype);
-
-
- select * from json_populate_record(null::myrowtype,
- '{"a": 1, "b": ["2", "a b"], "c": {"d": 4, "e": "a b c"}, "x": "foo"}')
-
-
- a | b | c
----+-----------+-------------
- 1 | {2,"a b"} | (4,"a b c")
-
-
-
-
-
-
-
- jsonb_populate_record_valid
-
- jsonb_populate_record_valid ( baseanyelement, from_jsonjson )
- boolean
-
-
- Function for testing jsonb_populate_record. Returns
- true if the input jsonb_populate_record
- would finish without an error for the given input JSON object; that is, it's
- valid input, false otherwise.
-
-
- create type jsb_char2 as (a char(2));
-
-
- select jsonb_populate_record_valid(NULL::jsb_char2, '{"a": "aaa"}');
-
-
- jsonb_populate_record_valid
------------------------------
- f
-(1 row)
-
-
- select * from jsonb_populate_record(NULL::jsb_char2, '{"a": "aaa"}') q;
-
-
-ERROR: value too long for type character(2)
-
- select jsonb_populate_record_valid(NULL::jsb_char2, '{"a": "aa"}');
-
-
- jsonb_populate_record_valid
------------------------------
- t
-(1 row)
-
-
- select * from jsonb_populate_record(NULL::jsb_char2, '{"a": "aa"}') q;
-
-
- a
-----
- aa
-(1 row)
-
-
-
-
-
-
-
- json_populate_recordset
-
- json_populate_recordset ( baseanyelement, from_jsonjson )
- setof anyelement
-
-
-
- jsonb_populate_recordset
-
- jsonb_populate_recordset ( baseanyelement, from_jsonjsonb )
- setof anyelement
-
-
- Expands the top-level JSON array of objects to a set of rows having
- the composite type of the base argument.
- Each element of the JSON array is processed as described above
- for json[b]_populate_record.
-
-
- create type twoints as (a int, b int);
-
-
- select * from json_populate_recordset(null::twoints, '[{"a":1,"b":2}, {"a":3,"b":4}]')
-
-
- a | b
----+---
- 1 | 2
- 3 | 4
-
-
-
-
-
-
-
- json_to_record
-
- json_to_record ( json )
- record
-
-
-
- jsonb_to_record
-
- jsonb_to_record ( jsonb )
- record
-
-
- Expands the top-level JSON object to a row having the composite type
- defined by an AS clause. (As with all functions
- returning record, the calling query must explicitly
- define the structure of the record with an AS
- clause.) The output record is filled from fields of the JSON object,
- in the same way as described above
- for json[b]_populate_record. Since there is no
- input record value, unmatched columns are always filled with nulls.
-
-
- create type myrowtype as (a int, b text);
-
-
- 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)
-
-
- a | b | c | d | r
----+---------+---------+---+---------------
- 1 | [1,2,3] | {1,2,3} | | (123,"a b c")
-
-
-
-
-
-
-
- json_to_recordset
-
- json_to_recordset ( json )
- setof record
-
-
-
- jsonb_to_recordset
-
- jsonb_to_recordset ( jsonb )
- setof record
-
-
- Expands the top-level JSON array of objects to a set of rows having
- the composite type defined by an AS clause. (As
- with all functions returning record, the calling query
- must explicitly define the structure of the record with
- an AS clause.) Each element of the JSON array is
- processed as described above
- for json[b]_populate_record.
-
-
- select * from json_to_recordset('[{"a":1,"b":"foo"}, {"a":"2","c":"bar"}]') as x(a int, b text)
-
-
- a | b
----+-----
- 1 | foo
- 2 |
-
-
-
-
-
-
-
- jsonb_set
-
- jsonb_set ( targetjsonb, pathtext[], new_valuejsonb, create_if_missingboolean )
- jsonb
-
-
- Returns target
- with the item designated by path
- replaced by new_value, or with
- new_value added if
- create_if_missing is true (which is the
- default) and the item designated by path
- does not exist.
- All earlier steps in the path must exist, or
- the target is returned unchanged.
- As with the path oriented operators, negative integers that
- appear in the path count from the end
- of JSON arrays.
- If the last path step is an array index that is out of range,
- and create_if_missing 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.
-
-
- jsonb_set('[{"f1":1,"f2":null},2,null,3]', '{0,f1}', '[2,3,4]', false)
- [{"f1": [2, 3, 4], "f2": null}, 2, null, 3]
-
-
- jsonb_set('[{"f1":1,"f2":null},2]', '{0,f3}', '[2,3,4]')
- [{"f1": 1, "f2": null, "f3": [2, 3, 4]}, 2]
-
-
-
-
-
-
- jsonb_set_lax
-
- jsonb_set_lax ( targetjsonb, pathtext[], new_valuejsonb, create_if_missingboolean, null_value_treatmenttext )
- jsonb
-
-
- If new_value is not NULL,
- behaves identically to jsonb_set. Otherwise behaves
- according to the value
- of null_value_treatment which must be one
- of 'raise_exception',
- 'use_json_null', 'delete_key', or
- 'return_target'. The default is
- 'use_json_null'.
-
-
- jsonb_set_lax('[{"f1":1,"f2":null},2,null,3]', '{0,f1}', null)
- [{"f1": null, "f2": null}, 2, null, 3]
-
-
- jsonb_set_lax('[{"f1":99,"f2":null},2]', '{0,f3}', null, true, 'return_target')
- [{"f1": 99, "f2": null}, 2]
-
-
-
-
-
-
- jsonb_insert
-
- jsonb_insert ( targetjsonb, pathtext[], new_valuejsonb, insert_afterboolean )
- jsonb
-
-
- Returns target
- with new_value inserted. If the item
- designated by the path is an array
- element, new_value will be inserted before
- that item if insert_after is false (which
- is the default), or after it
- if insert_after is true. If the item
- designated by the path is an object
- field, new_value will be inserted only if
- the object does not already contain that key.
- All earlier steps in the path must exist, or
- the target is returned unchanged.
- As with the path oriented operators, negative integers that
- appear in the path 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.
-
-
- jsonb_insert('{"a": [0,1,2]}', '{a, 1}', '"new_value"')
- {"a": [0, "new_value", 1, 2]}
-
-
- jsonb_insert('{"a": [0,1,2]}', '{a, 1}', '"new_value"', true)
- {"a": [0, 1, "new_value", 2]}
-
-
-
-
-
-
- json_strip_nulls
-
- json_strip_nulls ( json )
- json
-
-
-
- jsonb_strip_nulls
-
- jsonb_strip_nulls ( jsonb )
- jsonb
-
-
- Deletes all object fields that have null values from the given JSON
- value, recursively. Null values that are not object fields are
- untouched.
-
-
- json_strip_nulls('[{"f1":1, "f2":null}, 2, null, 3]')
- [{"f1":1},2,null,3]
-
-
-
-
-
-
- jsonb_path_exists
-
- jsonb_path_exists ( targetjsonb, pathjsonpath, varsjsonb, silentboolean )
- boolean
-
-
- Checks whether the JSON path returns any item for the specified JSON
- value.
- (This is useful only with SQL-standard JSON path expressions, not
- predicate check
- expressions, since those always return a value.)
- If the vars argument is specified, it must
- be a JSON object, and its fields provide named values to be
- substituted into the jsonpath expression.
- If the silent argument is specified and
- is true, the function suppresses the same errors
- as the @? and @@ operators do.
-
-
- jsonb_path_exists('{"a":[1,2,3,4,5]}', '$.a[*] ? (@ >= $min && @ <= $max)', '{"min":2, "max":4}')
- t
-
-
-
-
-
-
- jsonb_path_match
-
- jsonb_path_match ( targetjsonb, pathjsonpath, varsjsonb, silentboolean )
- boolean
-
-
- Returns the result of a JSON path predicate check for the specified
- JSON value.
- (This is useful only
- with predicate
- check expressions, not SQL-standard JSON path expressions,
- since it will either fail or return NULL if the
- path result is not a single boolean value.)
- The optional vars
- and silent arguments act the same as
- for jsonb_path_exists.
-
-
- jsonb_path_match('{"a":[1,2,3,4,5]}', 'exists($.a[*] ? (@ >= $min && @ <= $max))', '{"min":2, "max":4}')
- t
-
-
-
-
-
-
- jsonb_path_query
-
- jsonb_path_query ( targetjsonb, pathjsonpath, varsjsonb, silentboolean )
- setof jsonb
-
-
- Returns all JSON items returned by the JSON path for the specified
- JSON value.
- For SQL-standard JSON path expressions it returns the JSON
- values selected from target.
- For predicate
- check expressions it returns the result of the predicate
- check: true, false,
- or null.
- The optional vars
- and silent arguments act the same as
- for jsonb_path_exists.
-
-
- select * from jsonb_path_query('{"a":[1,2,3,4,5]}', '$.a[*] ? (@ >= $min && @ <= $max)', '{"min":2, "max":4}')
-
-
- jsonb_path_query
-------------------
- 2
- 3
- 4
-
-
-
-
-
-
-
- jsonb_path_query_array
-
- jsonb_path_query_array ( targetjsonb, pathjsonpath, varsjsonb, silentboolean )
- jsonb
-
-
- Returns all JSON items returned by the JSON path for the specified
- JSON value, as a JSON array.
- The parameters are the same as
- for jsonb_path_query.
-
-
- jsonb_path_query_array('{"a":[1,2,3,4,5]}', '$.a[*] ? (@ >= $min && @ <= $max)', '{"min":2, "max":4}')
- [2, 3, 4]
-
-
-
-
-
-
- jsonb_path_query_first
-
- jsonb_path_query_first ( targetjsonb, pathjsonpath, varsjsonb, silentboolean )
- jsonb
-
-
- Returns the first JSON item returned by the JSON path for the
- specified JSON value, or NULL if there are no
- results.
- The parameters are the same as
- for jsonb_path_query.
-
-
- jsonb_path_query_first('{"a":[1,2,3,4,5]}', '$.a[*] ? (@ >= $min && @ <= $max)', '{"min":2, "max":4}')
- 2
-
-
-
-
-
-
- jsonb_path_exists_tz
-
- jsonb_path_exists_tz ( targetjsonb, pathjsonpath, varsjsonb, silentboolean )
- boolean
-
-
-
- jsonb_path_match_tz
-
- jsonb_path_match_tz ( targetjsonb, pathjsonpath, varsjsonb, silentboolean )
- boolean
-
-
-
- jsonb_path_query_tz
-
- jsonb_path_query_tz ( targetjsonb, pathjsonpath, varsjsonb, silentboolean )
- setof jsonb
-
-
-
- jsonb_path_query_array_tz
-
- jsonb_path_query_array_tz ( targetjsonb, pathjsonpath, varsjsonb, silentboolean )
- jsonb
-
-
-
- jsonb_path_query_first_tz
-
- jsonb_path_query_first_tz ( targetjsonb, pathjsonpath, varsjsonb, silentboolean )
- jsonb
-
-
- These functions act like their counterparts described above without
- the _tz 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 2015-08-02 as a timestamp with time
- zone, so the result depends on the current
- 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.
-
-
- jsonb_path_exists_tz('["2015-08-01 12:00:00-05"]', '$[*] ? (@.datetime() < "2015-08-02".datetime())')
- t
-
-
-
-
-
-
- jsonb_pretty
-
- jsonb_pretty ( jsonb )
- text
-
-
- Converts the given JSON value to pretty-printed, indented text.
-
-
- jsonb_pretty('[{"f1":1,"f2":null}, 2]')
-
-
-[
- {
- "f1": 1,
- "f2": null
- },
- 2
-]
-
-
-
-
-
-
-
- json_typeof
-
- json_typeof ( json )
- text
-
-
-
- jsonb_typeof
-
- jsonb_typeof ( jsonb )
- text
-
-
- Returns the type of the top-level JSON value as a text string.
- Possible types are
- object, array,
- string, number,
- boolean, and null.
- (The null result should not be confused
- with an SQL NULL; see the examples.)
-
-
- json_typeof('-123.4')
- number
-
-
- json_typeof('null'::json)
- null
-
-
- json_typeof(NULL::json) IS NULL
- t
-
-
-
-
-
-
-
-
- The SQL/JSON Path Language
-
-
- SQL/JSON path language
-
-
-
- SQL/JSON path expressions specify item(s) to be retrieved
- from a JSON value, similarly to XPath expressions used
- for access to XML content. In PostgreSQL,
- path expressions are implemented as the jsonpath
- data type and can use any elements described in
- .
-
-
-
- JSON query functions and operators
- pass the provided path expression to the path engine
- for evaluation. If the expression matches the queried JSON data,
- the corresponding JSON item, or set of items, is returned.
- If there is no match, the result will be NULL,
- false, or an error, depending on the function.
- Path expressions are written in the SQL/JSON path language
- and can include arithmetic expressions and functions.
-
-
-
- A path expression consists of a sequence of elements allowed
- by the jsonpath 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.
-
-
-
- To refer to the JSON value being queried (the
- context item), use the $ variable
- in the path expression. The first element of a path must always
- be $. It can be followed by one or more
- accessor operators,
- which go down the JSON structure level by level to retrieve sub-items
- of the context item. Each accessor operator acts on the
- result(s) of the previous evaluation step, producing zero, one, or more
- output items from each input item.
-
-
-
- For example, suppose you have some JSON data from a GPS tracker that you
- would like to parse, such as:
-
-SELECT '{
- "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
- }
- ]
- }
-}' AS json \gset
-
- (The above example can be copied-and-pasted
- into psql to set things up for the following
- examples. Then psql will
- expand :'json' into a suitably-quoted string
- constant containing the JSON value.)
-
-
-
- To retrieve the available track segments, you need to use the
- .key accessor
- operator to descend through surrounding JSON objects, for example:
-
-=>select jsonb_path_query(:'json', '$.track.segments');
- jsonb_path_query
------------------------------------------------------------&zwsp;-----------------------------------------------------------&zwsp;---------------------------------------------
- [{"HR": 73, "location": [47.763, 13.4034], "start time": "2018-10-14 10:05:14"}, {"HR": 135, "location": [47.706, 13.2635], "start time": "2018-10-14 10:39:21"}]
-
-
-
-
- To retrieve the contents of an array, you typically use the
- [*] operator.
- The following example will return the location coordinates for all
- the available track segments:
-
-=>select jsonb_path_query(:'json', '$.track.segments[*].location');
- jsonb_path_query
--------------------
- [47.763, 13.4034]
- [47.706, 13.2635]
-
- Here we started with the whole JSON input value ($),
- then the .track accessor selected the JSON object
- associated with the "track" object key, then
- the .segments accessor selected the JSON array
- associated with the "segments" key within that
- object, then the [*] accessor selected each element
- of that array (producing a series of items), then
- the .location accessor selected the JSON array
- associated with the "location" key within each of
- those objects. In this example, each of those objects had
- a "location" key; but if any of them did not,
- the .location accessor would have simply produced no
- output for that input item.
-
-
-
- To return the coordinates of the first segment only, you can
- specify the corresponding subscript in the []
- accessor operator. Recall that JSON array indexes are 0-relative:
-
-=>select jsonb_path_query(:'json', '$.track.segments[0].location');
- jsonb_path_query
--------------------
- [47.763, 13.4034]
-
-
-
-
- The result of each path evaluation step can be processed
- by one or more of the jsonpath operators and methods
- listed in .
- Each method name must be preceded by a dot. For example,
- you can get the size of an array:
-
-=>select jsonb_path_query(:'json', '$.track.segments.size()');
- jsonb_path_query
-------------------
- 2
-
- More examples of using jsonpath operators
- and methods within path expressions appear below in
- .
-
-
-
- A path can also contain
- filter expressions that work similarly to the
- WHERE clause in SQL. A filter expression begins with
- a question mark and provides a condition in parentheses:
-
-
-? (condition)
-
-
-
-
- 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
- produce true, false,
- or unknown. The unknown value
- plays the same role as SQL NULL and can be tested
- for with the is unknown predicate. Further path
- evaluation steps use only those items for which the filter expression
- returned true.
-
-
-
- The functions and operators that can be used in filter expressions are
- listed in . Within a
- filter expression, the @ variable denotes the value
- being considered (i.e., one result of the preceding path step). You can
- write accessor operators after @ to retrieve component
- items.
-
-
-
- For example, suppose you would like to retrieve all heart rate values higher
- than 130. You can achieve this as follows:
-
-=>select jsonb_path_query(:'json', '$.track.segments[*].HR ? (@ > 130)');
- jsonb_path_query
-------------------
- 135
-
-
-
-
- To get the start times of segments with such values, you have to
- filter out irrelevant segments before selecting the start times, so the
- filter expression is applied to the previous step, and the path used
- in the condition is different:
-
-=>select jsonb_path_query(:'json', '$.track.segments[*] ? (@.HR > 130)."start time"');
- jsonb_path_query
------------------------
- "2018-10-14 10:39:21"
-
-
-
-
- You can use several filter expressions in sequence, if required.
- The following example selects start times of all segments that
- contain locations with relevant coordinates and high heart rate values:
-
-=>select jsonb_path_query(:'json', '$.track.segments[*] ? (@.location[1] < 13.4) ? (@.HR > 130)."start time"');
- jsonb_path_query
------------------------
- "2018-10-14 10:39:21"
-
-
-
-
- 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:
-
-=>select jsonb_path_query(:'json', '$.track.segments[*] ? (@.location[1] < 13.4).HR ? (@ > 130)');
- jsonb_path_query
-------------------
- 135
-
-
-
-
- You can also nest filter expressions within each other.
- This example returns the size of the track if it contains any
- segments with high heart rate values, or an empty sequence otherwise:
-
-=>select jsonb_path_query(:'json', '$.track ? (exists(@.segments[*] ? (@.HR > 130))).segments.size()');
- jsonb_path_query
-------------------
- 2
-
-
-
-
- Deviations from the SQL Standard
-
- PostgreSQL's implementation of the SQL/JSON path
- language has the following deviations from the SQL/JSON standard.
-
-
-
- Boolean Predicate Check Expressions
-
- As an extension to the SQL standard,
- a PostgreSQL path expression can be a
- Boolean predicate, whereas the SQL standard allows predicates only within
- filters. While SQL-standard path expressions return the relevant
- element(s) of the queried JSON value, predicate check expressions
- return the single three-valued result of the
- predicate: true,
- false, or unknown.
- For example, we could write this SQL-standard filter expression:
-
-=>select jsonb_path_query(:'json', '$.track.segments ?(@[*].HR > 130)');
- jsonb_path_query
------------------------------------------------------------&zwsp;----------------------
- {"HR": 135, "location": [47.706, 13.2635], "start time": "2018-10-14 10:39:21"}
-
- The similar predicate check expression simply
- returns true, indicating that a match exists:
-
-=>select jsonb_path_query(:'json', '$.track.segments[*].HR > 130');
- jsonb_path_query
-------------------
- true
-
-
-
-
-
- Predicate check expressions are required in the
- @@ operator (and the
- jsonb_path_match function), and should not be used
- with the @? operator (or the
- jsonb_path_exists function).
-
-
-
-
-
- Regular Expression Interpretation
-
- There are minor differences in the interpretation of regular
- expression patterns used in like_regex filters, as
- described in .
-
-
-
-
-
- Strict and Lax Modes
-
- 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 is defined as a
- structural error. SQL/JSON path expressions have two modes
- of handling structural errors:
-
-
-
-
-
- lax (default) — the path engine implicitly adapts
- the queried data to the specified path.
- Any structural errors that cannot be fixed as described below
- are suppressed, producing no match.
-
-
-
-
- strict — if a structural error occurs, an error is raised.
-
-
-
-
-
- Lax mode facilitates matching of a JSON document and path
- expression when 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
- the operation. Also, comparison operators automatically unwrap their
- operands in 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 when:
-
-
-
- The path expression contains type() or
- size() methods that return the type
- and the number of elements in the array, respectively.
-
-
-
-
- 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.
-
-
-
-
-
-
- For example, when querying the GPS data listed above, you can
- abstract from the fact that it stores an array of segments
- when using lax mode:
-
-=>select jsonb_path_query(:'json', 'lax $.track.segments.location');
- jsonb_path_query
--------------------
- [47.763, 13.4034]
- [47.706, 13.2635]
-
-
-
-
- In strict mode, the specified path must exactly match the structure of
- the queried JSON document, so using this path
- expression will cause an error:
-
-=>select jsonb_path_query(:'json', 'strict $.track.segments.location');
-ERROR: jsonpath member accessor can only be applied to an object
-
- To get the same result as in lax mode, you have to explicitly unwrap the
- segments array:
-
-=>select jsonb_path_query(:'json', 'strict $.track.segments[*].location');
- jsonb_path_query
--------------------
- [47.763, 13.4034]
- [47.706, 13.2635]
-
-
-
-
- The unwrapping behavior of lax mode can lead to surprising results. For
- instance, the following query using the .** accessor
- selects every HR value twice:
-
-=>select jsonb_path_query(:'json', 'lax $.**.HR');
- jsonb_path_query
-------------------
- 73
- 135
- 73
- 135
-
- This happens because the .** accessor selects both
- the segments array and each of its elements, while
- the .HR accessor automatically unwraps arrays when
- using lax mode. To avoid surprising results, we recommend using
- the .** accessor only in strict mode. The
- following query selects each HR value just once:
-
-=>select jsonb_path_query(:'json', 'strict $.**.HR');
- jsonb_path_query
-------------------
- 73
- 135
-
-
-
-
- The unwrapping of arrays can also lead to unexpected results. Consider this
- example, which selects all the location arrays:
-
-=>select jsonb_path_query(:'json', 'lax $.track.segments[*].location');
- jsonb_path_query
--------------------
- [47.763, 13.4034]
- [47.706, 13.2635]
-(2 rows)
-
- As expected it returns the full arrays. But applying a filter expression
- causes the arrays to be unwrapped to evaluate each item, returning only the
- items that match the expression:
-
-=>select jsonb_path_query(:'json', 'lax $.track.segments[*].location ?(@[*] > 15)');
- jsonb_path_query
-------------------
- 47.763
- 47.706
-(2 rows)
-
- This despite the fact that the full arrays are selected by the path
- expression. Use strict mode to restore selecting the arrays:
-
-=>select jsonb_path_query(:'json', 'strict $.track.segments[*].location ?(@[*] > 15)');
- jsonb_path_query
--------------------
- [47.763, 13.4034]
- [47.706, 13.2635]
-(2 rows)
-
-
-
-
-
- SQL/JSON Path Operators and Methods
-
-
- shows the operators and
- methods available in jsonpath. 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.
-
-
-
- <type>jsonpath</type> Operators and Methods
-
-
-
-
- Operator/Method
-
-
- Description
-
-
- Example(s)
-
-
-
-
-
-
-
- number+number
- number
-
-
- Addition
-
-
- jsonb_path_query('[2]', '$[0] + 3')
- 5
-
-
-
-
-
- +number
- number
-
-
- Unary plus (no operation); unlike addition, this can iterate over
- multiple values
-
-
- jsonb_path_query_array('{"x": [2,3,4]}', '+ $.x')
- [2, 3, 4]
-
-
-
-
-
- number-number
- number
-
-
- Subtraction
-
-
- jsonb_path_query('[2]', '7 - $[0]')
- 5
-
-
-
-
-
- -number
- number
-
-
- Negation; unlike subtraction, this can iterate over
- multiple values
-
-
- jsonb_path_query_array('{"x": [2,3,4]}', '- $.x')
- [-2, -3, -4]
-
-
-
-
-
- number*number
- number
-
-
- Multiplication
-
-
- jsonb_path_query('[4]', '2 * $[0]')
- 8
-
-
-
-
-
- number/number
- number
-
-
- Division
-
-
- jsonb_path_query('[8.5]', '$[0] / 2')
- 4.2500000000000000
-
-
-
-
-
- number%number
- number
-
-
- Modulo (remainder)
-
-
- jsonb_path_query('[32]', '$[0] % 10')
- 2
-
-
-
-
-
- value.type()
- string
-
-
- Type of the JSON item (see json_typeof)
-
-
- jsonb_path_query_array('[1, "2", {}]', '$[*].type()')
- ["number", "string", "object"]
-
-
-
-
-
- value.size()
- number
-
-
- Size of the JSON item (number of array elements, or 1 if not an
- array)
-
-
- jsonb_path_query('{"m": [11, 15]}', '$.m.size()')
- 2
-
-
-
-
-
- value.boolean()
- boolean
-
-
- Boolean value converted from a JSON boolean, number, or string
-
-
- jsonb_path_query_array('[1, "yes", false]', '$[*].boolean()')
- [true, true, false]
-
-
-
-
-
- value.string()
- string
-
-
- String value converted from a JSON boolean, number, string, or datetime
-
-
- jsonb_path_query_array('[1.23, "xyz", false]', '$[*].string()')
- ["1.23", "xyz", "false"]
-
-
- jsonb_path_query('"2023-08-15"', '$.datetime().string()')
- "2023-08-15"
-
-
-
-
-
- value.double()
- number
-
-
- Approximate floating-point number converted from a JSON number or
- string
-
-
- jsonb_path_query('{"len": "1.9"}', '$.len.double() * 2')
- 3.8
-
-
-
-
-
- number.ceiling()
- number
-
-
- Nearest integer greater than or equal to the given number
-
-
- jsonb_path_query('{"h": 1.3}', '$.h.ceiling()')
- 2
-
-
-
-
-
- number.floor()
- number
-
-
- Nearest integer less than or equal to the given number
-
-
- jsonb_path_query('{"h": 1.7}', '$.h.floor()')
- 1
-
-
-
-
-
- number.abs()
- number
-
-
- Absolute value of the given number
-
-
- jsonb_path_query('{"z": -0.3}', '$.z.abs()')
- 0.3
-
-
-
-
-
- value.bigint()
- bigint
-
-
- Big integer value converted from a JSON number or string
-
-
- jsonb_path_query('{"len": "9876543219"}', '$.len.bigint()')
- 9876543219
-
-
-
-
-
- value.decimal( [ precision [ , scale ] ] )
- decimal
-
-
- Rounded decimal value converted from a JSON number or string. precision and scale must be integer values.
-
-
- jsonb_path_query('1234.5678', '$.decimal(6, 2)')
- 1234.57
-
-
-
-
-
- value.integer()
- integer
-
-
- Integer value converted from a JSON number or string
-
-
- jsonb_path_query('{"len": "12345"}', '$.len.integer()')
- 12345
-
-
-
-
-
- value.number()
- numeric
-
-
- Numeric value converted from a JSON number or string
-
-
- jsonb_path_query('{"len": "123.45"}', '$.len.number()')
- 123.45
-
-
-
-
-
- string.datetime()
- datetime_type
- (see note)
-
-
- Date/time value converted from a string
-
-
- jsonb_path_query('["2015-8-1", "2015-08-12"]', '$[*] ? (@.datetime() < "2015-08-2".datetime())')
- "2015-8-1"
-
-
-
-
-
- string.datetime(template)
- datetime_type
- (see note)
-
-
- Date/time value converted from a string using the
- specified to_timestamp template
-
-
- jsonb_path_query_array('["12:30", "18:40"]', '$[*].datetime("HH24:MI")')
- ["12:30:00", "18:40:00"]
-
-
-
-
-
- string.date()
- date
-
-
- Date value converted from a string
-
-
- jsonb_path_query('"2023-08-15"', '$.date()')
- "2023-08-15"
-
-
-
-
-
- string.time()
- time without time zone
-
-
- Time without time zone value converted from a string
-
-
- jsonb_path_query('"12:34:56"', '$.time()')
- "12:34:56"
-
-
-
-
-
- string.time(precision)
- time without time zone
-
-
- Time without time zone value converted from a string, with fractional
- seconds adjusted to the given precision.
-
-
- jsonb_path_query('"12:34:56.789"', '$.time(2)')
- "12:34:56.79"
-
-
-
-
-
- string.time_tz()
- time with time zone
-
-
- Time with time zone value converted from a string
-
-
- jsonb_path_query('"12:34:56 +05:30"', '$.time_tz()')
- "12:34:56+05:30"
-
-
-
-
-
- string.time_tz(precision)
- time with time zone
-
-
- Time with time zone value converted from a string, with fractional
- seconds adjusted to the given precision.
-
-
- jsonb_path_query('"12:34:56.789 +05:30"', '$.time_tz(2)')
- "12:34:56.79+05:30"
-
-
-
-
-
- string.timestamp()
- timestamp without time zone
-
-
- Timestamp without time zone value converted from a string
-
-
- jsonb_path_query('"2023-08-15 12:34:56"', '$.timestamp()')
- "2023-08-15T12:34:56"
-
-
-
-
-
- string.timestamp(precision)
- timestamp without time zone
-
-
- Timestamp without time zone value converted from a string, with
- fractional seconds adjusted to the given precision.
-
-
- jsonb_path_query('"2023-08-15 12:34:56.789"', '$.timestamp(2)')
- "2023-08-15T12:34:56.79"
-
-
-
-
-
- string.timestamp_tz()
- timestamp with time zone
-
-
- Timestamp with time zone value converted from a string
-
-
- jsonb_path_query('"2023-08-15 12:34:56 +05:30"', '$.timestamp_tz()')
- "2023-08-15T12:34:56+05:30"
-
-
-
-
-
- string.timestamp_tz(precision)
- timestamp with time zone
-
-
- Timestamp with time zone value converted from a string, with fractional
- seconds adjusted to the given precision.
-
-
- jsonb_path_query('"2023-08-15 12:34:56.789 +05:30"', '$.timestamp_tz(2)')
- "2023-08-15T12:34:56.79+05:30"
-
-
-
-
-
- object.keyvalue()
- array
-
-
- The object's key-value pairs, represented as an array of objects
- containing three fields: "key",
- "value", and "id";
- "id" is a unique identifier of the object the
- key-value pair belongs to
-
-
- jsonb_path_query_array('{"x": "20", "y": 32}', '$.keyvalue()')
- [{"id": 0, "key": "x", "value": "20"}, {"id": 0, "key": "y", "value": 32}]
-
-
-
-
-
-
-
-
- The result type of the datetime() and
- datetime(template)
- methods can be date, timetz, time,
- timestamptz, or timestamp.
- Both methods determine their result type dynamically.
-
-
- The datetime() method sequentially tries to
- match its input string to the ISO formats
- for date, timetz, time,
- timestamptz, and timestamp. It stops on
- the first matching format and emits the corresponding data type.
-
-
- The datetime(template)
- method determines the result type according to the fields used in the
- provided template string.
-
-
- The datetime() and
- datetime(template) methods
- use the same parsing rules as the to_timestamp SQL
- function does (see ), 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.
-
-
- If different date/time types need to be compared, an implicit cast is
- applied. A date value can be cast to timestamp
- or timestamptz, timestamp can be cast to
- timestamptz, and time to timetz.
- However, all but the first of these conversions depend on the current
- setting, and thus can only be performed
- within timezone-aware jsonpath functions. Similarly, other
- date/time-related methods that convert strings to date/time types
- also do this casting, which may involve the current
- setting. Therefore, these conversions can
- also only be performed within timezone-aware jsonpath
- functions.
-
-
-
-
- shows the available
- filter expression elements.
-
-
-
-
-
-
-
- SQL/JSON Regular Expressions
-
-
- LIKE_REGEX
- in SQL/JSON
-
-
-
- SQL/JSON path expressions allow matching text to a regular expression
- with the like_regex filter. For example, the
- following SQL/JSON path query would case-insensitively match all
- strings in an array that start with an English vowel:
-
-$[*] ? (@ like_regex "^[aeiou]" flag "i")
-
-
-
-
- The optional flag string may include one or more of
- the characters
- i for case-insensitive match,
- m to allow ^
- and $ to match at newlines,
- s to allow . to match a newline,
- and q to quote the whole pattern (reducing the
- behavior to a simple substring match).
-
-
-
- The SQL/JSON standard borrows its definition for regular expressions
- from the LIKE_REGEX operator, which in turn uses the
- XQuery standard. PostgreSQL does not currently support the
- LIKE_REGEX operator. Therefore,
- the like_regex filter is implemented using the
- POSIX regular expression engine described in
- . This leads to various minor
- discrepancies from standard SQL/JSON behavior, which are cataloged in
- .
- 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.
-
-
-
- Keep in mind that the pattern argument of like_regex
- is a JSON path string literal, written according to the rules given in
- . 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:
-
-$.* ? (@ like_regex "^\\d+$")
-
-
-
-
-
-
- SQL/JSON Query Functions
-
- SQL/JSON functions JSON_EXISTS(),
- JSON_QUERY(), and JSON_VALUE()
- described in can be used
- to query JSON documents. Each of these functions apply a
- path_expression (the query) to a
- context_item (the document); see
- for more details on what
- path_expression can contain.
-
-
-
- SQL/JSON Query Functions
-
-
-
-
- Function signature
-
-
- Description
-
-
- Example(s)
-
-
-
-
-
-
- json_exists
- json_exists (
- context_item, path_expressionPASSING { valueASvarname } , ...
- { TRUE | FALSE | UNKNOWN | ERROR } ON ERROR)
-
-
- Returns true if the SQL/JSON path_expression
- applied to the context_item using the
- PASSINGvalues yields any
- items.
-
-
- The ON ERROR clause specifies the behavior if
- an error occurs; the default is to return the boolean
- FALSE value. Note that if the
- path_expression is strict
- and ON ERROR behavior is ERROR,
- an error is generated if it yields no items.
-
-
- Examples:
-
-
- select json_exists(jsonb '{"key1": [1,2,3]}', 'strict $.key1[*] ? (@ > 2)')
- t
-
-
- select json_exists(jsonb '{"a": [1,2,3]}', 'lax $.a[5]' ERROR ON ERROR)
- f
-
-
- select json_exists(jsonb '{"a": [1,2,3]}', 'strict $.a[5]' ERROR ON ERROR)
-
-
-ERROR: jsonpath array subscript is out of bounds
-
-
-
-
-
- json_query
- json_query (
- context_item, path_expressionPASSING { valueASvarname } , ...
- RETURNINGdata_typeFORMAT JSONENCODING UTF8
- { WITHOUT | WITH { CONDITIONAL | UNCONDITIONAL } } ARRAYWRAPPER
- { KEEP | OMIT } QUOTESON SCALAR STRING
- { ERROR | NULL | EMPTY { ARRAY | OBJECT } | DEFAULTexpression } ON EMPTY
- { ERROR | NULL | EMPTY { ARRAY | OBJECT } | DEFAULTexpression } ON ERROR)
-
-
- Returns the result of applying the SQL/JSON
- path_expression to the
- context_item using the
- PASSINGvalues.
-
-
- If the path expression returns multiple SQL/JSON items, it might be
- necessary to wrap the result using the WITH WRAPPER
- clause to make it a valid JSON string. If the wrapper is
- UNCONDITIONAL, an array wrapper will always be
- applied, even if the returned value is already a single JSON object
- or an array. If it is CONDITIONAL, it will not be
- applied to a single JSON object or an array.
- UNCONDITIONAL is the default.
-
-
- If the result is a scalar string, by default, the returned value will
- be surrounded by quotes, making it a valid JSON value. It can be made
- explicit by specifying KEEP QUOTES. Conversely,
- quotes can be omitted by specifying OMIT QUOTES.
- Note that OMIT QUOTES cannot be specified when
- WITH WRAPPER is also specified.
-
-
- The RETURNING clause can be used to specify the
- data_type of the result value. By default,
- the returned value will be of type jsonb.
-
-
- The ON EMPTY clause specifies the behavior if
- evaluating path_expression yields no value
- at all. The default when ON EMPTY is not specified
- is to return a null value.
-
-
- The ON ERROR clause specifies the
- behavior if an error occurs when evaluating
- path_expression, including the operation to
- coerce the result value to the output type, or during the execution of
- ON EMPTY behavior (that is caused by empty result
- of path_expression evaluation). The default
- when ON ERROR is not specified is to return a null
- value.
-
-
- Examples:
-
-
- select json_query(jsonb '[1,[2,3],null]', 'lax $[*][1]' WITH CONDITIONAL WRAPPER)
- [3]
-
-
- select json_query(jsonb '{"a": "[1, 2]"}', 'lax $.a' OMIT QUOTES);
- [1, 2]
-
-
- select json_query(jsonb '{"a": "[1, 2]"}', 'lax $.a' RETURNING int[] OMIT QUOTES ERROR ON ERROR);
-
-
-ERROR: malformed array literal: "[1, 2]"
-DETAIL: Missing "]" after array dimensions.
-
-
-
-
-
-
- json_value
- json_value (
- context_item, path_expression
- PASSING { valueASvarname } , ...
- RETURNINGdata_type
- { ERROR | NULL | DEFAULTexpression } ON EMPTY
- { ERROR | NULL | DEFAULTexpression } ON ERROR)
-
-
- Returns the result of applying the SQL/JSON
- path_expression to the
- context_item using the
- PASSINGvalues.
-
-
- The extracted value must be a single SQL/JSON
- scalar item; an error is thrown if that's not the case. If you expect
- that extracted value might be an object or an array, use the
- json_query function instead.
-
-
- The RETURNING clause can be used to specify the
- data_type of the result value. By default,
- the returned value will be of type text.
-
-
- The ON ERROR and ON EMPTY
- clauses have similar semantics as mentioned in the description of
- json_query.
-
-
- Note that scalar strings returned by json_value
- always have their quotes removed, equivalent to specifying
- OMIT QUOTES in json_query.
-
-
- Examples:
-
-
- select json_value(jsonb '"123.45"', '$' RETURNING float)
- 123.45
-
-
- select json_value(jsonb '"03:04 2015-02-01"', '$.datetime("HH24:MI YYYY-MM-DD")' RETURNING date)
- 2015-02-01
-
-
- select json_value(jsonb '[1,2]', 'strict $[*]' DEFAULT 9 ON ERROR)
- 9
-
-
-
-
-
-
-
-
- JSON_TABLE
-
- json_table
-
-
-
- JSON_TABLE is an SQL/JSON function which
- queries JSON data
- and presents the results as a relational view, which can be accessed as a
- regular SQL table. You can use JSON_TABLE inside
- the FROM clause of a SELECT,
- UPDATE, or DELETE and as data source
- in a MERGE statement.
-
-
-
- Taking JSON data as input, JSON_TABLE uses a JSON path
- expression to extract a part of the provided data to use as a
- row pattern for the constructed view. Each SQL/JSON
- value given by the row pattern serves as source for a separate row in the
- constructed view.
-
-
-
- To split the row pattern into columns, JSON_TABLE
- provides the COLUMNS clause that defines the
- schema of the created view. For each column, a separate JSON path expression
- can be specified to be evaluated against the row pattern to get an SQL/JSON
- value that will become the value for the specified column in a given output
- row.
-
-
-
- JSON data stored at a nested level of the row pattern can be extracted using
- the NESTED PATH clause. Each
- NESTED PATH clause can be used to generate one or more
- columns using the data from a nested level of the row pattern. Those
- columns can be specified using a COLUMNS clause that
- looks similar to the top-level COLUMNS clause. Rows constructed from
- NESTED COLUMNS are called child rows and are joined
- against the row constructed from the columns specified in the parent
- COLUMNS clause to get the row in the final view. Child
- columns themselves may contain a NESTED PATH
- specification thus allowing to extract data located at arbitrary nesting
- levels. Columns produced by multiple NESTED PATHs at the
- same level are considered to be siblings of each
- other and their rows after joining with the parent row are combined using
- UNION.
-
-
-
- The rows produced by JSON_TABLE are laterally
- joined to the row that generated them, so you do not have to explicitly join
- the constructed view with the original table holding JSON
- data.
-
-
-
- The syntax is:
-
-
-
-JSON_TABLE (
- context_item, path_expression AS json_path_name PASSING { value AS varname } , ...
- COLUMNS ( json_table_column, ... )
- { ERROR | EMPTY } ON ERROR
-)
-
-
-where json_table_column is:
-
- name FOR ORDINALITY
- | nametype
- FORMAT JSON ENCODING UTF8
- PATH path_expression
- { WITHOUT | WITH { CONDITIONAL | UNCONDITIONAL } } ARRAY WRAPPER
- { KEEP | OMIT } QUOTES ON SCALAR STRING
- { ERROR | NULL | EMPTY { ARRAY | OBJECT } | DEFAULT expression } ON EMPTY
- { ERROR | NULL | EMPTY { ARRAY | OBJECT } | DEFAULT expression } ON ERROR
- | nametype EXISTS PATH path_expression
- { ERROR | TRUE | FALSE | UNKNOWN } ON ERROR
- | NESTED PATH path_expression AS json_path_name COLUMNS ( json_table_column, ... )
-
-
-
- Each syntax element is described below in more detail.
-
-
-
-
-
- context_item, path_expressionASjson_path_namePASSING { valueASvarname } , ...
-
-
-
- The input data to query (context_item),
- the JSON path expression defining the query (path_expression)
- with an optional name (json_path_name), and an
- optional PASSING clause, which can provide data values
- to the path_expression. The result of the input
- data evaluation using the aforementioned elements is called the
- row pattern, which is used as the source for row
- values in the constructed view.
-
-
-
-
-
-
- COLUMNS ( json_table_column, ... )
-
-
-
-
- The COLUMNS clause defining the schema of the
- constructed view. In this clause, you can specify each column to be
- filled with an SQL/JSON value obtained by applying a JSON path expression
- against the row pattern. json_table_column has
- the following variants:
-
-
-
-
-
- nameFOR ORDINALITY
-
-
-
- Adds an ordinality column that provides sequential row numbering starting
- from 1. Each NESTED PATH (see below) gets its own
- counter for any nested ordinality columns.
-
-
-
-
-
-
- nametype
- FORMAT JSONENCODING UTF8
- PATHpath_expression
-
-
-
- Inserts an SQL/JSON value obtained by applying
- path_expression against the row pattern into
- the view's output row after coercing it to specified
- type.
-
-
- Specifying FORMAT JSON makes it explicit that you
- expect the value to be a valid json object. It only
- makes sense to specify FORMAT JSON if
- type is one of bpchar,
- bytea, character varying, name,
- json, jsonb, text, or a domain over
- these types.
-
-
- Optionally, you can specify WRAPPER and
- QUOTES clauses to format the output. Note that
- specifying OMIT QUOTES overrides
- FORMAT JSON if also specified, because unquoted
- literals do not constitute valid json values.
-
-
- Optionally, you can use ON EMPTY and
- ON ERROR clauses to specify whether to throw the error
- or return the specified value when the result of JSON path evaluation is
- empty and when an error occurs during JSON path evaluation or when
- coercing the SQL/JSON value to the specified type, respectively. The
- default for both is to return a NULL value.
-
-
-
- This clause is internally turned into and has the same semantics as
- JSON_VALUE or JSON_QUERY.
- The latter if the specified type is not a scalar type or if either of
- FORMAT JSON, WRAPPER, or
- QUOTES clause is present.
-
-
-
-
-
-
-
- nametype
- EXISTSPATHpath_expression
-
-
-
- Inserts a boolean value obtained by applying
- path_expression against the row pattern
- into the view's output row after coercing it to specified
- type.
-
-
- The value corresponds to whether applying the PATH
- expression to the row pattern yields any values.
-
-
- The specified type should have a cast from the
- boolean type.
-
-
- Optionally, you can use ON ERROR to specify whether to
- throw the error or return the specified value when an error occurs during
- JSON path evaluation or when coercing SQL/JSON value to the specified
- type. The default is to return a boolean value
- FALSE.
-
-
-
- This clause is internally turned into and has the same semantics as
- JSON_EXISTS.
-
-
-
-
-
-
-
- NESTED PATH path_expressionASjson_path_name
- COLUMNS ( json_table_column, ... )
-
-
-
-
- Extracts SQL/JSON values from nested levels of the row pattern,
- generates one or more columns as defined by the COLUMNS
- subclause, and inserts the extracted SQL/JSON values into those
- columns. The json_table_column
- expression in the COLUMNS subclause uses the same
- syntax as in the parent COLUMNS clause.
-
-
-
- The NESTED PATH syntax is recursive,
- so you can go down multiple nested levels by specifying several
- NESTED PATH subclauses within each other.
- It allows to unnest the hierarchy of JSON objects and arrays
- in a single function invocation rather than chaining several
- JSON_TABLE expressions in an SQL statement.
-
-
-
-
-
-
-
- In each variant of json_table_column described
- above, if the PATH clause is omitted, path expression
- $.name is used, where
- name is the provided column name.
-
-
-
-
-
-
-
-
- ASjson_path_name
-
-
-
-
- The optional json_path_name serves as an
- identifier of the provided path_expression.
- The name must be unique and distinct from the column names.
-
-
-
-
-
-
- { ERROR | EMPTY } ON ERROR
-
-
-
-
- The optional ON ERROR can be used to specify how to
- handle errors when evaluating the top-level
- path_expression. Use ERROR
- if you want the errors to be thrown and EMPTY to
- return an empty table, that is, a table containing 0 rows. Note that
- this clause does not affect the errors that occur when evaluating
- columns, for which the behavior depends on whether the
- ON ERROR clause is specified against a given column.
-
-
-
-
-
- Examples
-
-
- In the examples that follow, the following table containing JSON data
- will be used:
-
-
-CREATE TABLE my_films ( js jsonb );
-
-INSERT INTO my_films VALUES (
-'{ "favorites" : [
- { "kind" : "comedy", "films" : [
- { "title" : "Bananas",
- "director" : "Woody Allen"},
- { "title" : "The Dinner Game",
- "director" : "Francis Veber" } ] },
- { "kind" : "horror", "films" : [
- { "title" : "Psycho",
- "director" : "Alfred Hitchcock" } ] },
- { "kind" : "thriller", "films" : [
- { "title" : "Vertigo",
- "director" : "Alfred Hitchcock" } ] },
- { "kind" : "drama", "films" : [
- { "title" : "Yojimbo",
- "director" : "Akira Kurosawa" } ] }
- ] }');
-
-
-
-
- The following query shows how to use JSON_TABLE to
- turn the JSON objects in the my_films table
- to a view containing columns for the keys kind,
- title, and director contained in
- the original JSON along with an ordinality column:
-
-
-SELECT jt.* FROM
- my_films,
- JSON_TABLE (js, '$.favorites[*]' COLUMNS (
- id FOR ORDINALITY,
- kind text PATH '$.kind',
- title text PATH '$.films[*].title' WITH WRAPPER,
- director text PATH '$.films[*].director' WITH WRAPPER)) AS jt;
-
-
-
- id | kind | title | director
-----+----------+--------------------------------+----------------------------------
- 1 | comedy | ["Bananas", "The Dinner Game"] | ["Woody Allen", "Francis Veber"]
- 2 | horror | ["Psycho"] | ["Alfred Hitchcock"]
- 3 | thriller | ["Vertigo"] | ["Alfred Hitchcock"]
- 4 | drama | ["Yojimbo"] | ["Akira Kurosawa"]
-(4 rows)
-
-
-
-
- The following is a modified version of the above query to show the
- usage of PASSING arguments in the filter specified in
- the top-level JSON path expression and the various options for the
- individual columns:
-
-
-SELECT jt.* FROM
- my_films,
- JSON_TABLE (js, '$.favorites[*] ? (@.films[*].director == $filter)'
- PASSING 'Alfred Hitchcock' AS filter, 'Vertigo' AS filter2
- COLUMNS (
- id FOR ORDINALITY,
- kind text PATH '$.kind',
- title text FORMAT JSON PATH '$.films[*].title' OMIT QUOTES,
- director text PATH '$.films[*].director' KEEP QUOTES)) AS jt;
-
-
-
- id | kind | title | director
-----+----------+---------+--------------------
- 1 | horror | Psycho | "Alfred Hitchcock"
- 2 | thriller | Vertigo | "Alfred Hitchcock"
-(2 rows)
-
-
-
-
- The following is a modified version of the above query to show the usage
- of NESTED PATH for populating title and director
- columns, illustrating how they are joined to the parent columns id and
- kind:
-
-
-SELECT jt.* FROM
- my_films,
- JSON_TABLE ( js, '$.favorites[*] ? (@.films[*].director == $filter)'
- PASSING 'Alfred Hitchcock' AS filter
- COLUMNS (
- id FOR ORDINALITY,
- kind text PATH '$.kind',
- NESTED PATH '$.films[*]' COLUMNS (
- title text FORMAT JSON PATH '$.title' OMIT QUOTES,
- director text PATH '$.director' KEEP QUOTES))) AS jt;
-
-
-
- id | kind | title | director
-----+----------+---------+--------------------
- 1 | horror | Psycho | "Alfred Hitchcock"
- 2 | thriller | Vertigo | "Alfred Hitchcock"
-(2 rows)
-
-
-
-
-
- The following is the same query but without the filter in the root
- path:
-
-
-SELECT jt.* FROM
- my_films,
- JSON_TABLE ( js, '$.favorites[*]'
- COLUMNS (
- id FOR ORDINALITY,
- kind text PATH '$.kind',
- NESTED PATH '$.films[*]' COLUMNS (
- title text FORMAT JSON PATH '$.title' OMIT QUOTES,
- director text PATH '$.director' KEEP QUOTES))) AS jt;
-
-
-
- id | kind | title | director
-----+----------+-----------------+--------------------
- 1 | comedy | Bananas | "Woody Allen"
- 1 | comedy | The Dinner Game | "Francis Veber"
- 2 | horror | Psycho | "Alfred Hitchcock"
- 3 | thriller | Vertigo | "Alfred Hitchcock"
- 4 | drama | Yojimbo | "Akira Kurosawa"
-(5 rows)
-
-
-
-
-
- The following shows another query using a different JSON
- object as input. It shows the UNION "sibling join" between
- NESTED paths $.movies[*] and
- $.books[*] and also the usage of
- FOR ORDINALITY column at NESTED
- levels (columns movie_id, book_id,
- and author_id):
-
-
-SELECT * FROM JSON_TABLE (
-'{"favorites":
- {"movies":
- [{"name": "One", "director": "John Doe"},
- {"name": "Two", "director": "Don Joe"}],
- "books":
- [{"name": "Mystery", "authors": [{"name": "Brown Dan"}]},
- {"name": "Wonder", "authors": [{"name": "Jun Murakami"}, {"name":"Craig Doe"}]}]
-}}'::json, '$.favorites[*]'
-COLUMNS (
- user_id FOR ORDINALITY,
- NESTED '$.movies[*]'
- COLUMNS (
- movie_id FOR ORDINALITY,
- mname text PATH '$.name',
- director text),
- NESTED '$.books[*]'
- COLUMNS (
- book_id FOR ORDINALITY,
- bname text PATH '$.name',
- NESTED '$.authors[*]'
- COLUMNS (
- author_id FOR ORDINALITY,
- author_name text PATH '$.name'))));
-
-
-
- user_id | movie_id | mname | director | book_id | bname | author_id | author_name
----------+----------+-------+----------+---------+---------+-----------+--------------
- 1 | 1 | One | John Doe | | | |
- 1 | 2 | Two | Don Joe | | | |
- 1 | | | | 1 | Mystery | 1 | Brown Dan
- 1 | | | | 2 | Wonder | 1 | Jun Murakami
- 1 | | | | 2 | Wonder | 2 | Craig Doe
-(5 rows)
-
-
-
-
-
-
-
- Sequence Manipulation Functions
-
-
- sequence
-
-
-
- This section describes functions for operating on sequence
- objects, also called sequence generators or just sequences.
- Sequence objects are special single-row tables created with .
- Sequence objects are commonly used to generate unique identifiers
- for rows of a table. The sequence functions, listed in , provide simple, multiuser-safe
- methods for obtaining successive sequence values from sequence
- objects.
-
-
-
- Sequence Functions
-
-
-
-
- Function
-
-
- Description
-
-
-
-
-
-
-
-
- nextval
-
- nextval ( regclass )
- bigint
-
-
- Advances the sequence object to its next value and returns that value.
- This is done atomically: even if multiple sessions
- execute nextval concurrently, each will safely
- receive a distinct sequence value.
- If the sequence object has been created with default parameters,
- successive nextval calls will return successive
- values beginning with 1. Other behaviors can be obtained by using
- appropriate parameters in the
- command.
-
-
- This function requires USAGE
- or UPDATE privilege on the sequence.
-
-
-
-
-
-
- setval
-
- setval ( regclass, bigint, boolean )
- bigint
-
-
- Sets the sequence object's current value, and optionally
- its is_called flag. The two-parameter
- form sets the sequence's last_value field to the
- specified value and sets its is_called field to
- true, meaning that the next
- nextval will advance the sequence before
- returning a value. The value that will be reported
- by currval is also set to the specified value.
- In the three-parameter form, is_called can be set
- to either true
- or false. true has the same
- effect as the two-parameter form. If it is set
- to false, the next nextval
- will return exactly the specified value, and sequence advancement
- commences with the following nextval.
- Furthermore, the value reported by currval is not
- changed in this case. For example,
-
-SELECT setval('myseq', 42); Next nextval will return 43
-SELECT setval('myseq', 42, true); Same as above
-SELECT setval('myseq', 42, false); Next nextval will return 42
-
- The result returned by setval is just the value of its
- second argument.
-
-
- This function requires UPDATE privilege on the
- sequence.
-
-
-
-
-
-
- currval
-
- currval ( regclass )
- bigint
-
-
- Returns the value most recently obtained
- by nextval for this sequence in the current
- session. (An error is reported if nextval 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 nextval since
- the current session did.
-
-
- This function requires USAGE
- or SELECT privilege on the sequence.
-
-
-
-
-
-
- lastval
-
- lastval ()
- bigint
-
-
- Returns the value most recently returned by
- nextval in the current session. This function is
- identical to currval, except that instead
- of taking the sequence name as an argument it refers to whichever
- sequence nextval was most recently applied to
- in the current session. It is an error to call
- lastval if nextval
- has not yet been called in the current session.
-
-
- This function requires USAGE
- or SELECT privilege on the last used sequence.
-
-
-
-
-
-
-
-
- To avoid blocking concurrent transactions that obtain numbers from
- the same sequence, the value obtained by nextval
- 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 INSERT with
- an ON CONFLICT clause will compute the to-be-inserted
- tuple, including doing any required nextval
- calls, before detecting any conflict that would cause it to follow
- the ON CONFLICT rule instead.
- Thus, PostgreSQL sequence
- objects cannot be used to obtain gapless
- sequences.
-
-
-
- Likewise, sequence state changes made by setval
- are immediately visible to other transactions, and are not undone if
- the calling transaction rolls back.
-
-
-
- If the database cluster crashes before committing a transaction
- containing a nextval
- or setval 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
- nextval call has been committed before doing so.
-
-
-
-
- The sequence to be operated on by a sequence function is specified by
- a regclass argument, which is simply the OID of the sequence in the
- pg_class system catalog. You do not have to look up the
- OID by hand, however, since the regclass data type's input
- converter will do the work for you. See
- for details.
-
-
-
-
-
- Conditional Expressions
-
-
- CASE
-
-
-
- conditional expression
-
-
-
- This section describes the SQL-compliant conditional expressions
- available in PostgreSQL.
-
-
-
-
- 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.
-
-
-
-
-
- Although COALESCE, GREATEST, and
- LEAST are syntactically similar to functions, they are
- not ordinary functions, and thus cannot be used with explicit
- VARIADIC array arguments.
-
-
-
-
- <literal>CASE</literal>
-
-
- The SQL CASE expression is a
- generic conditional expression, similar to if/else statements in
- other programming languages:
-
-
-CASE WHEN condition THEN result
- WHEN ...
- ELSE result
-END
-
-
- CASE clauses can be used wherever
- an expression is valid. Each condition is an
- expression that returns a boolean result. If the condition's
- result is true, the value of the CASE expression is the
- result that follows the condition, and the
- remainder of the CASE expression is not processed. If the
- condition's result is not true, any subsequent WHEN clauses
- are examined in the same manner. If no WHEN
- condition yields true, the value of the
- CASE expression is the result of the
- ELSE clause. If the ELSE clause is
- omitted and no condition is true, the result is null.
-
-
-
- An example:
-
-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
-
-
-
-
- The data types of all the result
- expressions must be convertible to a single output type.
- See for more details.
-
-
-
- There is a simple form of CASE expression
- that is a variant of the general form above:
-
-
-CASE expression
- WHEN value THEN result
- WHEN ...
- ELSE result
-END
-
-
- The first
- expression is computed, then compared to
- each of the value expressions in the
- WHEN clauses until one is found that is equal to it. If
- no match is found, the result of the
- ELSE clause (or a null value) is returned. This is similar
- to the switch statement in C.
-
-
-
- The example above can be written using the simple
- CASE syntax:
-
-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
-
-
-
-
- A CASE 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:
-
-SELECT ... WHERE CASE WHEN x <> 0 THEN y/x > 1.5 ELSE false END;
-
-
-
-
-
- As described in , there are various
- situations in which subexpressions of an expression are evaluated at
- different times, so that the principle that CASE
- evaluates only necessary subexpressions is not ironclad. For
- example a constant 1/0 subexpression will usually result in
- a division-by-zero failure at planning time, even if it's within
- a CASE arm that would never be entered at run time.
-
-
-
-
-
- <literal>COALESCE</literal>
-
-
- COALESCE
-
-
-
- NVL
-
-
-
- IFNULL
-
-
-
-COALESCE(value, ...)
-
-
-
- The COALESCE 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:
-
-SELECT COALESCE(description, short_description, '(none)') ...
-
- This returns description if it is not null, otherwise
- short_description if it is not null, otherwise (none).
-
-
-
- The arguments must all be convertible to a common data type, which
- will be the type of the result (see
- for details).
-
-
-
- Like a CASE expression, COALESCE 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 NVL and IFNULL, which are used in some other
- database systems.
-
-
-
-
- <literal>NULLIF</literal>
-
-
- NULLIF
-
-
-
-NULLIF(value1, value2)
-
-
-
- The NULLIF function returns a null value if
- value1 equals value2;
- otherwise it returns value1.
- This can be used to perform the inverse operation of the
- COALESCE example given above:
-
-SELECT NULLIF(value, '(none)') ...
-
- In this example, if value is (none),
- null is returned, otherwise the value of value
- is returned.
-
-
-
- The two arguments must be of comparable types.
- To be specific, they are compared exactly as if you had
- written value1
- = value2, so there must be a
- suitable = operator available.
-
-
-
- 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 = operator, and in some cases that will have
- been promoted to match the second argument's type. For
- example, NULLIF(1, 2.2) yields numeric,
- because there is no integer=
- numeric operator,
- only numeric=numeric.
-
-
-
-
-
- <literal>GREATEST</literal> and <literal>LEAST</literal>
-
-
- GREATEST
-
-
- LEAST
-
-
-
-GREATEST(value, ...)
-
-
-LEAST(value, ...)
-
-
-
- The GREATEST and LEAST 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 for details).
-
-
-
- NULL values in the argument list are ignored. The result will be NULL
- only if all the expressions evaluate to NULL. (This is a deviation from
- the SQL standard. According to the standard, the return value is NULL if
- any argument is NULL. Some other databases behave this way.)
-
-
-
-
-
- Array Functions and Operators
-
-
- shows the specialized operators
- available for array types.
- In addition to those, the usual comparison operators shown in 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.
-
-
-
- Array Operators
-
-
-
-
- Operator
-
-
- Description
-
-
- Example(s)
-
-
-
-
-
-
-
- anyarray@>anyarray
- boolean
-
-
- 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 ARRAY[1] and ARRAY[1,1] are
- each considered to contain the other.)
-
-
- ARRAY[1,4,3] @> ARRAY[3,1,3]
- t
-
-
-
-
-
- anyarray<@anyarray
- boolean
-
-
- Is the first array contained by the second?
-
-
- ARRAY[2,2,7] <@ ARRAY[1,7,4,2,6]
- t
-
-
-
-
-
- anyarray&&anyarray
- boolean
-
-
- Do the arrays overlap, that is, have any elements in common?
-
-
- ARRAY[1,4,3] && ARRAY[2,1]
- t
-
-
-
-
-
- anycompatiblearray||anycompatiblearray
- anycompatiblearray
-
-
- 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 ).
-
-
- ARRAY[1,2,3] || ARRAY[4,5,6,7]
- {1,2,3,4,5,6,7}
-
-
- ARRAY[1,2,3] || ARRAY[[4,5,6],[7,8,9.9]]
- {{1,2,3},{4,5,6},{7,8,9.9}}
-
-
-
-
-
- anycompatible||anycompatiblearray
- anycompatiblearray
-
-
- Concatenates an element onto the front of an array (which must be
- empty or one-dimensional).
-
-
- 3 || ARRAY[4,5,6]
- {3,4,5,6}
-
-
-
-
-
- anycompatiblearray||anycompatible
- anycompatiblearray
-
-
- Concatenates an element onto the end of an array (which must be
- empty or one-dimensional).
-
-
- ARRAY[4,5,6] || 7
- {4,5,6,7}
-
-
-
-
-
-
-
- See for more details about array operator
- behavior. See for more details about
- which operators support indexed operations.
-
-
-
- shows the functions
- available for use with array types. See
- for more information and examples of the use of these functions.
-
-
-
- Array Functions
-
-
-
-
- Function
-
-
- Description
-
-
- Example(s)
-
-
-
-
-
-
-
-
- array_append
-
- array_append ( anycompatiblearray, anycompatible )
- anycompatiblearray
-
-
- Appends an element to the end of an array (same as
- the anycompatiblearray||anycompatible
- operator).
-
-
- array_append(ARRAY[1,2], 3)
- {1,2,3}
-
-
-
-
-
-
- array_cat
-
- array_cat ( anycompatiblearray, anycompatiblearray )
- anycompatiblearray
-
-
- Concatenates two arrays (same as
- the anycompatiblearray||anycompatiblearray
- operator).
-
-
- array_cat(ARRAY[1,2,3], ARRAY[4,5])
- {1,2,3,4,5}
-
-
-
-
-
-
- array_dims
-
- array_dims ( anyarray )
- text
-
-
- Returns a text representation of the array's dimensions.
-
-
- array_dims(ARRAY[[1,2,3], [4,5,6]])
- [1:2][1:3]
-
-
-
-
-
-
- array_fill
-
- array_fill ( anyelement, integer[]
- , integer[] )
- anyarray
-
-
- 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 1).
-
-
- array_fill(11, ARRAY[2,3])
- {{11,11,11},{11,11,11}}
-
-
- array_fill(7, ARRAY[3], ARRAY[2])
- [2:4]={7,7,7}
-
-
-
-
-
-
- array_length
-
- array_length ( anyarray, integer )
- integer
-
-
- Returns the length of the requested array dimension.
- (Produces NULL instead of 0 for empty or missing array dimensions.)
-
-
- array_length(array[1,2,3], 1)
- 3
-
-
- array_length(array[]::int[], 1)
- NULL
-
-
- array_length(array['text'], 2)
- NULL
-
-
-
-
-
-
- array_lower
-
- array_lower ( anyarray, integer )
- integer
-
-
- Returns the lower bound of the requested array dimension.
-
-
- array_lower('[0:2]={1,2,3}'::integer[], 1)
- 0
-
-
-
-
-
-
- array_ndims
-
- array_ndims ( anyarray )
- integer
-
-
- Returns the number of dimensions of the array.
-
-
- array_ndims(ARRAY[[1,2,3], [4,5,6]])
- 2
-
-
-
-
-
-
- array_position
-
- array_position ( anycompatiblearray, anycompatible, integer )
- integer
-
-
- Returns the subscript of the first occurrence of the second argument
- in the array, or NULL 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 IS NOT DISTINCT FROM
- semantics, so it is possible to search for NULL.
-
-
- array_position(ARRAY['sun', 'mon', 'tue', 'wed', 'thu', 'fri', 'sat'], 'mon')
- 2
-
-
-
-
-
-
- array_positions
-
- array_positions ( anycompatiblearray, anycompatible )
- integer[]
-
-
- 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 IS NOT DISTINCT FROM
- semantics, so it is possible to search for NULL.
- NULL is returned only if the array
- is NULL; if the value is not found in the array, an
- empty array is returned.
-
-
- array_positions(ARRAY['A','A','B','A'], 'A')
- {1,2,4}
-
-
-
-
-
-
- array_prepend
-
- array_prepend ( anycompatible, anycompatiblearray )
- anycompatiblearray
-
-
- Prepends an element to the beginning of an array (same as
- the anycompatible||anycompatiblearray
- operator).
-
-
- array_prepend(1, ARRAY[2,3])
- {1,2,3}
-
-
-
-
-
-
- array_remove
-
- array_remove ( anycompatiblearray, anycompatible )
- anycompatiblearray
-
-
- Removes all elements equal to the given value from the array.
- The array must be one-dimensional.
- Comparisons are done using IS NOT DISTINCT FROM
- semantics, so it is possible to remove NULLs.
-
-
- array_remove(ARRAY[1,2,3,2], 2)
- {1,3}
-
-
-
-
-
-
- array_replace
-
- array_replace ( anycompatiblearray, anycompatible, anycompatible )
- anycompatiblearray
-
-
- Replaces each array element equal to the second argument with the
- third argument.
-
-
- array_replace(ARRAY[1,2,5,4], 5, 3)
- {1,2,3,4}
-
-
-
-
-
-
- array_sample
-
- array_sample ( arrayanyarray, ninteger )
- anyarray
-
-
- Returns an array of n items randomly selected
- from array. n may not
- exceed the length of array's first dimension.
- If array is multi-dimensional,
- an item is a slice having a given first subscript.
-
-
- array_sample(ARRAY[1,2,3,4,5,6], 3)
- {2,6,1}
-
-
- array_sample(ARRAY[[1,2],[3,4],[5,6]], 2)
- {{5,6},{1,2}}
-
-
-
-
-
-
- array_shuffle
-
- array_shuffle ( anyarray )
- anyarray
-
-
- Randomly shuffles the first dimension of the array.
-
-
- array_shuffle(ARRAY[[1,2],[3,4],[5,6]])
- {{5,6},{1,2},{3,4}}
-
-
-
-
-
-
- array_to_string
-
- array_to_string ( arrayanyarray, delimitertext, null_stringtext )
- text
-
-
- Converts each array element to its text representation, and
- concatenates those separated by
- the delimiter string.
- If null_string is given and is
- not NULL, then NULL array
- entries are represented by that string; otherwise, they are omitted.
- See also string_to_array.
-
-
- array_to_string(ARRAY[1, 2, 3, NULL, 5], ',', '*')
- 1,2,3,*,5
-
-
-
-
-
-
- array_upper
-
- array_upper ( anyarray, integer )
- integer
-
-
- Returns the upper bound of the requested array dimension.
-
-
- array_upper(ARRAY[1,8,3,7], 1)
- 4
-
-
-
-
-
-
- cardinality
-
- cardinality ( anyarray )
- integer
-
-
- Returns the total number of elements in the array, or 0 if the array
- is empty.
-
-
- cardinality(ARRAY[[1,2],[3,4]])
- 4
-
-
-
-
-
-
- trim_array
-
- trim_array ( arrayanyarray, ninteger )
- anyarray
-
-
- Trims an array by removing the last n elements.
- If the array is multidimensional, only the first dimension is trimmed.
-
-
- trim_array(ARRAY[1,2,3,4,5,6], 2)
- {1,2,3,4}
-
-
-
-
-
-
- unnest
-
- unnest ( anyarray )
- setof anyelement
-
-
- Expands an array into a set of rows.
- The array's elements are read out in storage order.
-
-
- unnest(ARRAY[1,2])
-
-
- 1
- 2
-
-
-
- unnest(ARRAY[['foo','bar'],['baz','quux']])
-
-
- foo
- bar
- baz
- quux
-
-
-
-
-
-
- unnest ( anyarray, anyarray, ... )
- setof anyelement, anyelement [, ... ]
-
-
- 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 NULLs. This form is only allowed
- in a query's FROM clause; see .
-
-
- select * from unnest(ARRAY[1,2], ARRAY['foo','bar','baz']) as x(a,b)
-
-
- a | b
----+-----
- 1 | foo
- 2 | bar
- | baz
-
-
-
-
-
-
-
-
- See also about the aggregate
- function array_agg for use with arrays.
-
-
-
-
- Range/Multirange Functions and Operators
-
-
- See for an overview of range types.
-
-
-
- shows the specialized operators
- available for range types.
- shows the specialized operators
- available for multirange types.
- In addition to those, the usual comparison operators shown in
- 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.
-
-
-
- Range Operators
-
-
-
-
- Operator
-
-
- Description
-
-
- Example(s)
-
-
-
-
-
-
-
- anyrange@>anyrange
- boolean
-
-
- Does the first range contain the second?
-
-
- int4range(2,4) @> int4range(2,3)
- t
-
-
-
-
-
- anyrange@>anyelement
- boolean
-
-
- Does the range contain the element?
-
-
- '[2011-01-01,2011-03-01)'::tsrange @> '2011-01-10'::timestamp
- t
-
-
-
-
-
- anyrange<@anyrange
- boolean
-
-
- Is the first range contained by the second?
-
-
- int4range(2,4) <@ int4range(1,7)
- t
-
-
-
-
-
- anyelement<@anyrange
- boolean
-
-
- Is the element contained in the range?
-
-
- 42 <@ int4range(1,7)
- f
-
-
-
-
-
- anyrange&&anyrange
- boolean
-
-
- Do the ranges overlap, that is, have any elements in common?
-
-
- int8range(3,7) && int8range(4,12)
- t
-
-
-
-
-
- anyrange<<anyrange
- boolean
-
-
- Is the first range strictly left of the second?
-
-
- int8range(1,10) << int8range(100,110)
- t
-
-
-
-
-
- anyrange>>anyrange
- boolean
-
-
- Is the first range strictly right of the second?
-
-
- int8range(50,60) >> int8range(20,30)
- t
-
-
-
-
-
- anyrange&<anyrange
- boolean
-
-
- Does the first range not extend to the right of the second?
-
-
- int8range(1,20) &< int8range(18,20)
- t
-
-
-
-
-
- anyrange&>anyrange
- boolean
-
-
- Does the first range not extend to the left of the second?
-
-
- int8range(7,20) &> int8range(5,10)
- t
-
-
-
-
-
- anyrange-|-anyrange
- boolean
-
-
- Are the ranges adjacent?
-
-
- numrange(1.1,2.2) -|- numrange(2.2,3.3)
- t
-
-
-
-
-
- anyrange+anyrange
- anyrange
-
-
- Computes the union of the ranges. The ranges must overlap or be
- adjacent, so that the union is a single range (but
- see range_merge()).
-
-
- numrange(5,15) + numrange(10,20)
- [5,20)
-
-
-
-
-
- anyrange*anyrange
- anyrange
-
-
- Computes the intersection of the ranges.
-
-
- int8range(5,15) * int8range(10,20)
- [10,15)
-
-
-
-
-
- anyrange-anyrange
- anyrange
-
-
- 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.
-
-
- int8range(5,15) - int8range(10,20)
- [5,10)
-
-
-
-
-
-
-
- Multirange Operators
-
-
-
-
- Operator
-
-
- Description
-
-
- Example(s)
-
-
-
-
-
-
-
- anymultirange@>anymultirange
- boolean
-
-
- Does the first multirange contain the second?
-
-
- '{[2,4)}'::int4multirange @> '{[2,3)}'::int4multirange
- t
-
-
-
-
-
- anymultirange@>anyrange
- boolean
-
-
- Does the multirange contain the range?
-
-
- '{[2,4)}'::int4multirange @> int4range(2,3)
- t
-
-
-
-
-
- anymultirange@>anyelement
- boolean
-
-
- Does the multirange contain the element?
-
-
- '{[2011-01-01,2011-03-01)}'::tsmultirange @> '2011-01-10'::timestamp
- t
-
-
-
-
-
- anyrange@>anymultirange
- boolean
-
-
- Does the range contain the multirange?
-
-
- '[2,4)'::int4range @> '{[2,3)}'::int4multirange
- t
-
-
-
-
-
- anymultirange<@anymultirange
- boolean
-
-
- Is the first multirange contained by the second?
-
-
- '{[2,4)}'::int4multirange <@ '{[1,7)}'::int4multirange
- t
-
-
-
-
-
- anymultirange<@anyrange
- boolean
-
-
- Is the multirange contained by the range?
-
-
- '{[2,4)}'::int4multirange <@ int4range(1,7)
- t
-
-
-
-
-
- anyrange<@anymultirange
- boolean
-
-
- Is the range contained by the multirange?
-
-
- int4range(2,4) <@ '{[1,7)}'::int4multirange
- t
-
-
-
-
-
- anyelement<@anymultirange
- boolean
-
-
- Is the element contained by the multirange?
-
-
- 4 <@ '{[1,7)}'::int4multirange
- t
-
-
-
-
-
- anymultirange&&anymultirange
- boolean
-
-
- Do the multiranges overlap, that is, have any elements in common?
-
-
- '{[3,7)}'::int8multirange && '{[4,12)}'::int8multirange
- t
-
-
-
-
-
- anymultirange&&anyrange
- boolean
-
-
- Does the multirange overlap the range?
-
-
- '{[3,7)}'::int8multirange && int8range(4,12)
- t
-
-
-
-
-
- anyrange&&anymultirange
- boolean
-
-
- Does the range overlap the multirange?
-
-
- int8range(3,7) && '{[4,12)}'::int8multirange
- t
-
-
-
-
-
- anymultirange<<anymultirange
- boolean
-
-
- Is the first multirange strictly left of the second?
-
-
- '{[1,10)}'::int8multirange << '{[100,110)}'::int8multirange
- t
-
-
-
-
-
- anymultirange<<anyrange
- boolean
-
-
- Is the multirange strictly left of the range?
-
-
- '{[1,10)}'::int8multirange << int8range(100,110)
- t
-
-
-
-
-
- anyrange<<anymultirange
- boolean
-
-
- Is the range strictly left of the multirange?
-
-
- int8range(1,10) << '{[100,110)}'::int8multirange
- t
-
-
-
-
-
- anymultirange>>anymultirange
- boolean
-
-
- Is the first multirange strictly right of the second?
-
-
- '{[50,60)}'::int8multirange >> '{[20,30)}'::int8multirange
- t
-
-
-
-
-
- anymultirange>>anyrange
- boolean
-
-
- Is the multirange strictly right of the range?
-
-
- '{[50,60)}'::int8multirange >> int8range(20,30)
- t
-
-
-
-
-
- anyrange>>anymultirange
- boolean
-
-
- Is the range strictly right of the multirange?
-
-
- int8range(50,60) >> '{[20,30)}'::int8multirange
- t
-
-
-
-
-
- anymultirange&<anymultirange
- boolean
-
-
- Does the first multirange not extend to the right of the second?
-
-
- '{[1,20)}'::int8multirange &< '{[18,20)}'::int8multirange
- t
-
-
-
-
-
- anymultirange&<anyrange
- boolean
-
-
- Does the multirange not extend to the right of the range?
-
-
- '{[1,20)}'::int8multirange &< int8range(18,20)
- t
-
-
-
-
-
- anyrange&<anymultirange
- boolean
-
-
- Does the range not extend to the right of the multirange?
-
-
- int8range(1,20) &< '{[18,20)}'::int8multirange
- t
-
-
-
-
-
- anymultirange&>anymultirange
- boolean
-
-
- Does the first multirange not extend to the left of the second?
-
-
- '{[7,20)}'::int8multirange &> '{[5,10)}'::int8multirange
- t
-
-
-
-
-
- anymultirange&>anyrange
- boolean
-
-
- Does the multirange not extend to the left of the range?
-
-
- '{[7,20)}'::int8multirange &> int8range(5,10)
- t
-
-
-
-
-
- anyrange&>anymultirange
- boolean
-
-
- Does the range not extend to the left of the multirange?
-
-
- int8range(7,20) &> '{[5,10)}'::int8multirange
- t
-
-
-
-
-
- anymultirange-|-anymultirange
- boolean
-
-
- Are the multiranges adjacent?
-
-
- '{[1.1,2.2)}'::nummultirange -|- '{[2.2,3.3)}'::nummultirange
- t
-
-
-
-
-
- anymultirange-|-anyrange
- boolean
-
-
- Is the multirange adjacent to the range?
-
-
- '{[1.1,2.2)}'::nummultirange -|- numrange(2.2,3.3)
- t
-
-
-
-
-
- anyrange-|-anymultirange
- boolean
-
-
- Is the range adjacent to the multirange?
-
-
- numrange(1.1,2.2) -|- '{[2.2,3.3)}'::nummultirange
- t
-
-
-
-
-
- anymultirange+anymultirange
- anymultirange
-
-
- Computes the union of the multiranges. The multiranges need not overlap
- or be adjacent.
-
-
- '{[5,10)}'::nummultirange + '{[15,20)}'::nummultirange
- {[5,10), [15,20)}
-
-
-
-
-
- anymultirange*anymultirange
- anymultirange
-
-
- Computes the intersection of the multiranges.
-
-
- '{[5,15)}'::int8multirange * '{[10,20)}'::int8multirange
- {[10,15)}
-
-
-
-
-
- anymultirange-anymultirange
- anymultirange
-
-
- Computes the difference of the multiranges.
-
-
- '{[5,20)}'::int8multirange - '{[10,15)}'::int8multirange
- {[5,10), [15,20)}
-
-
-
-
-
-
-
- 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.
-
-
-
- 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.
-
-
-
- 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.
-
-
-
- shows the functions
- available for use with range types.
- shows the functions
- available for use with multirange types.
-
-
-
- Range Functions
-
-
-
-
- Function
-
-
- Description
-
-
- Example(s)
-
-
-
-
-
-
-
-
- lower
-
- lower ( anyrange )
- anyelement
-
-
- Extracts the lower bound of the range (NULL if the
- range is empty or has no lower bound).
-
-
- lower(numrange(1.1,2.2))
- 1.1
-
-
-
-
-
-
- upper
-
- upper ( anyrange )
- anyelement
-
-
- Extracts the upper bound of the range (NULL if the
- range is empty or has no upper bound).
-
-
- upper(numrange(1.1,2.2))
- 2.2
-
-
-
-
-
-
- isempty
-
- isempty ( anyrange )
- boolean
-
-
- Is the range empty?
-
-
- isempty(numrange(1.1,2.2))
- f
-
-
-
-
-
-
- lower_inc
-
- lower_inc ( anyrange )
- boolean
-
-
- Is the range's lower bound inclusive?
-
-
- lower_inc(numrange(1.1,2.2))
- t
-
-
-
-
-
-
- upper_inc
-
- upper_inc ( anyrange )
- boolean
-
-
- Is the range's upper bound inclusive?
-
-
- upper_inc(numrange(1.1,2.2))
- f
-
-
-
-
-
-
- lower_inf
-
- lower_inf ( anyrange )
- boolean
-
-
- Does the range have no lower bound? (A lower bound of
- -Infinity returns false.)
-
-
- lower_inf('(,)'::daterange)
- t
-
-
-
-
-
-
- upper_inf
-
- upper_inf ( anyrange )
- boolean
-
-
- Does the range have no upper bound? (An upper bound of
- Infinity returns false.)
-
-
- upper_inf('(,)'::daterange)
- t
-
-
-
-
-
-
- range_merge
-
- range_merge ( anyrange, anyrange )
- anyrange
-
-
- Computes the smallest range that includes both of the given ranges.
-
-
- range_merge('[1,2)'::int4range, '[3,4)'::int4range)
- [1,4)
-
-
-
-
-
-
-
- Multirange Functions
-
-
-
-
- Function
-
-
- Description
-
-
- Example(s)
-
-
-
-
-
-
-
- lower
-
- lower ( anymultirange )
- anyelement
-
-
- Extracts the lower bound of the multirange (NULL if the
- multirange is empty has no lower bound).
-
-
- lower('{[1.1,2.2)}'::nummultirange)
- 1.1
-
-
-
-
-
-
- upper
-
- upper ( anymultirange )
- anyelement
-
-
- Extracts the upper bound of the multirange (NULL if the
- multirange is empty or has no upper bound).
-
-
- upper('{[1.1,2.2)}'::nummultirange)
- 2.2
-
-
-
-
-
-
- isempty
-
- isempty ( anymultirange )
- boolean
-
-
- Is the multirange empty?
-
-
- isempty('{[1.1,2.2)}'::nummultirange)
- f
-
-
-
-
-
-
- lower_inc
-
- lower_inc ( anymultirange )
- boolean
-
-
- Is the multirange's lower bound inclusive?
-
-
- lower_inc('{[1.1,2.2)}'::nummultirange)
- t
-
-
-
-
-
-
- upper_inc
-
- upper_inc ( anymultirange )
- boolean
-
-
- Is the multirange's upper bound inclusive?
-
-
- upper_inc('{[1.1,2.2)}'::nummultirange)
- f
-
-
-
-
-
-
- lower_inf
-
- lower_inf ( anymultirange )
- boolean
-
-
- Does the multirange have no lower bound? (A lower bound of
- -Infinity returns false.)
-
-
- lower_inf('{(,)}'::datemultirange)
- t
-
-
-
-
-
-
- upper_inf
-
- upper_inf ( anymultirange )
- boolean
-
-
- Does the multirange have no upper bound? (An upper bound of
- Infinity returns false.)
-
-
- upper_inf('{(,)}'::datemultirange)
- t
-
-
-
-
-
-
- range_merge
-
- range_merge ( anymultirange )
- anyrange
-
-
- Computes the smallest range that includes the entire multirange.
-
-
- range_merge('{[1,2), [3,4)}'::int4multirange)
- [1,4)
-
-
-
-
-
-
- multirange (function)
-
- multirange ( anyrange )
- anymultirange
-
-
- Returns a multirange containing just the given range.
-
-
- multirange('[1,2)'::int4range)
- {[1,2)}
-
-
-
-
-
-
- unnest
- for multirange
-
- unnest ( anymultirange )
- setof anyrange
-
-
- Expands a multirange into a set of ranges in ascending order.
-
-
- unnest('{[1,2), [3,4)}'::int4multirange)
-
-
- [1,2)
- [3,4)
-
-
-
-
-
-
-
-
- The lower_inc, upper_inc,
- lower_inf, and upper_inf
- functions all return false for an empty range or multirange.
-
-
-
-
- Aggregate Functions
-
-
- aggregate function
- built-in
-
-
-
- Aggregate functions compute a single result
- from a set of input values. The built-in general-purpose aggregate
- functions are listed in
- while statistical aggregates are in .
- The built-in within-group ordered-set aggregate functions
- are listed in
- while the built-in within-group hypothetical-set ones are in . Grouping operations,
- which are closely related to aggregate functions, are listed in
- .
- The special syntax considerations for aggregate
- functions are explained in .
- Consult for additional introductory
- information.
-
-
-
- Aggregate functions that support Partial Mode
- are eligible to participate in various optimizations, such as parallel
- aggregation.
-
-
-
- While all aggregates below accept an optional
- ORDER BY clause (as outlined in ), the clause has only been added to
- aggregates whose output is affected by ordering.
-
-
-
- General-Purpose Aggregate Functions
-
-
-
-
-
-
- Function
-
-
- Description
-
- Partial Mode
-
-
-
-
-
-
-
- any_value
-
- any_value ( anyelement )
- same as input type
-
-
- Returns an arbitrary value from the non-null input values.
-
- Yes
-
-
-
-
-
- array_agg
-
- array_agg ( anynonarrayORDER BYinput_sort_columns )
- anyarray
-
-
- Collects all the input values, including nulls, into an array.
-
- Yes
-
-
-
-
- array_agg ( anyarrayORDER BYinput_sort_columns )
- anyarray
-
-
- 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.)
-
- Yes
-
-
-
-
-
- average
-
-
- avg
-
- avg ( smallint )
- numeric
-
-
- avg ( integer )
- numeric
-
-
- avg ( bigint )
- numeric
-
-
- avg ( numeric )
- numeric
-
-
- avg ( real )
- double precision
-
-
- avg ( double precision )
- double precision
-
-
- avg ( interval )
- interval
-
-
- Computes the average (arithmetic mean) of all the non-null input
- values.
-
- Yes
-
-
-
-
-
- bit_and
-
- bit_and ( smallint )
- smallint
-
-
- bit_and ( integer )
- integer
-
-
- bit_and ( bigint )
- bigint
-
-
- bit_and ( bit )
- bit
-
-
- Computes the bitwise AND of all non-null input values.
-
- Yes
-
-
-
-
-
- bit_or
-
- bit_or ( smallint )
- smallint
-
-
- bit_or ( integer )
- integer
-
-
- bit_or ( bigint )
- bigint
-
-
- bit_or ( bit )
- bit
-
-
- Computes the bitwise OR of all non-null input values.
-
- Yes
-
-
-
-
-
- bit_xor
-
- bit_xor ( smallint )
- smallint
-
-
- bit_xor ( integer )
- integer
-
-
- bit_xor ( bigint )
- bigint
-
-
- bit_xor ( bit )
- bit
-
-
- Computes the bitwise exclusive OR of all non-null input values.
- Can be useful as a checksum for an unordered set of values.
-
- Yes
-
-
-
-
-
- bool_and
-
- bool_and ( boolean )
- boolean
-
-
- Returns true if all non-null input values are true, otherwise false.
-
- Yes
-
-
-
-
-
- bool_or
-
- bool_or ( boolean )
- boolean
-
-
- Returns true if any non-null input value is true, otherwise false.
-
- Yes
-
-
-
-
-
- count
-
- count ( * )
- bigint
-
-
- Computes the number of input rows.
-
- Yes
-
-
-
-
- count ( "any" )
- bigint
-
-
- Computes the number of input rows in which the input value is not
- null.
-
- Yes
-
-
-
-
-
- every
-
- every ( boolean )
- boolean
-
-
- This is the SQL standard's equivalent to bool_and.
-
- Yes
-
-
-
-
-
- json_agg
-
- json_agg ( anyelementORDER BYinput_sort_columns )
- json
-
-
-
- jsonb_agg
-
- jsonb_agg ( anyelementORDER BYinput_sort_columns )
- jsonb
-
-
- Collects all the input values, including nulls, into a JSON array.
- Values are converted to JSON as per to_json
- or to_jsonb.
-
- No
-
-
-
-
- json_objectagg
- json_objectagg (
- { key_expression { VALUE | ':' } value_expression }
- { NULL | ABSENT } ON NULL
- { WITH | WITHOUT } UNIQUEKEYS
- RETURNINGdata_typeFORMAT JSONENCODING UTF8)
-
-
- Behaves like json_object, but as an
- aggregate function, so it only takes one
- key_expression and one
- value_expression parameter.
-
-
- SELECT json_objectagg(k:v) FROM (VALUES ('a'::text,current_date),('b',current_date + 1)) AS t(k,v)
- { "a" : "2022-05-10", "b" : "2022-05-11" }
-
- No
-
-
-
-
-
- json_object_agg
-
- json_object_agg ( key
- "any", value
- "any"
- ORDER BYinput_sort_columns )
- json
-
-
-
- jsonb_object_agg
-
- jsonb_object_agg ( key
- "any", value
- "any"
- ORDER BYinput_sort_columns )
- jsonb
-
-
- Collects all the key/value pairs into a JSON object. Key arguments
- are coerced to text; value arguments are converted as per
- to_json or to_jsonb.
- Values can be null, but keys cannot.
-
- No
-
-
-
-
-
- json_object_agg_strict
-
- json_object_agg_strict (
- key"any",
- value"any" )
- json
-
-
-
- jsonb_object_agg_strict
-
- jsonb_object_agg_strict (
- key"any",
- value"any" )
- jsonb
-
-
- Collects all the key/value pairs into a JSON object. Key arguments
- are coerced to text; value arguments are converted as per
- to_json or to_jsonb.
- The key can not be null. If the
- value is null then the entry is skipped,
-
- No
-
-
-
-
-
- json_object_agg_unique
-
- json_object_agg_unique (
- key"any",
- value"any" )
- json
-
-
-
- jsonb_object_agg_unique
-
- jsonb_object_agg_unique (
- key"any",
- value"any" )
- jsonb
-
-
- Collects all the key/value pairs into a JSON object. Key arguments
- are coerced to text; value arguments are converted as per
- to_json or to_jsonb.
- Values can be null, but keys cannot.
- If there is a duplicate key an error is thrown.
-
- No
-
-
-
-
- json_arrayagg
- json_arrayagg (
- value_expression
- ORDER BYsort_expression
- { NULL | ABSENT } ON NULL
- RETURNINGdata_typeFORMAT JSONENCODING UTF8)
-
-
- Behaves in the same way as json_array
- but as an aggregate function so it only takes one
- value_expression parameter.
- If ABSENT ON NULL is specified, any NULL
- values are omitted.
- If ORDER BY is specified, the elements will
- appear in the array in that order rather than in the input order.
-
-
- SELECT json_arrayagg(v) FROM (VALUES(2),(1)) t(v)
- [2, 1]
-
- No
-
-
-
-
-
- json_object_agg_unique_strict
-
- json_object_agg_unique_strict (
- key"any",
- value"any" )
- json
-
-
-
- jsonb_object_agg_unique_strict
-
- jsonb_object_agg_unique_strict (
- key"any",
- value"any" )
- jsonb
-
-
- Collects all the key/value pairs into a JSON object. Key arguments
- are coerced to text; value arguments are converted as per
- to_json or to_jsonb.
- The key can not be null. If the
- value is null then the entry is skipped.
- If there is a duplicate key an error is thrown.
-
- No
-
-
-
-
-
- max
-
- max ( see text )
- same as input type
-
-
- Computes the maximum of the non-null input
- values. Available for any numeric, string, date/time, or enum type,
- as well as inet, interval,
- money, oid, pg_lsn,
- tid, xid8,
- and arrays of any of these types.
-
- Yes
-
-
-
-
-
- min
-
- min ( see text )
- same as input type
-
-
- Computes the minimum of the non-null input
- values. Available for any numeric, string, date/time, or enum type,
- as well as inet, interval,
- money, oid, pg_lsn,
- tid, xid8,
- and arrays of any of these types.
-
- Yes
-
-
-
-
-
- range_agg
-
- range_agg ( value
- anyrange )
- anymultirange
-
-
- range_agg ( value
- anymultirange )
- anymultirange
-
-
- Computes the union of the non-null input values.
-
- No
-
-
-
-
-
- range_intersect_agg
-
- range_intersect_agg ( value
- anyrange )
- anyrange
-
-
- range_intersect_agg ( value
- anymultirange )
- anymultirange
-
-
- Computes the intersection of the non-null input values.
-
- No
-
-
-
-
-
- json_agg_strict
-
- json_agg_strict ( anyelement )
- json
-
-
-
- jsonb_agg_strict
-
- jsonb_agg_strict ( anyelement )
- jsonb
-
-
- Collects all the input values, skipping nulls, into a JSON array.
- Values are converted to JSON as per to_json
- or to_jsonb.
-
- No
-
-
-
-
-
- string_agg
-
- string_agg ( value
- text, delimitertext )
- text
-
-
- string_agg ( value
- bytea, delimiterbytea
- ORDER BYinput_sort_columns )
- bytea
-
-
- Concatenates the non-null input values into a string. Each value
- after the first is preceded by the
- corresponding delimiter (if it's not null).
-
- Yes
-
-
-
-
-
- sum
-
- sum ( smallint )
- bigint
-
-
- sum ( integer )
- bigint
-
-
- sum ( bigint )
- numeric
-
-
- sum ( numeric )
- numeric
-
-
- sum ( real )
- real
-
-
- sum ( double precision )
- double precision
-
-
- sum ( interval )
- interval
-
-
- sum ( money )
- money
-
-
- Computes the sum of the non-null input values.
-
- Yes
-
-
-
-
-
- xmlagg
-
- xmlagg ( xmlORDER BYinput_sort_columns )
- xml
-
-
- Concatenates the non-null XML input values (see
- ).
-
- No
-
-
-
-
-
-
- It should be noted that except for count,
- these functions return a null value when no rows are selected. In
- particular, sum of no rows returns null, not
- zero as one might expect, and array_agg
- returns null rather than an empty array when there are no input
- rows. The coalesce function can be used to
- substitute zero or an empty array for null when necessary.
-
-
-
- The aggregate functions array_agg,
- json_agg, jsonb_agg,
- json_agg_strict, jsonb_agg_strict,
- json_object_agg, jsonb_object_agg,
- json_object_agg_strict, jsonb_object_agg_strict,
- json_object_agg_unique, jsonb_object_agg_unique,
- json_object_agg_unique_strict,
- jsonb_object_agg_unique_strict,
- string_agg,
- and xmlagg, 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
- ORDER BY clause within the aggregate call, as shown in
- .
- Alternatively, supplying the input values from a sorted subquery
- will usually work. For example:
-
-
-
- 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.
-
-
-
-
- ANY
-
-
- SOME
-
-
- The boolean aggregates bool_and and
- bool_or correspond to the standard SQL aggregates
- every and any or
- some.
- PostgreSQL
- supports every, but not any
- or some, because there is an ambiguity built into
- the standard syntax:
-
-SELECT b1 = ANY((SELECT b2 FROM t2 ...)) FROM t1 ...;
-
- Here ANY 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.
-
-
-
-
-
- Users accustomed to working with other SQL database management
- systems might be disappointed by the performance of the
- count aggregate when it is applied to the
- entire table. A query like:
-
-SELECT count(*) FROM sometable;
-
- will require effort proportional to the size of the table:
- PostgreSQL will need to scan either the
- entire table or the entirety of an index that includes all rows in
- the table.
-
-
-
-
- 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 numeric_type are available for all
- the types smallint, integer,
- bigint, numeric, real,
- and double precision.
- Where the description mentions
- N, 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 N is zero.
-
-
-
- statistics
-
-
- linear regression
-
-
-
- Aggregate Functions for Statistics
-
-
-
-
-
-
- Function
-
-
- Description
-
- Partial Mode
-
-
-
-
-
-
-
- correlation
-
-
- corr
-
- corr ( Ydouble precision, Xdouble precision )
- double precision
-
-
- Computes the correlation coefficient.
-
- Yes
-
-
-
-
-
- covariance
- population
-
-
- covar_pop
-
- covar_pop ( Ydouble precision, Xdouble precision )
- double precision
-
-
- Computes the population covariance.
-
- Yes
-
-
-
-
-
- covariance
- sample
-
-
- covar_samp
-
- covar_samp ( Ydouble precision, Xdouble precision )
- double precision
-
-
- Computes the sample covariance.
-
- Yes
-
-
-
-
-
- regr_avgx
-
- regr_avgx ( Ydouble precision, Xdouble precision )
- double precision
-
-
- Computes the average of the independent variable,
- sum(X)/N.
-
- Yes
-
-
-
-
-
- regr_avgy
-
- regr_avgy ( Ydouble precision, Xdouble precision )
- double precision
-
-
- Computes the average of the dependent variable,
- sum(Y)/N.
-
- Yes
-
-
-
-
-
- regr_count
-
- regr_count ( Ydouble precision, Xdouble precision )
- bigint
-
-
- Computes the number of rows in which both inputs are non-null.
-
- Yes
-
-
-
-
-
- regression intercept
-
-
- regr_intercept
-
- regr_intercept ( Ydouble precision, Xdouble precision )
- double precision
-
-
- Computes the y-intercept of the least-squares-fit linear equation
- determined by the
- (X, Y) pairs.
-
- Yes
-
-
-
-
-
- regr_r2
-
- regr_r2 ( Ydouble precision, Xdouble precision )
- double precision
-
-
- Computes the square of the correlation coefficient.
-
- Yes
-
-
-
-
-
- regression slope
-
-
- regr_slope
-
- regr_slope ( Ydouble precision, Xdouble precision )
- double precision
-
-
- Computes the slope of the least-squares-fit linear equation determined
- by the (X, Y)
- pairs.
-
- Yes
-
-
-
-
-
- regr_sxx
-
- regr_sxx ( Ydouble precision, Xdouble precision )
- double precision
-
-
- Computes the sum of squares of the independent
- variable,
- sum(X^2) - sum(X)^2/N.
-
- Yes
-
-
-
-
-
- regr_sxy
-
- regr_sxy ( Ydouble precision, Xdouble precision )
- double precision
-
-
- Computes the sum of products of independent times
- dependent variables,
- sum(X*Y) - sum(X) * sum(Y)/N.
-
- Yes
-
-
-
-
-
- regr_syy
-
- regr_syy ( Ydouble precision, Xdouble precision )
- double precision
-
-
- Computes the sum of squares of the dependent
- variable,
- sum(Y^2) - sum(Y)^2/N.
-
- Yes
-
-
-
-
-
- standard deviation
-
-
- stddev
-
- stddev ( numeric_type )
- double precision
- for real or double precision,
- otherwise numeric
-
-
- This is a historical alias for stddev_samp.
-
- Yes
-
-
-
-
-
- standard deviation
- population
-
-
- stddev_pop
-
- stddev_pop ( numeric_type )
- double precision
- for real or double precision,
- otherwise numeric
-
-
- Computes the population standard deviation of the input values.
-
- Yes
-
-
-
-
-
- standard deviation
- sample
-
-
- stddev_samp
-
- stddev_samp ( numeric_type )
- double precision
- for real or double precision,
- otherwise numeric
-
-
- Computes the sample standard deviation of the input values.
-
- Yes
-
-
-
-
-
- variance
-
- variance ( numeric_type )
- double precision
- for real or double precision,
- otherwise numeric
-
-
- This is a historical alias for var_samp.
-
- Yes
-
-
-
-
-
- variance
- population
-
-
- var_pop
-
- var_pop ( numeric_type )
- double precision
- for real or double precision,
- otherwise numeric
-
-
- Computes the population variance of the input values (square of the
- population standard deviation).
-
- Yes
-
-
-
-
-
- variance
- sample
-
-
- var_samp
-
- var_samp ( numeric_type )
- double precision
- for real or double precision,
- otherwise numeric
-
-
- Computes the sample variance of the input values (square of the sample
- standard deviation).
-
- Yes
-
-
-
-
-
-
- shows some
- aggregate functions that use the ordered-set aggregate
- syntax. These functions are sometimes referred to as inverse
- distribution functions. Their aggregated input is introduced by
- ORDER BY, and they may also take a direct
- argument that is not aggregated, but is computed only once.
- All these functions ignore null values in their aggregated input.
- For those that take a fraction parameter, the
- fraction value must be between 0 and 1; an error is thrown if not.
- However, a null fraction value simply produces a
- null result.
-
-
-
- ordered-set aggregate
- built-in
-
-
- inverse distribution
-
-
-
- Ordered-Set Aggregate Functions
-
-
-
-
-
-
- Function
-
-
- Description
-
- Partial Mode
-
-
-
-
-
-
-
- mode
- statistical
-
- mode () WITHIN GROUP ( ORDER BYanyelement )
- anyelement
-
-
- Computes the mode, 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.
-
- No
-
-
-
-
-
- percentile
- continuous
-
- percentile_cont ( fractiondouble precision ) WITHIN GROUP ( ORDER BYdouble precision )
- double precision
-
-
- percentile_cont ( fractiondouble precision ) WITHIN GROUP ( ORDER BYinterval )
- interval
-
-
- Computes the continuous percentile, a value
- corresponding to the specified fraction
- within the ordered set of aggregated argument values. This will
- interpolate between adjacent input items if needed.
-
- No
-
-
-
-
- percentile_cont ( fractionsdouble precision[] ) WITHIN GROUP ( ORDER BYdouble precision )
- double precision[]
-
-
- percentile_cont ( fractionsdouble precision[] ) WITHIN GROUP ( ORDER BYinterval )
- interval[]
-
-
- Computes multiple continuous percentiles. The result is an array of
- the same dimensions as the fractions
- parameter, with each non-null element replaced by the (possibly
- interpolated) value corresponding to that percentile.
-
- No
-
-
-
-
-
- percentile
- discrete
-
- percentile_disc ( fractiondouble precision ) WITHIN GROUP ( ORDER BYanyelement )
- anyelement
-
-
- Computes the discrete percentile, the first
- value within the ordered set of aggregated argument values whose
- position in the ordering equals or exceeds the
- specified fraction. The aggregated
- argument must be of a sortable type.
-
- No
-
-
-
-
- percentile_disc ( fractionsdouble precision[] ) WITHIN GROUP ( ORDER BYanyelement )
- anyarray
-
-
- Computes multiple discrete percentiles. The result is an array of the
- same dimensions as the fractions parameter,
- with each non-null element replaced by the input value corresponding
- to that percentile.
- The aggregated argument must be of a sortable type.
-
- No
-
-
-
-
-
-
- hypothetical-set aggregate
- built-in
-
-
-
- Each of the hypothetical-set aggregates listed in
- is associated with a
- window function of the same name defined in
- . In each case, the aggregate's result
- is the value that the associated window function would have
- returned for the hypothetical row constructed from
- args, if such a row had been added to the sorted
- group of rows represented by the sorted_args.
- For each of these functions, the list of direct arguments
- given in args must match the number and types of
- the aggregated arguments given in sorted_args.
- 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 ORDER BY clause.
-
-
-
- Hypothetical-Set Aggregate Functions
-
-
-
-
-
-
- Function
-
-
- Description
-
- Partial Mode
-
-
-
-
-
-
-
- rank
- hypothetical
-
- rank ( args ) WITHIN GROUP ( ORDER BYsorted_args )
- bigint
-
-
- Computes the rank of the hypothetical row, with gaps; that is, the row
- number of the first row in its peer group.
-
- No
-
-
-
-
-
- dense_rank
- hypothetical
-
- dense_rank ( args ) WITHIN GROUP ( ORDER BYsorted_args )
- bigint
-
-
- Computes the rank of the hypothetical row, without gaps; this function
- effectively counts peer groups.
-
- No
-
-
-
-
-
- percent_rank
- hypothetical
-
- percent_rank ( args ) WITHIN GROUP ( ORDER BYsorted_args )
- double precision
-
-
- Computes the relative rank of the hypothetical row, that is
- (rank - 1) / (total rows - 1).
- The value thus ranges from 0 to 1 inclusive.
-
- No
-
-
-
-
-
- cume_dist
- hypothetical
-
- cume_dist ( args ) WITHIN GROUP ( ORDER BYsorted_args )
- double precision
-
-
- Computes the cumulative distribution, that is (number of rows
- preceding or peers with hypothetical row) / (total rows). The value
- thus ranges from 1/N to 1.
-
- No
-
-
-
-
-
-
- Grouping Operations
-
-
-
-
- Function
-
-
- Description
-
-
-
-
-
-
-
-
- GROUPING
-
- GROUPING ( group_by_expression(s) )
- integer
-
-
- Returns a bit mask indicating which GROUP BY
- 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.
-
-
-
-
-
-
-
- The grouping operations shown in
- are used in conjunction with
- grouping sets (see ) to distinguish
- result rows. The arguments to the GROUPING function
- are not actually evaluated, but they must exactly match expressions given
- in the GROUP BY clause of the associated query level.
- For example:
-
-=>SELECT * FROM items_sold;
- make | model | sales
--------+-------+-------
- Foo | GT | 10
- Foo | Tour | 20
- Bar | City | 15
- Bar | Sport | 5
-(4 rows)
-
-=>SELECT make, model, GROUPING(make,model), sum(sales) FROM items_sold GROUP BY ROLLUP(make,model);
- 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)
-
- Here, the grouping value 0 in the
- first four rows shows that those have been grouped normally, over both the
- grouping columns. The value 1 indicates
- that model was not grouped by in the next-to-last two
- rows, and the value 3 indicates that
- neither make nor model was grouped
- by in the last row (which therefore is an aggregate over all the input
- rows).
-
-
-
-
-
- Window Functions
-
-
- window function
- built-in
-
-
-
- Window functions provide the ability to perform
- calculations across sets of rows that are related to the current query
- row. See for an introduction to this
- feature, and for syntax
- details.
-
-
-
- The built-in window functions are listed in
- . Note that these functions
- must be invoked using window function syntax, i.e., an
- OVER clause is required.
-
-
-
- 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
- for a list of the built-in aggregates.
- Aggregate functions act as window functions only when an OVER
- clause follows the call; otherwise they act as plain aggregates
- and return a single row for the entire set.
-
-
-
- General-Purpose Window Functions
-
-
-
-
- Function
-
-
- Description
-
-
-
-
-
-
-
-
- row_number
-
- row_number ()
- bigint
-
-
- Returns the number of the current row within its partition, counting
- from 1.
-
-
-
-
-
-
- rank
-
- rank ()
- bigint
-
-
- Returns the rank of the current row, with gaps; that is,
- the row_number of the first row in its peer
- group.
-
-
-
-
-
-
- dense_rank
-
- dense_rank ()
- bigint
-
-
- Returns the rank of the current row, without gaps; this function
- effectively counts peer groups.
-
-
-
-
-
-
- percent_rank
-
- percent_rank ()
- double precision
-
-
- Returns the relative rank of the current row, that is
- (rank - 1) / (total partition rows - 1).
- The value thus ranges from 0 to 1 inclusive.
-
-
-
-
-
-
- cume_dist
-
- cume_dist ()
- double precision
-
-
- 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/N to 1.
-
-
-
-
-
-
- ntile
-
- ntile ( num_bucketsinteger )
- integer
-
-
- Returns an integer ranging from 1 to the argument value, dividing the
- partition as equally as possible.
-
-
-
-
-
-
- lag
-
- lag ( valueanycompatible
- , offsetinteger
- , defaultanycompatible )
- anycompatible
-
-
- Returns value evaluated at
- the row that is offset
- rows before the current row within the partition; if there is no such
- row, instead returns default
- (which must be of a type compatible with
- value).
- Both offset and
- default are evaluated
- with respect to the current row. If omitted,
- offset defaults to 1 and
- default to NULL.
-
-
-
-
-
-
- lead
-
- lead ( valueanycompatible
- , offsetinteger
- , defaultanycompatible )
- anycompatible
-
-
- Returns value evaluated at
- the row that is offset
- rows after the current row within the partition; if there is no such
- row, instead returns default
- (which must be of a type compatible with
- value).
- Both offset and
- default are evaluated
- with respect to the current row. If omitted,
- offset defaults to 1 and
- default to NULL.
-
-
-
-
-
-
- first_value
-
- first_value ( valueanyelement )
- anyelement
-
-
- Returns value evaluated
- at the row that is the first row of the window frame.
-
-
-
-
-
-
- last_value
-
- last_value ( valueanyelement )
- anyelement
-
-
- Returns value evaluated
- at the row that is the last row of the window frame.
-
-
-
-
-
-
- nth_value
-
- nth_value ( valueanyelement, ninteger )
- anyelement
-
-
- Returns value evaluated
- at the row that is the n'th
- row of the window frame (counting from 1);
- returns NULL if there is no such row.
-
-
-
-
-
-
-
- All of the functions listed in
- depend on the sort ordering
- specified by the ORDER BY clause of the associated window
- definition. Rows that are not distinct when considering only the
- ORDER BY columns are said to be peers.
- The four ranking functions (including cume_dist) are
- defined so that they give the same answer for all rows of a peer group.
-
-
-
- Note that first_value, last_value, and
- nth_value consider only the rows within the window
- frame, 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 last_value and
- sometimes also nth_value. You can redefine the frame by
- adding a suitable frame specification (RANGE,
- ROWS or GROUPS) to
- the OVER clause.
- See for more information
- about frame specifications.
-
-
-
- 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 ORDER BY and the default window frame
- definition produces a running sum type of behavior, which may or
- may not be what's wanted. To obtain
- aggregation over the whole partition, omit ORDER BY or use
- ROWS BETWEEN UNBOUNDED PRECEDING AND UNBOUNDED FOLLOWING.
- Other frame specifications can be used to obtain other effects.
-
-
-
-
- The SQL standard defines a RESPECT NULLS or
- IGNORE NULLS option for lead, lag,
- first_value, last_value, and
- nth_value. This is not implemented in
- PostgreSQL: the behavior is always the
- same as the standard's default, namely RESPECT NULLS.
- Likewise, the standard's FROM FIRST or FROM LAST
- option for nth_value is not implemented: only the
- default FROM FIRST behavior is supported. (You can achieve
- the result of FROM LAST by reversing the ORDER BY
- ordering.)
-
-
-
-
-
-
- Merge Support Functions
-
-
- MERGE
- RETURNING
-
-
-
- PostgreSQL includes one merge support function
- that may be used in the RETURNING list of a
- command to identify the action taken for each
- row; see .
-
-
-
- Merge Support Functions
-
-
-
-
-
- Function
-
-
- Description
-
-
-
-
-
-
-
-
- merge_action
-
- merge_action ( )
- text
-
-
- Returns the merge action command executed for the current row. This
- will be 'INSERT', 'UPDATE', or
- 'DELETE'.
-
-
-
-
-
-
-
- Example:
- 0 THEN
- UPDATE SET in_stock = true, quantity = s.quantity
- WHEN MATCHED THEN
- UPDATE SET in_stock = false, quantity = 0
- WHEN NOT MATCHED THEN
- INSERT (product_id, in_stock, quantity)
- VALUES (s.product_id, true, s.quantity)
- RETURNING merge_action(), p.*;
-
- merge_action | product_id | in_stock | quantity
---------------+------------+----------+----------
- UPDATE | 1001 | t | 50
- UPDATE | 1002 | f | 0
- INSERT | 1003 | t | 10
-]]>
-
-
-
- Note that this function can only be used in the RETURNING
- list of a MERGE command. It is an error to use it in any
- other part of a query.
-
-
-
-
-
- Subquery Expressions
-
-
- EXISTS
-
-
-
- IN
-
-
-
- NOT IN
-
-
-
- ANY
-
-
-
- ALL
-
-
-
- SOME
-
-
-
- subquery
-
-
-
- This section describes the SQL-compliant subquery
- expressions available in PostgreSQL.
- All of the expression forms documented in this section return
- Boolean (true/false) results.
-
-
-
- <literal>EXISTS</literal>
-
-
-EXISTS (subquery)
-
-
-
- The argument of EXISTS is an arbitrary SELECT statement,
- or subquery. The
- subquery is evaluated to determine whether it returns any rows.
- If it returns at least one row, the result of EXISTS is
- true; if the subquery returns no rows, the result of EXISTS
- is false.
-
-
-
- The subquery can refer to variables from the surrounding query,
- which will act as constants during any one evaluation of the subquery.
-
-
-
- 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.
-
-
-
- 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 EXISTS tests in the form
- EXISTS(SELECT 1 WHERE ...). There are exceptions to
- this rule however, such as subqueries that use INTERSECT.
-
-
-
- This simple example is like an inner join on col2, but
- it produces at most one output row for each tab1 row,
- even if there are several matching tab2 rows:
-
-SELECT col1
-FROM tab1
-WHERE EXISTS (SELECT 1 FROM tab2 WHERE col2 = tab1.col2);
-
-
-
-
-
- <literal>IN</literal>
-
-
-expression IN (subquery)
-
-
-
- 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 IN is true if any equal subquery row is found.
- The result is false if no equal row is found (including the
- case where the subquery returns no rows).
-
-
-
- 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 IN construct will be null, not false.
- This is in accordance with SQL's normal rules for Boolean combinations
- of null values.
-
-
-
- As with EXISTS, it's unwise to assume that the subquery will
- be evaluated completely.
-
-
-
-row_constructor IN (subquery)
-
-
-
- The left-hand side of this form of IN is a row constructor,
- as described in .
- The right-hand side is a parenthesized
- subquery, which must return exactly as many columns as there are
- expressions in the left-hand row. The left-hand expressions are
- evaluated and compared row-wise to each row of the subquery result.
- The result of IN is true if any equal subquery row is found.
- The result is false if no equal row is found (including the
- case where the subquery returns no rows).
-
-
-
- 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 IN is null.
-
-
-
-
- <literal>NOT IN</literal>
-
-
-expression NOT IN (subquery)
-
-
-
- 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 NOT IN is true if only unequal subquery rows
- are found (including the case where the subquery returns no rows).
- The result is false if any equal row is found.
-
-
-
- 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 NOT IN construct will be null, not true.
- This is in accordance with SQL's normal rules for Boolean combinations
- of null values.
-
-
-
- As with EXISTS, it's unwise to assume that the subquery will
- be evaluated completely.
-
-
-
-row_constructor NOT IN (subquery)
-
-
-
- The left-hand side of this form of NOT IN is a row constructor,
- as described in .
- The right-hand side is a parenthesized
- subquery, which must return exactly as many columns as there are
- expressions in the left-hand row. The left-hand expressions are
- evaluated and compared row-wise to each row of the subquery result.
- The result of NOT IN is true if only unequal subquery rows
- are found (including the case where the subquery returns no rows).
- The result is false if any equal row is found.
-
-
-
- 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 NOT IN is null.
-
-
-
-
- <literal>ANY</literal>/<literal>SOME</literal>
-
-
-expressionoperator ANY (subquery)
-expressionoperator SOME (subquery)
-
-
-
- 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 operator, which must yield a Boolean
- result.
- The result of ANY is true if any true result is obtained.
- The result is false if no true result is found (including the
- case where the subquery returns no rows).
-
-
-
- SOME is a synonym for ANY.
- IN is equivalent to = ANY.
-
-
-
- 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 ANY construct
- will be null, not false.
- This is in accordance with SQL's normal rules for Boolean combinations
- of null values.
-
-
-
- As with EXISTS, it's unwise to assume that the subquery will
- be evaluated completely.
-
-
-
-row_constructoroperator ANY (subquery)
-row_constructoroperator SOME (subquery)
-
-
-
- The left-hand side of this form of ANY is a row constructor,
- as described in .
- The right-hand side is a parenthesized
- subquery, which must return exactly as many columns as there are
- expressions in the left-hand row. The left-hand expressions are
- evaluated and compared row-wise to each row of the subquery result,
- using the given operator.
- The result of ANY is true if the comparison
- returns true for any subquery row.
- The result is false 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.
-
-
-
- See for details about the meaning
- of a row constructor comparison.
-
-
-
-
- <literal>ALL</literal>
-
-
-expressionoperator ALL (subquery)
-
-
-
- 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 operator, which must yield a Boolean
- result.
- The result of ALL is true if all rows yield true
- (including the case where the subquery returns no rows).
- The result is false 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.
-
-
-
- NOT IN is equivalent to <> ALL.
-
-
-
- As with EXISTS, it's unwise to assume that the subquery will
- be evaluated completely.
-
-
-
-row_constructoroperator ALL (subquery)
-
-
-
- The left-hand side of this form of ALL is a row constructor,
- as described in .
- The right-hand side is a parenthesized
- subquery, which must return exactly as many columns as there are
- expressions in the left-hand row. The left-hand expressions are
- evaluated and compared row-wise to each row of the subquery result,
- using the given operator.
- The result of ALL is true if the comparison
- returns true for all subquery rows (including the
- case where the subquery returns no rows).
- The result is false 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.
-
-
-
- See for details about the meaning
- of a row constructor comparison.
-
-
-
-
- Single-Row Comparison
-
-
- comparison
- subquery result row
-
-
-
-row_constructoroperator (subquery)
-
-
-
- The left-hand side is a row constructor,
- as described in .
- The right-hand side is a parenthesized subquery, which must return exactly
- as many columns as there are expressions in the left-hand row. Furthermore,
- the subquery cannot return more than one row. (If it returns zero rows,
- the result is taken to be null.) The left-hand side is evaluated and
- compared row-wise to the single subquery result row.
-
-
-
- See for details about the meaning
- of a row constructor comparison.
-
-
-
-
-
-
- Row and Array Comparisons
-
-
- IN
-
-
-
- NOT IN
-
-
-
- ANY
-
-
-
- ALL
-
-
-
- SOME
-
-
-
- composite type
- comparison
-
-
-
- row-wise comparison
-
-
-
- comparison
- composite type
-
-
-
- comparison
- row constructor
-
-
-
- IS DISTINCT FROM
-
-
-
- IS NOT DISTINCT FROM
-
-
-
- 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
- PostgreSQL extensions; the rest are
- SQL-compliant.
- All of the expression forms documented in this section return
- Boolean (true/false) results.
-
-
-
- <literal>IN</literal>
-
-
-expression IN (value, ...)
-
-
-
- The right-hand side is a parenthesized list
- of expressions. The result is true if the left-hand expression's
- result is equal to any of the right-hand expressions. This is a shorthand
- notation for
-
-
-expression = value1
-OR
-expression = value2
-OR
-...
-
-
-
-
- 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 IN construct will be null, not false.
- This is in accordance with SQL's normal rules for Boolean combinations
- of null values.
-
-
-
-
- <literal>NOT IN</literal>
-
-
-expression NOT IN (value, ...)
-
-
-
- The right-hand side is a parenthesized list
- of expressions. The result is true if the left-hand expression's
- result is unequal to all of the right-hand expressions. This is a shorthand
- notation for
-
-
-expression <> value1
-AND
-expression <> value2
-AND
-...
-
-
-
-
- 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 NOT IN 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.
-
-
-
-
- x NOT IN y is equivalent to NOT (x IN y) in all
- cases. However, null values are much more likely to trip up the novice when
- working with NOT IN than when working with IN.
- It is best to express your condition positively if possible.
-
-
-
-
-
- <literal>ANY</literal>/<literal>SOME</literal> (array)
-
-
-expressionoperator ANY (array expression)
-expressionoperator SOME (array expression)
-
-
-
- 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 operator, which must yield a Boolean
- result.
- The result of ANY is true if any true result is obtained.
- The result is false if no true result is found (including the
- case where the array has zero elements).
-
-
-
- If the array expression yields a null array, the result of
- ANY will be null. If the left-hand expression yields null,
- the result of ANY 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 ANY
- 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.
-
-
-
- SOME is a synonym for ANY.
-
-
-
-
- <literal>ALL</literal> (array)
-
-
-expressionoperator ALL (array expression)
-
-
-
- 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 operator, which must yield a Boolean
- result.
- The result of ALL is true if all comparisons yield true
- (including the case where the array has zero elements).
- The result is false if any false result is found.
-
-
-
- If the array expression yields a null array, the result of
- ALL will be null. If the left-hand expression yields null,
- the result of ALL 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 ALL
- 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.
-
-
-
-
- Row Constructor Comparison
-
-
-row_constructoroperatorrow_constructor
-
-
-
- Each side is a row constructor,
- as described in .
- The two row constructors must have the same number of fields.
- The given operator 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 = member of a B-tree
- operator class, meaning that row constructor comparison is only
- possible when the operator is
- =,
- <>,
- <,
- <=,
- >, or
- >=,
- or has semantics similar to one of these.
-
-
-
- The = and <> 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).
-
-
-
- For the <, <=, > and
- >= 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,
- ROW(1,2,NULL) < ROW(1,3,0)
- yields true, not null, because the third pair of elements are not
- considered.
-
-
-
-row_constructor IS DISTINCT FROM row_constructor
-
-
-
- This construct is similar to a <> 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.
-
-
-
-row_constructor IS NOT DISTINCT FROM row_constructor
-
-
-
- This construct is similar to a = 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.
-
-
-
-
-
- Composite Type Comparison
-
-
-recordoperatorrecord
-
-
-
- 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.
- PostgreSQL does this only when comparing the
- results of two row constructors (as in
- ) or comparing a row constructor
- to the output of a subquery (as in ).
- 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.
-
-
-
- Each side is evaluated and they are compared row-wise. Composite type
- comparisons are allowed when the operator is
- =,
- <>,
- <,
- <=,
- > or
- >=,
- 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 = member of a B-tree operator
- class.) The default behavior of the above operators is the same as for
- IS [ NOT ] DISTINCT FROM for row constructors (see
- ).
-
-
-
- To support matching of rows which include elements without a default
- B-tree operator class, the following operators are defined for composite
- type comparison:
- *=,
- *<>,
- *<,
- *<=,
- *>, and
- *>=.
- 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 ). They are not intended to be
- generally useful for writing queries, though.
-
-
-
-
-
- Set Returning Functions
-
-
- set returning functions
- functions
-
-
-
- This section describes functions that possibly return more than one row.
- The most widely used functions in this class are series generating
- functions, as detailed in and
- . Other, more specialized
- set-returning functions are described elsewhere in this manual.
- See for ways to combine multiple
- set-returning functions.
-
-
-
- Series Generating Functions
-
-
-
-
- Function
-
-
- Description
-
-
-
-
-
-
-
-
- generate_series
-
- generate_series ( startinteger, stopinteger, stepinteger )
- setof integer
-
-
- generate_series ( startbigint, stopbigint, stepbigint )
- setof bigint
-
-
- generate_series ( startnumeric, stopnumeric, stepnumeric )
- setof numeric
-
-
- Generates a series of values from start
- to stop, with a step size
- of step. step
- defaults to 1.
-
-
-
-
-
- generate_series ( starttimestamp, stoptimestamp, stepinterval )
- setof timestamp
-
-
- generate_series ( starttimestamp with time zone, stoptimestamp with time zone, stepinterval, timezonetext )
- setof timestamp with time zone
-
-
- Generates a series of values from start
- to stop, with a step size
- of step.
- In the timezone-aware form, times of day and daylight-savings
- adjustments are computed according to the time zone named by
- the timezone argument, or the current
- setting if that is omitted.
-
-
-
-
-
-
-
- When step is positive, zero rows are returned if
- start is greater than stop.
- Conversely, when step is negative, zero rows are
- returned if start is less than stop.
- Zero rows are also returned if any input is NULL.
- It is an error
- for step to be zero. Some examples follow:
-
-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)
-
--- this example assumes that TimeZone is set to UTC; note the DST transition:
-SELECT * FROM generate_series('2001-10-22 00:00 -04:00'::timestamptz,
- '2001-11-01 00:00 -05:00'::timestamptz,
- '1 day'::interval, 'America/New_York');
- generate_series
-------------------------
- 2001-10-22 04:00:00+00
- 2001-10-23 04:00:00+00
- 2001-10-24 04:00:00+00
- 2001-10-25 04:00:00+00
- 2001-10-26 04:00:00+00
- 2001-10-27 04:00:00+00
- 2001-10-28 04:00:00+00
- 2001-10-29 05:00:00+00
- 2001-10-30 05:00:00+00
- 2001-10-31 05:00:00+00
- 2001-11-01 05:00:00+00
-(11 rows)
-
-
-
-
- Subscript Generating Functions
-
-
-
-
- Function
-
-
- Description
-
-
-
-
-
-
-
-
- generate_subscripts
-
- generate_subscripts ( arrayanyarray, diminteger )
- setof integer
-
-
- Generates a series comprising the valid subscripts of
- the dim'th dimension of the given array.
-
-
-
-
-
- generate_subscripts ( arrayanyarray, diminteger, reverseboolean )
- setof integer
-
-
- Generates a series comprising the valid subscripts of
- the dim'th dimension of the given array.
- When reverse is true, returns the series in
- reverse order.
-
-
-
-
-
-
-
- generate_subscripts 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 NULL.
- Some examples follow:
-
--- 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)
-
-
-
-
- ordinality
-
-
-
- When a function in the FROM clause is suffixed
- by WITH ORDINALITY, a bigint 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 unnest().
-
-
--- 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)
-
-
-
-
-
-
- System Information Functions and Operators
-
-
- The functions described in this section are used to obtain various
- information about a PostgreSQL installation.
-
-
-
- Session Information Functions
-
-
- shows several
- functions that extract session and system information.
-
-
-
- In addition to the functions listed in this section, there are a number of
- functions related to the statistics system that also provide system
- information. See for more
- information.
-
-
-
- Session Information Functions
-
-
-
-
- Function
-
-
- Description
-
-
-
-
-
-
-
-
- current_catalog
-
- current_catalog
- name
-
-
-
- current_database
-
- current_database ()
- name
-
-
- Returns the name of the current database. (Databases are
- called catalogs in the SQL standard,
- so current_catalog is the standard's
- spelling.)
-
-
-
-
-
-
- current_query
-
- current_query ()
- text
-
-
- Returns the text of the currently executing query, as submitted
- by the client (which might contain more than one statement).
-
-
-
-
-
-
- current_role
-
- current_role
- name
-
-
- This is equivalent to current_user.
-
-
-
-
-
-
- current_schema
-
-
- schema
- current
-
- current_schema
- name
-
-
- current_schema ()
- name
-
-
- 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.
-
-
-
-
-
-
- current_schemas
-
-
- search path
- current
-
- current_schemas ( include_implicitboolean )
- name[]
-
-
- Returns an array of the names of all schemas presently in the
- effective search path, in their priority order. (Items in the current
- setting that do not correspond to
- existing, searchable schemas are omitted.) If the Boolean argument
- is true, then implicitly-searched system schemas
- such as pg_catalog are included in the result.
-
-
-
-
-
-
- current_user
-
-
- user
- current
-
- current_user
- name
-
-
- Returns the user name of the current execution context.
-
-
-
-
-
-
- inet_client_addr
-
- inet_client_addr ()
- inet
-
-
- Returns the IP address of the current client,
- or NULL if the current connection is via a
- Unix-domain socket.
-
-
-
-
-
-
- inet_client_port
-
- inet_client_port ()
- integer
-
-
- Returns the IP port number of the current client,
- or NULL if the current connection is via a
- Unix-domain socket.
-
-
-
-
-
-
- inet_server_addr
-
- inet_server_addr ()
- inet
-
-
- Returns the IP address on which the server accepted the current
- connection,
- or NULL if the current connection is via a
- Unix-domain socket.
-
-
-
-
-
-
- inet_server_port
-
- inet_server_port ()
- integer
-
-
- Returns the IP port number on which the server accepted the current
- connection,
- or NULL if the current connection is via a
- Unix-domain socket.
-
-
-
-
-
-
- pg_backend_pid
-
- pg_backend_pid ()
- integer
-
-
- Returns the process ID of the server process attached to the current
- session.
-
-
-
-
-
-
- pg_blocking_pids
-
- pg_blocking_pids ( integer )
- integer[]
-
-
- 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.
-
-
- 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, pg_backend_pid 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.
-
-
- 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.
-
-
-
-
-
-
- pg_conf_load_time
-
- pg_conf_load_time ()
- timestamp with time zone
-
-
- 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.
-
-
-
-
-
-
- pg_current_logfile
-
-
- Logging
- pg_current_logfile function
-
-
- current_logfiles
- and the pg_current_logfile function
-
-
- Logging
- current_logfiles file and the pg_current_logfile
- function
-
- pg_current_logfile ( text )
- text
-
-
- Returns the path name of the log file currently in use by the logging
- collector. The path includes the
- directory and the individual log file name. The result
- is NULL if the logging collector is disabled.
- When multiple log files exist, each in a different
- format, pg_current_logfile without an argument
- returns the path of the file having the first format found in the
- ordered list: stderr,
- csvlog, jsonlog.
- NULL is returned if no log file has any of these
- formats.
- To request information about a specific log file format, supply
- either csvlog, jsonlog or
- stderr as the
- value of the optional parameter. The result is NULL
- if the log format requested is not configured in
- .
- The result reflects the contents of
- the current_logfiles file.
-
-
- This function is restricted to superusers and roles with privileges of
- the pg_monitor role by default, but other users can
- be granted EXECUTE to run the function.
-
-
-
-
-
-
- pg_my_temp_schema
-
- pg_my_temp_schema ()
- oid
-
-
- Returns the OID of the current session's temporary schema, or zero if
- it has none (because it has not created any temporary tables).
-
-
-
-
-
-
- pg_is_other_temp_schema
-
- pg_is_other_temp_schema ( oid )
- boolean
-
-
- 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.)
-
-
-
-
-
-
- pg_jit_available
-
- pg_jit_available ()
- boolean
-
-
- Returns true if a JIT compiler extension is
- available (see ) and the
- configuration parameter is set to
- on.
-
-
-
-
-
-
- pg_listening_channels
-
- pg_listening_channels ()
- setof text
-
-
- Returns the set of names of asynchronous notification channels that
- the current session is listening to.
-
-
-
-
-
-
- pg_notification_queue_usage
-
- pg_notification_queue_usage ()
- double precision
-
-
- 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 and
- for more information.
-
-
-
-
-
-
- pg_postmaster_start_time
-
- pg_postmaster_start_time ()
- timestamp with time zone
-
-
- Returns the time when the server started.
-
-
-
-
-
-
- pg_safe_snapshot_blocking_pids
-
- pg_safe_snapshot_blocking_pids ( integer )
- integer[]
-
-
- 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.
-
-
- A session running a SERIALIZABLE transaction blocks
- a SERIALIZABLE READ ONLY DEFERRABLE transaction
- from acquiring a snapshot until the latter determines that it is safe
- to avoid taking any predicate locks. See
- for more information about
- serializable and deferrable transactions.
-
-
- Frequent calls to this function could have some impact on database
- performance, because it needs access to the predicate lock manager's
- shared state for a short time.
-
-
-
-
-
-
- pg_trigger_depth
-
- pg_trigger_depth ()
- integer
-
-
- Returns the current nesting level
- of PostgreSQL triggers (0 if not called,
- directly or indirectly, from inside a trigger).
-
-
-
-
-
-
- session_user
-
- session_user
- name
-
-
- Returns the session user's name.
-
-
-
-
-
-
- system_user
-
- system_user
- text
-
-
- Returns the authentication method and the identity (if any) that the
- user presented during the authentication cycle before they were
- assigned a database role. It is represented as
- auth_method:identity or
- NULL if the user has not been authenticated (for
- example if Trust authentication has
- been used).
-
-
-
-
-
-
- user
-
- user
- name
-
-
- This is equivalent to current_user.
-
-
-
-
-
-
-
-
- current_catalog,
- current_role,
- current_schema,
- current_user,
- session_user,
- and user have special syntactic status
- in SQL: they must be called without trailing
- parentheses. In PostgreSQL, parentheses can optionally be used with
- current_schema, but not with the others.
-
-
-
-
- The session_user is normally the user who initiated
- the current database connection; but superusers can change this setting
- with .
- The current_user is the user identifier
- that is applicable for permission checking. Normally it is equal
- to the session user, but it can be changed with
- .
- It also changes during the execution of
- functions with the attribute SECURITY DEFINER.
- In Unix parlance, the session user is the real user and
- the current user is the effective user.
- current_role and user are
- synonyms for current_user. (The SQL standard draws
- a distinction between current_role
- and current_user, but PostgreSQL
- does not, since it unifies users and roles into a single kind of entity.)
-
-
-
-
-
- Access Privilege Inquiry Functions
-
-
- privilege
- querying
-
-
-
- lists functions that
- allow querying object access privileges programmatically.
- (See for more information about
- privileges.)
- In these functions, the user whose privileges are being inquired about
- can be specified by name or by OID
- (pg_authid.oid), or if
- the name is given as public then the privileges of the
- PUBLIC pseudo-role are checked. Also, the user
- argument can be omitted entirely, in which case
- the current_user 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., SELECT). Optionally, WITH GRANT
- OPTION 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:
-
-SELECT has_table_privilege('myschema.mytable', 'select');
-SELECT has_table_privilege('joe', 'mytable', 'INSERT, SELECT WITH GRANT OPTION');
-
-
-
-
- Access Privilege Inquiry Functions
-
-
-
-
- Function
-
-
- Description
-
-
-
-
-
-
-
-
- has_any_column_privilege
-
- has_any_column_privilege (
- username or oid,
- tabletext or oid,
- privilegetext )
- boolean
-
-
- 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
- SELECT, INSERT,
- UPDATE, and REFERENCES.
-
-
-
-
-
-
- has_column_privilege
-
- has_column_privilege (
- username or oid,
- tabletext or oid,
- columntext or smallint,
- privilegetext )
- boolean
-
-
- 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
- (pg_attribute.attnum).
- Allowable privilege types are
- SELECT, INSERT,
- UPDATE, and REFERENCES.
-
-
-
-
-
-
- has_database_privilege
-
- has_database_privilege (
- username or oid,
- databasetext or oid,
- privilegetext )
- boolean
-
-
- Does user have privilege for database?
- Allowable privilege types are
- CREATE,
- CONNECT,
- TEMPORARY, and
- TEMP (which is equivalent to
- TEMPORARY).
-
-
-
-
-
-
- has_foreign_data_wrapper_privilege
-
- has_foreign_data_wrapper_privilege (
- username or oid,
- fdwtext or oid,
- privilegetext )
- boolean
-
-
- Does user have privilege for foreign-data wrapper?
- The only allowable privilege type is USAGE.
-
-
-
-
-
-
- has_function_privilege
-
- has_function_privilege (
- username or oid,
- functiontext or oid,
- privilegetext )
- boolean
-
-
- Does user have privilege for function?
- The only allowable privilege type is EXECUTE.
-
-
- When specifying a function by name rather than by OID, the allowed
- input is the same as for the regprocedure data type (see
- ).
- An example is:
-
-SELECT has_function_privilege('joeuser', 'myfunc(int, text)', 'execute');
-
-
-
-
-
-
-
- has_language_privilege
-
- has_language_privilege (
- username or oid,
- languagetext or oid,
- privilegetext )
- boolean
-
-
- Does user have privilege for language?
- The only allowable privilege type is USAGE.
-
-
-
-
-
-
- has_parameter_privilege
-
- has_parameter_privilege (
- username or oid,
- parametertext,
- privilegetext )
- boolean
-
-
- Does user have privilege for configuration parameter?
- The parameter name is case-insensitive.
- Allowable privilege types are SET
- and ALTER SYSTEM.
-
-
-
-
-
-
- has_schema_privilege
-
- has_schema_privilege (
- username or oid,
- schematext or oid,
- privilegetext )
- boolean
-
-
- Does user have privilege for schema?
- Allowable privilege types are
- CREATE and
- USAGE.
-
-
-
-
-
-
- has_sequence_privilege
-
- has_sequence_privilege (
- username or oid,
- sequencetext or oid,
- privilegetext )
- boolean
-
-
- Does user have privilege for sequence?
- Allowable privilege types are
- USAGE,
- SELECT, and
- UPDATE.
-
-
-
-
-
-
- has_server_privilege
-
- has_server_privilege (
- username or oid,
- servertext or oid,
- privilegetext )
- boolean
-
-
- Does user have privilege for foreign server?
- The only allowable privilege type is USAGE.
-
-
-
-
-
-
- has_table_privilege
-
- has_table_privilege (
- username or oid,
- tabletext or oid,
- privilegetext )
- boolean
-
-
- Does user have privilege for table?
- Allowable privilege types
- are SELECT, INSERT,
- UPDATE, DELETE,
- TRUNCATE, REFERENCES,
- TRIGGER, and MAINTAIN.
-
-
-
-
-
-
- has_tablespace_privilege
-
- has_tablespace_privilege (
- username or oid,
- tablespacetext or oid,
- privilegetext )
- boolean
-
-
- Does user have privilege for tablespace?
- The only allowable privilege type is CREATE.
-
-
-
-
-
-
- has_type_privilege
-
- has_type_privilege (
- username or oid,
- typetext or oid,
- privilegetext )
- boolean
-
-
- Does user have privilege for data type?
- The only allowable privilege type is USAGE.
- When specifying a type by name rather than by OID, the allowed input
- is the same as for the regtype data type (see
- ).
-
-
-
-
-
-
- pg_has_role
-
- pg_has_role (
- username or oid,
- roletext or oid,
- privilegetext )
- boolean
-
-
- Does user have privilege for role?
- Allowable privilege types are
- MEMBER, USAGE,
- and SET.
- MEMBER denotes direct or indirect membership in
- the role without regard to what specific privileges may be conferred.
- USAGE denotes whether the privileges of the role
- are immediately available without doing SET ROLE,
- while SET denotes whether it is possible to change
- to the role using the SET ROLE command.
- This function does not allow the special case of
- setting user to public,
- because the PUBLIC pseudo-role can never be a member of real roles.
-
-
-
-
-
-
- row_security_active
-
- row_security_active (
- tabletext or oid )
- boolean
-
-
- Is row-level security active for the specified table in the context of
- the current user and current environment?
-
-
-
-
-
-
-
- shows the operators
- available for the aclitem type, which is the catalog
- representation of access privileges. See
- for information about how to read access privilege values.
-
-
-
- <type>aclitem</type> Operators
-
-
-
-
- Operator
-
-
- Description
-
-
- Example(s)
-
-
-
-
-
-
-
-
- aclitemeq
-
- aclitem=aclitem
- boolean
-
-
- Are aclitems equal? (Notice that
- type aclitem lacks the usual set of comparison
- operators; it has only equality. In turn, aclitem
- arrays can only be compared for equality.)
-
-
- 'calvin=r*w/hobbes'::aclitem = 'calvin=r*w*/hobbes'::aclitem
- f
-
-
-
-
-
-
- aclcontains
-
- aclitem[]@>aclitem
- boolean
-
-
- Does array contain the specified privileges? (This is true if there
- is an array entry that matches the aclitem's grantee and
- grantor, and has at least the specified set of privileges.)
-
-
- '{calvin=r*w/hobbes,hobbes=r*w*/postgres}'::aclitem[] @> 'calvin=r*/hobbes'::aclitem
- t
-
-
-
-
-
- aclitem[]~aclitem
- boolean
-
-
- This is a deprecated alias for @>.
-
-
- '{calvin=r*w/hobbes,hobbes=r*w*/postgres}'::aclitem[] ~ 'calvin=r*/hobbes'::aclitem
- t
-
-
-
-
-
-
-
- shows some additional
- functions to manage the aclitem type.
-
-
-
- <type>aclitem</type> Functions
-
-
-
-
- Function
-
-
- Description
-
-
-
-
-
-
-
-
- acldefault
-
- acldefault (
- type"char",
- ownerIdoid )
- aclitem[]
-
-
- Constructs an aclitem array holding the default access
- privileges for an object of type type belonging
- to the role with OID ownerId. This represents
- the access privileges that will be assumed when an object's ACL entry
- is null. (The default access privileges are described in
- .)
- The type parameter must be one of
- 'c' for COLUMN,
- 'r' for TABLE and table-like objects,
- 's' for SEQUENCE,
- 'd' for DATABASE,
- 'f' for FUNCTION or PROCEDURE,
- 'l' for LANGUAGE,
- 'L' for LARGE OBJECT,
- 'n' for SCHEMA,
- 'p' for PARAMETER,
- 't' for TABLESPACE,
- 'F' for FOREIGN DATA WRAPPER,
- 'S' for FOREIGN SERVER,
- or
- 'T' for TYPE or DOMAIN.
-
-
-
-
-
-
- aclexplode
-
- aclexplode ( aclitem[] )
- setof record
- ( grantoroid,
- granteeoid,
- privilege_typetext,
- is_grantableboolean )
-
-
- Returns the aclitem array as a set of rows.
- If the grantee is the pseudo-role PUBLIC, it is represented by zero in
- the grantee column. Each granted privilege is
- represented as SELECT, INSERT,
- etc (see for a full list).
- Note that each privilege is broken out as a separate row, so
- only one keyword appears in the privilege_type
- column.
-
-
-
-
-
-
- makeaclitem
-
- makeaclitem (
- granteeoid,
- grantoroid,
- privilegestext,
- is_grantableboolean )
- aclitem
-
-
- Constructs an aclitem with the given properties.
- privileges is a comma-separated list of
- privilege names such as SELECT,
- INSERT, etc, all of which are set in the
- result. (Case of the privilege string is not significant, and
- extra whitespace is allowed between but not within privilege
- names.)
-
-
-
-
-
-
-
-
-
- Schema Visibility Inquiry Functions
-
-
- shows functions that
- determine whether a certain object is visible in the
- current schema search path.
- For example, a table is said to be visible if its
- 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:
-
-SELECT relname FROM pg_class WHERE pg_table_is_visible(oid);
-
- For functions and operators, an object in the search path is said to be
- visible if there is no object of the same name and argument data
- type(s) earlier in the path. For operator classes and families,
- both the name and the associated index access method are considered.
-
-
-
- search path
- object visibility
-
-
-
- Schema Visibility Inquiry Functions
-
-
-
-
- Function
-
-
- Description
-
-
-
-
-
-
-
-
- pg_collation_is_visible
-
- pg_collation_is_visible ( collationoid )
- boolean
-
-
- Is collation visible in search path?
-
-
-
-
-
-
- pg_conversion_is_visible
-
- pg_conversion_is_visible ( conversionoid )
- boolean
-
-
- Is conversion visible in search path?
-
-
-
-
-
-
- pg_function_is_visible
-
- pg_function_is_visible ( functionoid )
- boolean
-
-
- Is function visible in search path?
- (This also works for procedures and aggregates.)
-
-
-
-
-
-
- pg_opclass_is_visible
-
- pg_opclass_is_visible ( opclassoid )
- boolean
-
-
- Is operator class visible in search path?
-
-
-
-
-
-
- pg_operator_is_visible
-
- pg_operator_is_visible ( operatoroid )
- boolean
-
-
- Is operator visible in search path?
-
-
-
-
-
-
- pg_opfamily_is_visible
-
- pg_opfamily_is_visible ( opclassoid )
- boolean
-
-
- Is operator family visible in search path?
-
-
-
-
-
-
- pg_statistics_obj_is_visible
-
- pg_statistics_obj_is_visible ( statoid )
- boolean
-
-
- Is statistics object visible in search path?
-
-
-
-
-
-
- pg_table_is_visible
-
- pg_table_is_visible ( tableoid )
- boolean
-
-
- Is table visible in search path?
- (This works for all types of relations, including views, materialized
- views, indexes, sequences and foreign tables.)
-
-
-
-
-
-
- pg_ts_config_is_visible
-
- pg_ts_config_is_visible ( configoid )
- boolean
-
-
- Is text search configuration visible in search path?
-
-
-
-
-
-
- pg_ts_dict_is_visible
-
- pg_ts_dict_is_visible ( dictoid )
- boolean
-
-
- Is text search dictionary visible in search path?
-
-
-
-
-
-
- pg_ts_parser_is_visible
-
- pg_ts_parser_is_visible ( parseroid )
- boolean
-
-
- Is text search parser visible in search path?
-
-
-
-
-
-
- pg_ts_template_is_visible
-
- pg_ts_template_is_visible ( templateoid )
- boolean
-
-
- Is text search template visible in search path?
-
-
-
-
-
-
- pg_type_is_visible
-
- pg_type_is_visible ( typeoid )
- boolean
-
-
- Is type (or domain) visible in search path?
-
-
-
-
-
-
-
- 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 (regclass, regtype,
- regprocedure, regoperator, regconfig,
- or regdictionary),
- for example:
-
-SELECT pg_type_is_visible('myschema.widget'::regtype);
-
- 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.
-
-
-
-
-
- System Catalog Information Functions
-
-
- lists functions that
- extract information from the system catalogs.
-
-
-
- System Catalog Information Functions
-
-
-
-
- Function
-
-
- Description
-
-
-
-
-
-
-
-
- format_type
-
- format_type ( typeoid, typemodinteger )
- text
-
-
- 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.
-
-
-
-
-
-
- pg_basetype
-
- pg_basetype ( regtype )
- regtype
-
-
- Returns the OID of the base type of a domain identified by its
- type OID. If the argument is the OID of a non-domain type,
- returns the argument as-is. Returns NULL if the argument is
- not a valid type OID. If there's a chain of domain dependencies,
- it will recurse until finding the base type.
-
-
- Assuming CREATE DOMAIN mytext AS text:
-
-
- pg_basetype('mytext'::regtype)
- text
-
-
-
-
-
-
- pg_char_to_encoding
-
- pg_char_to_encoding ( encodingname )
- integer
-
-
- Converts the supplied encoding name into an integer representing the
- internal identifier used in some system catalog tables.
- Returns -1 if an unknown encoding name is provided.
-
-
-
-
-
-
- pg_encoding_to_char
-
- pg_encoding_to_char ( encodinginteger )
- name
-
-
- 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.
-
-
-
-
-
-
- pg_get_catalog_foreign_keys
-
- pg_get_catalog_foreign_keys ()
- setof record
- ( fktableregclass,
- fkcolstext[],
- pktableregclass,
- pkcolstext[],
- is_arrayboolean,
- is_optboolean )
-
-
- Returns a set of records describing the foreign key relationships
- that exist within the PostgreSQL system
- catalogs.
- The fktable column contains the name of the
- referencing catalog, and the fkcols column
- contains the name(s) of the referencing column(s). Similarly,
- the pktable column contains the name of the
- referenced catalog, and the pkcols column
- contains the name(s) of the referenced column(s).
- If is_array is true, the last referencing
- column is an array, each of whose elements should match some entry
- in the referenced catalog.
- If is_opt is true, the referencing column(s)
- are allowed to contain zeroes instead of a valid reference.
-
-
-
-
-
-
- pg_get_constraintdef
-
- pg_get_constraintdef ( constraintoid, prettyboolean )
- text
-
-
- Reconstructs the creating command for a constraint.
- (This is a decompiled reconstruction, not the original text
- of the command.)
-
-
-
-
-
-
- pg_get_expr
-
- pg_get_expr ( exprpg_node_tree, relationoid, prettyboolean )
- text
-
-
- 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.
-
-
-
-
-
-
- pg_get_functiondef
-
- pg_get_functiondef ( funcoid )
- text
-
-
- 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 CREATE OR REPLACE FUNCTION
- or CREATE OR REPLACE PROCEDURE statement.
-
-
-
-
-
-
- pg_get_function_arguments
-
- pg_get_function_arguments ( funcoid )
- text
-
-
- Reconstructs the argument list of a function or procedure, in the form
- it would need to appear in within CREATE FUNCTION
- (including default values).
-
-
-
-
-
-
- pg_get_function_identity_arguments
-
- pg_get_function_identity_arguments ( funcoid )
- text
-
-
- Reconstructs the argument list necessary to identify a function or
- procedure, in the form it would need to appear in within commands such
- as ALTER FUNCTION. This form omits default values.
-
-
-
-
-
-
- pg_get_function_result
-
- pg_get_function_result ( funcoid )
- text
-
-
- Reconstructs the RETURNS clause of a function, in
- the form it would need to appear in within CREATE
- FUNCTION. Returns NULL for a procedure.
-
-
-
-
-
-
- pg_get_indexdef
-
- pg_get_indexdef ( indexoid, columninteger, prettyboolean )
- text
-
-
- Reconstructs the creating command for an index.
- (This is a decompiled reconstruction, not the original text
- of the command.) If column is supplied and is
- not zero, only the definition of that column is reconstructed.
-
-
-
-
-
-
- pg_get_keywords
-
- pg_get_keywords ()
- setof record
- ( wordtext,
- catcode"char",
- barelabelboolean,
- catdesctext,
- baredesctext )
-
-
- Returns a set of records describing the SQL keywords recognized by the
- server. The word column contains the
- keyword. The catcode column contains a
- category code: U for an unreserved
- keyword, C for a keyword that can be a column
- name, T for a keyword that can be a type or
- function name, or R for a fully reserved keyword.
- The barelabel column
- contains true if the keyword can be used as
- a bare column label in SELECT lists,
- or false if it can only be used
- after AS.
- The catdesc column contains a
- possibly-localized string describing the keyword's category.
- The baredesc column contains a
- possibly-localized string describing the keyword's column label status.
-
-
-
-
-
-
- pg_get_partkeydef
-
- pg_get_partkeydef ( tableoid )
- text
-
-
- Reconstructs the definition of a partitioned table's partition
- key, in the form it would have in the PARTITION
- BY clause of CREATE TABLE.
- (This is a decompiled reconstruction, not the original text
- of the command.)
-
-
-
-
-
-
- pg_get_ruledef
-
- pg_get_ruledef ( ruleoid, prettyboolean )
- text
-
-
- Reconstructs the creating command for a rule.
- (This is a decompiled reconstruction, not the original text
- of the command.)
-
-
-
-
-
-
- pg_get_serial_sequence
-
- pg_get_serial_sequence ( tabletext, columntext )
- text
-
-
- 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
- (serial, smallserial, bigserial),
- it is the sequence created for that serial column definition.
- In the latter case, the association can be modified or removed
- with ALTER SEQUENCE OWNED BY.
- (This function probably should have been
- called pg_get_owned_sequence; 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 typical use is in reading the current value of the sequence for an
- identity or serial column, for example:
-
-SELECT currval(pg_get_serial_sequence('sometable', 'id'));
-
-
-
-
-
-
-
- pg_get_statisticsobjdef
-
- pg_get_statisticsobjdef ( statobjoid )
- text
-
-
- Reconstructs the creating command for an extended statistics object.
- (This is a decompiled reconstruction, not the original text
- of the command.)
-
-
-
-
-
-
- pg_get_triggerdef
-
-pg_get_triggerdef ( triggeroid, prettyboolean )
- text
-
-
- Reconstructs the creating command for a trigger.
- (This is a decompiled reconstruction, not the original text
- of the command.)
-
-
-
-
-
-
- pg_get_userbyid
-
- pg_get_userbyid ( roleoid )
- name
-
-
- Returns a role's name given its OID.
-
-
-
-
-
-
- pg_get_viewdef
-
- pg_get_viewdef ( viewoid, prettyboolean )
- text
-
-
- Reconstructs the underlying SELECT command for a
- view or materialized view. (This is a decompiled reconstruction, not
- the original text of the command.)
-
-
-
-
-
- pg_get_viewdef ( viewoid, wrap_columninteger )
- text
-
-
- Reconstructs the underlying SELECT 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.
-
-
-
-
-
- pg_get_viewdef ( viewtext, prettyboolean )
- text
-
-
- Reconstructs the underlying SELECT 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.)
-
-
-
-
-
-
- pg_index_column_has_property
-
- pg_index_column_has_property ( indexregclass, columninteger, propertytext )
- boolean
-
-
- Tests whether an index column has the named property.
- Common index column properties are listed in
- .
- (Note that extension access methods can define additional property
- names for their indexes.)
- NULL is returned if the property name is not known
- or does not apply to the particular object, or if the OID or column
- number does not identify a valid object.
-
-
-
-
-
-
- pg_index_has_property
-
- pg_index_has_property ( indexregclass, propertytext )
- boolean
-
-
- Tests whether an index has the named property.
- Common index properties are listed in
- .
- (Note that extension access methods can define additional property
- names for their indexes.)
- NULL 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.
-
-
-
-
-
-
- pg_indexam_has_property
-
- pg_indexam_has_property ( amoid, propertytext )
- boolean
-
-
- Tests whether an index access method has the named property.
- Access method properties are listed in
- .
- NULL 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.
-
-
-
-
-
-
- pg_options_to_table
-
- pg_options_to_table ( options_arraytext[] )
- setof record
- ( option_nametext,
- option_valuetext )
-
-
- Returns the set of storage options represented by a value from
- pg_class.reloptions or
- pg_attribute.attoptions.
-
-
-
-
-
-
- pg_settings_get_flags
-
- pg_settings_get_flags ( guctext )
- text[]
-
-
- Returns an array of the flags associated with the given GUC, or
- NULL 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
- are exposed.
-
-
-
-
-
-
- pg_tablespace_databases
-
- pg_tablespace_databases ( tablespaceoid )
- setof oid
-
-
- 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 pg_tablespace_databases
- and query their pg_class catalogs.
-
-
-
-
-
-
- pg_tablespace_location
-
- pg_tablespace_location ( tablespaceoid )
- text
-
-
- Returns the file system path that this tablespace is located in.
-
-
-
-
-
-
- pg_typeof
-
- pg_typeof ( "any" )
- regtype
-
-
- 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 regtype, which is an OID alias type (see
- ); this means that it is the same as an
- OID for comparison purposes but displays as a type name.
-
-
- pg_typeof(33)
- integer
-
-
-
-
-
-
- COLLATION FOR
-
- COLLATION FOR ( "any" )
- text
-
-
- 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 NULL is returned. If the argument is not of a
- collatable data type, then an error is raised.
-
-
- collation for ('foo'::text)
- "default"
-
-
- collation for ('foo' COLLATE "de_DE")
- "de_DE"
-
-
-
-
-
-
- to_regclass
-
- to_regclass ( text )
- regclass
-
-
- Translates a textual relation name to its OID. A similar result is
- obtained by casting the string to type regclass (see
- ); however, this function will return
- NULL rather than throwing an error if the name is
- not found.
-
-
-
-
-
-
- to_regcollation
-
- to_regcollation ( text )
- regcollation
-
-
- Translates a textual collation name to its OID. A similar result is
- obtained by casting the string to type regcollation (see
- ); however, this function will return
- NULL rather than throwing an error if the name is
- not found.
-
-
-
-
-
-
- to_regnamespace
-
- to_regnamespace ( text )
- regnamespace
-
-
- Translates a textual schema name to its OID. A similar result is
- obtained by casting the string to type regnamespace (see
- ); however, this function will return
- NULL rather than throwing an error if the name is
- not found.
-
-
-
-
-
-
- to_regoper
-
- to_regoper ( text )
- regoper
-
-
- Translates a textual operator name to its OID. A similar result is
- obtained by casting the string to type regoper (see
- ); however, this function will return
- NULL rather than throwing an error if the name is
- not found or is ambiguous.
-
-
-
-
-
-
- to_regoperator
-
- to_regoperator ( text )
- regoperator
-
-
- Translates a textual operator name (with parameter types) to its OID. A similar result is
- obtained by casting the string to type regoperator (see
- ); however, this function will return
- NULL rather than throwing an error if the name is
- not found.
-
-
-
-
-
-
- to_regproc
-
- to_regproc ( text )
- regproc
-
-
- Translates a textual function or procedure name to its OID. A similar result is
- obtained by casting the string to type regproc (see
- ); however, this function will return
- NULL rather than throwing an error if the name is
- not found or is ambiguous.
-
-
-
-
-
-
- to_regprocedure
-
- to_regprocedure ( text )
- regprocedure
-
-
- Translates a textual function or procedure name (with argument types) to its OID. A similar result is
- obtained by casting the string to type regprocedure (see
- ); however, this function will return
- NULL rather than throwing an error if the name is
- not found.
-
-
-
-
-
-
- to_regrole
-
- to_regrole ( text )
- regrole
-
-
- Translates a textual role name to its OID. A similar result is
- obtained by casting the string to type regrole (see
- ); however, this function will return
- NULL rather than throwing an error if the name is
- not found.
-
-
-
-
-
-
- to_regtype
-
- to_regtype ( text )
- regtype
-
-
- Parses a string of text, extracts a potential type name from it,
- and translates that name into a type OID. A syntax error in the
- string will result in an error; but if the string is a
- syntactically valid type name that happens not to be found in the
- catalogs, the result is NULL. A similar result
- is obtained by casting the string to type regtype
- (see ), except that that will throw
- error for name not found.
-
-
-
-
-
-
- to_regtypemod
-
- to_regtypemod ( text )
- integer
-
-
- Parses a string of text, extracts a potential type name from it,
- and translates its type modifier, if any. A syntax error in the
- string will result in an error; but if the string is a
- syntactically valid type name that happens not to be found in the
- catalogs, the result is NULL. The result is
- -1 if no type modifier is present.
-
-
- to_regtypemod can be combined with
- to produce appropriate inputs for
- , allowing a string representing a
- type name to be canonicalized.
-
-
- format_type(to_regtype('varchar(32)'), to_regtypemod('varchar(32)'))
- character varying(32)
-
-
-
-
-
-
-
- Most of the functions that reconstruct (decompile) database objects
- have an optional pretty flag, which
- if true causes the result to
- be pretty-printed. 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
- PostgreSQL; so avoid using pretty-printed output
- for dump purposes. Passing false for
- the pretty parameter yields the same result as
- omitting the parameter.
-
-
-
- Index Column Properties
-
-
- NameDescription
-
-
-
- asc
- Does the column sort in ascending order on a forward scan?
-
-
-
- desc
- Does the column sort in descending order on a forward scan?
-
-
-
- nulls_first
- Does the column sort with nulls first on a forward scan?
-
-
-
- nulls_last
- Does the column sort with nulls last on a forward scan?
-
-
-
- orderable
- Does the column possess any defined sort ordering?
-
-
-
- distance_orderable
- Can the column be scanned in order by a distance
- operator, for example ORDER BY col <-> constant ?
-
-
-
- returnable
- Can the column value be returned by an index-only scan?
-
-
-
- search_array
- Does the column natively support col = ANY(array)
- searches?
-
-
-
- search_nulls
- Does the column support IS NULL and
- IS NOT NULL searches?
-
-
-
-
-
-
-
- Index Properties
-
-
- NameDescription
-
-
-
- clusterable
- Can the index be used in a CLUSTER command?
-
-
-
- index_scan
- Does the index support plain (non-bitmap) scans?
-
-
-
- bitmap_scan
- Does the index support bitmap scans?
-
-
-
- backward_scan
- Can the scan direction be changed in mid-scan (to
- support FETCH BACKWARD on a cursor without
- needing materialization)?
-
-
-
-
-
-
-
- Index Access Method Properties
-
-
- NameDescription
-
-
-
- can_order
- Does the access method support ASC,
- DESC and related keywords in
- CREATE INDEX?
-
-
-
- can_unique
- Does the access method support unique indexes?
-
-
-
- can_multi_col
- Does the access method support indexes with multiple columns?
-
-
-
- can_exclude
- Does the access method support exclusion constraints?
-
-
-
- can_include
- Does the access method support the INCLUDE
- clause of CREATE INDEX?
-
-
-
-
-
-
-
- GUC Flags
-
-
- FlagDescription
-
-
-
- EXPLAIN
- Parameters with this flag are included in
- EXPLAIN (SETTINGS) commands.
-
-
-
- NO_SHOW_ALL
- Parameters with this flag are excluded from
- SHOW ALL commands.
-
-
-
- NO_RESET
- Parameters with this flag do not support
- RESET commands.
-
-
-
- NO_RESET_ALL
- Parameters with this flag are excluded from
- RESET ALL commands.
-
-
-
- NOT_IN_SAMPLE
- Parameters with this flag are not included in
- postgresql.conf by default.
-
-
-
- RUNTIME_COMPUTED
- Parameters with this flag are runtime-computed ones.
-
-
-
-
-
-
-
-
-
- Object Information and Addressing Functions
-
-
- lists functions related to
- database object identification and addressing.
-
-
-
- Object Information and Addressing Functions
-
-
-
-
- Function
-
-
- Description
-
-
-
-
-
-
-
-
- pg_describe_object
-
- pg_describe_object ( classidoid, objidoid, objsubidinteger )
- text
-
-
- 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
- pg_depend catalog. This function returns
- NULL values for undefined objects.
-
-
-
-
-
-
- pg_identify_object
-
- pg_identify_object ( classidoid, objidoid, objsubidinteger )
- record
- ( typetext,
- schematext,
- nametext,
- identitytext )
-
-
- 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.
- type identifies the type of database object;
- schema is the schema name that the object
- belongs in, or NULL for object types that do not
- belong to schemas;
- name 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 NULL;
- identity 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 NULL values.
-
-
-
-
-
-
- pg_identify_object_as_address
-
- pg_identify_object_as_address ( classidoid, objidoid, objsubidinteger )
- record
- ( typetext,
- object_namestext[],
- object_argstext[] )
-
-
- 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.
- type identifies the type of database object;
- object_names and
- object_args
- are text arrays that together form a reference to the object.
- These three values can be passed
- to pg_get_object_address to obtain the internal
- address of the object.
-
-
-
-
-
-
- pg_get_object_address
-
- pg_get_object_address ( typetext, object_namestext[], object_argstext[] )
- record
- ( classidoid,
- objidoid,
- objsubidinteger )
-
-
- 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 pg_depend; they can be passed to
- other system functions such as pg_describe_object
- or pg_identify_object.
- classid is the OID of the system catalog
- containing the object;
- objid is the OID of the object itself, and
- objsubid is the sub-object ID, or zero if none.
- This function is the inverse
- of pg_identify_object_as_address.
- Undefined objects are identified with NULL values.
-
-
-
-
-
-
-
-
-
- Comment Information Functions
-
-
- comment
- about database objects
-
-
-
- The functions shown in
- extract comments previously stored with the
- command. A null value is returned if no
- comment could be found for the specified parameters.
-
-
-
- Comment Information Functions
-
-
-
-
- Function
-
-
- Description
-
-
-
-
-
-
-
-
- col_description
-
- col_description ( tableoid, columninteger )
- text
-
-
- Returns the comment for a table column, which is specified by the OID
- of its table and its column number.
- (obj_description cannot be used for table
- columns, since columns do not have OIDs of their own.)
-
-
-
-
-
-
- obj_description
-
- obj_description ( objectoid, catalogname )
- text
-
-
- Returns the comment for a database object specified by its OID and the
- name of the containing system catalog. For
- example, obj_description(123456, 'pg_class') would
- retrieve the comment for the table with OID 123456.
-
-
-
-
-
- obj_description ( objectoid )
- text
-
-
- Returns the comment for a database object specified by its OID alone.
- This is deprecated since there is no guarantee
- that OIDs are unique across different system catalogs; therefore, the
- wrong comment might be returned.
-
-
-
-
-
-
- shobj_description
-
- shobj_description ( objectoid, catalogname )
- text
-
-
- Returns the comment for a shared database object specified by its OID
- and the name of the containing system catalog. This is just
- like obj_description 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.
-
-
-
-
-
-
-
-
-
- Data Validity Checking Functions
-
-
- The functions shown in
- can be helpful for checking validity of proposed input data.
-
-
-
- Data Validity Checking Functions
-
-
-
-
- Function
-
-
- Description
-
-
- Example(s)
-
-
-
-
-
-
-
-
- pg_input_is_valid
-
- pg_input_is_valid (
- stringtext,
- typetext
- )
- boolean
-
-
- Tests whether the given string is valid
- input for the specified data type, returning true or false.
-
-
- This function will only work as desired if the data type's input
- function has been updated to report invalid input as
- a soft error. Otherwise, invalid input will abort
- the transaction, just as if the string had been cast to the type
- directly.
-
-
- pg_input_is_valid('42', 'integer')
- t
-
-
- pg_input_is_valid('42000000000', 'integer')
- f
-
-
- pg_input_is_valid('1234.567', 'numeric(7,4)')
- f
-
-
-
-
-
- pg_input_error_info
-
- pg_input_error_info (
- stringtext,
- typetext
- )
- record
- ( messagetext,
- detailtext,
- hinttext,
- sql_error_codetext )
-
-
- Tests whether the given string is valid
- input for the specified data type; if not, return the details of
- the error that would have been thrown. If the input is valid, the
- results are NULL. The inputs are the same as
- for pg_input_is_valid.
-
-
- This function will only work as desired if the data type's input
- function has been updated to report invalid input as
- a soft error. Otherwise, invalid input will abort
- the transaction, just as if the string had been cast to the type
- directly.
-
-
- SELECT * FROM pg_input_error_info('42000000000', 'integer')
-
-
- message | detail | hint | sql_error_code
-------------------------------------------------------+--------+------+----------------
- value "42000000000" is out of range for type integer | | | 22003
-
-
-
-
-
-
-
-
-
-
- Transaction ID and Snapshot Information Functions
-
-
- The functions shown in
- provide server transaction information in an exportable form. The main
- use of these functions is to determine which transactions were committed
- between two snapshots.
-
-
-
- Transaction ID and Snapshot Information Functions
-
-
-
-
- Function
-
-
- Description
-
-
-
-
-
-
-
-
- pg_current_xact_id
-
- pg_current_xact_id ()
- xid8
-
-
- 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); see for details. If executed in a
- subtransaction, this will return the top-level transaction ID;
- see for details.
-
-
-
-
-
-
- pg_current_xact_id_if_assigned
-
- pg_current_xact_id_if_assigned ()
- xid8
-
-
- Returns the current transaction's ID, or NULL 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.)
- If executed in a subtransaction, this will return the top-level
- transaction ID.
-
-
-
-
-
-
- pg_xact_status
-
- pg_xact_status ( xid8 )
- text
-
-
- Reports the commit status of a recent transaction.
- The result is one of in progress,
- committed, or aborted,
- 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 NULL.
- 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 COMMIT is in progress.
- Note that prepared transactions are reported as in
- progress; applications must check pg_prepared_xacts
- if they need to determine whether a transaction ID belongs to a
- prepared transaction.
-
-
-
-
-
-
- pg_current_snapshot
-
- pg_current_snapshot ()
- pg_snapshot
-
-
- Returns a current snapshot, a data structure
- showing which transaction IDs are now in-progress.
- Only top-level transaction IDs are included in the snapshot;
- subtransaction IDs are not shown; see
- for details.
-
-
-
-
-
-
- pg_snapshot_xip
-
- pg_snapshot_xip ( pg_snapshot )
- setof xid8
-
-
- Returns the set of in-progress transaction IDs contained in a snapshot.
-
-
-
-
-
-
- pg_snapshot_xmax
-
- pg_snapshot_xmax ( pg_snapshot )
- xid8
-
-
- Returns the xmax of a snapshot.
-
-
-
-
-
-
- pg_snapshot_xmin
-
- pg_snapshot_xmin ( pg_snapshot )
- xid8
-
-
- Returns the xmin of a snapshot.
-
-
-
-
-
-
- pg_visible_in_snapshot
-
- pg_visible_in_snapshot ( xid8, pg_snapshot )
- boolean
-
-
- Is the given transaction ID visible 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 (subxid); see for
- details.
-
-
-
-
-
-
-
- The internal transaction ID type xid is 32 bits wide and
- wraps around every 4 billion transactions. However,
- the functions shown in use a
- 64-bit type xid8 that does not wrap around during the life
- of an installation and can be converted to xid by casting if
- required; see for details.
- The data type pg_snapshot stores information about
- transaction ID visibility at a particular moment in time. Its components
- are described in .
- pg_snapshot's textual representation is
- xmin:xmax:xip_list.
- For example 10:20:10,14,15 means
- xmin=10, xmax=20, xip_list=10, 14, 15.
-
-
-
- Snapshot Components
-
-
-
- Name
- Description
-
-
-
-
-
- xmin
-
- Lowest transaction ID that was still active. All transaction IDs
- less than xmin are either committed and visible,
- or rolled back and dead.
-
-
-
-
- xmax
-
- One past the highest completed transaction ID. All transaction IDs
- greater than or equal to xmax had not yet
- completed as of the time of the snapshot, and thus are invisible.
-
-
-
-
- xip_list
-
- Transactions in progress at the time of the snapshot. A transaction
- ID that is xmin <= X <
- xmax 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 (subxids).
-
-
-
-
-
-
-
- In releases of PostgreSQL before 13 there was
- no xid8 type, so variants of these functions were provided
- that used bigint to represent a 64-bit XID, with a
- correspondingly distinct snapshot data type txid_snapshot.
- These older functions have txid in their names. They
- are still supported for backward compatibility, but may be removed from a
- future release. See .
-
-
-
- Deprecated Transaction ID and Snapshot Information Functions
-
-
-
-
- Function
-
-
- Description
-
-
-
-
-
-
-
-
- age
-
- age ( xid )
- integer
-
-
- Returns the number of transactions between the supplied
- transaction id and the current transaction counter.
-
-
-
-
-
-
- mxid_age
-
- mxid_age ( xid )
- integer
-
-
- Returns the number of multixacts IDs between the supplied
- multixact ID and the current multixacts counter.
-
-
-
-
-
-
- txid_current
-
- txid_current ()
- bigint
-
-
- See pg_current_xact_id().
-
-
-
-
-
-
- txid_current_if_assigned
-
- txid_current_if_assigned ()
- bigint
-
-
- See pg_current_xact_id_if_assigned().
-
-
-
-
-
-
- txid_current_snapshot
-
- txid_current_snapshot ()
- txid_snapshot
-
-
- See pg_current_snapshot().
-
-
-
-
-
-
- txid_snapshot_xip
-
- txid_snapshot_xip ( txid_snapshot )
- setof bigint
-
-
- See pg_snapshot_xip().
-
-
-
-
-
-
- txid_snapshot_xmax
-
- txid_snapshot_xmax ( txid_snapshot )
- bigint
-
-
- See pg_snapshot_xmax().
-
-
-
-
-
-
- txid_snapshot_xmin
-
- txid_snapshot_xmin ( txid_snapshot )
- bigint
-
-
- See pg_snapshot_xmin().
-
-
-
-
-
-
- txid_visible_in_snapshot
-
- txid_visible_in_snapshot ( bigint, txid_snapshot )
- boolean
-
-
- See pg_visible_in_snapshot().
-
-
-
-
-
-
- txid_status
-
- txid_status ( bigint )
- text
-
-
- See pg_xact_status().
-
-
-
-
-
-
-
-
-
- Committed Transaction Information Functions
-
-
- The functions shown in
- provide information about when past transactions were committed.
- They only provide useful data when the
- configuration option is
- enabled, and only for transactions that were committed after it was
- enabled. Commit timestamp information is routinely removed during
- vacuum.
-
-
-
- Committed Transaction Information Functions
-
-
-
-
- Function
-
-
- Description
-
-
-
-
-
-
-
-
- pg_xact_commit_timestamp
-
- pg_xact_commit_timestamp ( xid )
- timestamp with time zone
-
-
- Returns the commit timestamp of a transaction.
-
-
-
-
-
-
- pg_xact_commit_timestamp_origin
-
- pg_xact_commit_timestamp_origin ( xid )
- record
- ( timestamptimestamp with time zone,
- roidentoid)
-
-
- Returns the commit timestamp and replication origin of a transaction.
-
-
-
-
-
-
- pg_last_committed_xact
-
- pg_last_committed_xact ()
- record
- ( xidxid,
- timestamptimestamp with time zone,
- roidentoid )
-
-
- Returns the transaction ID, commit timestamp and replication origin
- of the latest committed transaction.
-
-
-
-
-
-
-
-
-
- Control Data Functions
-
-
- The functions shown in
- print information initialized during initdb, such
- as the catalog version. They also show information about write-ahead
- logging and checkpoint processing. This information is cluster-wide,
- not specific to any one database. These functions provide most of the same
- information, from the same source, as the
- application.
-
-
-
- Control Data Functions
-
-
-
-
- Function
-
-
- Description
-
-
-
-
-
-
-
-
- pg_control_checkpoint
-
- pg_control_checkpoint ()
- record
-
-
- Returns information about current checkpoint state, as shown in
- .
-
-
-
-
-
-
- pg_control_system
-
- pg_control_system ()
- record
-
-
- Returns information about current control file state, as shown in
- .
-
-
-
-
-
-
- pg_control_init
-
- pg_control_init ()
- record
-
-
- Returns information about cluster initialization state, as shown in
- .
-
-
-
-
-
-
- pg_control_recovery
-
- pg_control_recovery ()
- record
-
-
- Returns information about recovery state, as shown in
- .
-
-
-
-
-
-
-
-
-
- Version Information Functions
-
-
- The functions shown in
- print version information.
-
-
-
- Version Information Functions
-
-
-
-
- Function
-
-
- Description
-
-
-
-
-
-
-
-
- version
-
- version ()
- text
-
-
- Returns a string describing the PostgreSQL
- server's version. You can also get this information from
- , or for a machine-readable
- version use . Software
- developers should use server_version_num (available
- since 8.2) or instead of
- parsing the text version.
-
-
-
-
-
-
- unicode_version
-
- unicode_version ()
- text
-
-
- Returns a string representing the version of Unicode used by
- PostgreSQL.
-
-
-
-
-
- icu_unicode_version
-
- icu_unicode_version ()
- text
-
-
- Returns a string representing the version of Unicode used by ICU, if
- the server was built with ICU support; otherwise returns
- NULL
-
-
-
-
-
-
-
-
- WAL Summarization Information Functions
-
-
- The functions shown in
- print information about the status of WAL summarization.
- See .
-
-
-
- WAL Summarization Information Functions
-
-
-
-
- Function
-
-
- Description
-
-
-
-
-
-
-
-
- pg_available_wal_summaries
-
- pg_available_wal_summaries ()
- setof record
- ( tlibigint,
- start_lsnpg_lsn,
- end_lsnpg_lsn )
-
-
- Returns information about the WAL summary files present in the
- data directory, under pg_wal/summaries.
- One row will be returned per WAL summary file. Each file summarizes
- WAL on the indicated TLI within the indicated LSN range. This function
- might be useful to determine whether enough WAL summaries are present
- on the server to take an incremental backup based on some prior
- backup whose start LSN is known.
-
-
-
-
-
-
- pg_wal_summary_contents
-
- pg_wal_summary_contents ( tlibigint, start_lsnpg_lsn, end_lsnpg_lsn )
- setof record
- ( relfilenodeoid,
- reltablespaceoid,
- reldatabaseoid,
- relforknumbersmallint,
- relblocknumberbigint,
- is_limit_blockboolean )
-
-
- Returns one information about the contents of a single WAL summary file
- identified by TLI and starting and ending LSNs. Each row with
- is_limit_block false indicates that the block
- identified by the remaining output columns was modified by at least
- one WAL record within the range of records summarized by this file.
- Each row with is_limit_block true indicates either
- that (a) the relation fork was truncated to the length given by
- relblocknumber within the relevant range of WAL
- records or (b) that the relation fork was created or dropped within
- the relevant range of WAL records; in such cases,
- relblocknumber will be zero.
-
-
-
-
-
-
- pg_get_wal_summarizer_state
-
- pg_get_wal_summarizer_state ()
- record
- ( summarized_tlibigint,
- summarized_lsnpg_lsn,
- pending_lsnpg_lsn,
- summarizer_pidint )
-
-
- Returns information about the progress of the WAL summarizer. If the
- WAL summarizer has never run since the instance was started, then
- summarized_tli and summarized_lsn
- will be 0 and 0/0 respectively;
- otherwise, they will be the TLI and ending LSN of the last WAL summary
- file written to disk. If the WAL summarizer is currently running,
- pending_lsn will be the ending LSN of the last
- record that it has consumed, which must always be greater than or
- equal to summarized_lsn; if the WAL summarizer is
- not running, it will be equal to summarized_lsn.
- summarizer_pid is the PID of the WAL summarizer
- process, if it is running, and otherwise NULL.
-
-
-
-
-
-
-
-
-
-
-
- System Administration Functions
-
-
- The functions described in this section are used to control and
- monitor a PostgreSQL installation.
-
-
-
- Configuration Settings Functions
-
-
- SET
-
-
-
- SHOW
-
-
-
- configuration
- of the server
- functions
-
-
-
- shows the functions
- available to query and alter run-time configuration parameters.
-
-
-
- Configuration Settings Functions
-
-
-
-
- Function
-
-
- Description
-
-
- Example(s)
-
-
-
-
-
-
-
-
- current_setting
-
- current_setting ( setting_nametext, missing_okboolean )
- text
-
-
- Returns the current value of the
- setting setting_name. If there is no such
- setting, current_setting throws an error
- unless missing_ok is supplied and
- is true (in which case NULL is returned).
- This function corresponds to
- the SQL command .
-
-
- current_setting('datestyle')
- ISO, MDY
-
-
-
-
-
-
- set_config
-
- set_config (
- setting_nametext,
- new_valuetext,
- is_localboolean )
- text
-
-
- Sets the parameter setting_name
- to new_value, and returns that value.
- If is_local is true, 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 false instead. This function corresponds to
- the SQL command .
-
-
- set_config('log_statement_stats', 'off', false)
- off
-
-
-
-
-
-
-
-
-
- Server Signaling Functions
-
-
- signal
- backend processes
-
-
-
- The functions shown in send control signals to
- other server processes. Use of these functions is restricted to
- superusers by default but access may be granted to others using
- GRANT, with noted exceptions.
-
-
-
- Each of these functions returns true if
- the signal was successfully sent and false
- if sending the signal failed.
-
-
-
- Server Signaling Functions
-
-
-
-
- Function
-
-
- Description
-
-
-
-
-
-
-
-
- pg_cancel_backend
-
- pg_cancel_backend ( pidinteger )
- boolean
-
-
- 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 pg_signal_backend,
- however only superusers can cancel superuser backends.
-
-
-
-
-
-
- pg_log_backend_memory_contexts
-
- pg_log_backend_memory_contexts ( pidinteger )
- boolean
-
-
- 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
- LOG message level. They will appear in
- the server log based on the log configuration set
- (see for more information),
- but will not be sent to the client regardless of
- .
-
-
-
-
-
-
- pg_reload_conf
-
- pg_reload_conf ()
- boolean
-
-
- Causes all processes of the PostgreSQL
- server to reload their configuration files. (This is initiated by
- sending a SIGHUP signal to the postmaster
- process, which in turn sends SIGHUP to each
- of its children.) You can use the
- pg_file_settings,
- pg_hba_file_rules and
- pg_ident_file_mappings views
- to check the configuration files for possible errors, before reloading.
-
-
-
-
-
-
- pg_rotate_logfile
-
- pg_rotate_logfile ()
- boolean
-
-
- 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.
-
-
-
-
-
-
- pg_terminate_backend
-
- pg_terminate_backend ( pidinteger, timeoutbigintDEFAULT0 )
- boolean
-
-
- 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 pg_signal_backend,
- however only superusers can terminate superuser backends.
-
-
- If timeout is not specified or zero, this
- function returns true whether the process actually
- terminates or not, indicating only that the sending of the signal was
- successful. If the timeout 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 true. On timeout, a warning is emitted and
- false is returned.
-
-
-
-
-
-
-
- pg_cancel_backend and pg_terminate_backend
- send signals (SIGINT or SIGTERM
- respectively) to backend processes identified by process ID.
- The process ID of an active backend can be found from
- the pid column of the
- pg_stat_activity view, or by listing the
- postgres processes on the server (using
- ps on Unix or the Task
- Manager on Windows).
- The role of an active backend can be found from the
- usename column of the
- pg_stat_activity view.
-
-
-
- pg_log_backend_memory_contexts can be used
- to log the memory contexts of a backend process. For example:
-
-postgres=# SELECT pg_log_backend_memory_contexts(pg_backend_pid());
- pg_log_backend_memory_contexts
---------------------------------
- t
-(1 row)
-
-One message for each memory context will be logged. For example:
-
-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
-
- 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.
-
-
-
-
-
- Backup Control Functions
-
-
- backup
-
-
-
- The functions shown in assist in making on-line backups.
- These functions cannot be executed during recovery (except
- pg_backup_start,
- pg_backup_stop,
- and pg_wal_lsn_diff).
-
-
-
- For details about proper usage of these functions, see
- .
-
-
-
- Backup Control Functions
-
-
-
-
- Function
-
-
- Description
-
-
-
-
-
-
-
-
- pg_create_restore_point
-
- pg_create_restore_point ( nametext )
- pg_lsn
-
-
- 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
- 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.
-
-
- This function is restricted to superusers by default, but other users
- can be granted EXECUTE to run the function.
-
-
-
-
-
-
- pg_current_wal_flush_lsn
-
- pg_current_wal_flush_lsn ()
- pg_lsn
-
-
- Returns the current write-ahead log flush location (see notes below).
-
-
-
-
-
-
- pg_current_wal_insert_lsn
-
- pg_current_wal_insert_lsn ()
- pg_lsn
-
-
- Returns the current write-ahead log insert location (see notes below).
-
-
-
-
-
-
- pg_current_wal_lsn
-
- pg_current_wal_lsn ()
- pg_lsn
-
-
- Returns the current write-ahead log write location (see notes below).
-
-
-
-
-
-
- pg_backup_start
-
- pg_backup_start (
- labeltext
- , fastboolean
- )
- pg_lsn
-
-
- 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 true,
- it specifies executing pg_backup_start as quickly
- as possible. This forces an immediate checkpoint which will cause a
- spike in I/O operations, slowing any concurrently executing queries.
-
-
- This function is restricted to superusers by default, but other users
- can be granted EXECUTE to run the function.
-
-
-
-
-
-
- pg_backup_stop
-
- pg_backup_stop (
- wait_for_archiveboolean
- )
- record
- ( lsnpg_lsn,
- labelfiletext,
- spcmapfiletext )
-
-
- 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).
-
-
- There is an optional parameter of type boolean.
- 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, pg_backup_stop will wait for
- WAL to be archived when archiving is enabled. (On a standby, this
- means that it will wait only when archive_mode =
- always. If write activity on the primary is low,
- it may be useful to run pg_switch_wal on the
- primary in order to trigger an immediate segment switch.)
-
-
- 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 pg_backup_start, 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.
-
-
- The result of the function is a single record.
- The lsn 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.
-
-
- This function is restricted to superusers by default, but other users
- can be granted EXECUTE to run the function.
-
-
-
-
-
-
- pg_switch_wal
-
- pg_switch_wal ()
- pg_lsn
-
-
- 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, pg_switch_wal does nothing and
- returns the start location of the write-ahead log file currently in
- use.
-
-
- This function is restricted to superusers by default, but other users
- can be granted EXECUTE to run the function.
-
-
-
-
-
-
- pg_walfile_name
-
- pg_walfile_name ( lsnpg_lsn )
- text
-
-
- Converts a write-ahead log location to the name of the WAL file
- holding that location.
-
-
-
-
-
-
- pg_walfile_name_offset
-
- pg_walfile_name_offset ( lsnpg_lsn )
- record
- ( file_nametext,
- file_offsetinteger )
-
-
- Converts a write-ahead log location to a WAL file name and byte offset
- within that file.
-
-
-
-
-
-
- pg_split_walfile_name
-
- pg_split_walfile_name ( file_nametext )
- record
- ( segment_numbernumeric,
- timeline_idbigint )
-
-
- Extracts the sequence number and timeline ID from a WAL file
- name.
-
-
-
-
-
-
- pg_wal_lsn_diff
-
- pg_wal_lsn_diff ( lsn1pg_lsn, lsn2pg_lsn )
- numeric
-
-
- Calculates the difference in bytes (lsn1 - lsn2) between two write-ahead log
- locations. This can be used
- with pg_stat_replication or some of the
- functions shown in to
- get the replication lag.
-
-
-
-
-
-
-
- pg_current_wal_lsn displays the current write-ahead
- log write location in the same format used by the above functions.
- Similarly, pg_current_wal_insert_lsn displays the
- current write-ahead log insertion location
- and pg_current_wal_flush_lsn displays the current
- write-ahead log flush location. The insertion location is
- the logical end of the write-ahead log at any instant,
- while the write location is the end of what has actually been written out
- from the server's internal buffers, and 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.
-
-
-
- You can use pg_walfile_name_offset to extract the
- corresponding write-ahead log file name and byte offset from
- a pg_lsn value. For example:
-
-postgres=# SELECT * FROM pg_walfile_name_offset((pg_backup_stop()).lsn);
- file_name | file_offset
---------------------------+-------------
- 00000001000000000000000D | 4039624
-(1 row)
-
- Similarly, pg_walfile_name extracts just the write-ahead log file name.
-
-
-
- pg_split_walfile_name is useful to compute a
- LSN from a file offset and WAL file name, for example:
-
-postgres=# \set file_name '000000010000000100C000AB'
-postgres=# \set offset 256
-postgres=# SELECT '0/0'::pg_lsn + pd.segment_number * ps.setting::int + :offset AS lsn
- FROM pg_split_walfile_name(:'file_name') pd,
- pg_show_all_settings() ps
- WHERE ps.name = 'wal_segment_size';
- lsn
----------------
- C001/AB000100
-(1 row)
-
-
-
-
-
-
- Recovery Control Functions
-
-
- The functions shown in provide information
- about the current status of a standby server.
- These functions may be executed both during recovery and in normal running.
-
-
-
- Recovery Information Functions
-
-
-
-
- Function
-
-
- Description
-
-
-
-
-
-
-
-
- pg_is_in_recovery
-
- pg_is_in_recovery ()
- boolean
-
-
- Returns true if recovery is still in progress.
-
-
-
-
-
-
- pg_last_wal_receive_lsn
-
- pg_last_wal_receive_lsn ()
- pg_lsn
-
-
- 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 NULL.
-
-
-
-
-
-
- pg_last_wal_replay_lsn
-
- pg_last_wal_replay_lsn ()
- pg_lsn
-
-
- 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 NULL.
-
-
-
-
-
-
- pg_last_xact_replay_timestamp
-
- pg_last_xact_replay_timestamp ()
- timestamp with time zone
-
-
- 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 NULL. 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 NULL.
-
-
-
-
-
-
- pg_get_wal_resource_managers
-
- pg_get_wal_resource_managers ()
- setof record
- ( rm_idinteger,
- rm_nametext,
- rm_builtinboolean )
-
-
- Returns the currently-loaded WAL resource managers in the system. The
- column rm_builtin indicates whether it's a
- built-in resource manager, or a custom resource manager loaded by an
- extension.
-
-
-
-
-
-
-
- The functions shown in control the progress of recovery.
- These functions may be executed only during recovery.
-
-
-
- Recovery Control Functions
-
-
-
-
- Function
-
-
- Description
-
-
-
-
-
-
-
-
- pg_is_wal_replay_paused
-
- pg_is_wal_replay_paused ()
- boolean
-
-
- Returns true if recovery pause is requested.
-
-
-
-
-
-
- pg_get_wal_replay_pause_state
-
- pg_get_wal_replay_pause_state ()
- text
-
-
- Returns recovery pause state. The return values are
- not paused if pause is not requested,
- pause requested if pause is requested but recovery is
- not yet paused, and paused if the recovery is
- actually paused.
-
-
-
-
-
-
- pg_promote
-
- pg_promote ( waitbooleanDEFAULTtrue, wait_secondsintegerDEFAULT60 )
- boolean
-
-
- Promotes a standby server to primary status.
- With wait set to true (the
- default), the function waits until promotion is completed
- or wait_seconds seconds have passed, and
- returns true if promotion is successful
- and false otherwise.
- If wait is set to false, the
- function returns true immediately after sending a
- SIGUSR1 signal to the postmaster to trigger
- promotion.
-
-
- This function is restricted to superusers by default, but other users
- can be granted EXECUTE to run the function.
-
-
-
-
-
-
- pg_wal_replay_pause
-
- pg_wal_replay_pause ()
- void
-
-
- 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
- pg_get_wal_replay_pause_state(). Note that
- pg_is_wal_replay_paused() 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.
-
-
- This function is restricted to superusers by default, but other users
- can be granted EXECUTE to run the function.
-
-
-
-
-
-
- pg_wal_replay_resume
-
- pg_wal_replay_resume ()
- void
-
-
- Restarts recovery if it was paused.
-
-
- This function is restricted to superusers by default, but other users
- can be granted EXECUTE to run the function.
-
-
-
-
-
-
-
- pg_wal_replay_pause and
- pg_wal_replay_resume cannot be executed while
- a promotion is ongoing. If a promotion is triggered while recovery
- is paused, the paused state ends and promotion continues.
-
-
-
- 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.
-
-
-
-
-
- Snapshot Synchronization Functions
-
-
- PostgreSQL allows database sessions to synchronize their
- snapshots. A snapshot 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 START TRANSACTION commands,
- so that one session sees the effects of that transaction and the other
- does not.
-
-
-
- To solve this problem, PostgreSQL allows a transaction to
- export the snapshot it is using. As long as the exporting
- transaction remains open, other transactions can import 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.
-
-
-
- Snapshots are exported with the pg_export_snapshot function,
- shown in , and
- imported with the command.
-
-
-
- Snapshot Synchronization Functions
-
-
-
-
- Function
-
-
- Description
-
-
-
-
-
-
-
-
- pg_export_snapshot
-
- pg_export_snapshot ()
- text
-
-
- Saves the transaction's current snapshot and returns
- a text 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.
-
-
- A transaction can export more than one snapshot, if needed. Note that
- doing so is only useful in READ COMMITTED
- transactions, since in REPEATABLE READ and higher
- isolation levels, transactions use the same snapshot throughout their
- lifetime. Once a transaction has exported any snapshots, it cannot be
- prepared with .
-
-
-
-
-
- pg_log_standby_snapshot
-
- pg_log_standby_snapshot ()
- pg_lsn
-
-
- Take a snapshot of running transactions and write it to WAL, without
- having to wait for bgwriter or checkpointer to log one. This is useful
- for logical decoding on standby, as logical slot creation has to wait
- until such a record is replayed on the standby.
-
-
-
-
-
-
-
-
-
- Replication Management Functions
-
-
- The functions shown
- in are for
- controlling and interacting with replication features.
- See ,
- , and
-
- 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
- GRANT command.
- Use of functions for replication slots is restricted to superusers
- and users having REPLICATION privilege.
-
-
-
- Many of these functions have equivalent commands in the replication
- protocol; see .
-
-
-
- The functions described in
- ,
- , and
-
- are also relevant for replication.
-
-
-
- Replication Management Functions
-
-
-
-
- Function
-
-
- Description
-
-
-
-
-
-
-
-
- pg_create_physical_replication_slot
-
- pg_create_physical_replication_slot ( slot_namename, immediately_reserveboolean, temporaryboolean )
- record
- ( slot_namename,
- lsnpg_lsn )
-
-
- Creates a new physical replication slot named
- slot_name. The optional second parameter,
- when true, specifies that the LSN for this
- replication slot be reserved immediately; otherwise
- the LSN is reserved on first connection from a streaming
- replication client. Streaming changes from a physical slot is only
- possible with the streaming-replication protocol —
- see . The optional third
- parameter, temporary, 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 CREATE_REPLICATION_SLOT
- ... PHYSICAL.
-
-
-
-
-
-
- pg_drop_replication_slot
-
- pg_drop_replication_slot ( slot_namename )
- void
-
-
- Drops the physical or logical replication slot
- named slot_name. Same as replication protocol
- command DROP_REPLICATION_SLOT. For logical slots, this must
- be called while connected to the same database the slot was created on.
-
-
-
-
-
-
- pg_create_logical_replication_slot
-
- pg_create_logical_replication_slot ( slot_namename, pluginname, temporaryboolean, twophaseboolean, failoverboolean )
- record
- ( slot_namename,
- lsnpg_lsn )
-
-
- Creates a new logical (decoding) replication slot named
- slot_name using the output plugin
- plugin. The optional third
- parameter, temporary, when set to true, specifies that
- the slot should not be permanently stored to disk and is only meant
- for use by the current session. Temporary slots are also
- released upon any error. The optional fourth parameter,
- twophase, when set to true, specifies
- that the decoding of prepared transactions is enabled for this
- slot. The optional fifth parameter,
- failover, when set to true,
- specifies that this slot is enabled to be synced to the
- standbys so that logical replication can be resumed after
- failover. A call to this function has the same effect as
- the replication protocol command
- CREATE_REPLICATION_SLOT ... LOGICAL.
-
-
-
-
-
-
- pg_copy_physical_replication_slot
-
- pg_copy_physical_replication_slot ( src_slot_namename, dst_slot_namename, temporaryboolean )
- record
- ( slot_namename,
- lsnpg_lsn )
-
-
- Copies an existing physical replication slot named src_slot_name
- to a physical replication slot named dst_slot_name.
- The copied physical slot starts to reserve WAL from the same LSN as the
- source slot.
- temporary is optional. If temporary
- is omitted, the same value as the source slot is used.
-
-
-
-
-
-
- pg_copy_logical_replication_slot
-
- pg_copy_logical_replication_slot ( src_slot_namename, dst_slot_namename, temporaryboolean, pluginname )
- record
- ( slot_namename,
- lsnpg_lsn )
-
-
- Copies an existing logical replication slot
- named src_slot_name to a logical replication
- slot named dst_slot_name, optionally changing
- the output plugin and persistence. The copied logical slot starts
- from the same LSN as the source logical slot. Both
- temporary and plugin are
- optional; if they are omitted, the values of the source slot are used.
-
-
-
-
-
-
- pg_logical_slot_get_changes
-
- pg_logical_slot_get_changes ( slot_namename, upto_lsnpg_lsn, upto_nchangesinteger, VARIADICoptionstext[] )
- setof record
- ( lsnpg_lsn,
- xidxid,
- datatext )
-
-
- Returns changes in the slot slot_name, starting
- from the point from which changes have been consumed last. If
- upto_lsn
- and upto_nchanges are NULL,
- logical decoding will continue until end of WAL. If
- upto_lsn is non-NULL, decoding will include only
- those transactions which commit prior to the specified LSN. If
- upto_nchanges 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.
- If the specified slot is a logical failover slot then the function will
- not return until all physical slots specified in
- standby_slot_names
- have confirmed WAL receipt.
-
-
-
-
-
-
- pg_logical_slot_peek_changes
-
- pg_logical_slot_peek_changes ( slot_namename, upto_lsnpg_lsn, upto_nchangesinteger, VARIADICoptionstext[] )
- setof record
- ( lsnpg_lsn,
- xidxid,
- datatext )
-
-
- Behaves just like
- the pg_logical_slot_get_changes() function,
- except that changes are not consumed; that is, they will be returned
- again on future calls.
-
-
-
-
-
-
- pg_logical_slot_get_binary_changes
-
- pg_logical_slot_get_binary_changes ( slot_namename, upto_lsnpg_lsn, upto_nchangesinteger, VARIADICoptionstext[] )
- setof record
- ( lsnpg_lsn,
- xidxid,
- databytea )
-
-
- Behaves just like
- the pg_logical_slot_get_changes() function,
- except that changes are returned as bytea.
-
-
-
-
-
-
- pg_logical_slot_peek_binary_changes
-
- pg_logical_slot_peek_binary_changes ( slot_namename, upto_lsnpg_lsn, upto_nchangesinteger, VARIADICoptionstext[] )
- setof record
- ( lsnpg_lsn,
- xidxid,
- databytea )
-
-
- Behaves just like
- the pg_logical_slot_peek_changes() function,
- except that changes are returned as bytea.
-
-
-
-
-
-
- pg_replication_slot_advance
-
- pg_replication_slot_advance ( slot_namename, upto_lsnpg_lsn )
- record
- ( slot_namename,
- end_lsnpg_lsn )
-
-
- Advances the current confirmed position of a replication slot named
- slot_name. 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. If the specified slot is a
- logical failover slot then the function will not return until all
- physical slots specified in
- standby_slot_names
- have confirmed WAL receipt.
-
-
-
-
-
-
- pg_replication_origin_create
-
- pg_replication_origin_create ( node_nametext )
- oid
-
-
- Creates a replication origin with the given external
- name, and returns the internal ID assigned to it.
-
-
-
-
-
-
- pg_replication_origin_drop
-
- pg_replication_origin_drop ( node_nametext )
- void
-
-
- Deletes a previously-created replication origin, including any
- associated replay progress.
-
-
-
-
-
-
- pg_replication_origin_oid
-
- pg_replication_origin_oid ( node_nametext )
- oid
-
-
- Looks up a replication origin by name and returns the internal ID. If
- no such replication origin is found, NULL is
- returned.
-
-
-
-
-
-
- pg_replication_origin_session_setup
-
- pg_replication_origin_session_setup ( node_nametext )
- void
-
-
- 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 pg_replication_origin_session_reset to undo.
-
-
-
-
-
-
- pg_replication_origin_session_reset
-
- pg_replication_origin_session_reset ()
- void
-
-
- Cancels the effects
- of pg_replication_origin_session_setup().
-
-
-
-
-
-
- pg_replication_origin_session_is_setup
-
- pg_replication_origin_session_is_setup ()
- boolean
-
-
- Returns true if a replication origin has been selected in the
- current session.
-
-
-
-
-
-
- pg_replication_origin_session_progress
-
- pg_replication_origin_session_progress ( flushboolean )
- pg_lsn
-
-
- Returns the replay location for the replication origin selected in
- the current session. The parameter flush
- determines whether the corresponding local transaction will be
- guaranteed to have been flushed to disk or not.
-
-
-
-
-
-
- pg_replication_origin_xact_setup
-
- pg_replication_origin_xact_setup ( origin_lsnpg_lsn, origin_timestamptimestamp with time zone )
- void
-
-
- Marks the current transaction as replaying a transaction that has
- committed at the given LSN and timestamp. Can
- only be called when a replication origin has been selected
- using pg_replication_origin_session_setup.
-
-
-
-
-
-
- pg_replication_origin_xact_reset
-
- pg_replication_origin_xact_reset ()
- void
-
-
- Cancels the effects of
- pg_replication_origin_xact_setup().
-
-
-
-
-
-
- pg_replication_origin_advance
-
- pg_replication_origin_advance ( node_nametext, lsnpg_lsn )
- void
-
-
- 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.
-
-
-
-
-
-
- pg_replication_origin_progress
-
- pg_replication_origin_progress ( node_nametext, flushboolean )
- pg_lsn
-
-
- Returns the replay location for the given replication origin. The
- parameter flush determines whether the
- corresponding local transaction will be guaranteed to have been
- flushed to disk or not.
-
-
-
-
-
-
- pg_logical_emit_message
-
- pg_logical_emit_message ( transactionalboolean, prefixtext, contenttext [, flushbooleanDEFAULTfalse] )
- pg_lsn
-
-
- pg_logical_emit_message ( transactionalboolean, prefixtext, contentbytea [, flushbooleanDEFAULTfalse] )
- pg_lsn
-
-
- Emits a logical decoding message. This can be used to pass generic
- messages to logical decoding plugins through
- WAL. The transactional 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 prefix parameter is a
- textual prefix that can be used by logical decoding plugins to easily
- recognize messages that are interesting for them.
- The content parameter is the content of the
- message, given either in text or binary form.
- The flush parameter (default set to
- false) controls if the message is immediately
- flushed to WAL or not. flush has no effect
- with transactional, as the message's WAL
- record is flushed along with its transaction.
-
-
-
-
-
-
- pg_sync_replication_slots
-
- pg_sync_replication_slots ()
- void
-
-
- Synchronize the logical failover replication slots from the primary
- server to the standby server. This function can only be executed on the
- standby server. Temporary synced slots, if any, cannot be used for
- logical decoding and must be dropped after promotion. See
- for details.
- Note that this function cannot be executed if
-
- sync_replication_slots is enabled and the slotsync
- worker is already running to perform the synchronization of slots.
-
-
-
-
- If, after executing the function,
-
- hot_standby_feedback is disabled on
- the standby or the physical slot configured in
-
- primary_slot_name is
- removed, then it is possible that the necessary rows of the
- synchronized slot will be removed by the VACUUM process on the primary
- server, resulting in the synchronized slot becoming invalidated.
-
-
-
-
-
-
-
-
-
-
-
-
- Database Object Management Functions
-
-
- The functions shown in calculate
- the disk space usage of database objects, or assist in presentation
- or understanding of usage results. bigint results
- are measured in bytes. If an OID that does
- not represent an existing object is passed to one of these
- functions, NULL is returned.
-
-
-
- Database Object Size Functions
-
-
-
-
- Function
-
-
- Description
-
-
-
-
-
-
-
-
- pg_column_size
-
- pg_column_size ( "any" )
- integer
-
-
- 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.
-
-
-
-
-
-
- pg_column_compression
-
- pg_column_compression ( "any" )
- text
-
-
- Shows the compression algorithm that was used to compress
- an individual variable-length value. Returns NULL
- if the value is not compressed.
-
-
-
-
-
-
- pg_column_toast_chunk_id
-
- pg_column_toast_chunk_id ( "any" )
- oid
-
-
- Shows the chunk_id of an on-disk
- TOASTed value. Returns NULL
- if the value is un-TOASTed or not on-disk. See
- for more information about
- TOAST.
-
-
-
-
-
-
- pg_database_size
-
- pg_database_size ( name )
- bigint
-
-
- pg_database_size ( oid )
- bigint
-
-
- Computes the total disk space used by the database with the specified
- name or OID. To use this function, you must
- have CONNECT privilege on the specified database
- (which is granted by default) or have privileges of
- the pg_read_all_stats role.
-
-
-
-
-
-
- pg_indexes_size
-
- pg_indexes_size ( regclass )
- bigint
-
-
- Computes the total disk space used by indexes attached to the
- specified table.
-
-
-
-
-
-
- pg_relation_size
-
- pg_relation_size ( relationregclass, forktext )
- bigint
-
-
- Computes the disk space used by one fork of the
- specified relation. (Note that for most purposes it is more
- convenient to use the higher-level
- functions pg_total_relation_size
- or pg_table_size, 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:
-
-
-
- main returns the size of the main
- data fork of the relation.
-
-
-
-
- fsm returns the size of the Free Space Map
- (see ) associated with the relation.
-
-
-
-
- vm returns the size of the Visibility Map
- (see ) associated with the relation.
-
-
-
-
- init returns the size of the initialization
- fork, if any, associated with the relation.
-
-
-
-
-
-
-
-
-
- pg_size_bytes
-
- pg_size_bytes ( text )
- bigint
-
-
- Converts a size in human-readable format (as returned
- by pg_size_pretty) into bytes. Valid units are
- bytes, B, kB,
- MB, GB, TB,
- and PB.
-
-
-
-
-
-
- pg_size_pretty
-
- pg_size_pretty ( bigint )
- text
-
-
- pg_size_pretty ( numeric )
- text
-
-
- 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 10242 = 1048576 bytes, and so on.
-
-
-
-
-
-
- pg_table_size
-
- pg_table_size ( regclass )
- bigint
-
-
- Computes the disk space used by the specified table, excluding indexes
- (but including its TOAST table if any, free space map, and visibility
- map).
-
-
-
-
-
-
- pg_tablespace_size
-
- pg_tablespace_size ( name )
- bigint
-
-
- pg_tablespace_size ( oid )
- bigint
-
-
- Computes the total disk space used in the tablespace with the
- specified name or OID. To use this function, you must
- have CREATE privilege on the specified tablespace
- or have privileges of the pg_read_all_stats role,
- unless it is the default tablespace for the current database.
-
-
-
-
-
-
- pg_total_relation_size
-
- pg_total_relation_size ( regclass )
- bigint
-
-
- Computes the total disk space used by the specified table, including
- all indexes and TOAST data. The result is
- equivalent to pg_table_size
- +pg_indexes_size.
-
-
-
-
-
-
-
- The functions above that operate on tables or indexes accept a
- regclass argument, which is simply the OID of the table or index
- in the pg_class system catalog. You do not have to look up
- the OID by hand, however, since the regclass data type's input
- converter will do the work for you. See
- for details.
-
-
-
- The functions shown in assist
- in identifying the specific disk files associated with database objects.
-
-
-
- Database Object Location Functions
-
-
-
-
- Function
-
-
- Description
-
-
-
-
-
-
-
-
- pg_relation_filenode
-
- pg_relation_filenode ( relationregclass )
- oid
-
-
- Returns the filenode number currently assigned to the
- specified relation. The filenode is the base component of the file
- name(s) used for the relation (see
- for more information).
- For most relations the result is the same as
- pg_class.relfilenode,
- but for certain system catalogs relfilenode
- 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.
-
-
-
-
-
-
- pg_relation_filepath
-
- pg_relation_filepath ( relationregclass )
- text
-
-
- Returns the entire file path name (relative to the database cluster's
- data directory, PGDATA) of the relation.
-
-
-
-
-
-
- pg_filenode_relation
-
- pg_filenode_relation ( tablespaceoid, filenodeoid )
- regclass
-
-
- Returns a relation's OID given the tablespace OID and filenode it is
- stored under. This is essentially the inverse mapping of
- pg_relation_filepath. For a relation in the
- database's default tablespace, the tablespace can be specified as zero.
- Returns NULL if no relation in the current database
- is associated with the given values.
-
-
-
-
-
-
-
- lists functions used to manage
- collations.
-
-
-
- Collation Management Functions
-
-
-
-
- Function
-
-
- Description
-
-
-
-
-
-
-
-
- pg_collation_actual_version
-
- pg_collation_actual_version ( oid )
- text
-
-
- 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
- pg_collation.collversion,
- then objects depending on the collation might need to be rebuilt. See
- also .
-
-
-
-
-
-
- pg_database_collation_actual_version
-
- pg_database_collation_actual_version ( oid )
- text
-
-
- 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
- pg_database.datcollversion,
- then objects depending on the collation might need to be rebuilt. See
- also .
-
-
-
-
-
-
- pg_import_system_collations
-
- pg_import_system_collations ( schemaregnamespace )
- integer
-
-
- Adds collations to the system
- catalog pg_collation based on all the locales
- it finds in the operating system. This is
- what initdb uses; see
- for more details. If additional
- locales are installed into the operating system later on, this
- function can be run again to add collations for the new locales.
- Locales that match existing entries
- in pg_collation will be skipped. (But
- collation objects based on locales that are no longer present in the
- operating system are not removed by this function.)
- The schema parameter would typically
- be pg_catalog, 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.
-
-
-
-
-
-
-
- lists functions that provide
- information about the structure of partitioned tables.
-
-
-
- Partitioning Information Functions
-
-
-
-
- Function
-
-
- Description
-
-
-
-
-
-
-
-
- pg_partition_tree
-
- pg_partition_tree ( regclass )
- setof record
- ( relidregclass,
- parentrelidregclass,
- isleafboolean,
- levelinteger )
-
-
- 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.
-
-
-
-
-
-
- pg_partition_ancestors
-
- pg_partition_ancestors ( regclass )
- setof regclass
-
-
- 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.
-
-
-
-
-
-
- pg_partition_root
-
- pg_partition_root ( regclass )
- regclass
-
-
- Returns the top-most parent of the partition tree to which the given
- relation belongs. Returns NULL if the relation
- does not exist or is not a partition or partitioned table.
-
-
-
-
-
-
-
- For example, to check the total size of the data contained in a
- partitioned table measurement, one could use the
- following query:
-
-SELECT pg_size_pretty(sum(pg_relation_size(relid))) AS total_size
- FROM pg_partition_tree('measurement');
-
-
-
-
-
-
- Index Maintenance Functions
-
-
- 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.
-
-
-
- Index Maintenance Functions
-
-
-
-
- Function
-
-
- Description
-
-
-
-
-
-
-
-
- brin_summarize_new_values
-
- brin_summarize_new_values ( indexregclass )
- integer
-
-
- 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.
-
-
-
-
-
-
- brin_summarize_range
-
- brin_summarize_range ( indexregclass, blockNumberbigint )
- integer
-
-
- Summarizes the page range covering the given block, if not already
- summarized. This is
- like brin_summarize_new_values except that it
- only processes the page range that covers the given table block number.
-
-
-
-
-
-
- brin_desummarize_range
-
- brin_desummarize_range ( indexregclass, blockNumberbigint )
- void
-
-
- Removes the BRIN index tuple that summarizes the page range covering
- the given table block, if there is one.
-
-
-
-
-
-
- gin_clean_pending_list
-
- gin_clean_pending_list ( indexregclass )
- bigint
-
-
- Cleans up the pending 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 fastupdate option disabled, no cleanup happens
- and the result is zero, because the index doesn't have a pending list.
- See and
- for details about the pending list and fastupdate
- option.
-
-
-
-
-
-
-
-
-
- Generic File Access Functions
-
-
- The functions shown in provide native access to
- files on the machine hosting the server. Only files within the
- database cluster directory and the log_directory can be
- accessed, unless the user is a superuser or is granted the role
- pg_read_server_files. Use a relative path for files in
- the cluster directory, and a path matching the log_directory
- configuration setting for log files.
-
-
-
- Note that granting users the EXECUTE privilege on
- pg_read_file(), 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 pg_authid 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.
-
-
-
- When granting privilege on these functions, note that the table entries
- showing optional parameters are mostly implemented as several physical
- functions with different parameter lists. Privilege must be granted
- separately on each such function, if it is to be
- used. psql's \df command
- can be useful to check what the actual function signatures are.
-
-
-
- Some of these functions take an optional missing_ok
- parameter, which specifies the behavior when the file or directory does
- not exist. If true, the function
- returns NULL or an empty result set, as appropriate.
- If false, an error is raised. (Failure conditions
- other than file not found are reported as errors in any
- case.) The default is false.
-
-
-
- Generic File Access Functions
-
-
-
-
- Function
-
-
- Description
-
-
-
-
-
-
-
-
- pg_ls_dir
-
- pg_ls_dir ( dirnametext, missing_okboolean, include_dot_dirsboolean )
- setof text
-
-
- Returns the names of all files (and directories and other special
- files) in the specified
- directory. The include_dot_dirs parameter
- indicates whether . and .. are to be
- included in the result set; the default is to exclude them. Including
- them can be useful when missing_ok
- is true, to distinguish an empty directory from a
- non-existent directory.
-
-
- This function is restricted to superusers by default, but other users
- can be granted EXECUTE to run the function.
-
-
-
-
-
-
- pg_ls_logdir
-
- pg_ls_logdir ()
- setof record
- ( nametext,
- sizebigint,
- modificationtimestamp with time zone )
-
-
- 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.
-
-
- This function is restricted to superusers and roles with privileges of
- the pg_monitor role by default, but other users can
- be granted EXECUTE to run the function.
-
-
-
-
-
-
- pg_ls_waldir
-
- pg_ls_waldir ()
- setof record
- ( nametext,
- sizebigint,
- modificationtimestamp with time zone )
-
-
- 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.
-
-
- This function is restricted to superusers and roles with privileges of
- the pg_monitor role by default, but other users can
- be granted EXECUTE to run the function.
-
-
-
-
-
-
- pg_ls_logicalmapdir
-
- pg_ls_logicalmapdir ()
- setof record
- ( nametext,
- sizebigint,
- modificationtimestamp with time zone )
-
-
- Returns the name, size, and last modification time (mtime) of each
- ordinary file in the server's pg_logical/mappings
- directory. Filenames beginning with a dot, directories, and other
- special files are excluded.
-
-
- This function is restricted to superusers and members of
- the pg_monitor role by default, but other users can
- be granted EXECUTE to run the function.
-
-
-
-
-
-
- pg_ls_logicalsnapdir
-
- pg_ls_logicalsnapdir ()
- setof record
- ( nametext,
- sizebigint,
- modificationtimestamp with time zone )
-
-
- Returns the name, size, and last modification time (mtime) of each
- ordinary file in the server's pg_logical/snapshots
- directory. Filenames beginning with a dot, directories, and other
- special files are excluded.
-
-
- This function is restricted to superusers and members of
- the pg_monitor role by default, but other users can
- be granted EXECUTE to run the function.
-
-
-
-
-
-
- pg_ls_replslotdir
-
- pg_ls_replslotdir ( slot_nametext )
- setof record
- ( nametext,
- sizebigint,
- modificationtimestamp with time zone )
-
-
- Returns the name, size, and last modification time (mtime) of each
- ordinary file in the server's pg_replslot/slot_name
- directory, where slot_name 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.
-
-
- This function is restricted to superusers and members of
- the pg_monitor role by default, but other users can
- be granted EXECUTE to run the function.
-
-
-
-
-
-
- pg_ls_archive_statusdir
-
- pg_ls_archive_statusdir ()
- setof record
- ( nametext,
- sizebigint,
- modificationtimestamp with time zone )
-
-
- Returns the name, size, and last modification time (mtime) of each
- ordinary file in the server's WAL archive status directory
- (pg_wal/archive_status). Filenames beginning
- with a dot, directories, and other special files are excluded.
-
-
- This function is restricted to superusers and members of
- the pg_monitor role by default, but other users can
- be granted EXECUTE to run the function.
-
-
-
-
-
-
-
- pg_ls_tmpdir
-
- pg_ls_tmpdir ( tablespaceoid )
- setof record
- ( nametext,
- sizebigint,
- modificationtimestamp with time zone )
-
-
- Returns the name, size, and last modification time (mtime) of each
- ordinary file in the temporary file directory for the
- specified tablespace.
- If tablespace is not provided,
- the pg_default tablespace is examined. Filenames
- beginning with a dot, directories, and other special files are
- excluded.
-
-
- This function is restricted to superusers and members of
- the pg_monitor role by default, but other users can
- be granted EXECUTE to run the function.
-
-
-
-
-
-
- pg_read_file
-
- pg_read_file ( filenametext, offsetbigint, lengthbigint, missing_okboolean )
- text
-
-
- Returns all or part of a text file, starting at the
- given byte offset, returning at
- most length bytes (less if the end of file is
- reached first). If offset is negative, it is
- relative to the end of the file. If offset
- and length 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.
-
-
- This function is restricted to superusers by default, but other users
- can be granted EXECUTE to run the function.
-
-
-
-
-
-
- pg_read_binary_file
-
- pg_read_binary_file ( filenametext, offsetbigint, lengthbigint, missing_okboolean )
- bytea
-
-
- Returns all or part of a file. This function is identical to
- pg_read_file except that it can read arbitrary
- binary data, returning the result as bytea
- not text; accordingly, no encoding checks are performed.
-
-
- This function is restricted to superusers by default, but other users
- can be granted EXECUTE to run the function.
-
-
- In combination with the convert_from function,
- this function can be used to read a text file in a specified encoding
- and convert to the database's encoding:
-
-SELECT convert_from(pg_read_binary_file('file_in_utf8.txt'), 'UTF8');
-
-
-
-
-
-
-
- pg_stat_file
-
- pg_stat_file ( filenametext, missing_okboolean )
- record
- ( sizebigint,
- accesstimestamp with time zone,
- modificationtimestamp with time zone,
- changetimestamp with time zone,
- creationtimestamp with time zone,
- isdirboolean )
-
-
- 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.
-
-
- This function is restricted to superusers by default, but other users
- can be granted EXECUTE to run the function.
-
-
-
-
-
-
-
-
-
-
- Advisory Lock Functions
-
-
- The functions shown in
- manage advisory locks. For details about proper use of these functions,
- see .
-
-
-
- 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 false 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.
-
-
-
- Advisory Lock Functions
-
-
-
-
- Function
-
-
- Description
-
-
-
-
-
-
-
-
- pg_advisory_lock
-
- pg_advisory_lock ( keybigint )
- void
-
-
- pg_advisory_lock ( key1integer, key2integer )
- void
-
-
- Obtains an exclusive session-level advisory lock, waiting if necessary.
-
-
-
-
-
-
- pg_advisory_lock_shared
-
- pg_advisory_lock_shared ( keybigint )
- void
-
-
- pg_advisory_lock_shared ( key1integer, key2integer )
- void
-
-
- Obtains a shared session-level advisory lock, waiting if necessary.
-
-
-
-
-
-
- pg_advisory_unlock
-
- pg_advisory_unlock ( keybigint )
- boolean
-
-
- pg_advisory_unlock ( key1integer, key2integer )
- boolean
-
-
- Releases a previously-acquired exclusive session-level advisory lock.
- Returns true if the lock is successfully released.
- If the lock was not held, false is returned, and in
- addition, an SQL warning will be reported by the server.
-
-
-
-
-
-
- pg_advisory_unlock_all
-
- pg_advisory_unlock_all ()
- void
-
-
- 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.)
-
-
-
-
-
-
- pg_advisory_unlock_shared
-
- pg_advisory_unlock_shared ( keybigint )
- boolean
-
-
- pg_advisory_unlock_shared ( key1integer, key2integer )
- boolean
-
-
- Releases a previously-acquired shared session-level advisory lock.
- Returns true if the lock is successfully released.
- If the lock was not held, false is returned, and in
- addition, an SQL warning will be reported by the server.
-
-
-
-
-
-
- pg_advisory_xact_lock
-
- pg_advisory_xact_lock ( keybigint )
- void
-
-
- pg_advisory_xact_lock ( key1integer, key2integer )
- void
-
-
- Obtains an exclusive transaction-level advisory lock, waiting if
- necessary.
-
-
-
-
-
-
- pg_advisory_xact_lock_shared
-
- pg_advisory_xact_lock_shared ( keybigint )
- void
-
-
- pg_advisory_xact_lock_shared ( key1integer, key2integer )
- void
-
-
- Obtains a shared transaction-level advisory lock, waiting if
- necessary.
-
-
-
-
-
-
- pg_try_advisory_lock
-
- pg_try_advisory_lock ( keybigint )
- boolean
-
-
- pg_try_advisory_lock ( key1integer, key2integer )
- boolean
-
-
- Obtains an exclusive session-level advisory lock if available.
- This will either obtain the lock immediately and
- return true, or return false
- without waiting if the lock cannot be acquired immediately.
-
-
-
-
-
-
- pg_try_advisory_lock_shared
-
- pg_try_advisory_lock_shared ( keybigint )
- boolean
-
-
- pg_try_advisory_lock_shared ( key1integer, key2integer )
- boolean
-
-
- Obtains a shared session-level advisory lock if available.
- This will either obtain the lock immediately and
- return true, or return false
- without waiting if the lock cannot be acquired immediately.
-
-
-
-
-
-
- pg_try_advisory_xact_lock
-
- pg_try_advisory_xact_lock ( keybigint )
- boolean
-
-
- pg_try_advisory_xact_lock ( key1integer, key2integer )
- boolean
-
-
- Obtains an exclusive transaction-level advisory lock if available.
- This will either obtain the lock immediately and
- return true, or return false
- without waiting if the lock cannot be acquired immediately.
-
-
-
-
-
-
- pg_try_advisory_xact_lock_shared
-
- pg_try_advisory_xact_lock_shared ( keybigint )
- boolean
-
-
- pg_try_advisory_xact_lock_shared ( key1integer, key2integer )
- boolean
-
-
- Obtains a shared transaction-level advisory lock if available.
- This will either obtain the lock immediately and
- return true, or return false
- without waiting if the lock cannot be acquired immediately.
-
-
-
-
-
-
-
-
-
-
-
- Trigger Functions
-
-
- While many uses of triggers involve user-written trigger functions,
- PostgreSQL provides a few built-in trigger
- functions that can be used directly in user-defined triggers. These
- are summarized in .
- (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.)
-
-
-
- For more information about creating triggers, see
- .
-
-
-
- Built-In Trigger Functions
-
-
-
-
- Function
-
-
- Description
-
-
- Example Usage
-
-
-
-
-
-
-
-
- suppress_redundant_updates_trigger
-
- suppress_redundant_updates_trigger ( )
- trigger
-
-
- Suppresses do-nothing update operations. See below for details.
-
-
- CREATE TRIGGER ... suppress_redundant_updates_trigger()
-
-
-
-
-
-
- tsvector_update_trigger
-
- tsvector_update_trigger ( )
- trigger
-
-
- Automatically updates a tsvector column from associated
- plain-text document column(s). The text search configuration to use
- is specified by name as a trigger argument. See
- for details.
-
-
- CREATE TRIGGER ... tsvector_update_trigger(tsvcol, 'pg_catalog.swedish', title, body)
-
-
-
-
-
-
- tsvector_update_trigger_column
-
- tsvector_update_trigger_column ( )
- trigger
-
-
- Automatically updates a tsvector column from associated
- plain-text document column(s). The text search configuration to use
- is taken from a regconfig column of the table. See
- for details.
-
-
- CREATE TRIGGER ... tsvector_update_trigger_column(tsvcol, tsconfigcol, title, body)
-
-
-
-
-
-
-
- The suppress_redundant_updates_trigger function,
- when applied as a row-level BEFORE UPDATE 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.)
-
-
-
- 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
- suppress_redundant_updates_trigger, 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.
-
-
-
- The suppress_redundant_updates_trigger function can be
- added to a table like this:
-
-CREATE TRIGGER z_min_update
-BEFORE UPDATE ON tablename
-FOR EACH ROW EXECUTE FUNCTION suppress_redundant_updates_trigger();
-
- 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 z prefix in the
- example.)
-
-
-
-
- Event Trigger Functions
-
-
- PostgreSQL provides these helper functions
- to retrieve information from event triggers.
-
-
-
- For more information about event triggers,
- see .
-
-
-
- Capturing Changes at Command End
-
-
- pg_event_trigger_ddl_commands
-
-
-
-pg_event_trigger_ddl_commands () setof record
-
-
-
- pg_event_trigger_ddl_commands returns a list of
- DDL commands executed by each user action,
- when invoked in a function attached to a
- ddl_command_end event trigger. If called in any other
- context, an error is raised.
- pg_event_trigger_ddl_commands 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:
-
-
-
-
-
- Name
- Type
- Description
-
-
-
-
-
- classid
- oid
- OID of catalog the object belongs in
-
-
- objid
- oid
- OID of the object itself
-
-
- objsubid
- integer
- Sub-object ID (e.g., attribute number for a column)
-
-
- command_tag
- text
- Command tag
-
-
- object_type
- text
- Type of the object
-
-
- schema_name
- text
-
- Name of the schema the object belongs in, if any; otherwise NULL.
- No quoting is applied.
-
-
-
- object_identity
- text
-
- Text rendering of the object identity, schema-qualified. Each
- identifier included in the identity is quoted if necessary.
-
-
-
- in_extension
- boolean
- True if the command is part of an extension script
-
-
- command
- pg_ddl_command
-
- 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.
-
-
-
-
-
-
-
-
-
- Processing Objects Dropped by a DDL Command
-
-
- pg_event_trigger_dropped_objects
-
-
-
-pg_event_trigger_dropped_objects () setof record
-
-
-
- pg_event_trigger_dropped_objects returns a list of all objects
- dropped by the command in whose sql_drop event it is called.
- If called in any other context, an error is raised.
- This function returns the following columns:
-
-
-
-
-
- Name
- Type
- Description
-
-
-
-
-
- classid
- oid
- OID of catalog the object belonged in
-
-
- objid
- oid
- OID of the object itself
-
-
- objsubid
- integer
- Sub-object ID (e.g., attribute number for a column)
-
-
- original
- boolean
- True if this was one of the root object(s) of the deletion
-
-
- normal
- boolean
-
- True if there was a normal dependency relationship
- in the dependency graph leading to this object
-
-
-
- is_temporary
- boolean
-
- True if this was a temporary object
-
-
-
- object_type
- text
- Type of the object
-
-
- schema_name
- text
-
- Name of the schema the object belonged in, if any; otherwise NULL.
- No quoting is applied.
-
-
-
- object_name
- text
-
- Name of the object, if the combination of schema and name can be
- used as a unique identifier for the object; otherwise NULL.
- No quoting is applied, and name is never schema-qualified.
-
-
-
- object_identity
- text
-
- Text rendering of the object identity, schema-qualified. Each
- identifier included in the identity is quoted if necessary.
-
-
-
- address_names
- text[]
-
- An array that, together with object_type and
- address_args, can be used by
- the pg_get_object_address function to
- recreate the object address in a remote server containing an
- identically named object of the same kind.
-
-
-
- address_args
- text[]
-
- Complement for address_names
-
-
-
-
-
-
-
-
- The pg_event_trigger_dropped_objects function can be used
- in an event trigger like this:
-
-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();
-
-
-
-
-
- Handling a Table Rewrite Event
-
-
- The functions shown in
-
- provide information about a table for which a
- table_rewrite event has just been called.
- If called in any other context, an error is raised.
-
-
-
- Table Rewrite Information Functions
-
-
-
-
- Function
-
-
- Description
-
-
-
-
-
-
-
-
- pg_event_trigger_table_rewrite_oid
-
- pg_event_trigger_table_rewrite_oid ()
- oid
-
-
- Returns the OID of the table about to be rewritten.
-
-
-
-
-
-
- pg_event_trigger_table_rewrite_reason
-
- pg_event_trigger_table_rewrite_reason ()
- integer
-
-
- Returns a code explaining the reason(s) for rewriting. The exact
- meaning of the codes is release dependent.
-
-
-
-
-
-
-
- These functions can be used in an event trigger like this:
-
-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();
-
-
-
-
-
-
- Statistics Information Functions
-
-
- function
- statistics
-
-
-
- PostgreSQL provides a function to inspect complex
- statistics defined using the CREATE STATISTICS command.
-
-
-
- Inspecting MCV Lists
-
-
- pg_mcv_list_items
-
-
-
-pg_mcv_list_items ( pg_mcv_list ) setof record
-
-
-
- pg_mcv_list_items returns a set of records describing
- all items stored in a multi-column MCV list. It
- returns the following columns:
-
-
-
-
-
- Name
- Type
- Description
-
-
-
-
-
- index
- integer
- index of the item in the MCV list
-
-
- values
- text[]
- values stored in the MCV item
-
-
- nulls
- boolean[]
- flags identifying NULL values
-
-
- frequency
- double precision
- frequency of this MCV item
-
-
- base_frequency
- double precision
- base frequency of this MCV item
-
-
-
-
-
-
-
- The pg_mcv_list_items function can be used like this:
-
-
-SELECT m.* FROM pg_statistic_ext join pg_statistic_ext_data on (oid = stxoid),
- pg_mcv_list_items(stxdmcv) m WHERE stxname = 'stts';
-
-
- Values of the pg_mcv_list type can be obtained only from the
- pg_statistic_ext_data.stxdmcv
- column.
-
-
-
-
-
-
diff --git a/doc/src/sgml/func/allfiles.sgml b/doc/src/sgml/func/allfiles.sgml
new file mode 100644
index 0000000000000..ce11ef1d5d8ed
--- /dev/null
+++ b/doc/src/sgml/func/allfiles.sgml
@@ -0,0 +1,40 @@
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
diff --git a/doc/src/sgml/func/func-admin.sgml b/doc/src/sgml/func/func-admin.sgml
new file mode 100644
index 0000000000000..57ff333159f00
--- /dev/null
+++ b/doc/src/sgml/func/func-admin.sgml
@@ -0,0 +1,2963 @@
+
+ System Administration Functions
+
+
+ The functions described in this section are used to control and
+ monitor a PostgreSQL installation.
+
+
+
+ Configuration Settings Functions
+
+
+ SET
+
+
+
+ SHOW
+
+
+
+ configuration
+ of the server
+ functions
+
+
+
+ shows the functions
+ available to query and alter run-time configuration parameters.
+
+
+
+ Configuration Settings Functions
+
+
+
+
+ Function
+
+
+ Description
+
+
+ Example(s)
+
+
+
+
+
+
+
+
+ current_setting
+
+ current_setting ( setting_nametext, missing_okboolean )
+ text
+
+
+ Returns the current value of the
+ setting setting_name. If there is no such
+ setting, current_setting throws an error
+ unless missing_ok is supplied and
+ is true (in which case NULL is returned).
+ This function corresponds to
+ the SQL command .
+
+
+ current_setting('datestyle')
+ ISO, MDY
+
+
+
+
+
+
+ set_config
+
+ set_config (
+ setting_nametext,
+ new_valuetext,
+ is_localboolean )
+ text
+
+
+ Sets the parameter setting_name
+ to new_value, and returns that value.
+ If is_local is true, 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 false instead. This function corresponds to
+ the SQL command .
+
+
+ set_config accepts the NULL value for
+ new_value, but as settings cannot be null, it
+ is interpreted as a request to reset the setting to its default value.
+
+
+ set_config('log_statement_stats', 'off', false)
+ off
+
+
+
+
+
+
+
+
+
+ Server Signaling Functions
+
+
+ signal
+ backend processes
+
+
+
+ The functions shown in send control signals to
+ other server processes. Use of these functions is restricted to
+ superusers by default but access may be granted to others using
+ GRANT, with noted exceptions.
+
+
+
+ Each of these functions returns true if
+ the signal was successfully sent and false
+ if sending the signal failed.
+
+
+
+ Server Signaling Functions
+
+
+
+
+ Function
+
+
+ Description
+
+
+
+
+
+
+
+
+ pg_cancel_backend
+
+ pg_cancel_backend ( pidinteger )
+ boolean
+
+
+ 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 pg_signal_backend,
+ however only superusers can cancel superuser backends.
+ As an exception, roles with privileges of
+ pg_signal_autovacuum_worker are permitted to
+ cancel autovacuum worker processes, which are otherwise considered
+ superuser backends.
+
+
+
+
+
+
+ pg_log_backend_memory_contexts
+
+ pg_log_backend_memory_contexts ( pidinteger )
+ boolean
+
+
+ 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
+ LOG message level. They will appear in
+ the server log based on the log configuration set
+ (see for more information),
+ but will not be sent to the client regardless of
+ .
+
+
+
+
+
+
+ pg_reload_conf
+
+ pg_reload_conf ()
+ boolean
+
+
+ Causes all processes of the PostgreSQL
+ server to reload their configuration files. (This is initiated by
+ sending a SIGHUP signal to the postmaster
+ process, which in turn sends SIGHUP to each
+ of its children.) You can use the
+ pg_file_settings,
+ pg_hba_file_rules and
+ pg_ident_file_mappings views
+ to check the configuration files for possible errors, before reloading.
+
+
+
+
+
+
+ pg_rotate_logfile
+
+ pg_rotate_logfile ()
+ boolean
+
+
+ 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.
+
+
+
+
+
+
+ pg_terminate_backend
+
+ pg_terminate_backend ( pidinteger, timeoutbigintDEFAULT0 )
+ boolean
+
+
+ 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 pg_signal_backend,
+ however only superusers can terminate superuser backends.
+ As an exception, roles with privileges of
+ pg_signal_autovacuum_worker are permitted to
+ terminate autovacuum worker processes, which are otherwise considered
+ superuser backends.
+
+
+ If timeout is not specified or zero, this
+ function returns true whether the process actually
+ terminates or not, indicating only that the sending of the signal was
+ successful. If the timeout 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 true. On timeout, a warning is emitted and
+ false is returned.
+
+
+
+
+
+
+
+ pg_cancel_backend and pg_terminate_backend
+ send signals (SIGINT or SIGTERM
+ respectively) to backend processes identified by process ID.
+ The process ID of an active backend can be found from
+ the pid column of the
+ pg_stat_activity view, or by listing the
+ postgres processes on the server (using
+ ps on Unix or the Task
+ Manager on Windows).
+ The role of an active backend can be found from the
+ usename column of the
+ pg_stat_activity view.
+
+
+
+ pg_log_backend_memory_contexts can be used
+ to log the memory contexts of a backend process. For example:
+
+postgres=# SELECT pg_log_backend_memory_contexts(pg_backend_pid());
+ pg_log_backend_memory_contexts
+--------------------------------
+ t
+(1 row)
+
+One message for each memory context will be logged. For example:
+
+LOG: logging memory contexts of PID 10377
+STATEMENT: SELECT pg_log_backend_memory_contexts(pg_backend_pid());
+LOG: level: 1; TopMemoryContext: 80800 total in 6 blocks; 14432 free (5 chunks); 66368 used
+LOG: level: 2; pgstat TabStatusArray lookup hash table: 8192 total in 1 blocks; 1408 free (0 chunks); 6784 used
+LOG: level: 2; TopTransactionContext: 8192 total in 1 blocks; 7720 free (1 chunks); 472 used
+LOG: level: 2; RowDescriptionContext: 8192 total in 1 blocks; 6880 free (0 chunks); 1312 used
+LOG: level: 2; MessageContext: 16384 total in 2 blocks; 5152 free (0 chunks); 11232 used
+LOG: level: 2; Operator class cache: 8192 total in 1 blocks; 512 free (0 chunks); 7680 used
+LOG: level: 2; smgr relation table: 16384 total in 2 blocks; 4544 free (3 chunks); 11840 used
+LOG: level: 2; TransactionAbortContext: 32768 total in 1 blocks; 32504 free (0 chunks); 264 used
+...
+LOG: level: 2; 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
+
+ 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.
+
+
+
+
+
+ Backup Control Functions
+
+
+ backup
+
+
+
+ The functions shown in assist in making on-line backups.
+ These functions cannot be executed during recovery (except
+ pg_backup_start,
+ pg_backup_stop,
+ and pg_wal_lsn_diff).
+
+
+
+ For details about proper usage of these functions, see
+ .
+
+
+
+ Backup Control Functions
+
+
+
+
+ Function
+
+
+ Description
+
+
+
+
+
+
+
+
+ pg_create_restore_point
+
+ pg_create_restore_point ( nametext )
+ pg_lsn
+
+
+ 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
+ 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.
+
+
+ This function is restricted to superusers by default, but other users
+ can be granted EXECUTE to run the function.
+
+
+
+
+
+
+ pg_current_wal_flush_lsn
+
+ pg_current_wal_flush_lsn ()
+ pg_lsn
+
+
+ Returns the current write-ahead log flush location (see notes below).
+
+
+
+
+
+
+ pg_current_wal_insert_lsn
+
+ pg_current_wal_insert_lsn ()
+ pg_lsn
+
+
+ Returns the current write-ahead log insert location (see notes below).
+
+
+
+
+
+
+ pg_current_wal_lsn
+
+ pg_current_wal_lsn ()
+ pg_lsn
+
+
+ Returns the current write-ahead log write location (see notes below).
+
+
+
+
+
+
+ pg_backup_start
+
+ pg_backup_start (
+ labeltext
+ , fastboolean
+ )
+ pg_lsn
+
+
+ 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 true,
+ it specifies executing pg_backup_start as quickly
+ as possible. This forces a fast checkpoint which will cause a
+ spike in I/O operations, slowing any concurrently executing queries.
+
+
+ This function is restricted to superusers by default, but other users
+ can be granted EXECUTE to run the function.
+
+
+
+
+
+
+ pg_backup_stop
+
+ pg_backup_stop (
+ wait_for_archiveboolean
+ )
+ record
+ ( lsnpg_lsn,
+ labelfiletext,
+ spcmapfiletext )
+
+
+ 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).
+
+
+ There is an optional parameter of type boolean.
+ 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, pg_backup_stop will wait for
+ WAL to be archived when archiving is enabled. (On a standby, this
+ means that it will wait only when archive_mode =
+ always. If write activity on the primary is low,
+ it may be useful to run pg_switch_wal on the
+ primary in order to trigger an immediate segment switch.)
+
+
+ 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 pg_backup_start, 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.
+
+
+ The result of the function is a single record.
+ The lsn 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.
+
+
+ This function is restricted to superusers by default, but other users
+ can be granted EXECUTE to run the function.
+
+
+
+
+
+
+ pg_switch_wal
+
+ pg_switch_wal ()
+ pg_lsn
+
+
+ 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, pg_switch_wal does nothing and
+ returns the start location of the write-ahead log file currently in
+ use.
+
+
+ This function is restricted to superusers by default, but other users
+ can be granted EXECUTE to run the function.
+
+
+
+
+
+
+ pg_walfile_name
+
+ pg_walfile_name ( lsnpg_lsn )
+ text
+
+
+ Converts a write-ahead log location to the name of the WAL file
+ holding that location.
+
+
+
+
+
+
+ pg_walfile_name_offset
+
+ pg_walfile_name_offset ( lsnpg_lsn )
+ record
+ ( file_nametext,
+ file_offsetinteger )
+
+
+ Converts a write-ahead log location to a WAL file name and byte offset
+ within that file.
+
+
+
+
+
+
+ pg_split_walfile_name
+
+ pg_split_walfile_name ( file_nametext )
+ record
+ ( segment_numbernumeric,
+ timeline_idbigint )
+
+
+ Extracts the sequence number and timeline ID from a WAL file
+ name.
+
+
+
+
+
+
+ pg_wal_lsn_diff
+
+ pg_wal_lsn_diff ( lsn1pg_lsn, lsn2pg_lsn )
+ numeric
+
+
+ Calculates the difference in bytes (lsn1 - lsn2) between two write-ahead log
+ locations. This can be used
+ with pg_stat_replication or some of the
+ functions shown in to
+ get the replication lag.
+
+
+
+
+
+
+
+ pg_current_wal_lsn displays the current write-ahead
+ log write location in the same format used by the above functions.
+ Similarly, pg_current_wal_insert_lsn displays the
+ current write-ahead log insertion location
+ and pg_current_wal_flush_lsn displays the current
+ write-ahead log flush location. The insertion location is
+ the logical end of the write-ahead log at any instant,
+ while the write location is the end of what has actually been written out
+ from the server's internal buffers, and 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.
+
+
+
+ You can use pg_walfile_name_offset to extract the
+ corresponding write-ahead log file name and byte offset from
+ a pg_lsn value. For example:
+
+postgres=# SELECT * FROM pg_walfile_name_offset((pg_backup_stop()).lsn);
+ file_name | file_offset
+--------------------------+-------------
+ 00000001000000000000000D | 4039624
+(1 row)
+
+ Similarly, pg_walfile_name extracts just the write-ahead log file name.
+
+
+
+ pg_split_walfile_name is useful to compute a
+ LSN from a file offset and WAL file name, for example:
+
+postgres=# \set file_name '000000010000000100C000AB'
+postgres=# \set offset 256
+postgres=# SELECT '0/0'::pg_lsn + pd.segment_number * ps.setting::int + :offset AS lsn
+ FROM pg_split_walfile_name(:'file_name') pd,
+ pg_show_all_settings() ps
+ WHERE ps.name = 'wal_segment_size';
+ lsn
+---------------
+ C001/AB000100
+(1 row)
+
+
+
+
+
+
+ Recovery Control Functions
+
+
+ The functions shown in provide information
+ about the current status of a standby server.
+ These functions may be executed both during recovery and in normal running.
+
+
+
+ Recovery Information Functions
+
+
+
+
+ Function
+
+
+ Description
+
+
+
+
+
+
+
+
+ pg_is_in_recovery
+
+ pg_is_in_recovery ()
+ boolean
+
+
+ Returns true if recovery is still in progress.
+
+
+
+
+
+
+ pg_last_wal_receive_lsn
+
+ pg_last_wal_receive_lsn ()
+ pg_lsn
+
+
+ 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 NULL.
+
+
+
+
+
+
+ pg_last_wal_replay_lsn
+
+ pg_last_wal_replay_lsn ()
+ pg_lsn
+
+
+ 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 NULL.
+
+
+
+
+
+
+ pg_last_xact_replay_timestamp
+
+ pg_last_xact_replay_timestamp ()
+ timestamp with time zone
+
+
+ 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 NULL. 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 NULL.
+
+
+
+
+
+
+ pg_get_wal_resource_managers
+
+ pg_get_wal_resource_managers ()
+ setof record
+ ( rm_idinteger,
+ rm_nametext,
+ rm_builtinboolean )
+
+
+ Returns the currently-loaded WAL resource managers in the system. The
+ column rm_builtin indicates whether it's a
+ built-in resource manager, or a custom resource manager loaded by an
+ extension.
+
+
+
+
+
+
+
+ The functions shown in control the progress of recovery.
+ These functions may be executed only during recovery.
+
+
+
+ Recovery Control Functions
+
+
+
+
+ Function
+
+
+ Description
+
+
+
+
+
+
+
+
+ pg_is_wal_replay_paused
+
+ pg_is_wal_replay_paused ()
+ boolean
+
+
+ Returns true if recovery pause is requested.
+
+
+
+
+
+
+ pg_get_wal_replay_pause_state
+
+ pg_get_wal_replay_pause_state ()
+ text
+
+
+ Returns recovery pause state. The return values are
+ not paused if pause is not requested,
+ pause requested if pause is requested but recovery is
+ not yet paused, and paused if the recovery is
+ actually paused.
+
+
+
+
+
+
+ pg_promote
+
+ pg_promote ( waitbooleanDEFAULTtrue, wait_secondsintegerDEFAULT60 )
+ boolean
+
+
+ Promotes a standby server to primary status.
+ With wait set to true (the
+ default), the function waits until promotion is completed
+ or wait_seconds seconds have passed, and
+ returns true if promotion is successful
+ and false otherwise.
+ If wait is set to false, the
+ function returns true immediately after sending a
+ SIGUSR1 signal to the postmaster to trigger
+ promotion.
+
+
+ This function is restricted to superusers by default, but other users
+ can be granted EXECUTE to run the function.
+
+
+
+
+
+
+ pg_wal_replay_pause
+
+ pg_wal_replay_pause ()
+ void
+
+
+ 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
+ pg_get_wal_replay_pause_state(). Note that
+ pg_is_wal_replay_paused() 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.
+
+
+ This function is restricted to superusers by default, but other users
+ can be granted EXECUTE to run the function.
+
+
+
+
+
+
+ pg_wal_replay_resume
+
+ pg_wal_replay_resume ()
+ void
+
+
+ Restarts recovery if it was paused.
+
+
+ This function is restricted to superusers by default, but other users
+ can be granted EXECUTE to run the function.
+
+
+
+
+
+
+
+ pg_wal_replay_pause and
+ pg_wal_replay_resume cannot be executed while
+ a promotion is ongoing. If a promotion is triggered while recovery
+ is paused, the paused state ends and promotion continues.
+
+
+
+ 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.
+
+
+
+
+
+ Snapshot Synchronization Functions
+
+
+ PostgreSQL allows database sessions to synchronize their
+ snapshots. A snapshot 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 START TRANSACTION commands,
+ so that one session sees the effects of that transaction and the other
+ does not.
+
+
+
+ To solve this problem, PostgreSQL allows a transaction to
+ export the snapshot it is using. As long as the exporting
+ transaction remains open, other transactions can import 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.
+
+
+
+ Snapshots are exported with the pg_export_snapshot function,
+ shown in , and
+ imported with the command.
+
+
+
+ Snapshot Synchronization Functions
+
+
+
+
+ Function
+
+
+ Description
+
+
+
+
+
+
+
+
+ pg_export_snapshot
+
+ pg_export_snapshot ()
+ text
+
+
+ Saves the transaction's current snapshot and returns
+ a text 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.
+
+
+ A transaction can export more than one snapshot, if needed. Note that
+ doing so is only useful in READ COMMITTED
+ transactions, since in REPEATABLE READ and higher
+ isolation levels, transactions use the same snapshot throughout their
+ lifetime. Once a transaction has exported any snapshots, it cannot be
+ prepared with .
+
+
+
+
+
+ pg_log_standby_snapshot
+
+ pg_log_standby_snapshot ()
+ pg_lsn
+
+
+ Take a snapshot of running transactions and write it to WAL, without
+ having to wait for bgwriter or checkpointer to log one. This is useful
+ for logical decoding on standby, as logical slot creation has to wait
+ until such a record is replayed on the standby.
+
+
+
+
+
+
+
+
+
+ Replication Management Functions
+
+
+ The functions shown
+ in are for
+ controlling and interacting with replication features.
+ See ,
+ , and
+
+ 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
+ GRANT command.
+ Use of functions for replication slots is restricted to superusers
+ and users having REPLICATION privilege.
+
+
+
+ Many of these functions have equivalent commands in the replication
+ protocol; see .
+
+
+
+ The functions described in
+ ,
+ , and
+
+ are also relevant for replication.
+
+
+
+ Replication Management Functions
+
+
+
+
+ Function
+
+
+ Description
+
+
+
+
+
+
+
+
+ pg_create_physical_replication_slot
+
+ pg_create_physical_replication_slot ( slot_namename, immediately_reserveboolean, temporaryboolean )
+ record
+ ( slot_namename,
+ lsnpg_lsn )
+
+
+ Creates a new physical replication slot named
+ slot_name. The name cannot be
+ pg_conflict_detection as it is reserved for the
+ conflict detection slot. The optional second parameter,
+ when true, specifies that the LSN for this
+ replication slot be reserved immediately; otherwise
+ the LSN is reserved on first connection from a streaming
+ replication client. Streaming changes from a physical slot is only
+ possible with the streaming-replication protocol —
+ see . The optional third
+ parameter, temporary, 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 CREATE_REPLICATION_SLOT
+ ... PHYSICAL.
+
+
+
+
+
+
+ pg_drop_replication_slot
+
+ pg_drop_replication_slot ( slot_namename )
+ void
+
+
+ Drops the physical or logical replication slot
+ named slot_name. Same as replication protocol
+ command DROP_REPLICATION_SLOT.
+
+
+
+
+
+
+ pg_create_logical_replication_slot
+
+ pg_create_logical_replication_slot ( slot_namename, pluginname, temporaryboolean, twophaseboolean, failoverboolean )
+ record
+ ( slot_namename,
+ lsnpg_lsn )
+
+
+ Creates a new logical (decoding) replication slot named
+ slot_name using the output plugin
+ plugin. The name cannot be
+ pg_conflict_detection as it is reserved for
+ the conflict detection slot. The optional third
+ parameter, temporary, when set to true, specifies that
+ the slot should not be permanently stored to disk and is only meant
+ for use by the current session. Temporary slots are also
+ released upon any error. The optional fourth parameter,
+ twophase, when set to true, specifies
+ that the decoding of prepared transactions is enabled for this
+ slot. The optional fifth parameter,
+ failover, when set to true,
+ specifies that this slot is enabled to be synced to the
+ standbys so that logical replication can be resumed after
+ failover. A call to this function has the same effect as
+ the replication protocol command
+ CREATE_REPLICATION_SLOT ... LOGICAL.
+
+
+
+
+
+
+ pg_copy_physical_replication_slot
+
+ pg_copy_physical_replication_slot ( src_slot_namename, dst_slot_namename, temporaryboolean )
+ record
+ ( slot_namename,
+ lsnpg_lsn )
+
+
+ Copies an existing physical replication slot named src_slot_name
+ to a physical replication slot named dst_slot_name.
+ The new slot name cannot be pg_conflict_detection,
+ as it is reserved for the conflict detection.
+ The copied physical slot starts to reserve WAL from the same LSN as the
+ source slot.
+ temporary is optional. If temporary
+ is omitted, the same value as the source slot is used. Copy of an
+ invalidated slot is not allowed.
+
+
+
+
+
+
+ pg_copy_logical_replication_slot
+
+ pg_copy_logical_replication_slot ( src_slot_namename, dst_slot_namename, temporaryboolean, pluginname )
+ record
+ ( slot_namename,
+ lsnpg_lsn )
+
+
+ Copies an existing logical replication slot
+ named src_slot_name to a logical replication
+ slot named dst_slot_name, optionally changing
+ the output plugin and persistence. The new slot name cannot be
+ pg_conflict_detection as it is reserved for
+ the conflict detection. The copied logical slot starts from the same
+ LSN as the source logical slot. Both
+ temporary and plugin are
+ optional; if they are omitted, the values of the source slot are used.
+ The failover option of the source logical slot
+ is not copied and is set to false by default. This
+ is to avoid the risk of being unable to continue logical replication
+ after failover to standby where the slot is being synchronized. Copy of
+ an invalidated slot is not allowed.
+
+
+
+
+
+
+ pg_logical_slot_get_changes
+
+ pg_logical_slot_get_changes ( slot_namename, upto_lsnpg_lsn, upto_nchangesinteger, VARIADICoptionstext[] )
+ setof record
+ ( lsnpg_lsn,
+ xidxid,
+ datatext )
+
+
+ Returns changes in the slot slot_name, starting
+ from the point from which changes have been consumed last. If
+ upto_lsn
+ and upto_nchanges are NULL,
+ logical decoding will continue until end of WAL. If
+ upto_lsn is non-NULL, decoding will include only
+ those transactions which commit prior to the specified LSN. If
+ upto_nchanges 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.
+ If the specified slot is a logical failover slot then the function will
+ not return until all physical slots specified in
+ synchronized_standby_slots
+ have confirmed WAL receipt.
+
+
+
+
+
+
+ pg_logical_slot_peek_changes
+
+ pg_logical_slot_peek_changes ( slot_namename, upto_lsnpg_lsn, upto_nchangesinteger, VARIADICoptionstext[] )
+ setof record
+ ( lsnpg_lsn,
+ xidxid,
+ datatext )
+
+
+ Behaves just like
+ the pg_logical_slot_get_changes() function,
+ except that changes are not consumed; that is, they will be returned
+ again on future calls.
+
+
+
+
+
+
+ pg_logical_slot_get_binary_changes
+
+ pg_logical_slot_get_binary_changes ( slot_namename, upto_lsnpg_lsn, upto_nchangesinteger, VARIADICoptionstext[] )
+ setof record
+ ( lsnpg_lsn,
+ xidxid,
+ databytea )
+
+
+ Behaves just like
+ the pg_logical_slot_get_changes() function,
+ except that changes are returned as bytea.
+
+
+
+
+
+
+ pg_logical_slot_peek_binary_changes
+
+ pg_logical_slot_peek_binary_changes ( slot_namename, upto_lsnpg_lsn, upto_nchangesinteger, VARIADICoptionstext[] )
+ setof record
+ ( lsnpg_lsn,
+ xidxid,
+ databytea )
+
+
+ Behaves just like
+ the pg_logical_slot_peek_changes() function,
+ except that changes are returned as bytea.
+
+
+
+
+
+
+ pg_replication_slot_advance
+
+ pg_replication_slot_advance ( slot_namename, upto_lsnpg_lsn )
+ record
+ ( slot_namename,
+ end_lsnpg_lsn )
+
+
+ Advances the current confirmed position of a replication slot named
+ slot_name. 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. If the specified slot is a
+ logical failover slot then the function will not return until all
+ physical slots specified in
+ synchronized_standby_slots
+ have confirmed WAL receipt.
+
+
+
+
+
+
+ pg_replication_origin_create
+
+ pg_replication_origin_create ( node_nametext )
+ oid
+
+
+ Creates a replication origin with the given external
+ name, and returns the internal ID assigned to it.
+ The name must be no longer than 512 bytes.
+
+
+
+
+
+
+ pg_replication_origin_drop
+
+ pg_replication_origin_drop ( node_nametext )
+ void
+
+
+ Deletes a previously-created replication origin, including any
+ associated replay progress.
+
+
+
+
+
+
+ pg_replication_origin_oid
+
+ pg_replication_origin_oid ( node_nametext )
+ oid
+
+
+ Looks up a replication origin by name and returns the internal ID. If
+ no such replication origin is found, NULL is
+ returned.
+
+
+
+
+
+
+ pg_replication_origin_session_setup
+
+ pg_replication_origin_session_setup ( node_nametext )
+ void
+
+
+ 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 pg_replication_origin_session_reset to undo.
+
+
+
+
+
+
+ pg_replication_origin_session_reset
+
+ pg_replication_origin_session_reset ()
+ void
+
+
+ Cancels the effects
+ of pg_replication_origin_session_setup().
+
+
+
+
+
+
+ pg_replication_origin_session_is_setup
+
+ pg_replication_origin_session_is_setup ()
+ boolean
+
+
+ Returns true if a replication origin has been selected in the
+ current session.
+
+
+
+
+
+
+ pg_replication_origin_session_progress
+
+ pg_replication_origin_session_progress ( flushboolean )
+ pg_lsn
+
+
+ Returns the replay location for the replication origin selected in
+ the current session. The parameter flush
+ determines whether the corresponding local transaction will be
+ guaranteed to have been flushed to disk or not.
+
+
+
+
+
+
+ pg_replication_origin_xact_setup
+
+ pg_replication_origin_xact_setup ( origin_lsnpg_lsn, origin_timestamptimestamp with time zone )
+ void
+
+
+ Marks the current transaction as replaying a transaction that has
+ committed at the given LSN and timestamp. Can
+ only be called when a replication origin has been selected
+ using pg_replication_origin_session_setup.
+
+
+
+
+
+
+ pg_replication_origin_xact_reset
+
+ pg_replication_origin_xact_reset ()
+ void
+
+
+ Cancels the effects of
+ pg_replication_origin_xact_setup().
+
+
+
+
+
+
+ pg_replication_origin_advance
+
+ pg_replication_origin_advance ( node_nametext, lsnpg_lsn )
+ void
+
+
+ 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.
+
+
+
+
+
+
+ pg_replication_origin_progress
+
+ pg_replication_origin_progress ( node_nametext, flushboolean )
+ pg_lsn
+
+
+ Returns the replay location for the given replication origin. The
+ parameter flush determines whether the
+ corresponding local transaction will be guaranteed to have been
+ flushed to disk or not.
+
+
+
+
+
+
+ pg_logical_emit_message
+
+ pg_logical_emit_message ( transactionalboolean, prefixtext, contenttext, flushbooleanDEFAULTfalse )
+ pg_lsn
+
+
+ pg_logical_emit_message ( transactionalboolean, prefixtext, contentbytea, flushbooleanDEFAULTfalse )
+ pg_lsn
+
+
+ Emits a logical decoding message. This can be used to pass generic
+ messages to logical decoding plugins through
+ WAL. The transactional 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 prefix parameter is a
+ textual prefix that can be used by logical decoding plugins to easily
+ recognize messages that are interesting for them.
+ The content parameter is the content of the
+ message, given either in text or binary form.
+ The flush parameter (default set to
+ false) controls if the message is immediately
+ flushed to WAL or not. flush has no effect
+ with transactional, as the message's WAL
+ record is flushed along with its transaction.
+
+
+
+
+
+
+ pg_sync_replication_slots
+
+ pg_sync_replication_slots ()
+ void
+
+
+ Synchronize the logical failover replication slots from the primary
+ server to the standby server. This function can only be executed on the
+ standby server. Temporary synced slots, if any, cannot be used for
+ logical decoding and must be dropped after promotion. See
+ for details.
+ Note that this function is primarily intended for testing and
+ debugging purposes and should be used with caution. Additionally,
+ this function cannot be executed if
+
+ sync_replication_slots is enabled and the slotsync
+ worker is already running to perform the synchronization of slots.
+
+
+
+
+ If, after executing the function,
+
+ hot_standby_feedback is disabled on
+ the standby or the physical slot configured in
+
+ primary_slot_name is
+ removed, then it is possible that the necessary rows of the
+ synchronized slot will be removed by the VACUUM process on the primary
+ server, resulting in the synchronized slot becoming invalidated.
+
+
+
+
+
+
+
+
+
+
+
+
+ Database Object Management Functions
+
+
+ The functions shown in calculate
+ the disk space usage of database objects, or assist in presentation
+ or understanding of usage results. bigint results
+ are measured in bytes. If an OID that does
+ not represent an existing object is passed to one of these
+ functions, NULL is returned.
+
+
+
+ Database Object Size Functions
+
+
+
+
+ Function
+
+
+ Description
+
+
+
+
+
+
+
+
+ pg_column_size
+
+ pg_column_size ( "any" )
+ integer
+
+
+ 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.
+
+
+
+
+
+
+ pg_column_compression
+
+ pg_column_compression ( "any" )
+ text
+
+
+ Shows the compression algorithm that was used to compress
+ an individual variable-length value. Returns NULL
+ if the value is not compressed.
+
+
+
+
+
+
+ pg_column_toast_chunk_id
+
+ pg_column_toast_chunk_id ( "any" )
+ oid
+
+
+ Shows the chunk_id of an on-disk
+ TOASTed value. Returns NULL
+ if the value is un-TOASTed or not on-disk. See
+ for more information about
+ TOAST.
+
+
+
+
+
+
+ pg_database_size
+
+ pg_database_size ( name )
+ bigint
+
+
+ pg_database_size ( oid )
+ bigint
+
+
+ Computes the total disk space used by the database with the specified
+ name or OID. To use this function, you must
+ have CONNECT privilege on the specified database
+ (which is granted by default) or have privileges of
+ the pg_read_all_stats role.
+
+
+
+
+
+
+ pg_indexes_size
+
+ pg_indexes_size ( regclass )
+ bigint
+
+
+ Computes the total disk space used by indexes attached to the
+ specified table.
+
+
+
+
+
+
+ pg_relation_size
+
+ pg_relation_size ( relationregclass, forktext )
+ bigint
+
+
+ Computes the disk space used by one fork of the
+ specified relation. (Note that for most purposes it is more
+ convenient to use the higher-level
+ functions pg_total_relation_size
+ or pg_table_size, 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:
+
+
+
+ main returns the size of the main
+ data fork of the relation.
+
+
+
+
+ fsm returns the size of the Free Space Map
+ (see ) associated with the relation.
+
+
+
+
+ vm returns the size of the Visibility Map
+ (see ) associated with the relation.
+
+
+
+
+ init returns the size of the initialization
+ fork, if any, associated with the relation.
+
+
+
+
+
+
+
+
+
+ pg_size_bytes
+
+ pg_size_bytes ( text )
+ bigint
+
+
+ Converts a size in human-readable format (as returned
+ by pg_size_pretty) into bytes. Valid units are
+ bytes, B, kB,
+ MB, GB, TB,
+ and PB.
+
+
+
+
+
+
+ pg_size_pretty
+
+ pg_size_pretty ( bigint )
+ text
+
+
+ pg_size_pretty ( numeric )
+ text
+
+
+ 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 10242 = 1048576 bytes, and so on.
+
+
+
+
+
+
+ pg_table_size
+
+ pg_table_size ( regclass )
+ bigint
+
+
+ Computes the disk space used by the specified table, excluding indexes
+ (but including its TOAST table if any, free space map, and visibility
+ map).
+
+
+
+
+
+
+ pg_tablespace_size
+
+ pg_tablespace_size ( name )
+ bigint
+
+
+ pg_tablespace_size ( oid )
+ bigint
+
+
+ Computes the total disk space used in the tablespace with the
+ specified name or OID. To use this function, you must
+ have CREATE privilege on the specified tablespace
+ or have privileges of the pg_read_all_stats role,
+ unless it is the default tablespace for the current database.
+
+
+
+
+
+
+ pg_total_relation_size
+
+ pg_total_relation_size ( regclass )
+ bigint
+
+
+ Computes the total disk space used by the specified table, including
+ all indexes and TOAST data. The result is
+ equivalent to pg_table_size
+ +pg_indexes_size.
+
+
+
+
+
+
+
+ The functions above that operate on tables or indexes accept a
+ regclass argument, which is simply the OID of the table or index
+ in the pg_class system catalog. You do not have to look up
+ the OID by hand, however, since the regclass data type's input
+ converter will do the work for you. See
+ for details.
+
+
+
+ The functions shown in assist
+ in identifying the specific disk files associated with database objects.
+
+
+
+ Database Object Location Functions
+
+
+
+
+ Function
+
+
+ Description
+
+
+
+
+
+
+
+
+ pg_relation_filenode
+
+ pg_relation_filenode ( relationregclass )
+ oid
+
+
+ Returns the filenode number currently assigned to the
+ specified relation. The filenode is the base component of the file
+ name(s) used for the relation (see
+ for more information).
+ For most relations the result is the same as
+ pg_class.relfilenode,
+ but for certain system catalogs relfilenode
+ 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.
+
+
+
+
+
+
+ pg_relation_filepath
+
+ pg_relation_filepath ( relationregclass )
+ text
+
+
+ Returns the entire file path name (relative to the database cluster's
+ data directory, PGDATA) of the relation.
+
+
+
+
+
+
+ pg_filenode_relation
+
+ pg_filenode_relation ( tablespaceoid, filenodeoid )
+ regclass
+
+
+ Returns a relation's OID given the tablespace OID and filenode it is
+ stored under. This is essentially the inverse mapping of
+ pg_relation_filepath. For a relation in the
+ database's default tablespace, the tablespace can be specified as zero.
+ Returns NULL if no relation in the current database
+ is associated with the given values, or if dealing with a temporary
+ relation.
+
+
+
+
+
+
+
+ lists functions used to manage
+ collations.
+
+
+
+ Collation Management Functions
+
+
+
+
+ Function
+
+
+ Description
+
+
+
+
+
+
+
+
+ pg_collation_actual_version
+
+ pg_collation_actual_version ( oid )
+ text
+
+
+ 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
+ pg_collation.collversion,
+ then objects depending on the collation might need to be rebuilt. See
+ also .
+
+
+
+
+
+
+ pg_database_collation_actual_version
+
+ pg_database_collation_actual_version ( oid )
+ text
+
+
+ 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
+ pg_database.datcollversion,
+ then objects depending on the collation might need to be rebuilt. See
+ also .
+
+
+
+
+
+
+ pg_import_system_collations
+
+ pg_import_system_collations ( schemaregnamespace )
+ integer
+
+
+ Adds collations to the system
+ catalog pg_collation based on all the locales
+ it finds in the operating system. This is
+ what initdb uses; see
+ for more details. If additional
+ locales are installed into the operating system later on, this
+ function can be run again to add collations for the new locales.
+ Locales that match existing entries
+ in pg_collation will be skipped. (But
+ collation objects based on locales that are no longer present in the
+ operating system are not removed by this function.)
+ The schema parameter would typically
+ be pg_catalog, 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.
+
+
+
+
+
+
+
+ lists functions used to
+ manipulate statistics.
+ These functions cannot be executed during recovery.
+
+
+ Changes made by these statistics manipulation functions are likely to be
+ overwritten by autovacuum (or manual
+ VACUUM or ANALYZE) and should be
+ considered temporary.
+
+
+
+
+
+ Database Object Statistics Manipulation Functions
+
+
+
+
+ Function
+
+
+ Description
+
+
+
+
+
+
+
+
+ pg_restore_relation_stats
+
+ pg_restore_relation_stats (
+ VARIADICkwargs"any" )
+ boolean
+
+
+ Updates table-level statistics. Ordinarily, these statistics are
+ collected automatically or updated as a part of or , so it's not
+ necessary to call this function. However, it is useful after a
+ restore to enable the optimizer to choose better plans if
+ ANALYZE has not been run yet.
+
+
+ The tracked statistics may change from version to version, so
+ arguments are passed as pairs of argname
+ and argvalue in the form:
+
+SELECT pg_restore_relation_stats(
+ 'arg1name', 'arg1value'::arg1type,
+ 'arg2name', 'arg2value'::arg2type,
+ 'arg3name', 'arg3value'::arg3type);
+
+
+
+ For example, to set the relpages and
+ reltuples values for the table
+ mytable:
+
+SELECT pg_restore_relation_stats(
+ 'schemaname', 'myschema',
+ 'relname', 'mytable',
+ 'relpages', 173::integer,
+ 'reltuples', 10000::real);
+
+
+
+ The arguments schemaname and
+ relname are required, and specify the table. Other
+ arguments are the names and values of statistics corresponding to
+ certain columns in pg_class.
+ The currently-supported relation statistics are
+ relpages with a value of type
+ integer, reltuples with a value of
+ type real, relallvisible with a value
+ of type integer, and relallfrozen
+ with a value of type integer.
+
+
+ Additionally, this function accepts argument name
+ version of type integer, which
+ specifies the server version from which the statistics originated.
+ This is anticipated to be helpful in porting statistics from older
+ versions of PostgreSQL.
+
+
+ Minor errors are reported as a WARNING and
+ ignored, and remaining statistics will still be restored. If all
+ specified statistics are successfully restored, returns
+ true, otherwise false.
+
+
+ The caller must have the MAINTAIN privilege on the
+ table or be the owner of the database.
+
+
+
+
+
+
+
+
+ pg_clear_relation_stats
+
+ pg_clear_relation_stats ( schemanametext, relnametext )
+ void
+
+
+ Clears table-level statistics for the given relation, as though the
+ table was newly created.
+
+
+ The caller must have the MAINTAIN privilege on the
+ table or be the owner of the database.
+
+
+
+
+
+
+
+ pg_restore_attribute_stats
+
+ pg_restore_attribute_stats (
+ VARIADICkwargs"any" )
+ boolean
+
+
+ Creates or updates column-level statistics. Ordinarily, these
+ statistics are collected automatically or updated as a part of or , so it's not
+ necessary to call this function. However, it is useful after a
+ restore to enable the optimizer to choose better plans if
+ ANALYZE has not been run yet.
+
+
+ The tracked statistics may change from version to version, so
+ arguments are passed as pairs of argname
+ and argvalue in the form:
+
+SELECT pg_restore_attribute_stats(
+ 'arg1name', 'arg1value'::arg1type,
+ 'arg2name', 'arg2value'::arg2type,
+ 'arg3name', 'arg3value'::arg3type);
+
+
+
+ For example, to set the avg_width and
+ null_frac values for the attribute
+ col1 of the table
+ mytable:
+
+SELECT pg_restore_attribute_stats(
+ 'schemaname', 'myschema',
+ 'relname', 'mytable',
+ 'attname', 'col1',
+ 'inherited', false,
+ 'avg_width', 125::integer,
+ 'null_frac', 0.5::real);
+
+
+
+ The required arguments are schemaname and
+ relname with a value of type text
+ which specify the table; either attname with a
+ value of type text or attnum with a
+ value of type smallint, which specifies the column; and
+ inherited, which specifies whether the statistics
+ include values from child tables. Other arguments are the names and
+ values of statistics corresponding to columns in pg_stats.
+
+
+ Additionally, this function accepts argument name
+ version of type integer, which
+ specifies the server version from which the statistics originated.
+ This is anticipated to be helpful in porting statistics from older
+ versions of PostgreSQL.
+
+
+ Minor errors are reported as a WARNING and
+ ignored, and remaining statistics will still be restored. If all
+ specified statistics are successfully restored, returns
+ true, otherwise false.
+
+
+ The caller must have the MAINTAIN privilege on the
+ table or be the owner of the database.
+
+
+
+
+
+
+
+
+ pg_clear_attribute_stats
+
+ pg_clear_attribute_stats (
+ schemanametext,
+ relnametext,
+ attnametext,
+ inheritedboolean )
+ void
+
+
+ Clears column-level statistics for the given relation and
+ attribute, as though the table was newly created.
+
+
+ The caller must have the MAINTAIN privilege on
+ the table or be the owner of the database.
+
+
+
+
+
+
+
+
+ lists functions that provide
+ information about the structure of partitioned tables.
+
+
+
+ Partitioning Information Functions
+
+
+
+
+ Function
+
+
+ Description
+
+
+
+
+
+
+
+
+ pg_partition_tree
+
+ pg_partition_tree ( regclass )
+ setof record
+ ( relidregclass,
+ parentrelidregclass,
+ isleafboolean,
+ levelinteger )
+
+
+ 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.
+
+
+
+
+
+
+ pg_partition_ancestors
+
+ pg_partition_ancestors ( regclass )
+ setof regclass
+
+
+ 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.
+
+
+
+
+
+
+ pg_partition_root
+
+ pg_partition_root ( regclass )
+ regclass
+
+
+ Returns the top-most parent of the partition tree to which the given
+ relation belongs. Returns NULL if the relation
+ does not exist or is not a partition or partitioned table.
+
+
+
+
+
+
+
+ For example, to check the total size of the data contained in a
+ partitioned table measurement, one could use the
+ following query:
+
+SELECT pg_size_pretty(sum(pg_relation_size(relid))) AS total_size
+ FROM pg_partition_tree('measurement');
+
+
+
+
+
+
+ Index Maintenance Functions
+
+
+ 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.
+
+
+
+ Index Maintenance Functions
+
+
+
+
+ Function
+
+
+ Description
+
+
+
+
+
+
+
+
+ brin_summarize_new_values
+
+ brin_summarize_new_values ( indexregclass )
+ integer
+
+
+ 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.
+
+
+
+
+
+
+ brin_summarize_range
+
+ brin_summarize_range ( indexregclass, blockNumberbigint )
+ integer
+
+
+ Summarizes the page range covering the given block, if not already
+ summarized. This is
+ like brin_summarize_new_values except that it
+ only processes the page range that covers the given table block number.
+
+
+
+
+
+
+ brin_desummarize_range
+
+ brin_desummarize_range ( indexregclass, blockNumberbigint )
+ void
+
+
+ Removes the BRIN index tuple that summarizes the page range covering
+ the given table block, if there is one.
+
+
+
+
+
+
+ gin_clean_pending_list
+
+ gin_clean_pending_list ( indexregclass )
+ bigint
+
+
+ Cleans up the pending 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 fastupdate option disabled, no cleanup happens
+ and the result is zero, because the index doesn't have a pending list.
+ See and
+ for details about the pending list and fastupdate
+ option.
+
+
+
+
+
+
+
+
+
+ Generic File Access Functions
+
+
+ The functions shown in provide native access to
+ files on the machine hosting the server. Only files within the
+ database cluster directory and the log_directory can be
+ accessed, unless the user is a superuser or is granted the role
+ pg_read_server_files. Use a relative path for files in
+ the cluster directory, and a path matching the log_directory
+ configuration setting for log files.
+
+
+
+ Note that granting users the EXECUTE privilege on
+ pg_read_file(), 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 pg_authid 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.
+
+
+
+ When granting privilege on these functions, note that the table entries
+ showing optional parameters are mostly implemented as several physical
+ functions with different parameter lists. Privilege must be granted
+ separately on each such function, if it is to be
+ used. psql's \df command
+ can be useful to check what the actual function signatures are.
+
+
+
+ Some of these functions take an optional missing_ok
+ parameter, which specifies the behavior when the file or directory does
+ not exist. If true, the function
+ returns NULL or an empty result set, as appropriate.
+ If false, an error is raised. (Failure conditions
+ other than file not found are reported as errors in any
+ case.) The default is false.
+
+
+
+ Generic File Access Functions
+
+
+
+
+ Function
+
+
+ Description
+
+
+
+
+
+
+
+
+ pg_ls_dir
+
+ pg_ls_dir ( dirnametext, missing_okboolean, include_dot_dirsboolean )
+ setof text
+
+
+ Returns the names of all files (and directories and other special
+ files) in the specified
+ directory. The include_dot_dirs parameter
+ indicates whether . and .. are to be
+ included in the result set; the default is to exclude them. Including
+ them can be useful when missing_ok
+ is true, to distinguish an empty directory from a
+ non-existent directory.
+
+
+ This function is restricted to superusers by default, but other users
+ can be granted EXECUTE to run the function.
+
+
+
+
+
+
+ pg_ls_logdir
+
+ pg_ls_logdir ()
+ setof record
+ ( nametext,
+ sizebigint,
+ modificationtimestamp with time zone )
+
+
+ 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.
+
+
+ This function is restricted to superusers and roles with privileges of
+ the pg_monitor role by default, but other users can
+ be granted EXECUTE to run the function.
+
+
+
+
+
+
+ pg_ls_waldir
+
+ pg_ls_waldir ()
+ setof record
+ ( nametext,
+ sizebigint,
+ modificationtimestamp with time zone )
+
+
+ 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.
+
+
+ This function is restricted to superusers and roles with privileges of
+ the pg_monitor role by default, but other users can
+ be granted EXECUTE to run the function.
+
+
+
+
+
+
+ pg_ls_logicalmapdir
+
+ pg_ls_logicalmapdir ()
+ setof record
+ ( nametext,
+ sizebigint,
+ modificationtimestamp with time zone )
+
+
+ Returns the name, size, and last modification time (mtime) of each
+ ordinary file in the server's pg_logical/mappings
+ directory. Filenames beginning with a dot, directories, and other
+ special files are excluded.
+
+
+ This function is restricted to superusers and members of
+ the pg_monitor role by default, but other users can
+ be granted EXECUTE to run the function.
+
+
+
+
+
+
+ pg_ls_logicalsnapdir
+
+ pg_ls_logicalsnapdir ()
+ setof record
+ ( nametext,
+ sizebigint,
+ modificationtimestamp with time zone )
+
+
+ Returns the name, size, and last modification time (mtime) of each
+ ordinary file in the server's pg_logical/snapshots
+ directory. Filenames beginning with a dot, directories, and other
+ special files are excluded.
+
+
+ This function is restricted to superusers and members of
+ the pg_monitor role by default, but other users can
+ be granted EXECUTE to run the function.
+
+
+
+
+
+
+ pg_ls_replslotdir
+
+ pg_ls_replslotdir ( slot_nametext )
+ setof record
+ ( nametext,
+ sizebigint,
+ modificationtimestamp with time zone )
+
+
+ Returns the name, size, and last modification time (mtime) of each
+ ordinary file in the server's pg_replslot/slot_name
+ directory, where slot_name 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.
+
+
+ This function is restricted to superusers and members of
+ the pg_monitor role by default, but other users can
+ be granted EXECUTE to run the function.
+
+
+
+
+
+
+ pg_ls_summariesdir
+
+ pg_ls_summariesdir ()
+ setof record
+ ( nametext,
+ sizebigint,
+ modificationtimestamp with time zone )
+
+
+ Returns the name, size, and last modification time (mtime) of each
+ ordinary file in the server's WAL summaries directory
+ (pg_wal/summaries). Filenames beginning
+ with a dot, directories, and other special files are excluded.
+
+
+ This function is restricted to superusers and members of
+ the pg_monitor role by default, but other users can
+ be granted EXECUTE to run the function.
+
+
+
+
+
+
+ pg_ls_archive_statusdir
+
+ pg_ls_archive_statusdir ()
+ setof record
+ ( nametext,
+ sizebigint,
+ modificationtimestamp with time zone )
+
+
+ Returns the name, size, and last modification time (mtime) of each
+ ordinary file in the server's WAL archive status directory
+ (pg_wal/archive_status). Filenames beginning
+ with a dot, directories, and other special files are excluded.
+
+
+ This function is restricted to superusers and members of
+ the pg_monitor role by default, but other users can
+ be granted EXECUTE to run the function.
+
+
+
+
+
+
+
+ pg_ls_tmpdir
+
+ pg_ls_tmpdir ( tablespaceoid )
+ setof record
+ ( nametext,
+ sizebigint,
+ modificationtimestamp with time zone )
+
+
+ Returns the name, size, and last modification time (mtime) of each
+ ordinary file in the temporary file directory for the
+ specified tablespace.
+ If tablespace is not provided,
+ the pg_default tablespace is examined. Filenames
+ beginning with a dot, directories, and other special files are
+ excluded.
+
+
+ This function is restricted to superusers and members of
+ the pg_monitor role by default, but other users can
+ be granted EXECUTE to run the function.
+
+
+
+
+
+
+ pg_read_file
+
+ pg_read_file ( filenametext, offsetbigint, lengthbigint, missing_okboolean )
+ text
+
+
+ Returns all or part of a text file, starting at the
+ given byte offset, returning at
+ most length bytes (less if the end of file is
+ reached first). If offset is negative, it is
+ relative to the end of the file. If offset
+ and length 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.
+
+
+ This function is restricted to superusers by default, but other users
+ can be granted EXECUTE to run the function.
+
+
+
+
+
+
+ pg_read_binary_file
+
+ pg_read_binary_file ( filenametext, offsetbigint, lengthbigint, missing_okboolean )
+ bytea
+
+
+ Returns all or part of a file. This function is identical to
+ pg_read_file except that it can read arbitrary
+ binary data, returning the result as bytea
+ not text; accordingly, no encoding checks are performed.
+
+
+ This function is restricted to superusers by default, but other users
+ can be granted EXECUTE to run the function.
+
+
+ In combination with the convert_from function,
+ this function can be used to read a text file in a specified encoding
+ and convert to the database's encoding:
+
+SELECT convert_from(pg_read_binary_file('file_in_utf8.txt'), 'UTF8');
+
+
+
+
+
+
+
+ pg_stat_file
+
+ pg_stat_file ( filenametext, missing_okboolean )
+ record
+ ( sizebigint,
+ accesstimestamp with time zone,
+ modificationtimestamp with time zone,
+ changetimestamp with time zone,
+ creationtimestamp with time zone,
+ isdirboolean )
+
+
+ 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.
+
+
+ This function is restricted to superusers by default, but other users
+ can be granted EXECUTE to run the function.
+
+
+
+
+
+
+
+
+
+
+ Advisory Lock Functions
+
+
+ The functions shown in
+ manage advisory locks. For details about proper use of these functions,
+ see .
+
+
+
+ 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 false 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.
+
+
+
+ Advisory Lock Functions
+
+
+
+
+ Function
+
+
+ Description
+
+
+
+
+
+
+
+
+ pg_advisory_lock
+
+ pg_advisory_lock ( keybigint )
+ void
+
+
+ pg_advisory_lock ( key1integer, key2integer )
+ void
+
+
+ Obtains an exclusive session-level advisory lock, waiting if necessary.
+
+
+
+
+
+
+ pg_advisory_lock_shared
+
+ pg_advisory_lock_shared ( keybigint )
+ void
+
+
+ pg_advisory_lock_shared ( key1integer, key2integer )
+ void
+
+
+ Obtains a shared session-level advisory lock, waiting if necessary.
+
+
+
+
+
+
+ pg_advisory_unlock
+
+ pg_advisory_unlock ( keybigint )
+ boolean
+
+
+ pg_advisory_unlock ( key1integer, key2integer )
+ boolean
+
+
+ Releases a previously-acquired exclusive session-level advisory lock.
+ Returns true if the lock is successfully released.
+ If the lock was not held, false is returned, and in
+ addition, an SQL warning will be reported by the server.
+
+
+
+
+
+
+ pg_advisory_unlock_all
+
+ pg_advisory_unlock_all ()
+ void
+
+
+ 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.)
+
+
+
+
+
+
+ pg_advisory_unlock_shared
+
+ pg_advisory_unlock_shared ( keybigint )
+ boolean
+
+
+ pg_advisory_unlock_shared ( key1integer, key2integer )
+ boolean
+
+
+ Releases a previously-acquired shared session-level advisory lock.
+ Returns true if the lock is successfully released.
+ If the lock was not held, false is returned, and in
+ addition, an SQL warning will be reported by the server.
+
+
+
+
+
+
+ pg_advisory_xact_lock
+
+ pg_advisory_xact_lock ( keybigint )
+ void
+
+
+ pg_advisory_xact_lock ( key1integer, key2integer )
+ void
+
+
+ Obtains an exclusive transaction-level advisory lock, waiting if
+ necessary.
+
+
+
+
+
+
+ pg_advisory_xact_lock_shared
+
+ pg_advisory_xact_lock_shared ( keybigint )
+ void
+
+
+ pg_advisory_xact_lock_shared ( key1integer, key2integer )
+ void
+
+
+ Obtains a shared transaction-level advisory lock, waiting if
+ necessary.
+
+
+
+
+
+
+ pg_try_advisory_lock
+
+ pg_try_advisory_lock ( keybigint )
+ boolean
+
+
+ pg_try_advisory_lock ( key1integer, key2integer )
+ boolean
+
+
+ Obtains an exclusive session-level advisory lock if available.
+ This will either obtain the lock immediately and
+ return true, or return false
+ without waiting if the lock cannot be acquired immediately.
+
+
+
+
+
+
+ pg_try_advisory_lock_shared
+
+ pg_try_advisory_lock_shared ( keybigint )
+ boolean
+
+
+ pg_try_advisory_lock_shared ( key1integer, key2integer )
+ boolean
+
+
+ Obtains a shared session-level advisory lock if available.
+ This will either obtain the lock immediately and
+ return true, or return false
+ without waiting if the lock cannot be acquired immediately.
+
+
+
+
+
+
+ pg_try_advisory_xact_lock
+
+ pg_try_advisory_xact_lock ( keybigint )
+ boolean
+
+
+ pg_try_advisory_xact_lock ( key1integer, key2integer )
+ boolean
+
+
+ Obtains an exclusive transaction-level advisory lock if available.
+ This will either obtain the lock immediately and
+ return true, or return false
+ without waiting if the lock cannot be acquired immediately.
+
+
+
+
+
+
+ pg_try_advisory_xact_lock_shared
+
+ pg_try_advisory_xact_lock_shared ( keybigint )
+ boolean
+
+
+ pg_try_advisory_xact_lock_shared ( key1integer, key2integer )
+ boolean
+
+
+ Obtains a shared transaction-level advisory lock if available.
+ This will either obtain the lock immediately and
+ return true, or return false
+ without waiting if the lock cannot be acquired immediately.
+
+
+
+
+
+
+
+
+
diff --git a/doc/src/sgml/func/func-aggregate.sgml b/doc/src/sgml/func/func-aggregate.sgml
new file mode 100644
index 0000000000000..f50b692516b62
--- /dev/null
+++ b/doc/src/sgml/func/func-aggregate.sgml
@@ -0,0 +1,1418 @@
+
+ Aggregate Functions
+
+
+ aggregate function
+ built-in
+
+
+
+ Aggregate functions compute a single result
+ from a set of input values. The built-in general-purpose aggregate
+ functions are listed in
+ while statistical aggregates are in .
+ The built-in within-group ordered-set aggregate functions
+ are listed in
+ while the built-in within-group hypothetical-set ones are in . Grouping operations,
+ which are closely related to aggregate functions, are listed in
+ .
+ The special syntax considerations for aggregate
+ functions are explained in .
+ Consult for additional introductory
+ information.
+
+
+
+ Aggregate functions that support Partial Mode
+ are eligible to participate in various optimizations, such as parallel
+ aggregation.
+
+
+
+ While all aggregates below accept an optional
+ ORDER BY clause (as outlined in ), the clause has only been added to
+ aggregates whose output is affected by ordering.
+
+
+
+ General-Purpose Aggregate Functions
+
+
+
+
+
+
+ Function
+
+
+ Description
+
+ Partial Mode
+
+
+
+
+
+
+
+ any_value
+
+ any_value ( anyelement )
+ same as input type
+
+
+ Returns an arbitrary value from the non-null input values.
+
+ Yes
+
+
+
+
+
+ array_agg
+
+ array_agg ( anynonarrayORDER BYinput_sort_columns )
+ anyarray
+
+
+ Collects all the input values, including nulls, into an array.
+
+ Yes
+
+
+
+
+ array_agg ( anyarrayORDER BYinput_sort_columns )
+ anyarray
+
+
+ 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.)
+
+ Yes
+
+
+
+
+
+ average
+
+
+ avg
+
+ avg ( smallint )
+ numeric
+
+
+ avg ( integer )
+ numeric
+
+
+ avg ( bigint )
+ numeric
+
+
+ avg ( numeric )
+ numeric
+
+
+ avg ( real )
+ double precision
+
+
+ avg ( double precision )
+ double precision
+
+
+ avg ( interval )
+ interval
+
+
+ Computes the average (arithmetic mean) of all the non-null input
+ values.
+
+ Yes
+
+
+
+
+
+ bit_and
+
+ bit_and ( smallint )
+ smallint
+
+
+ bit_and ( integer )
+ integer
+
+
+ bit_and ( bigint )
+ bigint
+
+
+ bit_and ( bit )
+ bit
+
+
+ Computes the bitwise AND of all non-null input values.
+
+ Yes
+
+
+
+
+
+ bit_or
+
+ bit_or ( smallint )
+ smallint
+
+
+ bit_or ( integer )
+ integer
+
+
+ bit_or ( bigint )
+ bigint
+
+
+ bit_or ( bit )
+ bit
+
+
+ Computes the bitwise OR of all non-null input values.
+
+ Yes
+
+
+
+
+
+ bit_xor
+
+ bit_xor ( smallint )
+ smallint
+
+
+ bit_xor ( integer )
+ integer
+
+
+ bit_xor ( bigint )
+ bigint
+
+
+ bit_xor ( bit )
+ bit
+
+
+ Computes the bitwise exclusive OR of all non-null input values.
+ Can be useful as a checksum for an unordered set of values.
+
+ Yes
+
+
+
+
+
+ bool_and
+
+ bool_and ( boolean )
+ boolean
+
+
+ Returns true if all non-null input values are true, otherwise false.
+
+ Yes
+
+
+
+
+
+ bool_or
+
+ bool_or ( boolean )
+ boolean
+
+
+ Returns true if any non-null input value is true, otherwise false.
+
+ Yes
+
+
+
+
+
+ count
+
+ count ( * )
+ bigint
+
+
+ Computes the number of input rows.
+
+ Yes
+
+
+
+
+ count ( "any" )
+ bigint
+
+
+ Computes the number of input rows in which the input value is not
+ null.
+
+ Yes
+
+
+
+
+
+ every
+
+ every ( boolean )
+ boolean
+
+
+ This is the SQL standard's equivalent to bool_and.
+
+ Yes
+
+
+
+
+
+ json_agg
+
+ json_agg ( anyelementORDER BYinput_sort_columns )
+ json
+
+
+
+ jsonb_agg
+
+ jsonb_agg ( anyelementORDER BYinput_sort_columns )
+ jsonb
+
+
+ Collects all the input values, including nulls, into a JSON array.
+ Values are converted to JSON as per to_json
+ or to_jsonb.
+
+ No
+
+
+
+
+
+ json_agg_strict
+
+ json_agg_strict ( anyelement )
+ json
+
+
+
+ jsonb_agg_strict
+
+ jsonb_agg_strict ( anyelement )
+ jsonb
+
+
+ Collects all the input values, skipping nulls, into a JSON array.
+ Values are converted to JSON as per to_json
+ or to_jsonb.
+
+ No
+
+
+
+
+ json_arrayagg
+ json_arrayagg (
+ value_expression
+ ORDER BYsort_expression
+ { NULL | ABSENT } ON NULL
+ RETURNINGdata_typeFORMAT JSONENCODING UTF8)
+
+
+ Behaves in the same way as json_array
+ but as an aggregate function so it only takes one
+ value_expression parameter.
+ If ABSENT ON NULL is specified, any NULL
+ values are omitted.
+ If ORDER BY is specified, the elements will
+ appear in the array in that order rather than in the input order.
+
+
+ SELECT json_arrayagg(v) FROM (VALUES(2),(1)) t(v)
+ [2, 1]
+
+ No
+
+
+
+
+ json_objectagg
+ json_objectagg (
+ { key_expression { VALUE | ':' } value_expression }
+ { NULL | ABSENT } ON NULL
+ { WITH | WITHOUT } UNIQUEKEYS
+ RETURNINGdata_typeFORMAT JSONENCODING UTF8)
+
+
+ Behaves like json_object, but as an
+ aggregate function, so it only takes one
+ key_expression and one
+ value_expression parameter.
+
+
+ SELECT json_objectagg(k:v) FROM (VALUES ('a'::text,current_date),('b',current_date + 1)) AS t(k,v)
+ { "a" : "2022-05-10", "b" : "2022-05-11" }
+
+ No
+
+
+
+
+
+ json_object_agg
+
+ json_object_agg ( key
+ "any", value
+ "any"
+ ORDER BYinput_sort_columns )
+ json
+
+
+
+ jsonb_object_agg
+
+ jsonb_object_agg ( key
+ "any", value
+ "any"
+ ORDER BYinput_sort_columns )
+ jsonb
+
+
+ Collects all the key/value pairs into a JSON object. Key arguments
+ are coerced to text; value arguments are converted as per
+ to_json or to_jsonb.
+ Values can be null, but keys cannot.
+
+ No
+
+
+
+
+
+ json_object_agg_strict
+
+ json_object_agg_strict (
+ key"any",
+ value"any" )
+ json
+
+
+
+ jsonb_object_agg_strict
+
+ jsonb_object_agg_strict (
+ key"any",
+ value"any" )
+ jsonb
+
+
+ Collects all the key/value pairs into a JSON object. Key arguments
+ are coerced to text; value arguments are converted as per
+ to_json or to_jsonb.
+ The key can not be null. If the
+ value is null then the entry is skipped,
+
+ No
+
+
+
+
+
+ json_object_agg_unique
+
+ json_object_agg_unique (
+ key"any",
+ value"any" )
+ json
+
+
+
+ jsonb_object_agg_unique
+
+ jsonb_object_agg_unique (
+ key"any",
+ value"any" )
+ jsonb
+
+
+ Collects all the key/value pairs into a JSON object. Key arguments
+ are coerced to text; value arguments are converted as per
+ to_json or to_jsonb.
+ Values can be null, but keys cannot.
+ If there is a duplicate key an error is thrown.
+
+ No
+
+
+
+
+
+ json_object_agg_unique_strict
+
+ json_object_agg_unique_strict (
+ key"any",
+ value"any" )
+ json
+
+
+
+ jsonb_object_agg_unique_strict
+
+ jsonb_object_agg_unique_strict (
+ key"any",
+ value"any" )
+ jsonb
+
+
+ Collects all the key/value pairs into a JSON object. Key arguments
+ are coerced to text; value arguments are converted as per
+ to_json or to_jsonb.
+ The key can not be null. If the
+ value is null then the entry is skipped.
+ If there is a duplicate key an error is thrown.
+
+ No
+
+
+
+
+
+ max
+
+ max ( see text )
+ same as input type
+
+
+ Computes the maximum of the non-null input
+ values. Available for any numeric, string, date/time, or enum type,
+ as well as bytea, inet, interval,
+ money, oid, pg_lsn,
+ tid, xid8,
+ and also arrays and composite types containing sortable data types.
+
+ Yes
+
+
+
+
+
+ min
+
+ min ( see text )
+ same as input type
+
+
+ Computes the minimum of the non-null input
+ values. Available for any numeric, string, date/time, or enum type,
+ as well as bytea, inet, interval,
+ money, oid, pg_lsn,
+ tid, xid8,
+ and also arrays and composite types containing sortable data types.
+
+ Yes
+
+
+
+
+
+ range_agg
+
+ range_agg ( value
+ anyrange )
+ anymultirange
+
+
+ range_agg ( value
+ anymultirange )
+ anymultirange
+
+
+ Computes the union of the non-null input values.
+
+ No
+
+
+
+
+
+ range_intersect_agg
+
+ range_intersect_agg ( value
+ anyrange )
+ anyrange
+
+
+ range_intersect_agg ( value
+ anymultirange )
+ anymultirange
+
+
+ Computes the intersection of the non-null input values.
+
+ No
+
+
+
+
+
+ string_agg
+
+ string_agg ( value
+ text, delimitertext )
+ text
+
+
+ string_agg ( value
+ bytea, delimiterbytea
+ ORDER BYinput_sort_columns )
+ bytea
+
+
+ Concatenates the non-null input values into a string. Each value
+ after the first is preceded by the
+ corresponding delimiter (if it's not null).
+
+ Yes
+
+
+
+
+
+ sum
+
+ sum ( smallint )
+ bigint
+
+
+ sum ( integer )
+ bigint
+
+
+ sum ( bigint )
+ numeric
+
+
+ sum ( numeric )
+ numeric
+
+
+ sum ( real )
+ real
+
+
+ sum ( double precision )
+ double precision
+
+
+ sum ( interval )
+ interval
+
+
+ sum ( money )
+ money
+
+
+ Computes the sum of the non-null input values.
+
+ Yes
+
+
+
+
+
+ xmlagg
+
+ xmlagg ( xmlORDER BYinput_sort_columns )
+ xml
+
+
+ Concatenates the non-null XML input values (see
+ ).
+
+ No
+
+
+
+
+
+
+ It should be noted that except for count,
+ these functions return a null value when no rows are selected. In
+ particular, sum of no rows returns null, not
+ zero as one might expect, and array_agg
+ returns null rather than an empty array when there are no input
+ rows. The coalesce function can be used to
+ substitute zero or an empty array for null when necessary.
+
+
+
+ The aggregate functions array_agg,
+ json_agg, jsonb_agg,
+ json_agg_strict, jsonb_agg_strict,
+ json_object_agg, jsonb_object_agg,
+ json_object_agg_strict, jsonb_object_agg_strict,
+ json_object_agg_unique, jsonb_object_agg_unique,
+ json_object_agg_unique_strict,
+ jsonb_object_agg_unique_strict,
+ string_agg,
+ and xmlagg, 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
+ ORDER BY clause within the aggregate call, as shown in
+ .
+ Alternatively, supplying the input values from a sorted subquery
+ will usually work. For example:
+
+
+
+ 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.
+
+
+
+
+ ANY
+
+
+ SOME
+
+
+ The boolean aggregates bool_and and
+ bool_or correspond to the standard SQL aggregates
+ every and any or
+ some.
+ PostgreSQL
+ supports every, but not any
+ or some, because there is an ambiguity built into
+ the standard syntax:
+
+SELECT b1 = ANY((SELECT b2 FROM t2 ...)) FROM t1 ...;
+
+ Here ANY 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.
+
+
+
+
+
+ Users accustomed to working with other SQL database management
+ systems might be disappointed by the performance of the
+ count aggregate when it is applied to the
+ entire table. A query like:
+
+SELECT count(*) FROM sometable;
+
+ will require effort proportional to the size of the table:
+ PostgreSQL will need to scan either the
+ entire table or the entirety of an index that includes all rows in
+ the table.
+
+
+
+
+ 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 numeric_type are available for all
+ the types smallint, integer,
+ bigint, numeric, real,
+ and double precision.
+ Where the description mentions
+ N, 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 N is zero.
+
+
+
+ statistics
+
+
+ linear regression
+
+
+
+ Aggregate Functions for Statistics
+
+
+
+
+
+
+ Function
+
+
+ Description
+
+ Partial Mode
+
+
+
+
+
+
+
+ correlation
+
+
+ corr
+
+ corr ( Ydouble precision, Xdouble precision )
+ double precision
+
+
+ Computes the correlation coefficient.
+
+ Yes
+
+
+
+
+
+ covariance
+ population
+
+
+ covar_pop
+
+ covar_pop ( Ydouble precision, Xdouble precision )
+ double precision
+
+
+ Computes the population covariance.
+
+ Yes
+
+
+
+
+
+ covariance
+ sample
+
+
+ covar_samp
+
+ covar_samp ( Ydouble precision, Xdouble precision )
+ double precision
+
+
+ Computes the sample covariance.
+
+ Yes
+
+
+
+
+
+ regr_avgx
+
+ regr_avgx ( Ydouble precision, Xdouble precision )
+ double precision
+
+
+ Computes the average of the independent variable,
+ sum(X)/N.
+
+ Yes
+
+
+
+
+
+ regr_avgy
+
+ regr_avgy ( Ydouble precision, Xdouble precision )
+ double precision
+
+
+ Computes the average of the dependent variable,
+ sum(Y)/N.
+
+ Yes
+
+
+
+
+
+ regr_count
+
+ regr_count ( Ydouble precision, Xdouble precision )
+ bigint
+
+
+ Computes the number of rows in which both inputs are non-null.
+
+ Yes
+
+
+
+
+
+ regression intercept
+
+
+ regr_intercept
+
+ regr_intercept ( Ydouble precision, Xdouble precision )
+ double precision
+
+
+ Computes the y-intercept of the least-squares-fit linear equation
+ determined by the
+ (X, Y) pairs.
+
+ Yes
+
+
+
+
+
+ regr_r2
+
+ regr_r2 ( Ydouble precision, Xdouble precision )
+ double precision
+
+
+ Computes the square of the correlation coefficient.
+
+ Yes
+
+
+
+
+
+ regression slope
+
+
+ regr_slope
+
+ regr_slope ( Ydouble precision, Xdouble precision )
+ double precision
+
+
+ Computes the slope of the least-squares-fit linear equation determined
+ by the (X, Y)
+ pairs.
+
+ Yes
+
+
+
+
+
+ regr_sxx
+
+ regr_sxx ( Ydouble precision, Xdouble precision )
+ double precision
+
+
+ Computes the sum of squares of the independent
+ variable,
+ sum(X^2) - sum(X)^2/N.
+
+ Yes
+
+
+
+
+
+ regr_sxy
+
+ regr_sxy ( Ydouble precision, Xdouble precision )
+ double precision
+
+
+ Computes the sum of products of independent times
+ dependent variables,
+ sum(X*Y) - sum(X) * sum(Y)/N.
+
+ Yes
+
+
+
+
+
+ regr_syy
+
+ regr_syy ( Ydouble precision, Xdouble precision )
+ double precision
+
+
+ Computes the sum of squares of the dependent
+ variable,
+ sum(Y^2) - sum(Y)^2/N.
+
+ Yes
+
+
+
+
+
+ standard deviation
+
+
+ stddev
+
+ stddev ( numeric_type )
+ double precision
+ for real or double precision,
+ otherwise numeric
+
+
+ This is a historical alias for stddev_samp.
+
+ Yes
+
+
+
+
+
+ standard deviation
+ population
+
+
+ stddev_pop
+
+ stddev_pop ( numeric_type )
+ double precision
+ for real or double precision,
+ otherwise numeric
+
+
+ Computes the population standard deviation of the input values.
+
+ Yes
+
+
+
+
+
+ standard deviation
+ sample
+
+
+ stddev_samp
+
+ stddev_samp ( numeric_type )
+ double precision
+ for real or double precision,
+ otherwise numeric
+
+
+ Computes the sample standard deviation of the input values.
+
+ Yes
+
+
+
+
+
+ variance
+
+ variance ( numeric_type )
+ double precision
+ for real or double precision,
+ otherwise numeric
+
+
+ This is a historical alias for var_samp.
+
+ Yes
+
+
+
+
+
+ variance
+ population
+
+
+ var_pop
+
+ var_pop ( numeric_type )
+ double precision
+ for real or double precision,
+ otherwise numeric
+
+
+ Computes the population variance of the input values (square of the
+ population standard deviation).
+
+ Yes
+
+
+
+
+
+ variance
+ sample
+
+
+ var_samp
+
+ var_samp ( numeric_type )
+ double precision
+ for real or double precision,
+ otherwise numeric
+
+
+ Computes the sample variance of the input values (square of the sample
+ standard deviation).
+
+ Yes
+
+
+
+
+
+
+ shows some
+ aggregate functions that use the ordered-set aggregate
+ syntax. These functions are sometimes referred to as inverse
+ distribution functions. Their aggregated input is introduced by
+ ORDER BY, and they may also take a direct
+ argument that is not aggregated, but is computed only once.
+ All these functions ignore null values in their aggregated input.
+ For those that take a fraction parameter, the
+ fraction value must be between 0 and 1; an error is thrown if not.
+ However, a null fraction value simply produces a
+ null result.
+
+
+
+ ordered-set aggregate
+ built-in
+
+
+ inverse distribution
+
+
+
+ Ordered-Set Aggregate Functions
+
+
+
+
+
+
+ Function
+
+
+ Description
+
+ Partial Mode
+
+
+
+
+
+
+
+ mode
+ statistical
+
+ mode () WITHIN GROUP ( ORDER BYanyelement )
+ anyelement
+
+
+ Computes the mode, 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.
+
+ No
+
+
+
+
+
+ percentile
+ continuous
+
+ percentile_cont ( fractiondouble precision ) WITHIN GROUP ( ORDER BYdouble precision )
+ double precision
+
+
+ percentile_cont ( fractiondouble precision ) WITHIN GROUP ( ORDER BYinterval )
+ interval
+
+
+ Computes the continuous percentile, a value
+ corresponding to the specified fraction
+ within the ordered set of aggregated argument values. This will
+ interpolate between adjacent input items if needed.
+
+ No
+
+
+
+
+ percentile_cont ( fractionsdouble precision[] ) WITHIN GROUP ( ORDER BYdouble precision )
+ double precision[]
+
+
+ percentile_cont ( fractionsdouble precision[] ) WITHIN GROUP ( ORDER BYinterval )
+ interval[]
+
+
+ Computes multiple continuous percentiles. The result is an array of
+ the same dimensions as the fractions
+ parameter, with each non-null element replaced by the (possibly
+ interpolated) value corresponding to that percentile.
+
+ No
+
+
+
+
+
+ percentile
+ discrete
+
+ percentile_disc ( fractiondouble precision ) WITHIN GROUP ( ORDER BYanyelement )
+ anyelement
+
+
+ Computes the discrete percentile, the first
+ value within the ordered set of aggregated argument values whose
+ position in the ordering equals or exceeds the
+ specified fraction. The aggregated
+ argument must be of a sortable type.
+
+ No
+
+
+
+
+ percentile_disc ( fractionsdouble precision[] ) WITHIN GROUP ( ORDER BYanyelement )
+ anyarray
+
+
+ Computes multiple discrete percentiles. The result is an array of the
+ same dimensions as the fractions parameter,
+ with each non-null element replaced by the input value corresponding
+ to that percentile.
+ The aggregated argument must be of a sortable type.
+
+ No
+
+
+
+
+
+
+ hypothetical-set aggregate
+ built-in
+
+
+
+ Each of the hypothetical-set aggregates listed in
+ is associated with a
+ window function of the same name defined in
+ . In each case, the aggregate's result
+ is the value that the associated window function would have
+ returned for the hypothetical row constructed from
+ args, if such a row had been added to the sorted
+ group of rows represented by the sorted_args.
+ For each of these functions, the list of direct arguments
+ given in args must match the number and types of
+ the aggregated arguments given in sorted_args.
+ 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 ORDER BY clause.
+
+
+
+ Hypothetical-Set Aggregate Functions
+
+
+
+
+
+
+ Function
+
+
+ Description
+
+ Partial Mode
+
+
+
+
+
+
+
+ rank
+ hypothetical
+
+ rank ( args ) WITHIN GROUP ( ORDER BYsorted_args )
+ bigint
+
+
+ Computes the rank of the hypothetical row, with gaps; that is, the row
+ number of the first row in its peer group.
+
+ No
+
+
+
+
+
+ dense_rank
+ hypothetical
+
+ dense_rank ( args ) WITHIN GROUP ( ORDER BYsorted_args )
+ bigint
+
+
+ Computes the rank of the hypothetical row, without gaps; this function
+ effectively counts peer groups.
+
+ No
+
+
+
+
+
+ percent_rank
+ hypothetical
+
+ percent_rank ( args ) WITHIN GROUP ( ORDER BYsorted_args )
+ double precision
+
+
+ Computes the relative rank of the hypothetical row, that is
+ (rank - 1) / (total rows - 1).
+ The value thus ranges from 0 to 1 inclusive.
+
+ No
+
+
+
+
+
+ cume_dist
+ hypothetical
+
+ cume_dist ( args ) WITHIN GROUP ( ORDER BYsorted_args )
+ double precision
+
+
+ Computes the cumulative distribution, that is (number of rows
+ preceding or peers with hypothetical row) / (total rows). The value
+ thus ranges from 1/N to 1.
+
+ No
+
+
+
+
+
+
+ Grouping Operations
+
+
+
+
+ Function
+
+
+ Description
+
+
+
+
+
+
+
+
+ GROUPING
+
+ GROUPING ( group_by_expression(s) )
+ integer
+
+
+ Returns a bit mask indicating which GROUP BY
+ 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.
+
+
+
+
+
+
+
+ The grouping operations shown in
+ are used in conjunction with
+ grouping sets (see ) to distinguish
+ result rows. The arguments to the GROUPING function
+ are not actually evaluated, but they must exactly match expressions given
+ in the GROUP BY clause of the associated query level.
+ For example:
+
+=>SELECT * FROM items_sold;
+ make | model | sales
+-------+-------+-------
+ Foo | GT | 10
+ Foo | Tour | 20
+ Bar | City | 15
+ Bar | Sport | 5
+(4 rows)
+
+=>SELECT make, model, GROUPING(make,model), sum(sales) FROM items_sold GROUP BY ROLLUP(make,model);
+ 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)
+
+ Here, the grouping value 0 in the
+ first four rows shows that those have been grouped normally, over both the
+ grouping columns. The value 1 indicates
+ that model was not grouped by in the next-to-last two
+ rows, and the value 3 indicates that
+ neither make nor model was grouped
+ by in the last row (which therefore is an aggregate over all the input
+ rows).
+
+
+
diff --git a/doc/src/sgml/func/func-array.sgml b/doc/src/sgml/func/func-array.sgml
new file mode 100644
index 0000000000000..97e4865a5f7d2
--- /dev/null
+++ b/doc/src/sgml/func/func-array.sgml
@@ -0,0 +1,646 @@
+
+ Array Functions and Operators
+
+
+ shows the specialized operators
+ available for array types.
+ In addition to those, the usual comparison operators shown in 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.
+
+
+
+ Array Operators
+
+
+
+
+ Operator
+
+
+ Description
+
+
+ Example(s)
+
+
+
+
+
+
+
+ anyarray@>anyarray
+ boolean
+
+
+ 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 ARRAY[1] and ARRAY[1,1] are
+ each considered to contain the other.)
+
+
+ ARRAY[1,4,3] @> ARRAY[3,1,3]
+ t
+
+
+
+
+
+ anyarray<@anyarray
+ boolean
+
+
+ Is the first array contained by the second?
+
+
+ ARRAY[2,2,7] <@ ARRAY[1,7,4,2,6]
+ t
+
+
+
+
+
+ anyarray&&anyarray
+ boolean
+
+
+ Do the arrays overlap, that is, have any elements in common?
+
+
+ ARRAY[1,4,3] && ARRAY[2,1]
+ t
+
+
+
+
+
+ anycompatiblearray||anycompatiblearray
+ anycompatiblearray
+
+
+ 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 ).
+
+
+ ARRAY[1,2,3] || ARRAY[4,5,6,7]
+ {1,2,3,4,5,6,7}
+
+
+ ARRAY[1,2,3] || ARRAY[[4,5,6],[7,8,9.9]]
+ {{1,2,3},{4,5,6},{7,8,9.9}}
+
+
+
+
+
+ anycompatible||anycompatiblearray
+ anycompatiblearray
+
+
+ Concatenates an element onto the front of an array (which must be
+ empty or one-dimensional).
+
+
+ 3 || ARRAY[4,5,6]
+ {3,4,5,6}
+
+
+
+
+
+ anycompatiblearray||anycompatible
+ anycompatiblearray
+
+
+ Concatenates an element onto the end of an array (which must be
+ empty or one-dimensional).
+
+
+ ARRAY[4,5,6] || 7
+ {4,5,6,7}
+
+
+
+
+
+
+
+ See for more details about array operator
+ behavior. See for more details about
+ which operators support indexed operations.
+
+
+
+ shows the functions
+ available for use with array types. See
+ for more information and examples of the use of these functions.
+
+
+
+ Array Functions
+
+
+
+
+ Function
+
+
+ Description
+
+
+ Example(s)
+
+
+
+
+
+
+
+
+ array_append
+
+ array_append ( anycompatiblearray, anycompatible )
+ anycompatiblearray
+
+
+ Appends an element to the end of an array (same as
+ the anycompatiblearray||anycompatible
+ operator).
+
+
+ array_append(ARRAY[1,2], 3)
+ {1,2,3}
+
+
+
+
+
+
+ array_cat
+
+ array_cat ( anycompatiblearray, anycompatiblearray )
+ anycompatiblearray
+
+
+ Concatenates two arrays (same as
+ the anycompatiblearray||anycompatiblearray
+ operator).
+
+
+ array_cat(ARRAY[1,2,3], ARRAY[4,5])
+ {1,2,3,4,5}
+
+
+
+
+
+
+ array_dims
+
+ array_dims ( anyarray )
+ text
+
+
+ Returns a text representation of the array's dimensions.
+
+
+ array_dims(ARRAY[[1,2,3], [4,5,6]])
+ [1:2][1:3]
+
+
+
+
+
+
+ array_fill
+
+ array_fill ( anyelement, integer[]
+ , integer[] )
+ anyarray
+
+
+ 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 1).
+
+
+ array_fill(11, ARRAY[2,3])
+ {{11,11,11},{11,11,11}}
+
+
+ array_fill(7, ARRAY[3], ARRAY[2])
+ [2:4]={7,7,7}
+
+
+
+
+
+
+ array_length
+
+ array_length ( anyarray, integer )
+ integer
+
+
+ Returns the length of the requested array dimension.
+ (Produces NULL instead of 0 for empty or missing array dimensions.)
+
+
+ array_length(array[1,2,3], 1)
+ 3
+
+
+ array_length(array[]::int[], 1)
+ NULL
+
+
+ array_length(array['text'], 2)
+ NULL
+
+
+
+
+
+
+ array_lower
+
+ array_lower ( anyarray, integer )
+ integer
+
+
+ Returns the lower bound of the requested array dimension.
+
+
+ array_lower('[0:2]={1,2,3}'::integer[], 1)
+ 0
+
+
+
+
+
+
+ array_ndims
+
+ array_ndims ( anyarray )
+ integer
+
+
+ Returns the number of dimensions of the array.
+
+
+ array_ndims(ARRAY[[1,2,3], [4,5,6]])
+ 2
+
+
+
+
+
+
+ array_position
+
+ array_position ( anycompatiblearray, anycompatible, integer )
+ integer
+
+
+ Returns the subscript of the first occurrence of the second argument
+ in the array, or NULL 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 IS NOT DISTINCT FROM
+ semantics, so it is possible to search for NULL.
+
+
+ array_position(ARRAY['sun', 'mon', 'tue', 'wed', 'thu', 'fri', 'sat'], 'mon')
+ 2
+
+
+
+
+
+
+ array_positions
+
+ array_positions ( anycompatiblearray, anycompatible )
+ integer[]
+
+
+ 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 IS NOT DISTINCT FROM
+ semantics, so it is possible to search for NULL.
+ NULL is returned only if the array
+ is NULL; if the value is not found in the array, an
+ empty array is returned.
+
+
+ array_positions(ARRAY['A','A','B','A'], 'A')
+ {1,2,4}
+
+
+
+
+
+
+ array_prepend
+
+ array_prepend ( anycompatible, anycompatiblearray )
+ anycompatiblearray
+
+
+ Prepends an element to the beginning of an array (same as
+ the anycompatible||anycompatiblearray
+ operator).
+
+
+ array_prepend(1, ARRAY[2,3])
+ {1,2,3}
+
+
+
+
+
+
+ array_remove
+
+ array_remove ( anycompatiblearray, anycompatible )
+ anycompatiblearray
+
+
+ Removes all elements equal to the given value from the array.
+ The array must be one-dimensional.
+ Comparisons are done using IS NOT DISTINCT FROM
+ semantics, so it is possible to remove NULLs.
+
+
+ array_remove(ARRAY[1,2,3,2], 2)
+ {1,3}
+
+
+
+
+
+
+ array_replace
+
+ array_replace ( anycompatiblearray, anycompatible, anycompatible )
+ anycompatiblearray
+
+
+ Replaces each array element equal to the second argument with the
+ third argument.
+
+
+ array_replace(ARRAY[1,2,5,4], 5, 3)
+ {1,2,3,4}
+
+
+
+
+
+
+ array_reverse
+
+ array_reverse ( anyarray )
+ anyarray
+
+
+ Reverses the first dimension of the array.
+
+
+ array_reverse(ARRAY[[1,2],[3,4],[5,6]])
+ {{5,6},{3,4},{1,2}}
+
+
+
+
+
+
+ array_sample
+
+ array_sample ( arrayanyarray, ninteger )
+ anyarray
+
+
+ Returns an array of n items randomly selected
+ from array. n may not
+ exceed the length of array's first dimension.
+ If array is multi-dimensional,
+ an item is a slice having a given first subscript.
+
+
+ array_sample(ARRAY[1,2,3,4,5,6], 3)
+ {2,6,1}
+
+
+ array_sample(ARRAY[[1,2],[3,4],[5,6]], 2)
+ {{5,6},{1,2}}
+
+
+
+
+
+
+ array_shuffle
+
+ array_shuffle ( anyarray )
+ anyarray
+
+
+ Randomly shuffles the first dimension of the array.
+
+
+ array_shuffle(ARRAY[[1,2],[3,4],[5,6]])
+ {{5,6},{1,2},{3,4}}
+
+
+
+
+
+
+ array_sort
+
+ array_sort (
+ arrayanyarray
+ , descendingboolean
+ , nulls_firstboolean
+ )
+ anyarray
+
+
+ Sorts the first dimension of the array.
+ The sort order is determined by the default sort ordering of the
+ array's element type; however, if the element type is collatable,
+ the collation to use can be specified by adding
+ a COLLATE clause to
+ the array argument.
+
+
+ If descending is true then sort in
+ descending order, otherwise ascending order. If omitted, the
+ default is ascending order.
+ If nulls_first is true then nulls appear
+ before non-null values, otherwise nulls appear after non-null
+ values.
+ If omitted, nulls_first is taken to have
+ the same value as descending.
+
+
+ array_sort(ARRAY[[2,4],[2,1],[6,5]])
+ {{2,1},{2,4},{6,5}}
+
+
+
+
+
+
+ array_to_string
+
+ array_to_string ( arrayanyarray, delimitertext, null_stringtext )
+ text
+
+
+ Converts each array element to its text representation, and
+ concatenates those separated by
+ the delimiter string.
+ If null_string is given and is
+ not NULL, then NULL array
+ entries are represented by that string; otherwise, they are omitted.
+ See also string_to_array.
+
+
+ array_to_string(ARRAY[1, 2, 3, NULL, 5], ',', '*')
+ 1,2,3,*,5
+
+
+
+
+
+
+ array_upper
+
+ array_upper ( anyarray, integer )
+ integer
+
+
+ Returns the upper bound of the requested array dimension.
+
+
+ array_upper(ARRAY[1,8,3,7], 1)
+ 4
+
+
+
+
+
+
+ cardinality
+
+ cardinality ( anyarray )
+ integer
+
+
+ Returns the total number of elements in the array, or 0 if the array
+ is empty.
+
+
+ cardinality(ARRAY[[1,2],[3,4]])
+ 4
+
+
+
+
+
+
+ trim_array
+
+ trim_array ( arrayanyarray, ninteger )
+ anyarray
+
+
+ Trims an array by removing the last n elements.
+ If the array is multidimensional, only the first dimension is trimmed.
+
+
+ trim_array(ARRAY[1,2,3,4,5,6], 2)
+ {1,2,3,4}
+
+
+
+
+
+
+ unnest
+
+ unnest ( anyarray )
+ setof anyelement
+
+
+ Expands an array into a set of rows.
+ The array's elements are read out in storage order.
+
+
+ unnest(ARRAY[1,2])
+
+
+ 1
+ 2
+
+
+
+ unnest(ARRAY[['foo','bar'],['baz','quux']])
+
+
+ foo
+ bar
+ baz
+ quux
+
+
+
+
+
+
+ unnest ( anyarray, anyarray, ... )
+ setof anyelement, anyelement [, ... ]
+
+
+ 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 NULLs. This form is only allowed
+ in a query's FROM clause; see .
+
+
+ select * from unnest(ARRAY[1,2], ARRAY['foo','bar','baz']) as x(a,b)
+
+
+ a | b
+---+-----
+ 1 | foo
+ 2 | bar
+ | baz
+
+
+
+
+
+
+
+
+ See also about the aggregate
+ function array_agg for use with arrays.
+
+
diff --git a/doc/src/sgml/func/func-binarystring.sgml b/doc/src/sgml/func/func-binarystring.sgml
new file mode 100644
index 0000000000000..78814ee0685eb
--- /dev/null
+++ b/doc/src/sgml/func/func-binarystring.sgml
@@ -0,0 +1,854 @@
+
+ Binary String Functions and Operators
+
+
+ binary data
+ functions
+
+
+
+ This section describes functions and operators for examining and
+ manipulating binary strings, that is values of type bytea.
+ Many of these are equivalent, in purpose and syntax, to the
+ text-string functions described in the previous section.
+
+
+
+ SQL defines some string functions that use
+ key words, rather than commas, to separate
+ arguments. Details are in
+ .
+ PostgreSQL also provides versions of these functions
+ that use the regular function invocation syntax
+ (see ).
+
+
+
+ <acronym>SQL</acronym> Binary String Functions and Operators
+
+
+
+
+ Function/Operator
+
+
+ Description
+
+
+ Example(s)
+
+
+
+
+
+
+
+
+ binary string
+ concatenation
+
+ bytea||bytea
+ bytea
+
+
+ Concatenates the two binary strings.
+
+
+ '\x123456'::bytea || '\x789a00bcde'::bytea
+ \x123456789a00bcde
+
+
+
+
+
+
+ bit_length
+
+ bit_length ( bytea )
+ integer
+
+
+ Returns number of bits in the binary string (8
+ times the octet_length).
+
+
+ bit_length('\x123456'::bytea)
+ 24
+
+
+
+
+
+
+ btrim
+
+ btrim ( bytesbytea,
+ bytesremovedbytea )
+ bytea
+
+
+ Removes the longest string containing only bytes appearing in
+ bytesremoved from the start and end of
+ bytes.
+
+
+ btrim('\x1234567890'::bytea, '\x9012'::bytea)
+ \x345678
+
+
+
+
+
+
+ ltrim
+
+ ltrim ( bytesbytea,
+ bytesremovedbytea )
+ bytea
+
+
+ Removes the longest string containing only bytes appearing in
+ bytesremoved from the start of
+ bytes.
+
+
+ ltrim('\x1234567890'::bytea, '\x9012'::bytea)
+ \x34567890
+
+
+
+
+
+
+ octet_length
+
+ octet_length ( bytea )
+ integer
+
+
+ Returns number of bytes in the binary string.
+
+
+ octet_length('\x123456'::bytea)
+ 3
+
+
+
+
+
+
+ overlay
+
+ overlay ( bytesbyteaPLACINGnewsubstringbyteaFROMstartintegerFORcountinteger )
+ bytea
+
+
+ Replaces the substring of bytes that starts at
+ the start'th byte and extends
+ for count bytes
+ with newsubstring.
+ If count is omitted, it defaults to the length
+ of newsubstring.
+
+
+ overlay('\x1234567890'::bytea placing '\002\003'::bytea from 2 for 3)
+ \x12020390
+
+
+
+
+
+
+ position
+
+ position ( substringbyteaINbytesbytea )
+ integer
+
+
+ Returns first starting index of the specified
+ substring within
+ bytes, or zero if it's not present.
+
+
+ position('\x5678'::bytea in '\x1234567890'::bytea)
+ 3
+
+
+
+
+
+
+ rtrim
+
+ rtrim ( bytesbytea,
+ bytesremovedbytea )
+ bytea
+
+
+ Removes the longest string containing only bytes appearing in
+ bytesremoved from the end of
+ bytes.
+
+
+ rtrim('\x1234567890'::bytea, '\x9012'::bytea)
+ \x12345678
+
+
+
+
+
+
+ substring
+
+ substring ( bytesbyteaFROMstartintegerFORcountinteger )
+ bytea
+
+
+ Extracts the substring of bytes starting at
+ the start'th byte if that is specified,
+ and stopping after count bytes if that is
+ specified. Provide at least one of start
+ and count.
+
+
+ substring('\x1234567890'::bytea from 3 for 2)
+ \x5678
+
+
+
+
+
+
+ trim
+
+ trim ( LEADING | TRAILING | BOTH
+ bytesremovedbyteaFROM
+ bytesbytea )
+ bytea
+
+
+ Removes the longest string containing only bytes appearing in
+ bytesremoved from the start,
+ end, or both ends (BOTH is the default)
+ of bytes.
+
+
+ trim('\x9012'::bytea from '\x1234567890'::bytea)
+ \x345678
+
+
+
+
+
+ trim ( LEADING | TRAILING | BOTHFROM
+ bytesbytea,
+ bytesremovedbytea )
+ bytea
+
+
+ This is a non-standard syntax for trim().
+
+
+ trim(both from '\x1234567890'::bytea, '\x9012'::bytea)
+ \x345678
+
+
+
+
+
+
+
+ Additional binary string manipulation functions are available and
+ are listed in . Some
+ of them are used internally to implement the
+ SQL-standard string functions listed in .
+
+
+
+ Other Binary String Functions
+
+
+
+
+ Function
+
+
+ Description
+
+
+ Example(s)
+
+
+
+
+
+
+
+
+ bit_count
+
+
+ popcount
+ bit_count
+
+ bit_count ( bytesbytea )
+ bigint
+
+
+ Returns the number of bits set in the binary string (also known as
+ popcount).
+
+
+ bit_count('\x1234567890'::bytea)
+ 15
+
+
+
+
+
+
+ crc32
+
+ crc32 ( bytea )
+ bigint
+
+
+ Computes the CRC-32 value of the binary string.
+
+
+ crc32('abc'::bytea)
+ 891568578
+
+
+
+
+
+
+ crc32c
+
+ crc32c ( bytea )
+ bigint
+
+
+ Computes the CRC-32C value of the binary string.
+
+
+ crc32c('abc'::bytea)
+ 910901175
+
+
+
+
+
+
+ get_bit
+
+ get_bit ( bytesbytea,
+ nbigint )
+ integer
+
+
+ Extracts n'th bit
+ from binary string.
+
+
+ get_bit('\x1234567890'::bytea, 30)
+ 1
+
+
+
+
+
+
+ get_byte
+
+ get_byte ( bytesbytea,
+ ninteger )
+ integer
+
+
+ Extracts n'th byte
+ from binary string.
+
+
+ get_byte('\x1234567890'::bytea, 4)
+ 144
+
+
+
+
+
+
+ length
+
+
+ binary string
+ length
+
+
+ length
+ of a binary string
+ binary strings, length
+
+ length ( bytea )
+ integer
+
+
+ Returns the number of bytes in the binary string.
+
+
+ length('\x1234567890'::bytea)
+ 5
+
+
+
+
+
+ length ( bytesbytea,
+ encodingname )
+ integer
+
+
+ Returns the number of characters in the binary string, assuming
+ that it is text in the given encoding.
+
+
+ length('jose'::bytea, 'UTF8')
+ 4
+
+
+
+
+
+
+ md5
+
+ md5 ( bytea )
+ text
+
+
+ Computes the MD5 hash of
+ the binary string, with the result written in hexadecimal.
+
+
+ md5('Th\000omas'::bytea)
+ 8ab2d3c9689aaf18&zwsp;b4958c334c82d8b1
+
+
+
+
+
+
+ reverse
+
+ reverse ( bytea )
+ bytea
+
+
+ Reverses the order of the bytes in the binary string.
+
+
+ reverse('\xabcd'::bytea)
+ \xcdab
+
+
+
+
+
+
+ set_bit
+
+ set_bit ( bytesbytea,
+ nbigint,
+ newvalueinteger )
+ bytea
+
+
+ Sets n'th bit in
+ binary string to newvalue.
+
+
+ set_bit('\x1234567890'::bytea, 30, 0)
+ \x1234563890
+
+
+
+
+
+
+ set_byte
+
+ set_byte ( bytesbytea,
+ ninteger,
+ newvalueinteger )
+ bytea
+
+
+ Sets n'th byte in
+ binary string to newvalue.
+
+
+ set_byte('\x1234567890'::bytea, 4, 64)
+ \x1234567840
+
+
+
+
+
+
+ sha224
+
+ sha224 ( bytea )
+ bytea
+
+
+ Computes the SHA-224 hash
+ of the binary string.
+
+
+ sha224('abc'::bytea)
+ \x23097d223405d8228642a477bda2&zwsp;55b32aadbce4bda0b3f7e36c9da7
+
+
+
+
+
+
+ sha256
+
+ sha256 ( bytea )
+ bytea
+
+
+ Computes the SHA-256 hash
+ of the binary string.
+
+
+ sha256('abc'::bytea)
+ \xba7816bf8f01cfea414140de5dae2223&zwsp;b00361a396177a9cb410ff61f20015ad
+
+
+
+
+
+
+ sha384
+
+ sha384 ( bytea )
+ bytea
+
+
+ Computes the SHA-384 hash
+ of the binary string.
+
+
+ sha384('abc'::bytea)
+ \xcb00753f45a35e8bb5a03d699ac65007&zwsp;272c32ab0eded1631a8b605a43ff5bed&zwsp;8086072ba1e7cc2358baeca134c825a7
+
+
+
+
+
+
+ sha512
+
+ sha512 ( bytea )
+ bytea
+
+
+ Computes the SHA-512 hash
+ of the binary string.
+
+
+ sha512('abc'::bytea)
+ \xddaf35a193617abacc417349ae204131&zwsp;12e6fa4e89a97ea20a9eeee64b55d39a&zwsp;2192992a274fc1a836ba3c23a3feebbd&zwsp;454d4423643ce80e2a9ac94fa54ca49f
+
+
+
+
+
+
+ substr
+
+ substr ( bytesbytea, startinteger, countinteger )
+ bytea
+
+
+ Extracts the substring of bytes starting at
+ the start'th byte,
+ and extending for count bytes if that is
+ specified. (Same
+ as substring(bytes
+ from start
+ for count).)
+
+
+ substr('\x1234567890'::bytea, 3, 2)
+ \x5678
+
+
+
+
+
+
+
+ Functions get_byte and set_byte
+ number the first byte of a binary string as byte 0.
+ Functions get_bit and set_bit
+ 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.
+
+
+
+ For historical reasons, the function md5
+ returns a hex-encoded value of type text whereas the SHA-2
+ functions return type bytea. Use the functions
+ encode
+ and decode to
+ convert between the two. For example write encode(sha256('abc'),
+ 'hex') to get a hex-encoded text representation,
+ or decode(md5('abc'), 'hex') to get
+ a bytea value.
+
+
+
+
+ character string
+ converting to binary string
+
+
+ binary string
+ converting to character string
+
+ Functions for converting strings between different character sets
+ (encodings), and for representing arbitrary binary data in textual
+ form, are shown in
+ . For these
+ functions, an argument or result of type text is expressed
+ in the database's default encoding, while arguments or results of
+ type bytea are in an encoding named by another argument.
+
+
+
+ Text/Binary String Conversion Functions
+
+
+
+
+ Function
+
+
+ Description
+
+
+ Example(s)
+
+
+
+
+
+
+
+
+ convert
+
+ convert ( bytesbytea,
+ src_encodingname,
+ dest_encodingname )
+ bytea
+
+
+ Converts a binary string representing text in
+ encoding src_encoding
+ to a binary string in encoding dest_encoding
+ (see for
+ available conversions).
+
+
+ convert('text_in_utf8', 'UTF8', 'LATIN1')
+ \x746578745f696e5f75746638
+
+
+
+
+
+
+ convert_from
+
+ convert_from ( bytesbytea,
+ src_encodingname )
+ text
+
+
+ Converts a binary string representing text in
+ encoding src_encoding
+ to text in the database encoding
+ (see for
+ available conversions).
+
+
+ convert_from('text_in_utf8', 'UTF8')
+ text_in_utf8
+
+
+
+
+
+
+ convert_to
+
+ convert_to ( stringtext,
+ dest_encodingname )
+ bytea
+
+
+ Converts a text string (in the database encoding) to a
+ binary string encoded in encoding dest_encoding
+ (see for
+ available conversions).
+
+
+ convert_to('some_text', 'UTF8')
+ \x736f6d655f74657874
+
+
+
+
+
+
+ encode
+
+ encode ( bytesbytea,
+ formattext )
+ text
+
+
+ Encodes binary data into a textual representation; supported
+ format values are:
+ base64,
+ escape,
+ hex.
+
+
+ encode('123\000\001', 'base64')
+ MTIzAAE=
+
+
+
+
+
+
+ decode
+
+ decode ( stringtext,
+ formattext )
+ bytea
+
+
+ Decodes binary data from a textual representation; supported
+ format values are the same as
+ for encode.
+
+
+ decode('MTIzAAE=', 'base64')
+ \x3132330001
+
+
+
+
+
+
+
+ The encode and decode
+ functions support the following textual formats:
+
+
+
+ base64
+
+ base64 format
+
+
+
+ The base64 format is that
+ of RFC
+ 2045 Section 6.8. As per the RFC, 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 decode function ignores carriage-return,
+ newline, space, and tab characters. Otherwise, an error is
+ raised when decode is supplied invalid
+ base64 data — including when trailing padding is incorrect.
+
+
+
+
+
+ escape
+
+ escape format
+
+
+
+ The escape format converts zero bytes and
+ bytes with the high bit set into octal escape sequences
+ (\nnn), and it doubles
+ backslashes. Other byte values are represented literally.
+ The decode 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.
+
+
+
+
+
+ hex
+
+ hex format
+
+
+
+ The hex format represents each 4 bits of
+ data as one hexadecimal digit, 0
+ through f, writing the higher-order digit of
+ each byte first. The encode function outputs
+ the a-f hex digits in lower
+ case. Because the smallest unit of data is 8 bits, there are
+ always an even number of characters returned
+ by encode.
+ The decode function
+ accepts the a-f characters in
+ either upper or lower case. An error is raised
+ when decode is given invalid hex data
+ — including when given an odd number of characters.
+
+
+
+
+
+
+
+ In addition, it is possible to cast integral values to and from type
+ bytea. Casting an integer to bytea produces
+ 2, 4, or 8 bytes, depending on the width of the integer type. The result
+ is the two's complement representation of the integer, with the most
+ significant byte first. Some examples:
+
+1234::smallint::bytea \x04d2
+cast(1234 as bytea) \x000004d2
+cast(-1234 as bytea) \xfffffb2e
+'\x8000'::bytea::smallint -32768
+'\x8000'::bytea::integer 32768
+
+ Casting a bytea to an integer will raise an error if the
+ length of the bytea exceeds the width of the integer type.
+
+
+
+ See also the aggregate function string_agg in
+ and the large object functions
+ in .
+
+
diff --git a/doc/src/sgml/func/func-bitstring.sgml b/doc/src/sgml/func/func-bitstring.sgml
new file mode 100644
index 0000000000000..f03dd63afcc6a
--- /dev/null
+++ b/doc/src/sgml/func/func-bitstring.sgml
@@ -0,0 +1,358 @@
+
+ Bit String Functions and Operators
+
+
+ bit strings
+ functions
+
+
+
+ This section describes functions and operators for examining and
+ manipulating bit strings, that is values of the types
+ bit and bit varying. (While only
+ type bit is mentioned in these tables, values of
+ type bit varying can be used interchangeably.)
+ Bit strings support the usual comparison operators shown in
+ , as well as the
+ operators shown in .
+
+
+
+ Bit String Operators
+
+
+
+
+ Operator
+
+
+ Description
+
+
+ Example(s)
+
+
+
+
+
+
+
+ bit||bit
+ bit
+
+
+ Concatenation
+
+
+ B'10001' || B'011'
+ 10001011
+
+
+
+
+
+ bit&bit
+ bit
+
+
+ Bitwise AND (inputs must be of equal length)
+
+
+ B'10001' & B'01101'
+ 00001
+
+
+
+
+
+ bit|bit
+ bit
+
+
+ Bitwise OR (inputs must be of equal length)
+
+
+ B'10001' | B'01101'
+ 11101
+
+
+
+
+
+ bit#bit
+ bit
+
+
+ Bitwise exclusive OR (inputs must be of equal length)
+
+
+ B'10001' # B'01101'
+ 11100
+
+
+
+
+
+ ~bit
+ bit
+
+
+ Bitwise NOT
+
+
+ ~ B'10001'
+ 01110
+
+
+
+
+
+ bit<<integer
+ bit
+
+
+ Bitwise shift left
+ (string length is preserved)
+
+
+ B'10001' << 3
+ 01000
+
+
+
+
+
+ bit>>integer
+ bit
+
+
+ Bitwise shift right
+ (string length is preserved)
+
+
+ B'10001' >> 2
+ 00100
+
+
+
+
+
+
+
+ Some of the functions available for binary strings are also available
+ for bit strings, as shown in .
+
+
+
+ Bit String Functions
+
+
+
+
+ Function
+
+
+ Description
+
+
+ Example(s)
+
+
+
+
+
+
+
+
+ bit_count
+
+ bit_count ( bit )
+ bigint
+
+
+ Returns the number of bits set in the bit string (also known as
+ popcount).
+
+
+ bit_count(B'10111')
+ 4
+
+
+
+
+
+
+ bit_length
+
+ bit_length ( bit )
+ integer
+
+
+ Returns number of bits in the bit string.
+
+
+ bit_length(B'10111')
+ 5
+
+
+
+
+
+
+ length
+
+
+ bit string
+ length
+
+ length ( bit )
+ integer
+
+
+ Returns number of bits in the bit string.
+
+
+ length(B'10111')
+ 5
+
+
+
+
+
+
+ octet_length
+
+ octet_length ( bit )
+ integer
+
+
+ Returns number of bytes in the bit string.
+
+
+ octet_length(B'1011111011')
+ 2
+
+
+
+
+
+
+ overlay
+
+ overlay ( bitsbitPLACINGnewsubstringbitFROMstartintegerFORcountinteger )
+ bit
+
+
+ Replaces the substring of bits that starts at
+ the start'th bit and extends
+ for count bits
+ with newsubstring.
+ If count is omitted, it defaults to the length
+ of newsubstring.
+
+
+ overlay(B'01010101010101010' placing B'11111' from 2 for 3)
+ 0111110101010101010
+
+
+
+
+
+
+ position
+
+ position ( substringbitINbitsbit )
+ integer
+
+
+ Returns first starting index of the specified substring
+ within bits, or zero if it's not present.
+
+
+ position(B'010' in B'000001101011')
+ 8
+
+
+
+
+
+
+ substring
+
+ substring ( bitsbitFROMstartintegerFORcountinteger )
+ bit
+
+
+ Extracts the substring of bits starting at
+ the start'th bit if that is specified,
+ and stopping after count bits if that is
+ specified. Provide at least one of start
+ and count.
+
+
+ substring(B'110010111111' from 3 for 2)
+ 00
+
+
+
+
+
+
+ get_bit
+
+ get_bit ( bitsbit,
+ ninteger )
+ integer
+
+
+ Extracts n'th bit
+ from bit string; the first (leftmost) bit is bit 0.
+
+
+ get_bit(B'101010101010101010', 6)
+ 1
+
+
+
+
+
+
+ set_bit
+
+ set_bit ( bitsbit,
+ ninteger,
+ newvalueinteger )
+ bit
+
+
+ Sets n'th bit in
+ bit string to newvalue;
+ the first (leftmost) bit is bit 0.
+
+
+ set_bit(B'101010101010101010', 6, 0)
+ 101010001010101010
+
+
+
+
+
+
+
+ In addition, it is possible to cast integral values to and from type
+ bit.
+ Casting an integer to bit(n) copies the rightmost
+ n bits. Casting an integer to a bit string width wider
+ than the integer itself will sign-extend on the left.
+ Some examples:
+
+44::bit(10) 0000101100
+44::bit(3) 100
+cast(-44 as bit(12)) 111111010100
+'1110'::bit(4)::integer 14
+
+ Note that casting to just bit means casting to
+ bit(1), and so will deliver only the least significant
+ bit of the integer.
+
+
diff --git a/doc/src/sgml/func/func-comparison.sgml b/doc/src/sgml/func/func-comparison.sgml
new file mode 100644
index 0000000000000..c1205983f8bac
--- /dev/null
+++ b/doc/src/sgml/func/func-comparison.sgml
@@ -0,0 +1,638 @@
+
+ Comparison Functions and Operators
+
+
+ comparison
+ operators
+
+
+
+ The usual comparison operators are available, as shown in .
+
+
+
+ Comparison Operators
+
+
+
+ Operator
+ Description
+
+
+
+
+
+
+ datatype<datatype
+ boolean
+
+ Less than
+
+
+
+
+ datatype>datatype
+ boolean
+
+ Greater than
+
+
+
+
+ datatype<=datatype
+ boolean
+
+ Less than or equal to
+
+
+
+
+ datatype>=datatype
+ boolean
+
+ Greater than or equal to
+
+
+
+
+ datatype=datatype
+ boolean
+
+ Equal
+
+
+
+
+ datatype<>datatype
+ boolean
+
+ Not equal
+
+
+
+
+ datatype!=datatype
+ boolean
+
+ Not equal
+
+
+
+
+
+
+
+ <> is the standard SQL notation for not
+ equal. != is an alias, which is converted
+ to <> at a very early stage of parsing.
+ Hence, it is not possible to implement !=
+ and <> operators that do different things.
+
+
+
+
+ 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.
+
+
+
+ It is usually possible to compare values of related data
+ types as well; for example integer>
+ bigint will work. Some cases of this sort are implemented
+ directly by cross-type 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.
+
+
+
+ As shown above, all comparison operators are binary operators that
+ return values of type boolean. Thus, expressions like
+ 1 < 2 < 3 are not valid (because there is
+ no < operator to compare a Boolean value with
+ 3). Use the BETWEEN predicates
+ shown below to perform range tests.
+
+
+
+ There are also some comparison predicates, as shown in . These behave much like
+ operators, but have special syntax mandated by the SQL standard.
+
+
+
+ Comparison Predicates
+
+
+
+
+ Predicate
+
+
+ Description
+
+
+ Example(s)
+
+
+
+
+
+
+
+ datatypeBETWEENdatatypeANDdatatype
+ boolean
+
+
+ Between (inclusive of the range endpoints).
+
+
+ 2 BETWEEN 1 AND 3
+ t
+
+
+ 2 BETWEEN 3 AND 1
+ f
+
+
+
+
+
+ datatypeNOT BETWEENdatatypeANDdatatype
+ boolean
+
+
+ Not between (the negation of BETWEEN).
+
+
+ 2 NOT BETWEEN 1 AND 3
+ f
+
+
+
+
+
+ datatypeBETWEEN SYMMETRICdatatypeANDdatatype
+ boolean
+
+
+ Between, after sorting the two endpoint values.
+
+
+ 2 BETWEEN SYMMETRIC 3 AND 1
+ t
+
+
+
+
+
+ datatypeNOT BETWEEN SYMMETRICdatatypeANDdatatype
+ boolean
+
+
+ Not between, after sorting the two endpoint values.
+
+
+ 2 NOT BETWEEN SYMMETRIC 3 AND 1
+ f
+
+
+
+
+
+ datatypeIS DISTINCT FROMdatatype
+ boolean
+
+
+ Not equal, treating null as a comparable value.
+
+
+ 1 IS DISTINCT FROM NULL
+ t (rather than NULL)
+
+
+ NULL IS DISTINCT FROM NULL
+ f (rather than NULL)
+
+
+
+
+
+ datatypeIS NOT DISTINCT FROMdatatype
+ boolean
+
+
+ Equal, treating null as a comparable value.
+
+
+ 1 IS NOT DISTINCT FROM NULL
+ f (rather than NULL)
+
+
+ NULL IS NOT DISTINCT FROM NULL
+ t (rather than NULL)
+
+
+
+
+
+ datatypeIS NULL
+ boolean
+
+
+ Test whether value is null.
+
+
+ 1.5 IS NULL
+ f
+
+
+
+
+
+ datatypeIS NOT NULL
+ boolean
+
+
+ Test whether value is not null.
+
+
+ 'null' IS NOT NULL
+ t
+
+
+
+
+
+ datatypeISNULL
+ boolean
+
+
+ Test whether value is null (nonstandard syntax).
+
+
+
+
+
+ datatypeNOTNULL
+ boolean
+
+
+ Test whether value is not null (nonstandard syntax).
+
+
+
+
+
+ booleanIS TRUE
+ boolean
+
+
+ Test whether boolean expression yields true.
+
+
+ true IS TRUE
+ t
+
+
+ NULL::boolean IS TRUE
+ f (rather than NULL)
+
+
+
+
+
+ booleanIS NOT TRUE
+ boolean
+
+
+ Test whether boolean expression yields false or unknown.
+
+
+ true IS NOT TRUE
+ f
+
+
+ NULL::boolean IS NOT TRUE
+ t (rather than NULL)
+
+
+
+
+
+ booleanIS FALSE
+ boolean
+
+
+ Test whether boolean expression yields false.
+
+
+ true IS FALSE
+ f
+
+
+ NULL::boolean IS FALSE
+ f (rather than NULL)
+
+
+
+
+
+ booleanIS NOT FALSE
+ boolean
+
+
+ Test whether boolean expression yields true or unknown.
+
+
+ true IS NOT FALSE
+ t
+
+
+ NULL::boolean IS NOT FALSE
+ t (rather than NULL)
+
+
+
+
+
+ booleanIS UNKNOWN
+ boolean
+
+
+ Test whether boolean expression yields unknown.
+
+
+ true IS UNKNOWN
+ f
+
+
+ NULL::boolean IS UNKNOWN
+ t (rather than NULL)
+
+
+
+
+
+ booleanIS NOT UNKNOWN
+ boolean
+
+
+ Test whether boolean expression yields true or false.
+
+
+ true IS NOT UNKNOWN
+ t
+
+
+ NULL::boolean IS NOT UNKNOWN
+ f (rather than NULL)
+
+
+
+
+
+
+
+
+ BETWEEN
+
+
+ BETWEEN SYMMETRIC
+
+ The BETWEEN predicate simplifies range tests:
+
+a BETWEEN x AND y
+
+ is equivalent to
+
+a >= x AND a <= y
+
+ Notice that BETWEEN treats the endpoint values as included
+ in the range.
+ BETWEEN SYMMETRIC is like BETWEEN
+ except there is no requirement that the argument to the left of
+ AND 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.
+
+
+
+ The various variants of BETWEEN are implemented in
+ terms of the ordinary comparison operators, and therefore will work for
+ any data type(s) that can be compared.
+
+
+
+
+ The use of AND in the BETWEEN
+ syntax creates an ambiguity with the use of AND as a
+ logical operator. To resolve this, only a limited set of expression
+ types are allowed as the second argument of a BETWEEN
+ clause. If you need to write a more complex sub-expression
+ in BETWEEN, write parentheses around the
+ sub-expression.
+
+
+
+
+
+ IS DISTINCT FROM
+
+
+ IS NOT DISTINCT FROM
+
+ Ordinary comparison operators yield null (signifying unknown),
+ not true or false, when either input is null. For example,
+ 7 = NULL yields null, as does 7 <> NULL. When
+ this behavior is not suitable, use the
+ IS NOT DISTINCT FROM predicates:
+
+a IS DISTINCT FROM b
+a IS NOT DISTINCT FROM b
+
+ For non-null inputs, IS DISTINCT FROM is
+ the same as the <> operator. However, if both
+ inputs are null it returns false, and if only one input is
+ null it returns true. Similarly, IS NOT DISTINCT
+ FROM is identical to = 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 unknown.
+
+
+
+
+ IS NULL
+
+
+ IS NOT NULL
+
+
+ ISNULL
+
+
+ NOTNULL
+
+ To check whether a value is or is not null, use the predicates:
+
+expression IS NULL
+expression IS NOT NULL
+
+ or the equivalent, but nonstandard, predicates:
+
+expression ISNULL
+expression NOTNULL
+
+ null valuecomparing
+
+
+
+ Do not write
+ expression = NULL
+ because NULL is not equal to
+ NULL. (The null value represents an unknown value,
+ and it is not known whether two unknown values are equal.)
+
+
+
+
+ Some applications might expect that
+ expression = NULL
+ returns true if expression evaluates to
+ the null value. It is highly recommended that these applications
+ be modified to comply with the SQL standard. However, if that
+ cannot be done the
+ configuration variable is available. If it is enabled,
+ PostgreSQL will convert x =
+ NULL clauses to x IS NULL.
+
+
+
+
+ If the expression is row-valued, then
+ IS NULL is true when the row expression itself is null
+ or when all the row's fields are null, while
+ IS NOT NULL is true when the row expression itself is non-null
+ and all the row's fields are non-null. Because of this behavior,
+ IS NULL and IS NOT NULL 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. For example:
+
+
+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
+
+SELECT ROW(table.*) IS NOT NULL FROM table; -- detect all-non-null rows
+
+SELECT NOT(ROW(table.*) IS NOT NULL) FROM TABLE; -- detect at least one null in rows
+
+
+ In some cases, it may be preferable to
+ write rowIS DISTINCT FROM NULL
+ or rowIS NOT DISTINCT FROM NULL,
+ which will simply check whether the overall row value is null without any
+ additional tests on the row fields.
+
+
+
+
+ IS TRUE
+
+
+ IS NOT TRUE
+
+
+ IS FALSE
+
+
+ IS NOT FALSE
+
+
+ IS UNKNOWN
+
+
+ IS NOT UNKNOWN
+
+ Boolean values can also be tested using the predicates
+
+boolean_expression IS TRUE
+boolean_expression IS NOT TRUE
+boolean_expression IS FALSE
+boolean_expression IS NOT FALSE
+boolean_expression IS UNKNOWN
+boolean_expression IS NOT UNKNOWN
+
+ 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 unknown.
+ Notice that IS UNKNOWN and IS NOT UNKNOWN are
+ effectively the same as IS NULL and
+ IS NOT NULL, respectively, except that the input
+ expression must be of Boolean type.
+
+
+
+ Some comparison-related functions are also available, as shown in .
+
+
+
+
+
diff --git a/doc/src/sgml/func/func-comparisons.sgml b/doc/src/sgml/func/func-comparisons.sgml
new file mode 100644
index 0000000000000..6a6e0bd401920
--- /dev/null
+++ b/doc/src/sgml/func/func-comparisons.sgml
@@ -0,0 +1,336 @@
+
+ Row and Array Comparisons
+
+
+ IN
+
+
+
+ NOT IN
+
+
+
+ ANY
+
+
+
+ ALL
+
+
+
+ SOME
+
+
+
+ composite type
+ comparison
+
+
+
+ row-wise comparison
+
+
+
+ comparison
+ composite type
+
+
+
+ comparison
+ row constructor
+
+
+
+ IS DISTINCT FROM
+
+
+
+ IS NOT DISTINCT FROM
+
+
+
+ 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
+ PostgreSQL extensions; the rest are
+ SQL-compliant.
+ All of the expression forms documented in this section return
+ Boolean (true/false) results.
+
+
+
+ <literal>IN</literal>
+
+
+expression IN (value, ...)
+
+
+
+ The right-hand side is a parenthesized list
+ of expressions. The result is true if the left-hand expression's
+ result is equal to any of the right-hand expressions. This is a shorthand
+ notation for
+
+
+expression = value1
+OR
+expression = value2
+OR
+...
+
+
+
+
+ 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 IN construct will be null, not false.
+ This is in accordance with SQL's normal rules for Boolean combinations
+ of null values.
+
+
+
+
+ <literal>NOT IN</literal>
+
+
+expression NOT IN (value, ...)
+
+
+
+ The right-hand side is a parenthesized list
+ of expressions. The result is true if the left-hand expression's
+ result is unequal to all of the right-hand expressions. This is a shorthand
+ notation for
+
+
+expression <> value1
+AND
+expression <> value2
+AND
+...
+
+
+
+
+ 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 NOT IN 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.
+
+
+
+
+ x NOT IN y is equivalent to NOT (x IN y) in all
+ cases. However, null values are much more likely to trip up the novice when
+ working with NOT IN than when working with IN.
+ It is best to express your condition positively if possible.
+
+
+
+
+
+ <literal>ANY</literal>/<literal>SOME</literal> (array)
+
+
+expressionoperator ANY (array expression)
+expressionoperator SOME (array expression)
+
+
+
+ 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 operator, which must yield a Boolean
+ result.
+ The result of ANY is true if any true result is obtained.
+ The result is false if no true result is found (including the
+ case where the array has zero elements).
+
+
+
+ If the array expression yields a null array, the result of
+ ANY will be null. If the left-hand expression yields null,
+ the result of ANY 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 ANY
+ 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.
+
+
+
+ SOME is a synonym for ANY.
+
+
+
+
+ <literal>ALL</literal> (array)
+
+
+expressionoperator ALL (array expression)
+
+
+
+ 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 operator, which must yield a Boolean
+ result.
+ The result of ALL is true if all comparisons yield true
+ (including the case where the array has zero elements).
+ The result is false if any false result is found.
+
+
+
+ If the array expression yields a null array, the result of
+ ALL will be null. If the left-hand expression yields null,
+ the result of ALL 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 ALL
+ 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.
+
+
+
+
+ Row Constructor Comparison
+
+
+row_constructoroperatorrow_constructor
+
+
+
+ Each side is a row constructor,
+ as described in .
+ The two row constructors must have the same number of fields.
+ The given operator 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 = member of a B-tree
+ operator class, meaning that row constructor comparison is only
+ possible when the operator is
+ =,
+ <>,
+ <,
+ <=,
+ >, or
+ >=,
+ or has semantics similar to one of these.
+
+
+
+ The = and <> 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).
+
+
+
+ For the <, <=, > and
+ >= 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,
+ ROW(1,2,NULL) < ROW(1,3,0)
+ yields true, not null, because the third pair of elements are not
+ considered.
+
+
+
+row_constructor IS DISTINCT FROM row_constructor
+
+
+
+ This construct is similar to a <> 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.
+
+
+
+row_constructor IS NOT DISTINCT FROM row_constructor
+
+
+
+ This construct is similar to a = 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.
+
+
+
+
+
+ Composite Type Comparison
+
+
+recordoperatorrecord
+
+
+
+ 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.
+ PostgreSQL does this only when comparing the
+ results of two row constructors (as in
+ ) or comparing a row constructor
+ to the output of a subquery (as in ).
+ 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.
+
+
+
+ Each side is evaluated and they are compared row-wise. Composite type
+ comparisons are allowed when the operator is
+ =,
+ <>,
+ <,
+ <=,
+ > or
+ >=,
+ 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 = member of a B-tree operator
+ class.) The default behavior of the above operators is the same as for
+ IS [ NOT ] DISTINCT FROM for row constructors (see
+ ).
+
+
+
+ To support matching of rows which include elements without a default
+ B-tree operator class, the following operators are defined for composite
+ type comparison:
+ *=,
+ *<>,
+ *<,
+ *<=,
+ *>, and
+ *>=.
+ 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 ). They are not intended to be
+ generally useful for writing queries, though.
+
+
+
diff --git a/doc/src/sgml/func/func-conditional.sgml b/doc/src/sgml/func/func-conditional.sgml
new file mode 100644
index 0000000000000..7ca53dbf1ab03
--- /dev/null
+++ b/doc/src/sgml/func/func-conditional.sgml
@@ -0,0 +1,283 @@
+
+ Conditional Expressions
+
+
+ CASE
+
+
+
+ conditional expression
+
+
+
+ This section describes the SQL-compliant conditional expressions
+ available in PostgreSQL.
+
+
+
+
+ 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.
+
+
+
+
+
+ Although COALESCE, GREATEST, and
+ LEAST are syntactically similar to functions, they are
+ not ordinary functions, and thus cannot be used with explicit
+ VARIADIC array arguments.
+
+
+
+
+ <literal>CASE</literal>
+
+
+ The SQL CASE expression is a
+ generic conditional expression, similar to if/else statements in
+ other programming languages:
+
+
+CASE WHEN condition THEN result
+ WHEN ...
+ ELSE result
+END
+
+
+ CASE clauses can be used wherever
+ an expression is valid. Each condition is an
+ expression that returns a boolean result. If the condition's
+ result is true, the value of the CASE expression is the
+ result that follows the condition, and the
+ remainder of the CASE expression is not processed. If the
+ condition's result is not true, any subsequent WHEN clauses
+ are examined in the same manner. If no WHEN
+ condition yields true, the value of the
+ CASE expression is the result of the
+ ELSE clause. If the ELSE clause is
+ omitted and no condition is true, the result is null.
+
+
+
+ An example:
+
+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
+
+
+
+
+ The data types of all the result
+ expressions must be convertible to a single output type.
+ See for more details.
+
+
+
+ There is a simple form of CASE expression
+ that is a variant of the general form above:
+
+
+CASE expression
+ WHEN value THEN result
+ WHEN ...
+ ELSE result
+END
+
+
+ The first
+ expression is computed, then compared to
+ each of the value expressions in the
+ WHEN clauses until one is found that is equal to it. If
+ no match is found, the result of the
+ ELSE clause (or a null value) is returned. This is similar
+ to the switch statement in C.
+
+
+
+ The example above can be written using the simple
+ CASE syntax:
+
+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
+
+
+
+
+ A CASE 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:
+
+SELECT ... WHERE CASE WHEN x <> 0 THEN y/x > 1.5 ELSE false END;
+
+
+
+
+
+ As described in , there are various
+ situations in which subexpressions of an expression are evaluated at
+ different times, so that the principle that CASE
+ evaluates only necessary subexpressions is not ironclad. For
+ example a constant 1/0 subexpression will usually result in
+ a division-by-zero failure at planning time, even if it's within
+ a CASE arm that would never be entered at run time.
+
+
+
+
+
+ <literal>COALESCE</literal>
+
+
+ COALESCE
+
+
+
+ NVL
+
+
+
+ IFNULL
+
+
+
+COALESCE(value, ...)
+
+
+
+ The COALESCE 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:
+
+SELECT COALESCE(description, short_description, '(none)') ...
+
+ This returns description if it is not null, otherwise
+ short_description if it is not null, otherwise (none).
+
+
+
+ The arguments must all be convertible to a common data type, which
+ will be the type of the result (see
+ for details).
+
+
+
+ Like a CASE expression, COALESCE 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 NVL and IFNULL, which are used in some other
+ database systems.
+
+
+
+
+ <literal>NULLIF</literal>
+
+
+ NULLIF
+
+
+
+NULLIF(value1, value2)
+
+
+
+ The NULLIF function returns a null value if
+ value1 equals value2;
+ otherwise it returns value1.
+ This can be used to perform the inverse operation of the
+ COALESCE example given above:
+
+SELECT NULLIF(value, '(none)') ...
+
+ In this example, if value is (none),
+ null is returned, otherwise the value of value
+ is returned.
+
+
+
+ The two arguments must be of comparable types.
+ To be specific, they are compared exactly as if you had
+ written value1
+ = value2, so there must be a
+ suitable = operator available.
+
+
+
+ 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 = operator, and in some cases that will have
+ been promoted to match the second argument's type. For
+ example, NULLIF(1, 2.2) yields numeric,
+ because there is no integer=
+ numeric operator,
+ only numeric=numeric.
+
+
+
+
+
+ <literal>GREATEST</literal> and <literal>LEAST</literal>
+
+
+ GREATEST
+
+
+ LEAST
+
+
+
+GREATEST(value, ...)
+
+
+LEAST(value, ...)
+
+
+
+ The GREATEST and LEAST 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 for details).
+
+
+
+ NULL values in the argument list are ignored. The result will be NULL
+ only if all the expressions evaluate to NULL. (This is a deviation from
+ the SQL standard. According to the standard, the return value is NULL if
+ any argument is NULL. Some other databases behave this way.)
+
+
+
diff --git a/doc/src/sgml/func/func-datetime.sgml b/doc/src/sgml/func/func-datetime.sgml
new file mode 100644
index 0000000000000..8cd7150b0d313
--- /dev/null
+++ b/doc/src/sgml/func/func-datetime.sgml
@@ -0,0 +1,2236 @@
+
+ Date/Time Functions and Operators
+
+
+ shows the available
+ functions for date/time value processing, with details appearing in
+ the following subsections. illustrates the behaviors of
+ the basic arithmetic operators (+,
+ *, etc.). For formatting functions, refer to
+ . You should be familiar with
+ the background information on date/time data types from .
+
+
+
+ In addition, the usual comparison operators shown in
+ 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 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 TimeZone zone when comparing it
+ to a timestamp.
+
+
+
+ All the functions and operators described below that take time or timestamp
+ inputs actually come in two variants: one that takes time with time zone or timestamp
+ with time zone, and one that takes time without time zone or timestamp without time zone.
+ For brevity, these variants are not shown separately. Also, the
+ + and * operators come in commutative pairs (for
+ example both date+integer
+ and integer+date); we show
+ only one of each such pair.
+
+
+
+ Date/Time Operators
+
+
+
+
+
+ Operator
+
+
+ Description
+
+
+ Example(s)
+
+
+
+
+
+
+
+ date+integer
+ date
+
+
+ Add a number of days to a date
+
+
+ date '2001-09-28' + 7
+ 2001-10-05
+
+
+
+
+
+ date+interval
+ timestamp
+
+
+ Add an interval to a date
+
+
+ date '2001-09-28' + interval '1 hour'
+ 2001-09-28 01:00:00
+
+
+
+
+
+ date+time
+ timestamp
+
+
+ Add a time-of-day to a date
+
+
+ date '2001-09-28' + time '03:00'
+ 2001-09-28 03:00:00
+
+
+
+
+
+ interval+interval
+ interval
+
+
+ Add intervals
+
+
+ interval '1 day' + interval '1 hour'
+ 1 day 01:00:00
+
+
+
+
+
+ timestamp+interval
+ timestamp
+
+
+ Add an interval to a timestamp
+
+
+ timestamp '2001-09-28 01:00' + interval '23 hours'
+ 2001-09-29 00:00:00
+
+
+
+
+
+ time+interval
+ time
+
+
+ Add an interval to a time
+
+
+ time '01:00' + interval '3 hours'
+ 04:00:00
+
+
+
+
+
+ -interval
+ interval
+
+
+ Negate an interval
+
+
+ - interval '23 hours'
+ -23:00:00
+
+
+
+
+
+ date-date
+ integer
+
+
+ Subtract dates, producing the number of days elapsed
+
+
+ date '2001-10-01' - date '2001-09-28'
+ 3
+
+
+
+
+
+ date-integer
+ date
+
+
+ Subtract a number of days from a date
+
+
+ date '2001-10-01' - 7
+ 2001-09-24
+
+
+
+
+
+ date-interval
+ timestamp
+
+
+ Subtract an interval from a date
+
+
+ date '2001-09-28' - interval '1 hour'
+ 2001-09-27 23:00:00
+
+
+
+
+
+ time-time
+ interval
+
+
+ Subtract times
+
+
+ time '05:00' - time '03:00'
+ 02:00:00
+
+
+
+
+
+ time-interval
+ time
+
+
+ Subtract an interval from a time
+
+
+ time '05:00' - interval '2 hours'
+ 03:00:00
+
+
+
+
+
+ timestamp-interval
+ timestamp
+
+
+ Subtract an interval from a timestamp
+
+
+ timestamp '2001-09-28 23:00' - interval '23 hours'
+ 2001-09-28 00:00:00
+
+
+
+
+
+ interval-interval
+ interval
+
+
+ Subtract intervals
+
+
+ interval '1 day' - interval '1 hour'
+ 1 day -01:00:00
+
+
+
+
+
+ timestamp-timestamp
+ interval
+
+
+ Subtract timestamps (converting 24-hour intervals into days,
+ similarly to justify_hours())
+
+
+ timestamp '2001-09-29 03:00' - timestamp '2001-07-27 12:00'
+ 63 days 15:00:00
+
+
+
+
+
+ interval*double precision
+ interval
+
+
+ Multiply an interval by a scalar
+
+
+ interval '1 second' * 900
+ 00:15:00
+
+
+ interval '1 day' * 21
+ 21 days
+
+
+ interval '1 hour' * 3.5
+ 03:30:00
+
+
+
+
+
+ interval/double precision
+ interval
+
+
+ Divide an interval by a scalar
+
+
+ interval '1 hour' / 1.5
+ 00:40:00
+
+
+
+
+
+
+
+ Date/Time Functions
+
+
+
+
+ Function
+
+
+ Description
+
+
+ Example(s)
+
+
+
+
+
+
+
+
+ age
+
+ age ( timestamp, timestamp )
+ interval
+
+
+ Subtract arguments, producing a symbolic result that
+ uses years and months, rather than just days
+
+
+ age(timestamp '2001-04-10', timestamp '1957-06-13')
+ 43 years 9 mons 27 days
+
+
+
+
+
+ age ( timestamp )
+ interval
+
+
+ Subtract argument from current_date (at midnight)
+
+
+ age(timestamp '1957-06-13')
+ 62 years 6 mons 10 days
+
+
+
+
+
+
+ clock_timestamp
+
+ clock_timestamp ( )
+ timestamp with time zone
+
+
+ Current date and time (changes during statement execution);
+ see
+
+
+ clock_timestamp()
+ 2019-12-23 14:39:53.662522-05
+
+
+
+
+
+
+ current_date
+
+ current_date
+ date
+
+
+ Current date; see
+
+
+ current_date
+ 2019-12-23
+
+
+
+
+
+
+ current_time
+
+ current_time
+ time with time zone
+
+
+ Current time of day; see
+
+
+ current_time
+ 14:39:53.662522-05
+
+
+
+
+
+ current_time ( integer )
+ time with time zone
+
+
+ Current time of day, with limited precision;
+ see
+
+
+ current_time(2)
+ 14:39:53.66-05
+
+
+
+
+
+
+ current_timestamp
+
+ current_timestamp
+ timestamp with time zone
+
+
+ Current date and time (start of current transaction);
+ see
+
+
+ current_timestamp
+ 2019-12-23 14:39:53.662522-05
+
+
+
+
+
+ current_timestamp ( integer )
+ timestamp with time zone
+
+
+ Current date and time (start of current transaction), with limited precision;
+ see
+
+
+ current_timestamp(0)
+ 2019-12-23 14:39:53-05
+
+
+
+
+
+
+ date_add
+
+ date_add ( timestamp with time zone, interval, text )
+ timestamp with time zone
+
+
+ Add an interval to a timestamp with time
+ zone, computing times of day and daylight-savings adjustments
+ according to the time zone named by the third argument, or the
+ current setting if that is omitted.
+ The form with two arguments is equivalent to the timestamp with
+ time zone+interval operator.
+
+
+ date_add('2021-10-31 00:00:00+02'::timestamptz, '1 day'::interval, 'Europe/Warsaw')
+ 2021-10-31 23:00:00+00
+
+
+
+
+
+ date_bin ( interval, timestamp, timestamp )
+ timestamp
+
+
+ Bin input into specified interval aligned with specified origin; see
+
+
+ date_bin('15 minutes', timestamp '2001-02-16 20:38:40', timestamp '2001-02-16 20:05:00')
+ 2001-02-16 20:35:00
+
+
+
+
+
+
+ date_part
+
+ date_part ( text, timestamp )
+ double precision
+
+
+ Get timestamp subfield (equivalent to extract);
+ see
+
+
+ date_part('hour', timestamp '2001-02-16 20:38:40')
+ 20
+
+
+
+
+
+ date_part ( text, interval )
+ double precision
+
+
+ Get interval subfield (equivalent to extract);
+ see
+
+
+ date_part('month', interval '2 years 3 months')
+ 3
+
+
+
+
+
+
+ date_subtract
+
+ date_subtract ( timestamp with time zone, interval, text )
+ timestamp with time zone
+
+
+ Subtract an interval from a timestamp with time
+ zone, computing times of day and daylight-savings adjustments
+ according to the time zone named by the third argument, or the
+ current setting if that is omitted.
+ The form with two arguments is equivalent to the timestamp with
+ time zone-interval operator.
+
+
+ date_subtract('2021-11-01 00:00:00+01'::timestamptz, '1 day'::interval, 'Europe/Warsaw')
+ 2021-10-30 22:00:00+00
+
+
+
+
+
+
+ date_trunc
+
+ date_trunc ( text, timestamp )
+ timestamp
+
+
+ Truncate to specified precision; see
+
+
+ date_trunc('hour', timestamp '2001-02-16 20:38:40')
+ 2001-02-16 20:00:00
+
+
+
+
+
+ date_trunc ( text, timestamp with time zone, text )
+ timestamp with time zone
+
+
+ Truncate to specified precision in the specified time zone; see
+
+
+
+ date_trunc('day', timestamptz '2001-02-16 20:38:40+00', 'Australia/Sydney')
+ 2001-02-16 13:00:00+00
+
+
+
+
+
+ date_trunc ( text, interval )
+ interval
+
+
+ Truncate to specified precision; see
+
+
+
+ date_trunc('hour', interval '2 days 3 hours 40 minutes')
+ 2 days 03:00:00
+
+
+
+
+
+
+ extract
+
+ extract ( fieldfromtimestamp )
+ numeric
+
+
+ Get timestamp subfield; see
+
+
+ extract(hour from timestamp '2001-02-16 20:38:40')
+ 20
+
+
+
+
+
+ extract ( fieldfrominterval )
+ numeric
+
+
+ Get interval subfield; see
+
+
+ extract(month from interval '2 years 3 months')
+ 3
+
+
+
+
+
+
+ isfinite
+
+ isfinite ( date )
+ boolean
+
+
+ Test for finite date (not +/-infinity)
+
+
+ isfinite(date '2001-02-16')
+ true
+
+
+
+
+
+ isfinite ( timestamp )
+ boolean
+
+
+ Test for finite timestamp (not +/-infinity)
+
+
+ isfinite(timestamp 'infinity')
+ false
+
+
+
+
+
+ isfinite ( interval )
+ boolean
+
+
+ Test for finite interval (not +/-infinity)
+
+
+ isfinite(interval '4 hours')
+ true
+
+
+
+
+
+
+ justify_days
+
+ justify_days ( interval )
+ interval
+
+
+ Adjust interval, converting 30-day time periods to months
+
+
+ justify_days(interval '1 year 65 days')
+ 1 year 2 mons 5 days
+
+
+
+
+
+
+ justify_hours
+
+ justify_hours ( interval )
+ interval
+
+
+ Adjust interval, converting 24-hour time periods to days
+
+
+ justify_hours(interval '50 hours 10 minutes')
+ 2 days 02:10:00
+
+
+
+
+
+
+ justify_interval
+
+ justify_interval ( interval )
+ interval
+
+
+ Adjust interval using justify_days
+ and justify_hours, with additional sign
+ adjustments
+
+
+ justify_interval(interval '1 mon -1 hour')
+ 29 days 23:00:00
+
+
+
+
+
+
+ localtime
+
+ localtime
+ time
+
+
+ Current time of day;
+ see
+
+
+ localtime
+ 14:39:53.662522
+
+
+
+
+
+ localtime ( integer )
+ time
+
+
+ Current time of day, with limited precision;
+ see
+
+
+ localtime(0)
+ 14:39:53
+
+
+
+
+
+
+ localtimestamp
+
+ localtimestamp
+ timestamp
+
+
+ Current date and time (start of current transaction);
+ see
+
+
+ localtimestamp
+ 2019-12-23 14:39:53.662522
+
+
+
+
+
+ localtimestamp ( integer )
+ timestamp
+
+
+ Current date and time (start of current
+ transaction), with limited precision;
+ see
+
+
+ localtimestamp(2)
+ 2019-12-23 14:39:53.66
+
+
+
+
+
+
+ make_date
+
+ make_date ( yearint,
+ monthint,
+ dayint )
+ date
+
+
+ Create date from year, month and day fields
+ (negative years signify BC)
+
+
+ make_date(2013, 7, 15)
+ 2013-07-15
+
+
+
+
+
+ make_interval
+
+ make_interval ( yearsint
+ , monthsint
+ , weeksint
+ , daysint
+ , hoursint
+ , minsint
+ , secsdouble precision
+ )
+ interval
+
+
+ Create interval from years, months, weeks, days, hours, minutes and
+ seconds fields, each of which can default to zero
+
+
+ make_interval(days => 10)
+ 10 days
+
+
+
+
+
+
+ make_time
+
+ make_time ( hourint,
+ minint,
+ secdouble precision )
+ time
+
+
+ Create time from hour, minute and seconds fields
+
+
+ make_time(8, 15, 23.5)
+ 08:15:23.5
+
+
+
+
+
+
+ make_timestamp
+
+ make_timestamp ( yearint,
+ monthint,
+ dayint,
+ hourint,
+ minint,
+ secdouble precision )
+ timestamp
+
+
+ Create timestamp from year, month, day, hour, minute and seconds fields
+ (negative years signify BC)
+
+
+ make_timestamp(2013, 7, 15, 8, 15, 23.5)
+ 2013-07-15 08:15:23.5
+
+
+
+
+
+
+ make_timestamptz
+
+ make_timestamptz ( yearint,
+ monthint,
+ dayint,
+ hourint,
+ minint,
+ secdouble precision
+ , timezonetext )
+ timestamp with time zone
+
+
+ Create timestamp with time zone from year, month, day, hour, minute
+ and seconds fields (negative years signify BC).
+ If timezone is not
+ specified, the current time zone is used; the examples assume the
+ session time zone is Europe/London
+
+
+ make_timestamptz(2013, 7, 15, 8, 15, 23.5)
+ 2013-07-15 08:15:23.5+01
+
+
+ make_timestamptz(2013, 7, 15, 8, 15, 23.5, 'America/New_York')
+ 2013-07-15 13:15:23.5+01
+
+
+
+
+
+
+ now
+
+ now ( )
+ timestamp with time zone
+
+
+ Current date and time (start of current transaction);
+ see
+
+
+ now()
+ 2019-12-23 14:39:53.662522-05
+
+
+
+
+
+
+ random
+
+ random ( mindate, maxdate )
+ date
+
+
+ random ( mintimestamp, maxtimestamp )
+ timestamp
+
+
+ random ( mintimestamptz, maxtimestamptz )
+ timestamptz
+
+
+ Returns a random value in the range
+ min <= x <= max.
+
+
+ Note that these functions use the same pseudo-random number generator
+ as the functions listed in ,
+ and respond in the same way to calling
+ setseed().
+
+
+ random('1979-02-08'::date,'2025-07-03'::date)
+ 1983-04-21
+
+
+ random('2000-01-01'::timestamptz, now())
+ 2015-09-27 09:11:33.732707+00
+
+
+
+
+
+
+ statement_timestamp
+
+ statement_timestamp ( )
+ timestamp with time zone
+
+
+ Current date and time (start of current statement);
+ see
+
+
+ statement_timestamp()
+ 2019-12-23 14:39:53.662522-05
+
+
+
+
+
+
+ timeofday
+
+ timeofday ( )
+ text
+
+
+ Current date and time
+ (like clock_timestamp, but as a text string);
+ see
+
+
+ timeofday()
+ Mon Dec 23 14:39:53.662522 2019 EST
+
+
+
+
+
+
+ transaction_timestamp
+
+ transaction_timestamp ( )
+ timestamp with time zone
+
+
+ Current date and time (start of current transaction);
+ see
+
+
+ transaction_timestamp()
+ 2019-12-23 14:39:53.662522-05
+
+
+
+
+
+
+ to_timestamp
+
+ to_timestamp ( double precision )
+ timestamp with time zone
+
+
+ Convert Unix epoch (seconds since 1970-01-01 00:00:00+00) to
+ timestamp with time zone
+
+
+ to_timestamp(1284352323)
+ 2010-09-13 04:32:03+00
+
+
+
+
+
+
+
+
+ OVERLAPS
+
+ In addition to these functions, the SQL OVERLAPS operator is
+ supported:
+
+(start1, end1) OVERLAPS (start2, end2)
+(start1, length1) OVERLAPS (start2, length2)
+
+ 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; OVERLAPS automatically takes the earlier value
+ of the pair as the start. Each time period is considered to
+ represent the half-open interval start<=
+ time<end, unless
+ start and end 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.
+
+
+
+SELECT (DATE '2001-02-16', DATE '2001-12-21') OVERLAPS
+ (DATE '2001-10-30', DATE '2002-10-30');
+Result: true
+SELECT (DATE '2001-02-16', INTERVAL '100 days') OVERLAPS
+ (DATE '2001-10-30', DATE '2002-10-30');
+Result: false
+SELECT (DATE '2001-10-29', DATE '2001-10-30') OVERLAPS
+ (DATE '2001-10-30', DATE '2001-10-31');
+Result: false
+SELECT (DATE '2001-10-30', DATE '2001-10-30') OVERLAPS
+ (DATE '2001-10-30', DATE '2001-10-31');
+Result: true
+
+
+
+ When adding an interval value to (or subtracting an
+ interval value from) a timestamp
+ or timestamp with time zone value, the months, days, and
+ microseconds fields of the interval value are handled in turn.
+ First, a nonzero months field advances or decrements the date of the
+ timestamp by the indicated number of months, keeping the day of month the
+ same unless it would be past the end of the new month, in which case the
+ last day of that month is used. (For example, March 31 plus 1 month
+ becomes April 30, but March 31 plus 2 months becomes May 31.)
+ Then the days field advances or decrements the date of the timestamp by
+ the indicated number of days. In both these steps the local time of day
+ is kept the same. Finally, if there is a nonzero microseconds field, it
+ is added or subtracted literally.
+ When doing arithmetic on a timestamp with time zone value in
+ a time zone that recognizes DST, this means that adding or subtracting
+ (say) interval '1 day' does not necessarily have the
+ same result as adding or subtracting interval '24
+ hours'.
+ For example, with the session time zone set
+ to America/Denver:
+
+SELECT timestamp with time zone '2005-04-02 12:00:00-07' + interval '1 day';
+Result: 2005-04-03 12:00:00-06
+SELECT timestamp with time zone '2005-04-02 12:00:00-07' + interval '24 hours';
+Result: 2005-04-03 13:00:00-06
+
+ This happens because an hour was skipped due to a change in daylight saving
+ time at 2005-04-03 02:00:00 in time zone
+ America/Denver.
+
+
+
+ Note there can be ambiguity in the months field returned by
+ age because different months have different numbers of
+ days. PostgreSQL's approach uses the month from the
+ earlier of the two dates when calculating partial months. For example,
+ age('2004-06-01', '2004-04-30') uses April to yield
+ 1 mon 1 day, while using May would yield 1 mon 2
+ days because May has 31 days, while April has only 30.
+
+
+
+ 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 EXTRACT(EPOCH FROM ...), then subtract the
+ results; this produces the
+ number of seconds 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 - operator
+ returns the number of days (24-hours) and hours/minutes/seconds
+ between the values, making the same adjustments. The age
+ 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 timezone
+ = 'US/Eastern'; there is a daylight saving time change between the
+ two dates used:
+
+
+
+SELECT EXTRACT(EPOCH FROM timestamptz '2013-07-01 12:00:00') -
+ EXTRACT(EPOCH FROM timestamptz '2013-03-01 12:00:00');
+Result: 10537200.000000
+SELECT (EXTRACT(EPOCH FROM timestamptz '2013-07-01 12:00:00') -
+ EXTRACT(EPOCH FROM timestamptz '2013-03-01 12:00:00'))
+ / 60 / 60 / 24;
+Result: 121.9583333333333333
+SELECT timestamptz '2013-07-01 12:00:00' - timestamptz '2013-03-01 12:00:00';
+Result: 121 days 23:00:00
+SELECT age(timestamptz '2013-07-01 12:00:00', timestamptz '2013-03-01 12:00:00');
+Result: 4 mons
+
+
+
+ <function>EXTRACT</function>, <function>date_part</function>
+
+
+ date_part
+
+
+ extract
+
+
+
+EXTRACT(field FROM source)
+
+
+
+ The extract function retrieves subfields
+ such as year or hour from date/time values.
+ source must be a value expression of
+ type timestamp, date, time,
+ or interval. (Timestamps and times can be with or
+ without time zone.)
+ field is an identifier or
+ string that selects what field to extract from the source value.
+ Not all fields are valid for every input data type; for example, fields
+ smaller than a day cannot be extracted from a date, while
+ fields of a day or more cannot be extracted from a time.
+ The extract function returns values of type
+ numeric.
+
+
+
+ The following are valid field names:
+
+
+
+
+ century
+
+
+ The century; for interval values, the year field
+ divided by 100
+
+
+
+SELECT EXTRACT(CENTURY FROM TIMESTAMP '2000-12-16 12:21:13');
+Result: 20
+SELECT EXTRACT(CENTURY FROM TIMESTAMP '2001-02-16 20:38:40');
+Result: 21
+SELECT EXTRACT(CENTURY FROM DATE '0001-01-01 AD');
+Result: 1
+SELECT EXTRACT(CENTURY FROM DATE '0001-12-31 BC');
+Result: -1
+SELECT EXTRACT(CENTURY FROM INTERVAL '2001 years');
+Result: 20
+
+
+
+
+
+ day
+
+
+ The day of the month (1–31); for interval
+ values, the number of days
+
+
+
+SELECT EXTRACT(DAY FROM TIMESTAMP '2001-02-16 20:38:40');
+Result: 16
+SELECT EXTRACT(DAY FROM INTERVAL '40 days 1 minute');
+Result: 40
+
+
+
+
+
+
+ decade
+
+
+ The year field divided by 10
+
+
+
+SELECT EXTRACT(DECADE FROM TIMESTAMP '2001-02-16 20:38:40');
+Result: 200
+
+
+
+
+
+ dow
+
+
+ The day of the week as Sunday (0) to
+ Saturday (6)
+
+
+
+SELECT EXTRACT(DOW FROM TIMESTAMP '2001-02-16 20:38:40');
+Result: 5
+
+
+ Note that extract's day of the week numbering
+ differs from that of the to_char(...,
+ 'D') function.
+
+
+
+
+
+
+ doy
+
+
+ The day of the year (1–365/366)
+
+
+
+SELECT EXTRACT(DOY FROM TIMESTAMP '2001-02-16 20:38:40');
+Result: 47
+
+
+
+
+
+ epoch
+
+
+ For timestamp with time zone values, the
+ number of seconds since 1970-01-01 00:00:00 UTC (negative for
+ timestamps before that);
+ for date and timestamp values, the
+ nominal number of seconds since 1970-01-01 00:00:00,
+ without regard to timezone or daylight-savings rules;
+ for interval values, the total number
+ of seconds in the interval
+
+
+
+SELECT EXTRACT(EPOCH FROM TIMESTAMP WITH TIME ZONE '2001-02-16 20:38:40.12-08');
+Result: 982384720.120000
+SELECT EXTRACT(EPOCH FROM TIMESTAMP '2001-02-16 20:38:40.12');
+Result: 982355920.120000
+SELECT EXTRACT(EPOCH FROM INTERVAL '5 days 3 hours');
+Result: 442800.000000
+
+
+
+ You can convert an epoch value back to a timestamp with time zone
+ with to_timestamp:
+
+
+SELECT to_timestamp(982384720.12);
+Result: 2001-02-17 04:38:40.12+00
+
+
+
+ Beware that applying to_timestamp to an epoch
+ extracted from a date or timestamp 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.
+
+
+
+
+
+ hour
+
+
+ The hour field (0–23 in timestamps, unrestricted in
+ intervals)
+
+
+
+SELECT EXTRACT(HOUR FROM TIMESTAMP '2001-02-16 20:38:40');
+Result: 20
+
+
+
+
+
+ isodow
+
+
+ The day of the week as Monday (1) to
+ Sunday (7)
+
+
+
+SELECT EXTRACT(ISODOW FROM TIMESTAMP '2001-02-18 20:38:40');
+Result: 7
+
+
+ This is identical to dow except for Sunday. This
+ matches the ISO 8601 day of the week numbering.
+
+
+
+
+
+
+ isoyear
+
+
+ The ISO 8601 week-numbering year that the date
+ falls in
+
+
+
+SELECT EXTRACT(ISOYEAR FROM DATE '2006-01-01');
+Result: 2005
+SELECT EXTRACT(ISOYEAR FROM DATE '2006-01-02');
+Result: 2006
+
+
+
+ Each ISO 8601 week-numbering year begins with the
+ Monday of the week containing the 4th of January, so in early
+ January or late December the ISO year may be
+ different from the Gregorian year. See the week
+ field for more information.
+
+
+
+
+
+ julian
+
+
+ The Julian Date corresponding to the
+ date or timestamp. Timestamps
+ that are not local midnight result in a fractional value. See
+ for more information.
+
+
+
+SELECT EXTRACT(JULIAN FROM DATE '2006-01-01');
+Result: 2453737
+SELECT EXTRACT(JULIAN FROM TIMESTAMP '2006-01-01 12:00');
+Result: 2453737.50000000000000000000
+
+
+
+
+
+ microseconds
+
+
+ The seconds field, including fractional parts, multiplied by 1
+ 000 000; note that this includes full seconds
+
+
+
+SELECT EXTRACT(MICROSECONDS FROM TIME '17:12:28.5');
+Result: 28500000
+
+
+
+
+
+ millennium
+
+
+ The millennium; for interval values, the year field
+ divided by 1000
+
+
+
+SELECT EXTRACT(MILLENNIUM FROM TIMESTAMP '2001-02-16 20:38:40');
+Result: 3
+SELECT EXTRACT(MILLENNIUM FROM INTERVAL '2001 years');
+Result: 2
+
+
+
+ Years in the 1900s are in the second millennium.
+ The third millennium started January 1, 2001.
+
+
+
+
+
+ milliseconds
+
+
+ The seconds field, including fractional parts, multiplied by
+ 1000. Note that this includes full seconds.
+
+
+
+SELECT EXTRACT(MILLISECONDS FROM TIME '17:12:28.5');
+Result: 28500.000
+
+
+
+
+
+ minute
+
+
+ The minutes field (0–59)
+
+
+
+SELECT EXTRACT(MINUTE FROM TIMESTAMP '2001-02-16 20:38:40');
+Result: 38
+
+
+
+
+
+ month
+
+
+ The number of the month within the year (1–12);
+ for interval values, the number of months modulo 12
+ (0–11)
+
+
+
+SELECT EXTRACT(MONTH FROM TIMESTAMP '2001-02-16 20:38:40');
+Result: 2
+SELECT EXTRACT(MONTH FROM INTERVAL '2 years 3 months');
+Result: 3
+SELECT EXTRACT(MONTH FROM INTERVAL '2 years 13 months');
+Result: 1
+
+
+
+
+
+ quarter
+
+
+ The quarter of the year (1–4) that the date is in;
+ for interval values, the month field divided by 3
+ plus 1
+
+
+
+SELECT EXTRACT(QUARTER FROM TIMESTAMP '2001-02-16 20:38:40');
+Result: 1
+SELECT EXTRACT(QUARTER FROM INTERVAL '1 year 6 months');
+Result: 3
+
+
+
+
+
+ second
+
+
+ The seconds field, including any fractional seconds
+
+
+
+SELECT EXTRACT(SECOND FROM TIMESTAMP '2001-02-16 20:38:40');
+Result: 40.000000
+SELECT EXTRACT(SECOND FROM TIME '17:12:28.5');
+Result: 28.500000
+
+
+
+
+ timezone
+
+
+ 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,
+ PostgreSQL does not use UTC because
+ leap seconds are not handled.)
+
+
+
+
+
+ timezone_hour
+
+
+ The hour component of the time zone offset
+
+
+
+
+
+ timezone_minute
+
+
+ The minute component of the time zone offset
+
+
+
+
+
+ week
+
+
+ The number of the ISO 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.
+
+
+ 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, 2005-01-01 is part of the 53rd week of year
+ 2004, and 2006-01-01 is part of the 52nd week of year
+ 2005, while 2012-12-31 is part of the first week of 2013.
+ It's recommended to use the isoyear field together with
+ week to get consistent results.
+
+
+
+ For interval values, the week field is simply the number
+ of integral days divided by 7.
+
+
+
+SELECT EXTRACT(WEEK FROM TIMESTAMP '2001-02-16 20:38:40');
+Result: 7
+SELECT EXTRACT(WEEK FROM INTERVAL '13 days 24 hours');
+Result: 1
+
+
+
+
+
+ year
+
+
+ The year field. Keep in mind there is no 0 AD, so subtracting
+ BC years from AD years should be done with care.
+
+
+
+SELECT EXTRACT(YEAR FROM TIMESTAMP '2001-02-16 20:38:40');
+Result: 2001
+
+
+
+
+
+
+
+
+ When processing an interval value,
+ the extract function produces field values that
+ match the interpretation used by the interval output function. This
+ can produce surprising results if one starts with a non-normalized
+ interval representation, for example:
+
+SELECT INTERVAL '80 minutes';
+Result: 01:20:00
+SELECT EXTRACT(MINUTES FROM INTERVAL '80 minutes');
+Result: 20
+
+
+
+
+
+ When the input value is +/-Infinity, extract returns
+ +/-Infinity for monotonically-increasing fields (epoch,
+ julian, year, isoyear,
+ decade, century, and millennium
+ for timestamp inputs; epoch, hour,
+ day, year, decade,
+ century, and millennium for
+ interval inputs).
+ For other fields, NULL is returned. PostgreSQL
+ versions before 9.6 returned zero for all cases of infinite input.
+
+
+
+
+ The extract function is primarily intended
+ for computational processing. For formatting date/time values for
+ display, see .
+
+
+
+ The date_part function is modeled on the traditional
+ Ingres equivalent to the
+ SQL-standard function extract:
+
+date_part('field', source)
+
+ Note that here the field parameter needs to
+ be a string value, not a name. The valid field names for
+ date_part are the same as for
+ extract.
+ For historical reasons, the date_part function
+ returns values of type double precision. This can result in
+ a loss of precision in certain uses. Using extract
+ is recommended instead.
+
+
+
+SELECT date_part('day', TIMESTAMP '2001-02-16 20:38:40');
+Result: 16
+SELECT date_part('hour', INTERVAL '4 hours 3 minutes');
+Result: 4
+
+
+
+
+
+ <function>date_trunc</function>
+
+
+ date_trunc
+
+
+
+ The function date_trunc is conceptually
+ similar to the trunc function for numbers.
+
+
+
+
+date_trunc(field, source, time_zone)
+
+ source is a value expression of type
+ timestamp, timestamp with time zone,
+ or interval.
+ (Values of type date and
+ time are cast automatically to timestamp or
+ interval, respectively.)
+ field selects to which precision to
+ truncate the input value. The return value is likewise of type
+ timestamp, timestamp with time zone,
+ or interval,
+ and it has all fields that are less significant than the
+ selected one set to zero (or one, for day and month).
+
+
+
+ Valid values for field are:
+
+ microseconds
+ milliseconds
+ second
+ minute
+ hour
+ day
+ week
+ month
+ quarter
+ year
+ decade
+ century
+ millennium
+
+
+
+
+ When the input value is of type timestamp with time zone,
+ the truncation is performed with respect to a particular time zone;
+ for example, truncation to day produces a value that
+ is midnight in that zone. By default, truncation is done with respect
+ to the current setting, but the
+ optional time_zone 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 time zone cannot be specified when processing timestamp without
+ time zone or interval inputs. These are always
+ taken at face value.
+
+
+
+ Examples (assuming the local time zone is America/New_York):
+
+SELECT date_trunc('hour', TIMESTAMP '2001-02-16 20:38:40');
+Result: 2001-02-16 20:00:00
+SELECT date_trunc('year', TIMESTAMP '2001-02-16 20:38:40');
+Result: 2001-01-01 00:00:00
+SELECT date_trunc('day', TIMESTAMP WITH TIME ZONE '2001-02-16 20:38:40+00');
+Result: 2001-02-16 00:00:00-05
+SELECT date_trunc('day', TIMESTAMP WITH TIME ZONE '2001-02-16 20:38:40+00', 'Australia/Sydney');
+Result: 2001-02-16 08:00:00-05
+SELECT date_trunc('hour', INTERVAL '3 days 02:47:33');
+Result: 3 days 02:00:00
+
+
+
+
+
+ <function>date_bin</function>
+
+
+ date_bin
+
+
+
+ The function date_binbins the input
+ timestamp into the specified interval (the stride)
+ aligned with a specified origin.
+
+
+
+
+date_bin(stride, source, origin)
+
+ source is a value expression of type
+ timestamp or timestamp with time zone. (Values
+ of type date are cast automatically to
+ timestamp.) stride is a value
+ expression of type interval. The return value is likewise
+ of type timestamp or timestamp with time zone,
+ and it marks the beginning of the bin into which the
+ source is placed.
+
+
+
+ Examples:
+
+SELECT date_bin('15 minutes', TIMESTAMP '2020-02-11 15:44:17', TIMESTAMP '2001-01-01');
+Result: 2020-02-11 15:30:00
+SELECT date_bin('15 minutes', TIMESTAMP '2020-02-11 15:44:17', TIMESTAMP '2001-01-01 00:02:30');
+Result: 2020-02-11 15:32:30
+
+
+
+
+ In the case of full units (1 minute, 1 hour, etc.), it gives the same result as
+ the analogous date_trunc call, but the difference is
+ that date_bin can truncate to an arbitrary interval.
+
+
+
+ The stride interval must be greater than zero and
+ cannot contain units of month or larger.
+
+
+
+
+ <literal>AT TIME ZONE</literal> and <literal>AT LOCAL</literal>
+
+
+ time zone
+ conversion
+
+
+
+ AT TIME ZONE
+
+
+
+ AT LOCAL
+
+
+
+ The AT TIME ZONE operator converts time
+ stamp without time zone to/from
+ time stamp with time zone, and
+ time with time zone values to different time
+ zones. shows its
+ variants.
+
+
+
+ <literal>AT TIME ZONE</literal> and <literal>AT LOCAL</literal> Variants
+
+
+
+
+ Operator
+
+
+ Description
+
+
+ Example(s)
+
+
+
+
+
+
+
+ timestamp without time zoneAT TIME ZONEzone
+ timestamp with time zone
+
+
+ Converts given time stamp without time zone to
+ time stamp with time zone, assuming the given
+ value is in the named time zone.
+
+
+ timestamp '2001-02-16 20:38:40' at time zone 'America/Denver'
+ 2001-02-17 03:38:40+00
+
+
+
+
+
+ timestamp without time zoneAT LOCAL
+ timestamp with time zone
+
+
+ Converts given time stamp without time zone to
+ time stamp with the session's
+ TimeZone value as time zone.
+
+
+ timestamp '2001-02-16 20:38:40' at local
+ 2001-02-17 03:38:40+00
+
+
+
+
+
+ timestamp with time zoneAT TIME ZONEzone
+ timestamp without time zone
+
+
+ Converts given time stamp with time zone to
+ time stamp without time zone, as the time would
+ appear in that zone.
+
+
+ timestamp with time zone '2001-02-16 20:38:40-05' at time zone 'America/Denver'
+ 2001-02-16 18:38:40
+
+
+
+
+
+ timestamp with time zoneAT LOCAL
+ timestamp without time zone
+
+
+ Converts given time stamp with time zone to
+ time stamp without time zone, as the time would
+ appear with the session's TimeZone value as time zone.
+
+
+ timestamp with time zone '2001-02-16 20:38:40-05' at local
+ 2001-02-16 18:38:40
+
+
+
+
+
+ time with time zoneAT TIME ZONEzone
+ time with time zone
+
+
+ Converts given time with time zone to a new time
+ zone. Since no date is supplied, this uses the currently active UTC
+ offset for the named destination zone.
+
+
+ time with time zone '05:34:17-05' at time zone 'UTC'
+ 10:34:17+00
+
+
+
+
+
+ time with time zoneAT LOCAL
+ time with time zone
+
+
+ Converts given time with time zone to a new time
+ zone. Since no date is supplied, this uses the currently active UTC
+ offset for the session's TimeZone value.
+
+
+ Assuming the session's TimeZone is set to UTC:
+
+
+ time with time zone '05:34:17-05' at local
+ 10:34:17+00
+
+
+
+
+
+
+
+ In these expressions, the desired time zone zone can be
+ specified either as a text value (e.g., 'America/Los_Angeles')
+ or as an interval (e.g., INTERVAL '-08:00').
+ In the text case, a time zone name can be specified in any of the ways
+ described in .
+ The interval case is only useful for zones that have fixed offsets from
+ UTC, so it is not very common in practice.
+
+
+
+ The syntax AT LOCAL may be used as shorthand for
+ AT TIME ZONE local, where
+ local is the session's
+ TimeZone value.
+
+
+
+ Examples (assuming the current setting
+ is America/Los_Angeles):
+
+SELECT TIMESTAMP '2001-02-16 20:38:40' AT TIME ZONE 'America/Denver';
+Result: 2001-02-16 19:38:40-08
+SELECT TIMESTAMP WITH TIME ZONE '2001-02-16 20:38:40-05' AT TIME ZONE 'America/Denver';
+Result: 2001-02-16 18:38:40
+SELECT TIMESTAMP '2001-02-16 20:38:40' AT TIME ZONE 'Asia/Tokyo' AT TIME ZONE 'America/Chicago';
+Result: 2001-02-16 05:38:40
+SELECT TIMESTAMP WITH TIME ZONE '2001-02-16 20:38:40-05' AT LOCAL;
+Result: 2001-02-16 17:38:40
+SELECT TIMESTAMP WITH TIME ZONE '2001-02-16 20:38:40-05' AT TIME ZONE '+05';
+Result: 2001-02-16 20:38:40
+SELECT TIME WITH TIME ZONE '20:38:40-05' AT LOCAL;
+Result: 17:38:40
+
+ The first example adds a time zone to a value that lacks it, and
+ displays the value using the current TimeZone
+ 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
+ TimeZone setting. The third example converts
+ Tokyo time to Chicago time. The fourth example shifts the time stamp
+ with time zone value to the time zone currently specified by the
+ TimeZone setting and returns the value without a
+ time zone. The fifth example demonstrates that the sign in a POSIX-style
+ time zone specification has the opposite meaning of the sign in an
+ ISO-8601 datetime literal, as described in
+ and .
+
+
+
+ The sixth example is a cautionary tale. Due to the fact that there is no
+ date associated with the input value, the conversion is made using the
+ current date of the session. Therefore, this static example may show a wrong
+ result depending on the time of the year it is viewed because
+ 'America/Los_Angeles' observes Daylight Savings Time.
+
+
+
+ The function timezone(zone,
+ timestamp) is equivalent to the SQL-conforming construct
+ timestamp AT TIME ZONE
+ zone.
+
+
+
+ The function timezone(zone,
+ time) is equivalent to the SQL-conforming construct
+ time AT TIME ZONE
+ zone.
+
+
+
+ The function timezone(timestamp)
+ is equivalent to the SQL-conforming construct timestamp
+ AT LOCAL.
+
+
+
+ The function timezone(time)
+ is equivalent to the SQL-conforming construct time
+ AT LOCAL.
+
+
+
+
+ Current Date/Time
+
+
+ date
+ current
+
+
+
+ time
+ current
+
+
+
+ PostgreSQL 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:
+
+CURRENT_DATE
+CURRENT_TIME
+CURRENT_TIMESTAMP
+CURRENT_TIME(precision)
+CURRENT_TIMESTAMP(precision)
+LOCALTIME
+LOCALTIMESTAMP
+LOCALTIME(precision)
+LOCALTIMESTAMP(precision)
+
+
+
+
+ CURRENT_TIME and
+ CURRENT_TIMESTAMP deliver values with time zone;
+ LOCALTIME and
+ LOCALTIMESTAMP deliver values without time zone.
+
+
+
+ CURRENT_TIME,
+ CURRENT_TIMESTAMP,
+ LOCALTIME, and
+ LOCALTIMESTAMP
+ 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.
+
+
+
+ Some examples:
+
+SELECT CURRENT_TIME;
+Result: 14:39:53.662522-05
+SELECT CURRENT_DATE;
+Result: 2019-12-23
+SELECT CURRENT_TIMESTAMP;
+Result: 2019-12-23 14:39:53.662522-05
+SELECT CURRENT_TIMESTAMP(2);
+Result: 2019-12-23 14:39:53.66-05
+SELECT LOCALTIMESTAMP;
+Result: 2019-12-23 14:39:53.662522
+
+
+
+
+ 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 current time, so that multiple
+ modifications within the same transaction bear the same
+ time stamp.
+
+
+
+
+ Other database systems might advance these values more
+ frequently.
+
+
+
+
+ PostgreSQL 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:
+
+transaction_timestamp()
+statement_timestamp()
+clock_timestamp()
+timeofday()
+now()
+
+
+
+
+ transaction_timestamp() is equivalent to
+ CURRENT_TIMESTAMP, but is named to clearly reflect
+ what it returns.
+ statement_timestamp() returns the start time of the current
+ statement (more specifically, the time of receipt of the latest command
+ message from the client).
+ statement_timestamp() and transaction_timestamp()
+ return the same value during the first statement of a transaction, but might
+ differ during subsequent statements.
+ clock_timestamp() returns the actual current time, and
+ therefore its value changes even within a single SQL statement.
+ timeofday() is a historical
+ PostgreSQL function. Like
+ clock_timestamp(), it returns the actual current time,
+ but as a formatted text string rather than a timestamp
+ with time zone value.
+ now() is a traditional PostgreSQL
+ equivalent to transaction_timestamp().
+
+
+
+ All the date/time data types also accept the special literal value
+ now to specify the current date and time (again,
+ interpreted as the transaction start time). Thus,
+ the following three all return the same result:
+
+SELECT CURRENT_TIMESTAMP;
+SELECT now();
+SELECT TIMESTAMP 'now'; -- but see tip below
+
+
+
+
+
+ Do not use the third form when specifying a value to be evaluated later,
+ for example in a DEFAULT clause for a table column.
+ The system will convert now
+ to a timestamp 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 .)
+
+
+
+
+
+ Delaying Execution
+
+
+ pg_sleep
+
+
+ pg_sleep_for
+
+
+ pg_sleep_until
+
+
+ sleep
+
+
+ delay
+
+
+
+ The following functions are available to delay execution of the server
+ process:
+
+pg_sleep ( double precision )
+pg_sleep_for ( interval )
+pg_sleep_until ( timestamp with time zone )
+
+
+ pg_sleep makes the current session's process
+ sleep until the given number of seconds have
+ elapsed. Fractional-second delays can be specified.
+ pg_sleep_for is a convenience function to
+ allow the sleep time to be specified as an interval.
+ pg_sleep_until is a convenience function for when
+ a specific wake-up time is desired.
+ For example:
+
+
+SELECT pg_sleep(1.5);
+SELECT pg_sleep_for('5 minutes');
+SELECT pg_sleep_until('tomorrow 03:00');
+
+
+
+
+
+ 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, pg_sleep_until is not guaranteed to
+ wake up exactly at the specified time, but it will not wake up any earlier.
+
+
+
+
+
+ Make sure that your session does not hold more locks than necessary
+ when calling pg_sleep or its variants. Otherwise
+ other sessions might have to wait for your sleeping process, slowing down
+ the entire system.
+
+
+
+
+
diff --git a/doc/src/sgml/func/func-enum.sgml b/doc/src/sgml/func/func-enum.sgml
new file mode 100644
index 0000000000000..6227afe4057ba
--- /dev/null
+++ b/doc/src/sgml/func/func-enum.sgml
@@ -0,0 +1,121 @@
+
+ Enum Support Functions
+
+
+ For enum types (described in ),
+ there are several functions that allow cleaner programming without
+ hard-coding particular values of an enum type.
+ These are listed in . The examples
+ assume an enum type created as:
+
+
+CREATE TYPE rainbow AS ENUM ('red', 'orange', 'yellow', 'green', 'blue', 'purple');
+
+
+
+
+
+ Enum Support Functions
+
+
+
+
+ Function
+
+
+ Description
+
+
+ Example(s)
+
+
+
+
+
+
+
+
+ enum_first
+
+ enum_first ( anyenum )
+ anyenum
+
+
+ Returns the first value of the input enum type.
+
+
+ enum_first(null::rainbow)
+ red
+
+
+
+
+
+ enum_last
+
+ enum_last ( anyenum )
+ anyenum
+
+
+ Returns the last value of the input enum type.
+
+
+ enum_last(null::rainbow)
+ purple
+
+
+
+
+
+ enum_range
+
+ enum_range ( anyenum )
+ anyarray
+
+
+ Returns all values of the input enum type in an ordered array.
+
+
+ enum_range(null::rainbow)
+ {red,orange,yellow,&zwsp;green,blue,purple}
+
+
+
+
+ enum_range ( anyenum, anyenum )
+ anyarray
+
+
+ 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.
+
+
+ enum_range('orange'::rainbow, 'green'::rainbow)
+ {orange,yellow,green}
+
+
+ enum_range(NULL, 'green'::rainbow)
+ {red,orange,&zwsp;yellow,green}
+
+
+ enum_range('orange'::rainbow, NULL)
+ {orange,yellow,green,&zwsp;blue,purple}
+
+
+
+
+
+
+
+ Notice that except for the two-argument form of enum_range,
+ 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.
+
+
diff --git a/doc/src/sgml/func/func-event-triggers.sgml b/doc/src/sgml/func/func-event-triggers.sgml
new file mode 100644
index 0000000000000..9f3f51e9f5133
--- /dev/null
+++ b/doc/src/sgml/func/func-event-triggers.sgml
@@ -0,0 +1,332 @@
+
+ Event Trigger Functions
+
+
+ PostgreSQL provides these helper functions
+ to retrieve information from event triggers.
+
+
+
+ For more information about event triggers,
+ see .
+
+
+
+ Capturing Changes at Command End
+
+
+ pg_event_trigger_ddl_commands
+
+
+
+pg_event_trigger_ddl_commands () setof record
+
+
+
+ pg_event_trigger_ddl_commands returns a list of
+ DDL commands executed by each user action,
+ when invoked in a function attached to a
+ ddl_command_end event trigger. If called in any other
+ context, an error is raised.
+ pg_event_trigger_ddl_commands 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:
+
+
+
+
+
+ Name
+ Type
+ Description
+
+
+
+
+
+ classid
+ oid
+ OID of catalog the object belongs in
+
+
+ objid
+ oid
+ OID of the object itself
+
+
+ objsubid
+ integer
+ Sub-object ID (e.g., attribute number for a column)
+
+
+ command_tag
+ text
+ Command tag
+
+
+ object_type
+ text
+ Type of the object
+
+
+ schema_name
+ text
+
+ Name of the schema the object belongs in, if any; otherwise NULL.
+ No quoting is applied.
+
+
+
+ object_identity
+ text
+
+ Text rendering of the object identity, schema-qualified. Each
+ identifier included in the identity is quoted if necessary.
+
+
+
+ in_extension
+ boolean
+ True if the command is part of an extension script
+
+
+ command
+ pg_ddl_command
+
+ 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.
+
+
+
+
+
+
+
+
+
+ Processing Objects Dropped by a DDL Command
+
+
+ pg_event_trigger_dropped_objects
+
+
+
+pg_event_trigger_dropped_objects () setof record
+
+
+
+ pg_event_trigger_dropped_objects returns a list of all objects
+ dropped by the command in whose sql_drop event it is called.
+ If called in any other context, an error is raised.
+ This function returns the following columns:
+
+
+
+
+
+ Name
+ Type
+ Description
+
+
+
+
+
+ classid
+ oid
+ OID of catalog the object belonged in
+
+
+ objid
+ oid
+ OID of the object itself
+
+
+ objsubid
+ integer
+ Sub-object ID (e.g., attribute number for a column)
+
+
+ original
+ boolean
+ True if this was one of the root object(s) of the deletion
+
+
+ normal
+ boolean
+
+ True if there was a normal dependency relationship
+ in the dependency graph leading to this object
+
+
+
+ is_temporary
+ boolean
+
+ True if this was a temporary object
+
+
+
+ object_type
+ text
+ Type of the object
+
+
+ schema_name
+ text
+
+ Name of the schema the object belonged in, if any; otherwise NULL.
+ No quoting is applied.
+
+
+
+ object_name
+ text
+
+ Name of the object, if the combination of schema and name can be
+ used as a unique identifier for the object; otherwise NULL.
+ No quoting is applied, and name is never schema-qualified.
+
+
+
+ object_identity
+ text
+
+ Text rendering of the object identity, schema-qualified. Each
+ identifier included in the identity is quoted if necessary.
+
+
+
+ address_names
+ text[]
+
+ An array that, together with object_type and
+ address_args, can be used by
+ the pg_get_object_address function to
+ recreate the object address in a remote server containing an
+ identically named object of the same kind.
+
+
+
+ address_args
+ text[]
+
+ Complement for address_names
+
+
+
+
+
+
+
+
+ The pg_event_trigger_dropped_objects function can be used
+ in an event trigger like this:
+
+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();
+
+
+
+
+
+ Handling a Table Rewrite Event
+
+
+ The functions shown in
+
+ provide information about a table for which a
+ table_rewrite event has just been called.
+ If called in any other context, an error is raised.
+
+
+
+ Table Rewrite Information Functions
+
+
+
+
+ Function
+
+
+ Description
+
+
+
+
+
+
+
+
+ pg_event_trigger_table_rewrite_oid
+
+ pg_event_trigger_table_rewrite_oid ()
+ oid
+
+
+ Returns the OID of the table about to be rewritten.
+
+
+
+
+
+
+ pg_event_trigger_table_rewrite_reason
+
+ pg_event_trigger_table_rewrite_reason ()
+ integer
+
+
+ Returns a code explaining the reason(s) for rewriting. The value is
+ a bitmap built from the following values: 1
+ (the table has changed its persistence), 2
+ (default value of a column has changed), 4
+ (a column has a new data type) and 8
+ (the table access method has changed).
+
+
+
+
+
+
+
+ These functions can be used in an event trigger like this:
+
+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();
+
+
+
+
diff --git a/doc/src/sgml/func/func-formatting.sgml b/doc/src/sgml/func/func-formatting.sgml
new file mode 100644
index 0000000000000..df05e5c167691
--- /dev/null
+++ b/doc/src/sgml/func/func-formatting.sgml
@@ -0,0 +1,1197 @@
+
+ Data Type Formatting Functions
+
+
+ formatting
+
+
+
+ The PostgreSQL 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.
+ 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.
+
+
+
+ Formatting Functions
+
+
+
+
+ Function
+
+
+ Description
+
+
+ Example(s)
+
+
+
+
+
+
+
+
+ to_char
+
+ to_char ( timestamp, text )
+ text
+
+
+ to_char ( timestamp with time zone, text )
+ text
+
+
+ Converts time stamp to string according to the given format.
+
+
+ to_char(timestamp '2002-04-20 17:31:12.66', 'HH12:MI:SS')
+ 05:31:12
+
+
+
+
+
+ to_char ( interval, text )
+ text
+
+
+ Converts interval to string according to the given format.
+
+
+ to_char(interval '15h 2m 12s', 'HH24:MI:SS')
+ 15:02:12
+
+
+
+
+
+ to_char ( numeric_type, text )
+ text
+
+
+ Converts number to string according to the given format; available
+ for integer, bigint, numeric,
+ real, double precision.
+
+
+ to_char(125, '999')
+ 125
+
+
+ to_char(125.8::real, '999D9')
+ 125.8
+
+
+ to_char(-125.8, '999D99S')
+ 125.80-
+
+
+
+
+
+
+ to_date
+
+ to_date ( text, text )
+ date
+
+
+ Converts string to date according to the given format.
+
+
+ to_date('05 Dec 2000', 'DD Mon YYYY')
+ 2000-12-05
+
+
+
+
+
+
+ to_number
+
+ to_number ( text, text )
+ numeric
+
+
+ Converts string to numeric according to the given format.
+
+
+ to_number('12,454.8-', '99G999D9S')
+ -12454.8
+
+
+
+
+
+
+ to_timestamp
+
+ to_timestamp ( text, text )
+ timestamp with time zone
+
+
+ Converts string to time stamp according to the given format.
+ (See also to_timestamp(double precision) in
+ .)
+
+
+ to_timestamp('05 Dec 2000', 'DD Mon YYYY')
+ 2000-12-05 00:00:00-05
+
+
+
+
+
+
+
+
+ to_timestamp and to_date
+ 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, to_number is unnecessary for standard numeric
+ representations.
+
+
+
+
+ In a to_char 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).
+
+
+
+ shows the
+ template patterns available for formatting date and time values.
+
+
+
+ Template Patterns for Date/Time Formatting
+
+
+
+
+
+ Pattern
+ Description
+
+
+
+
+ HH
+ hour of day (01–12)
+
+
+ HH12
+ hour of day (01–12)
+
+
+ HH24
+ hour of day (00–23)
+
+
+ MI
+ minute (00–59)
+
+
+ SS
+ second (00–59)
+
+
+ MS
+ millisecond (000–999)
+
+
+ US
+ microsecond (000000–999999)
+
+
+ FF1
+ tenth of second (0–9)
+
+
+ FF2
+ hundredth of second (00–99)
+
+
+ FF3
+ millisecond (000–999)
+
+
+ FF4
+ tenth of a millisecond (0000–9999)
+
+
+ FF5
+ hundredth of a millisecond (00000–99999)
+
+
+ FF6
+ microsecond (000000–999999)
+
+
+ SSSS, SSSSS
+ seconds past midnight (0–86399)
+
+
+ AM, am,
+ PM or pm
+ meridiem indicator (without periods)
+
+
+ A.M., a.m.,
+ P.M. or p.m.
+ meridiem indicator (with periods)
+
+
+ Y,YYY
+ year (4 or more digits) with comma
+
+
+ YYYY
+ year (4 or more digits)
+
+
+ YYY
+ last 3 digits of year
+
+
+ YY
+ last 2 digits of year
+
+
+ Y
+ last digit of year
+
+
+ IYYY
+ ISO 8601 week-numbering year (4 or more digits)
+
+
+ IYY
+ last 3 digits of ISO 8601 week-numbering year
+
+
+ IY
+ last 2 digits of ISO 8601 week-numbering year
+
+
+ I
+ last digit of ISO 8601 week-numbering year
+
+
+ BC, bc,
+ AD or ad
+ era indicator (without periods)
+
+
+ B.C., b.c.,
+ A.D. or a.d.
+ era indicator (with periods)
+
+
+ MONTH
+ full upper case month name (blank-padded to 9 chars)
+
+
+ Month
+ full capitalized month name (blank-padded to 9 chars)
+
+
+ month
+ full lower case month name (blank-padded to 9 chars)
+
+
+ MON
+ abbreviated upper case month name (3 chars in English, localized lengths vary)
+
+
+ Mon
+ abbreviated capitalized month name (3 chars in English, localized lengths vary)
+
+
+ mon
+ abbreviated lower case month name (3 chars in English, localized lengths vary)
+
+
+ MM
+ month number (01–12)
+
+
+ DAY
+ full upper case day name (blank-padded to 9 chars)
+
+
+ Day
+ full capitalized day name (blank-padded to 9 chars)
+
+
+ day
+ full lower case day name (blank-padded to 9 chars)
+
+
+ DY
+ abbreviated upper case day name (3 chars in English, localized lengths vary)
+
+
+ Dy
+ abbreviated capitalized day name (3 chars in English, localized lengths vary)
+
+
+ dy
+ abbreviated lower case day name (3 chars in English, localized lengths vary)
+
+
+ DDD
+ day of year (001–366)
+
+
+ IDDD
+ day of ISO 8601 week-numbering year (001–371; day 1 of the year is Monday of the first ISO week)
+
+
+ DD
+ day of month (01–31)
+
+
+ D
+ day of the week, Sunday (1) to Saturday (7)
+
+
+ ID
+ ISO 8601 day of the week, Monday (1) to Sunday (7)
+
+
+ W
+ week of month (1–5) (the first week starts on the first day of the month)
+
+
+ WW
+ week number of year (1–53) (the first week starts on the first day of the year)
+
+
+ IW
+ week number of ISO 8601 week-numbering year (01–53; the first Thursday of the year is in week 1)
+
+
+ CC
+ century (2 digits) (the twenty-first century starts on 2001-01-01)
+
+
+ J
+ Julian Date (integer days since November 24, 4714 BC at local
+ midnight; see )
+
+
+ Q
+ quarter
+
+
+ RM
+ month in upper case Roman numerals (I–XII; I=January)
+
+
+ rm
+ month in lower case Roman numerals (i–xii; i=January)
+
+
+ TZ
+ upper case time-zone abbreviation
+
+
+ tz
+ lower case time-zone abbreviation
+
+
+ TZH
+ time-zone hours
+
+
+ TZM
+ time-zone minutes
+
+
+ OF
+ time-zone offset from UTC (HH
+ or HH:MM)
+
+
+
+
+
+
+ Modifiers can be applied to any template pattern to alter its
+ behavior. For example, FMMonth
+ is the Month pattern with the
+ FM modifier.
+ shows the
+ modifier patterns for date/time formatting.
+
+
+
+ Template Pattern Modifiers for Date/Time Formatting
+
+
+
+ Modifier
+ Description
+ Example
+
+
+
+
+ FM prefix
+ fill mode (suppress leading zeroes and padding blanks)
+ FMMonth
+
+
+ TH suffix
+ upper case ordinal number suffix
+ DDTH, e.g., 12TH
+
+
+ th suffix
+ lower case ordinal number suffix
+ DDth, e.g., 12th
+
+
+ FX prefix
+ fixed format global option (see usage notes)
+ FX Month DD Day
+
+
+ TM prefix
+ translation mode (use localized day and month names based on
+ )
+ TMMonth
+
+
+ SP suffix
+ spell mode (not implemented)
+ DDSP
+
+
+
+
+
+
+ Usage notes for date/time formatting:
+
+
+
+
+ FM suppresses leading zeroes and trailing blanks
+ that would otherwise be added to make the output of a pattern be
+ fixed-width. In PostgreSQL,
+ FM modifies only the next specification, while in
+ Oracle FM affects all subsequent
+ specifications, and repeated FM modifiers
+ toggle fill mode on and off.
+
+
+
+
+
+ TM suppresses trailing blanks whether or
+ not FM is specified.
+
+
+
+
+
+ to_timestamp and to_date
+ ignore letter case in the input; so for
+ example MON, Mon,
+ and mon all accept the same strings. When using
+ the TM modifier, case-folding is done according to
+ the rules of the function's input collation (see
+ ).
+
+
+
+
+
+ to_timestamp and to_date
+ skip multiple blank spaces at the beginning of the input string and
+ around date and time values unless the FX option is used. For example,
+ to_timestamp(' 2000 JUN', 'YYYY MON') and
+ to_timestamp('2000 - JUN', 'YYYY-MON') work, but
+ to_timestamp('2000 JUN', 'FXYYYY MON') returns an error
+ because to_timestamp expects only a single space.
+ FX must be specified as the first item in
+ the template.
+
+
+
+
+
+ A separator (a space or non-letter/non-digit character) in the template string of
+ to_timestamp and to_date
+ matches any single separator in the input string or is skipped,
+ unless the FX option is used.
+ For example, to_timestamp('2000JUN', 'YYYY///MON') and
+ to_timestamp('2000/JUN', 'YYYY MON') work, but
+ to_timestamp('2000//JUN', 'YYYY/MON')
+ returns an error because the number of separators in the input string
+ exceeds the number of separators in the template.
+
+
+ If FX 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, to_timestamp('2000/JUN', 'FXYYYY MON')
+ works, but to_timestamp('2000/JUN', 'FXYYYY MON')
+ returns an error because the second space in the template string consumes
+ the letter J from the input string.
+
+
+
+
+
+ A TZH template pattern can match a signed number.
+ Without the FX 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
+ TZH 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 TZH.
+ Otherwise, the minus sign is considered to be a separator between values.
+ For example, to_timestamp('2000 -10', 'YYYY TZH') matches
+ -10 to TZH, but
+ to_timestamp('2000 -10', 'YYYY TZH')
+ matches 10 to TZH.
+
+
+
+
+
+ Ordinary text is allowed in to_char
+ 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
+ '"Hello Year "YYYY', the YYYY
+ will be replaced by the year data, but the single Y in Year
+ will not be.
+ In to_date, to_number,
+ and to_timestamp, literal text and double-quoted
+ strings result in skipping the number of characters contained in the
+ string; for example "XX" skips two input characters
+ (whether or not they are XX).
+
+
+
+ Prior to PostgreSQL 12, it was possible to
+ skip arbitrary text in the input string using non-letter or non-digit
+ characters. For example,
+ to_timestamp('2000y6m1d', 'yyyy-MM-DD') used to
+ work. Now you can only use letter characters for this purpose. For example,
+ to_timestamp('2000y6m1d', 'yyyytMMtDDt') and
+ to_timestamp('2000y6m1d', 'yyyy"y"MM"m"DD"d"')
+ skip y, m, and
+ d.
+
+
+
+
+
+
+ If you want to have a double quote in the output you must
+ precede it with a backslash, for example '\"YYYY
+ Month\"'.
+ 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).
+
+
+
+
+
+ In to_timestamp and to_date,
+ if the year format specification is less than four digits, e.g.,
+ YYY, and the supplied year is less than four digits,
+ the year will be adjusted to be nearest to the year 2020, e.g.,
+ 95 becomes 1995.
+
+
+
+
+
+ In to_timestamp and to_date,
+ negative years are treated as signifying BC. If you write both a
+ negative year and an explicit BC field, you get AD
+ again. An input of year zero is treated as 1 BC.
+
+
+
+
+
+ In to_timestamp and to_date,
+ the YYYY conversion has a restriction when
+ processing years with more than 4 digits. You must
+ use some non-digit character or template after YYYY,
+ otherwise the year is always interpreted as 4 digits. For example
+ (with the year 20000):
+ to_date('200001130', 'YYYYMMDD') will be
+ interpreted as a 4-digit year; instead use a non-digit
+ separator after the year, like
+ to_date('20000-1130', 'YYYY-MMDD') or
+ to_date('20000Nov30', 'YYYYMonDD').
+
+
+
+
+
+ In to_timestamp and to_date,
+ the CC (century) field is accepted but ignored
+ if there is a YYY, YYYY or
+ Y,YYY field. If CC is used with
+ YY or Y 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.
+
+
+
+
+
+ In to_timestamp and to_date,
+ weekday names or numbers (DAY, D,
+ and related field types) are accepted but are ignored for purposes of
+ computing the result. The same is true for quarter
+ (Q) fields.
+
+
+
+
+
+ In to_timestamp and to_date,
+ an ISO 8601 week-numbering date (as distinct from a Gregorian date)
+ can be specified in one of two ways:
+
+
+
+ Year, week number, and weekday: for
+ example to_date('2006-42-4', 'IYYY-IW-ID')
+ returns the date 2006-10-19.
+ If you omit the weekday it is assumed to be 1 (Monday).
+
+
+
+
+ Year and day of year: for example to_date('2006-291',
+ 'IYYY-IDDD') also returns 2006-10-19.
+
+
+
+
+
+ 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 month or day of month has no
+ meaning. In the context of a Gregorian year, the ISO week has no
+ meaning.
+
+
+
+ While to_date will reject a mixture of
+ Gregorian and ISO week-numbering date
+ fields, to_char will not, since output format
+ specifications like YYYY-MM-DD (IYYY-IDDD) can be
+ useful. But avoid writing something like IYYY-MM-DD;
+ that would yield surprising results near the start of the year.
+ (See for more
+ information.)
+
+
+
+
+
+
+ In to_timestamp, millisecond
+ (MS) or microsecond (US)
+ fields are used as the
+ seconds digits after the decimal point. For example
+ to_timestamp('12.3', 'SS.MS') is not 3 milliseconds,
+ but 300, because the conversion treats it as 12 + 0.3 seconds.
+ So, for the format SS.MS, the input values
+ 12.3, 12.30,
+ and 12.300 specify the
+ same number of milliseconds. To get three milliseconds, one must write
+ 12.003, which the conversion treats as
+ 12 + 0.003 = 12.003 seconds.
+
+
+
+ Here is a more
+ complex example:
+ to_timestamp('15:12:02.020.001230', 'HH24:MI:SS.MS.US')
+ is 15 hours, 12 minutes, and 2 seconds + 20 milliseconds +
+ 1230 microseconds = 2.021230 seconds.
+
+
+
+
+
+ to_char(..., 'ID')'s day of the week numbering
+ matches the extract(isodow from ...) function, but
+ to_char(..., 'D')'s does not match
+ extract(dow from ...)'s day numbering.
+
+
+
+
+
+ to_char(interval) formats HH and
+ HH12 as shown on a 12-hour clock, for example zero hours
+ and 36 hours both output as 12, while HH24
+ outputs the full hour value, which can exceed 23 in
+ an interval value.
+
+
+
+
+
+
+
+ shows the
+ template patterns available for formatting numeric values.
+
+
+
+ Template Patterns for Numeric Formatting
+
+
+
+
+
+ Pattern
+ Description
+
+
+
+
+ 9
+ digit position (can be dropped if insignificant)
+
+
+ 0
+ digit position (will not be dropped, even if insignificant)
+
+
+ . (period)
+ decimal point
+
+
+ , (comma)
+ group (thousands) separator
+
+
+ PR
+ negative value in angle brackets
+
+
+ S
+ sign anchored to number (uses locale)
+
+
+ L
+ currency symbol (uses locale)
+
+
+ D
+ decimal point (uses locale)
+
+
+ G
+ group separator (uses locale)
+
+
+ MI
+ minus sign in specified position (if number < 0)
+
+
+ PL
+ plus sign in specified position (if number > 0)
+
+
+ SG
+ plus/minus sign in specified position
+
+
+ RN or rn
+ Roman numeral (values between 1 and 3999)
+
+
+ TH or th
+ ordinal number suffix
+
+
+ V
+ shift specified number of digits (see notes)
+
+
+ EEEE
+ exponent for scientific notation
+
+
+
+
+
+
+ Usage notes for numeric formatting:
+
+
+
+
+ 0 specifies a digit position that will always be printed,
+ even if it contains a leading/trailing zero. 9 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 to_number(),
+ these two pattern characters are equivalent.)
+
+
+
+
+
+ If the format provides fewer fractional digits than the number being
+ formatted, to_char() will round the number to
+ the specified number of fractional digits.
+
+
+
+
+
+ The pattern characters S, L, D,
+ and G represent the sign, currency symbol, decimal point,
+ and thousands separator characters defined by the current locale
+ (see
+ and ). The pattern characters period
+ and comma represent those exact characters, with the meanings of
+ decimal point and thousands separator, regardless of locale.
+
+
+
+
+
+ If no explicit provision is made for a sign
+ in to_char()'s pattern, one column will be reserved for
+ the sign, and it will be anchored to (appear just left of) the
+ number. If S appears just left of some 9's,
+ it will likewise be anchored to the number.
+
+
+
+
+
+ A sign formatted using SG, PL, or
+ MI is not anchored to
+ the number; for example,
+ to_char(-12, 'MI9999') produces '- 12'
+ but to_char(-12, 'S9999') produces ' -12'.
+ (The Oracle implementation does not allow the use of
+ MI before 9, but rather
+ requires that 9 precede
+ MI.)
+
+
+
+
+
+ TH does not convert values less than zero
+ and does not convert fractional numbers.
+
+
+
+
+
+ PL, SG, and
+ TH are PostgreSQL
+ extensions.
+
+
+
+
+
+ In to_number, if non-data template patterns such
+ as L or TH 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, TH would skip two non-data characters.
+
+
+
+
+
+ V with to_char
+ multiplies the input values by
+ 10^n, where
+ n is the number of digits following
+ V. V with
+ to_number divides in a similar manner.
+ The V can be thought of as marking the position
+ of an implicit decimal point in the input or output string.
+ to_char and to_number
+ do not support the use of
+ V combined with a decimal point
+ (e.g., 99.9V99 is not allowed).
+
+
+
+
+
+ EEEE (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., 9.99EEEE is a valid pattern).
+
+
+
+
+
+ In to_number(), the RN
+ pattern converts Roman numerals (in standard form) to numbers.
+ Input is case-insensitive, so RN
+ and rn are equivalent. RN
+ cannot be used in combination with any other formatting patterns or
+ modifiers except FM, which is applicable only
+ in to_char() and is ignored
+ in to_number().
+
+
+
+
+
+
+ Certain modifiers can be applied to any template pattern to alter its
+ behavior. For example, FM99.99
+ is the 99.99 pattern with the
+ FM modifier.
+ shows the
+ modifier patterns for numeric formatting.
+
+
+
+ Template Pattern Modifiers for Numeric Formatting
+
+
+
+ Modifier
+ Description
+ Example
+
+
+
+
+ FM prefix
+ fill mode (suppress trailing zeroes and padding blanks)
+ FM99.99
+
+
+ TH suffix
+ upper case ordinal number suffix
+ 999TH
+
+
+ th suffix
+ lower case ordinal number suffix
+ 999th
+
+
+
+
+
+
+ shows some
+ examples of the use of the to_char function.
+
+
+
+
+
diff --git a/doc/src/sgml/func/func-geometry.sgml b/doc/src/sgml/func/func-geometry.sgml
new file mode 100644
index 0000000000000..ba203af3bd289
--- /dev/null
+++ b/doc/src/sgml/func/func-geometry.sgml
@@ -0,0 +1,1261 @@
+
+ Geometric Functions and Operators
+
+
+ The geometric types point, box,
+ lseg, line, path,
+ polygon, and circle have a large set of
+ native support functions and operators, shown in , , and .
+
+
+
+ Geometric Operators
+
+
+
+
+ Operator
+
+
+ Description
+
+
+ Example(s)
+
+
+
+
+
+
+
+ geometric_type+point
+ geometric_type
+
+
+ Adds the coordinates of the second point to those of each
+ point of the first argument, thus performing translation.
+ Available for point, box, path,
+ circle.
+
+
+ box '(1,1),(0,0)' + point '(2,0)'
+ (3,1),(2,0)
+
+
+
+
+
+ path+path
+ path
+
+
+ Concatenates two open paths (returns NULL if either path is closed).
+
+
+ path '[(0,0),(1,1)]' + path '[(2,2),(3,3),(4,4)]'
+ [(0,0),(1,1),(2,2),(3,3),(4,4)]
+
+
+
+
+
+ geometric_type-point
+ geometric_type
+
+
+ Subtracts the coordinates of the second point from those
+ of each point of the first argument, thus performing translation.
+ Available for point, box, path,
+ circle.
+
+
+ box '(1,1),(0,0)' - point '(2,0)'
+ (-1,1),(-2,0)
+
+
+
+
+
+ geometric_type*point
+ geometric_type
+
+
+ Multiplies each point of the first argument by the second
+ point (treating a point as being a complex number
+ represented by real and imaginary parts, and performing standard
+ complex multiplication). If one interprets
+ the second point 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 x axis.
+ Available for point, box,Rotating 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.
+ path, circle.
+
+
+ path '((0,0),(1,0),(1,1))' * point '(3.0,0)'
+ ((0,0),(3,0),(3,3))
+
+
+ path '((0,0),(1,0),(1,1))' * point(cosd(45), sind(45))
+ ((0,0),&zwsp;(0.7071067811865475,0.7071067811865475),&zwsp;(0,1.414213562373095))
+
+
+
+
+
+ geometric_type/point
+ geometric_type
+
+
+ Divides each point of the first argument by the second
+ point (treating a point as being a complex number
+ represented by real and imaginary parts, and performing standard
+ complex division). If one interprets
+ the second point 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 x axis.
+ Available for point, box,path,
+ circle.
+
+
+ path '((0,0),(1,0),(1,1))' / point '(2.0,0)'
+ ((0,0),(0.5,0),(0.5,0.5))
+
+
+ path '((0,0),(1,0),(1,1))' / point(cosd(45), sind(45))
+ ((0,0),&zwsp;(0.7071067811865476,-0.7071067811865476),&zwsp;(1.4142135623730951,0))
+
+
+
+
+
+ @-@geometric_type
+ double precision
+
+
+ Computes the total length.
+ Available for lseg, path.
+
+
+ @-@ path '[(0,0),(1,0),(1,1)]'
+ 2
+
+
+
+
+
+ @@geometric_type
+ point
+
+
+ Computes the center point.
+ Available for box, lseg,
+ polygon, circle.
+
+
+ @@ box '(2,2),(0,0)'
+ (1,1)
+
+
+
+
+
+ #geometric_type
+ integer
+
+
+ Returns the number of points.
+ Available for path, polygon.
+
+
+ # path '((1,0),(0,1),(-1,0))'
+ 3
+
+
+
+
+
+ geometric_type#geometric_type
+ point
+
+
+ Computes the point of intersection, or NULL if there is none.
+ Available for lseg, line.
+
+
+ lseg '[(0,0),(1,1)]' # lseg '[(1,0),(0,1)]'
+ (0.5,0.5)
+
+
+
+
+
+ box#box
+ box
+
+
+ Computes the intersection of two boxes, or NULL if there is none.
+
+
+ box '(2,2),(-1,-1)' # box '(1,1),(-2,-2)'
+ (1,1),(-1,-1)
+
+
+
+
+
+ geometric_type##geometric_type
+ point
+
+
+ Computes the closest point to the first object on the second object.
+ Available for these pairs of types:
+ (point, box),
+ (point, lseg),
+ (point, line),
+ (lseg, box),
+ (lseg, lseg),
+ (line, lseg).
+
+
+ point '(0,0)' ## lseg '[(2,0),(0,2)]'
+ (1,1)
+
+
+
+
+
+ geometric_type<->geometric_type
+ double precision
+
+
+ Computes the distance between the objects.
+ Available for all seven geometric types, for all combinations
+ of point with another geometric type, and for
+ these additional pairs of types:
+ (box, lseg),
+ (lseg, line),
+ (polygon, circle)
+ (and the commutator cases).
+
+
+ circle '<(0,0),1>' <-> circle '<(5,0),1>'
+ 3
+
+
+
+
+
+ geometric_type@>geometric_type
+ boolean
+
+
+ Does first object contain second?
+ Available for these pairs of types:
+ (box, point),
+ (box, box),
+ (path, point),
+ (polygon, point),
+ (polygon, polygon),
+ (circle, point),
+ (circle, circle).
+
+
+ circle '<(0,0),2>' @> point '(1,1)'
+ t
+
+
+
+
+
+ geometric_type<@geometric_type
+ boolean
+
+
+ Is first object contained in or on second?
+ Available for these pairs of types:
+ (point, box),
+ (point, lseg),
+ (point, line),
+ (point, path),
+ (point, polygon),
+ (point, circle),
+ (box, box),
+ (lseg, box),
+ (lseg, line),
+ (polygon, polygon),
+ (circle, circle).
+
+
+ point '(1,1)' <@ circle '<(0,0),2>'
+ t
+
+
+
+
+
+ geometric_type&&geometric_type
+ boolean
+
+
+ Do these objects overlap? (One point in common makes this true.)
+ Available for box, polygon,
+ circle.
+
+
+ box '(1,1),(0,0)' && box '(2,2),(0,0)'
+ t
+
+
+
+
+
+ geometric_type<<geometric_type
+ boolean
+
+
+ Is first object strictly left of second?
+ Available for point, box,
+ polygon, circle.
+
+
+ circle '<(0,0),1>' << circle '<(5,0),1>'
+ t
+
+
+
+
+
+ geometric_type>>geometric_type
+ boolean
+
+
+ Is first object strictly right of second?
+ Available for point, box,
+ polygon, circle.
+
+
+ circle '<(5,0),1>' >> circle '<(0,0),1>'
+ t
+
+
+
+
+
+ geometric_type&<geometric_type
+ boolean
+
+
+ Does first object not extend to the right of second?
+ Available for box, polygon,
+ circle.
+
+
+ box '(1,1),(0,0)' &< box '(2,2),(0,0)'
+ t
+
+
+
+
+
+ geometric_type&>geometric_type
+ boolean
+
+
+ Does first object not extend to the left of second?
+ Available for box, polygon,
+ circle.
+
+
+ box '(3,3),(0,0)' &> box '(2,2),(0,0)'
+ t
+
+
+
+
+
+ geometric_type<<|geometric_type
+ boolean
+
+
+ Is first object strictly below second?
+ Available for point, box, polygon,
+ circle.
+
+
+ box '(3,3),(0,0)' <<| box '(5,5),(3,4)'
+ t
+
+
+
+
+
+ geometric_type|>>geometric_type
+ boolean
+
+
+ Is first object strictly above second?
+ Available for point, box, polygon,
+ circle.
+
+
+ box '(5,5),(3,4)' |>> box '(3,3),(0,0)'
+ t
+
+
+
+
+
+ geometric_type&<|geometric_type
+ boolean
+
+
+ Does first object not extend above second?
+ Available for box, polygon,
+ circle.
+
+
+ box '(1,1),(0,0)' &<| box '(2,2),(0,0)'
+ t
+
+
+
+
+
+ geometric_type|&>geometric_type
+ boolean
+
+
+ Does first object not extend below second?
+ Available for box, polygon,
+ circle.
+
+
+ box '(3,3),(0,0)' |&> box '(2,2),(0,0)'
+ t
+
+
+
+
+
+ box<^box
+ boolean
+
+
+ Is first object below second (allows edges to touch)?
+
+
+ box '((1,1),(0,0))' <^ box '((2,2),(1,1))'
+ t
+
+
+
+
+
+ box>^box
+ boolean
+
+
+ Is first object above second (allows edges to touch)?
+
+
+ box '((2,2),(1,1))' >^ box '((1,1),(0,0))'
+ t
+
+
+
+
+
+ geometric_type?#geometric_type
+ boolean
+
+
+ Do these objects intersect?
+ Available for these pairs of types:
+ (box, box),
+ (lseg, box),
+ (lseg, lseg),
+ (lseg, line),
+ (line, box),
+ (line, line),
+ (path, path).
+
+
+ lseg '[(-1,0),(1,0)]' ?# box '(2,2),(-2,-2)'
+ t
+
+
+
+
+
+ ?-line
+ boolean
+
+
+ ?-lseg
+ boolean
+
+
+ Is line horizontal?
+
+
+ ?- lseg '[(-1,0),(1,0)]'
+ t
+
+
+
+
+
+ point?-point
+ boolean
+
+
+ Are points horizontally aligned (that is, have same y coordinate)?
+
+
+ point '(1,0)' ?- point '(0,0)'
+ t
+
+
+
+
+
+ ?|line
+ boolean
+
+
+ ?|lseg
+ boolean
+
+
+ Is line vertical?
+
+
+ ?| lseg '[(-1,0),(1,0)]'
+ f
+
+
+
+
+
+ point?|point
+ boolean
+
+
+ Are points vertically aligned (that is, have same x coordinate)?
+
+
+ point '(0,1)' ?| point '(0,0)'
+ t
+
+
+
+
+
+ line?-|line
+ boolean
+
+
+ lseg?-|lseg
+ boolean
+
+
+ Are lines perpendicular?
+
+
+ lseg '[(0,0),(0,1)]' ?-| lseg '[(0,0),(1,0)]'
+ t
+
+
+
+
+
+ line?||line
+ boolean
+
+
+ lseg?||lseg
+ boolean
+
+
+ Are lines parallel?
+
+
+ lseg '[(-1,0),(1,0)]' ?|| lseg '[(-1,2),(1,2)]'
+ t
+
+
+
+
+
+ geometric_type~=geometric_type
+ boolean
+
+
+ Are these objects the same?
+ Available for point, box,
+ polygon, circle.
+
+
+ polygon '((0,0),(1,1))' ~= polygon '((1,1),(0,0))'
+ t
+
+
+
+
+
+
+
+
+ Note that the same as operator, ~=,
+ represents the usual notion of equality for the point,
+ box, polygon, and circle types.
+ Some of the geometric types also have an = operator, but
+ = compares for equal areas only.
+ The other scalar comparison operators (<= and so
+ on), where available for these types, likewise compare areas.
+
+
+
+
+
+ Before PostgreSQL 14, the point
+ is strictly below/above comparison operators point
+ <<|point and point
+ |>>point were respectively
+ called <^ and >^. These
+ names are still available, but are deprecated and will eventually be
+ removed.
+
+
+
+
+ Geometric Functions
+
+
+
+
+ Function
+
+
+ Description
+
+
+ Example(s)
+
+
+
+
+
+
+
+
+ area
+
+ area ( geometric_type )
+ double precision
+
+
+ Computes area.
+ Available for box, path, circle.
+ A path input must be closed, else NULL is returned.
+ Also, if the path is self-intersecting, the result may be
+ meaningless.
+
+
+ area(box '(2,2),(0,0)')
+ 4
+
+
+
+
+
+
+ center
+
+ center ( geometric_type )
+ point
+
+
+ Computes center point.
+ Available for box, circle.
+
+
+ center(box '(1,2),(0,0)')
+ (0.5,1)
+
+
+
+
+
+
+ diagonal
+
+ diagonal ( box )
+ lseg
+
+
+ Extracts box's diagonal as a line segment
+ (same as lseg(box)).
+
+
+ diagonal(box '(1,2),(0,0)')
+ [(1,2),(0,0)]
+
+
+
+
+
+
+ diameter
+
+ diameter ( circle )
+ double precision
+
+
+ Computes diameter of circle.
+
+
+ diameter(circle '<(0,0),2>')
+ 4
+
+
+
+
+
+
+ height
+
+ height ( box )
+ double precision
+
+
+ Computes vertical size of box.
+
+
+ height(box '(1,2),(0,0)')
+ 2
+
+
+
+
+
+
+ isclosed
+
+ isclosed ( path )
+ boolean
+
+
+ Is path closed?
+
+
+ isclosed(path '((0,0),(1,1),(2,0))')
+ t
+
+
+
+
+
+
+ isopen
+
+ isopen ( path )
+ boolean
+
+
+ Is path open?
+
+
+ isopen(path '[(0,0),(1,1),(2,0)]')
+ t
+
+
+
+
+
+
+ length
+
+ length ( geometric_type )
+ double precision
+
+
+ Computes the total length.
+ Available for lseg, path.
+
+
+ length(path '((-1,0),(1,0))')
+ 4
+
+
+
+
+
+
+ npoints
+
+ npoints ( geometric_type )
+ integer
+
+
+ Returns the number of points.
+ Available for path, polygon.
+
+
+ npoints(path '[(0,0),(1,1),(2,0)]')
+ 3
+
+
+
+
+
+
+ pclose
+
+ pclose ( path )
+ path
+
+
+ Converts path to closed form.
+
+
+ pclose(path '[(0,0),(1,1),(2,0)]')
+ ((0,0),(1,1),(2,0))
+
+
+
+
+
+
+ popen
+
+ popen ( path )
+ path
+
+
+ Converts path to open form.
+
+
+ popen(path '((0,0),(1,1),(2,0))')
+ [(0,0),(1,1),(2,0)]
+
+
+
+
+
+
+ radius
+
+ radius ( circle )
+ double precision
+
+
+ Computes radius of circle.
+
+
+ radius(circle '<(0,0),2>')
+ 2
+
+
+
+
+
+
+ slope
+
+ slope ( point, point )
+ double precision
+
+
+ Computes slope of a line drawn through the two points.
+
+
+ slope(point '(0,0)', point '(2,1)')
+ 0.5
+
+
+
+
+
+
+ width
+
+ width ( box )
+ double precision
+
+
+ Computes horizontal size of box.
+
+
+ width(box '(1,2),(0,0)')
+ 1
+
+
+
+
+
+
+
+ Geometric Type Conversion Functions
+
+
+
+
+ Function
+
+
+ Description
+
+
+ Example(s)
+
+
+
+
+
+
+
+
+ box
+
+ box ( circle )
+ box
+
+
+ Computes box inscribed within the circle.
+
+
+ box(circle '<(0,0),2>')
+ (1.414213562373095,1.414213562373095),&zwsp;(-1.414213562373095,-1.414213562373095)
+
+
+
+
+
+ box ( point )
+ box
+
+
+ Converts point to empty box.
+
+
+ box(point '(1,0)')
+ (1,0),(1,0)
+
+
+
+
+
+ box ( point, point )
+ box
+
+
+ Converts any two corner points to box.
+
+
+ box(point '(0,1)', point '(1,0)')
+ (1,1),(0,0)
+
+
+
+
+
+ box ( polygon )
+ box
+
+
+ Computes bounding box of polygon.
+
+
+ box(polygon '((0,0),(1,1),(2,0))')
+ (2,1),(0,0)
+
+
+
+
+
+
+ bound_box
+
+ bound_box ( box, box )
+ box
+
+
+ Computes bounding box of two boxes.
+
+
+ bound_box(box '(1,1),(0,0)', box '(4,4),(3,3)')
+ (4,4),(0,0)
+
+
+
+
+
+
+ circle
+
+ circle ( box )
+ circle
+
+
+ Computes smallest circle enclosing box.
+
+
+ circle(box '(1,1),(0,0)')
+ <(0.5,0.5),0.7071067811865476>
+
+
+
+
+
+ circle ( point, double precision )
+ circle
+
+
+ Constructs circle from center and radius.
+
+
+ circle(point '(0,0)', 2.0)
+ <(0,0),2>
+
+
+
+
+
+ circle ( polygon )
+ circle
+
+
+ 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.
+
+
+ circle(polygon '((0,0),(1,3),(2,0))')
+ <(1,1),1.6094757082487299>
+
+
+
+
+
+
+ line
+
+ line ( point, point )
+ line
+
+
+ Converts two points to the line through them.
+
+
+ line(point '(-1,0)', point '(1,0)')
+ {0,-1,0}
+
+
+
+
+
+
+ lseg
+
+ lseg ( box )
+ lseg
+
+
+ Extracts box's diagonal as a line segment.
+
+
+ lseg(box '(1,0),(-1,0)')
+ [(1,0),(-1,0)]
+
+
+
+
+
+ lseg ( point, point )
+ lseg
+
+
+ Constructs line segment from two endpoints.
+
+
+ lseg(point '(-1,0)', point '(1,0)')
+ [(-1,0),(1,0)]
+
+
+
+
+
+
+ path
+
+ path ( polygon )
+ path
+
+
+ Converts polygon to a closed path with the same list of points.
+
+
+ path(polygon '((0,0),(1,1),(2,0))')
+ ((0,0),(1,1),(2,0))
+
+
+
+
+
+
+ point
+
+ point ( double precision, double precision )
+ point
+
+
+ Constructs point from its coordinates.
+
+
+ point(23.4, -44.5)
+ (23.4,-44.5)
+
+
+
+
+
+ point ( box )
+ point
+
+
+ Computes center of box.
+
+
+ point(box '(1,0),(-1,0)')
+ (0,0)
+
+
+
+
+
+ point ( circle )
+ point
+
+
+ Computes center of circle.
+
+
+ point(circle '<(0,0),2>')
+ (0,0)
+
+
+
+
+
+ point ( lseg )
+ point
+
+
+ Computes center of line segment.
+
+
+ point(lseg '[(-1,0),(1,0)]')
+ (0,0)
+
+
+
+
+
+ point ( polygon )
+ point
+
+
+ Computes center of polygon (the mean of the
+ positions of the polygon's points).
+
+
+ point(polygon '((0,0),(1,1),(2,0))')
+ (1,0.3333333333333333)
+
+
+
+
+
+
+ polygon
+
+ polygon ( box )
+ polygon
+
+
+ Converts box to a 4-point polygon.
+
+
+ polygon(box '(1,1),(0,0)')
+ ((0,0),(0,1),(1,1),(1,0))
+
+
+
+
+
+ polygon ( circle )
+ polygon
+
+
+ Converts circle to a 12-point polygon.
+
+
+ polygon(circle '<(0,0),2>')
+ ((-2,0),&zwsp;(-1.7320508075688774,0.9999999999999999),&zwsp;(-1.0000000000000002,1.7320508075688772),&zwsp;(-1.2246063538223773e-16,2),&zwsp;(0.9999999999999996,1.7320508075688774),&zwsp;(1.732050807568877,1.0000000000000007),&zwsp;(2,2.4492127076447545e-16),&zwsp;(1.7320508075688776,-0.9999999999999994),&zwsp;(1.0000000000000009,-1.7320508075688767),&zwsp;(3.673819061467132e-16,-2),&zwsp;(-0.9999999999999987,-1.732050807568878),&zwsp;(-1.7320508075688767,-1.0000000000000009))
+
+
+
+
+
+ polygon ( integer, circle )
+ polygon
+
+
+ Converts circle to an n-point polygon.
+
+
+ polygon(4, circle '<(3,0),1>')
+ ((2,0),&zwsp;(3,1),&zwsp;(4,1.2246063538223773e-16),&zwsp;(3,-1))
+
+
+
+
+
+ polygon ( path )
+ polygon
+
+
+ Converts closed path to a polygon with the same list of points.
+
+
+ polygon(path '((0,0),(1,1),(2,0))')
+ ((0,0),(1,1),(2,0))
+
+
+
+
+
+
+
+
+ It is possible to access the two component numbers of a point
+ as though the point were an array with indexes 0 and 1. For example, if
+ t.p is a point column then
+ SELECT p[0] FROM t retrieves the X coordinate and
+ UPDATE t SET p[1] = ... changes the Y coordinate.
+ In the same way, a value of type box or lseg can be treated
+ as an array of two point values.
+
+
+
diff --git a/doc/src/sgml/func/func-info.sgml b/doc/src/sgml/func/func-info.sgml
new file mode 100644
index 0000000000000..c393832d94c64
--- /dev/null
+++ b/doc/src/sgml/func/func-info.sgml
@@ -0,0 +1,3800 @@
+
+ System Information Functions and Operators
+
+
+ The functions described in this section are used to obtain various
+ information about a PostgreSQL installation.
+
+
+
+ Session Information Functions
+
+
+ shows several
+ functions that extract session and system information.
+
+
+
+ In addition to the functions listed in this section, there are a number of
+ functions related to the statistics system that also provide system
+ information. See for more
+ information.
+
+
+
+ Session Information Functions
+
+
+
+
+ Function
+
+
+ Description
+
+
+
+
+
+
+
+
+ current_catalog
+
+ current_catalog
+ name
+
+
+
+ current_database
+
+ current_database ()
+ name
+
+
+ Returns the name of the current database. (Databases are
+ called catalogs in the SQL standard,
+ so current_catalog is the standard's
+ spelling.)
+
+
+
+
+
+
+ current_query
+
+ current_query ()
+ text
+
+
+ Returns the text of the currently executing query, as submitted
+ by the client (which might contain more than one statement).
+
+
+
+
+
+
+ current_role
+
+ current_role
+ name
+
+
+ This is equivalent to current_user.
+
+
+
+
+
+
+ current_schema
+
+
+ schema
+ current
+
+ current_schema
+ name
+
+
+ current_schema ()
+ name
+
+
+ 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.
+
+
+
+
+
+
+ current_schemas
+
+
+ search path
+ current
+
+ current_schemas ( include_implicitboolean )
+ name[]
+
+
+ Returns an array of the names of all schemas presently in the
+ effective search path, in their priority order. (Items in the current
+ setting that do not correspond to
+ existing, searchable schemas are omitted.) If the Boolean argument
+ is true, then implicitly-searched system schemas
+ such as pg_catalog are included in the result.
+
+
+
+
+
+
+ current_user
+
+
+ user
+ current
+
+ current_user
+ name
+
+
+ Returns the user name of the current execution context.
+
+
+
+
+
+
+ inet_client_addr
+
+ inet_client_addr ()
+ inet
+
+
+ Returns the IP address of the current client,
+ or NULL if the current connection is via a
+ Unix-domain socket.
+
+
+
+
+
+
+ inet_client_port
+
+ inet_client_port ()
+ integer
+
+
+ Returns the IP port number of the current client,
+ or NULL if the current connection is via a
+ Unix-domain socket.
+
+
+
+
+
+
+ inet_server_addr
+
+ inet_server_addr ()
+ inet
+
+
+ Returns the IP address on which the server accepted the current
+ connection,
+ or NULL if the current connection is via a
+ Unix-domain socket.
+
+
+
+
+
+
+ inet_server_port
+
+ inet_server_port ()
+ integer
+
+
+ Returns the IP port number on which the server accepted the current
+ connection,
+ or NULL if the current connection is via a
+ Unix-domain socket.
+
+
+
+
+
+
+ pg_backend_pid
+
+ pg_backend_pid ()
+ integer
+
+
+ Returns the process ID of the server process attached to the current
+ session.
+
+
+
+
+
+
+ pg_blocking_pids
+
+ pg_blocking_pids ( integer )
+ integer[]
+
+
+ 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.
+
+
+ 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, pg_backend_pid 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.
+
+
+ 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.
+
+
+
+
+
+
+ pg_conf_load_time
+
+ pg_conf_load_time ()
+ timestamp with time zone
+
+
+ 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.
+
+
+
+
+
+
+ pg_current_logfile
+
+
+ Logging
+ pg_current_logfile function
+
+
+ current_logfiles
+ and the pg_current_logfile function
+
+
+ Logging
+ current_logfiles file and the pg_current_logfile
+ function
+
+ pg_current_logfile ( text )
+ text
+
+
+ Returns the path name of the log file currently in use by the logging
+ collector. The path includes the
+ directory and the individual log file name. The result
+ is NULL if the logging collector is disabled.
+ When multiple log files exist, each in a different
+ format, pg_current_logfile without an argument
+ returns the path of the file having the first format found in the
+ ordered list: stderr,
+ csvlog, jsonlog.
+ NULL is returned if no log file has any of these
+ formats.
+ To request information about a specific log file format, supply
+ either csvlog, jsonlog or
+ stderr as the
+ value of the optional parameter. The result is NULL
+ if the log format requested is not configured in
+ .
+ The result reflects the contents of
+ the current_logfiles file.
+
+
+ This function is restricted to superusers and roles with privileges of
+ the pg_monitor role by default, but other users can
+ be granted EXECUTE to run the function.
+
+
+
+
+
+
+ pg_get_loaded_modules
+
+ pg_get_loaded_modules ()
+ setof record
+ ( module_nametext,
+ versiontext,
+ file_nametext )
+
+
+ Returns a list of the loadable modules that are loaded into the
+ current server session. The module_name
+ and version fields are NULL unless the
+ module author supplied values for them using
+ the PG_MODULE_MAGIC_EXT macro.
+ The file_name field gives the file
+ name of the module (shared library).
+
+
+
+
+
+
+ pg_my_temp_schema
+
+ pg_my_temp_schema ()
+ oid
+
+
+ Returns the OID of the current session's temporary schema, or zero if
+ it has none (because it has not created any temporary tables).
+
+
+
+
+
+
+ pg_is_other_temp_schema
+
+ pg_is_other_temp_schema ( oid )
+ boolean
+
+
+ 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.)
+
+
+
+
+
+
+ pg_jit_available
+
+ pg_jit_available ()
+ boolean
+
+
+ Returns true if a JIT compiler extension is
+ available (see ) and the
+ configuration parameter is set to
+ on.
+
+
+
+
+
+
+ pg_numa_available
+
+ pg_numa_available ()
+ boolean
+
+
+ Returns true if the server has been compiled with NUMA support.
+
+
+
+
+
+
+ pg_listening_channels
+
+ pg_listening_channels ()
+ setof text
+
+
+ Returns the set of names of asynchronous notification channels that
+ the current session is listening to.
+
+
+
+
+
+
+ pg_notification_queue_usage
+
+ pg_notification_queue_usage ()
+ double precision
+
+
+ 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 and
+ for more information.
+
+
+
+
+
+
+ pg_postmaster_start_time
+
+ pg_postmaster_start_time ()
+ timestamp with time zone
+
+
+ Returns the time when the server started.
+
+
+
+
+
+
+ pg_safe_snapshot_blocking_pids
+
+ pg_safe_snapshot_blocking_pids ( integer )
+ integer[]
+
+
+ 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.
+
+
+ A session running a SERIALIZABLE transaction blocks
+ a SERIALIZABLE READ ONLY DEFERRABLE transaction
+ from acquiring a snapshot until the latter determines that it is safe
+ to avoid taking any predicate locks. See
+ for more information about
+ serializable and deferrable transactions.
+
+
+ Frequent calls to this function could have some impact on database
+ performance, because it needs access to the predicate lock manager's
+ shared state for a short time.
+
+
+
+
+
+
+ pg_trigger_depth
+
+ pg_trigger_depth ()
+ integer
+
+
+ Returns the current nesting level
+ of PostgreSQL triggers (0 if not called,
+ directly or indirectly, from inside a trigger).
+
+
+
+
+
+
+ session_user
+
+ session_user
+ name
+
+
+ Returns the session user's name.
+
+
+
+
+
+
+ system_user
+
+ system_user
+ text
+
+
+ Returns the authentication method and the identity (if any) that the
+ user presented during the authentication cycle before they were
+ assigned a database role. It is represented as
+ auth_method:identity or
+ NULL if the user has not been authenticated (for
+ example if Trust authentication has
+ been used).
+
+
+
+
+
+
+ user
+
+ user
+ name
+
+
+ This is equivalent to current_user.
+
+
+
+
+
+
+
+
+ current_catalog,
+ current_role,
+ current_schema,
+ current_user,
+ session_user,
+ and user have special syntactic status
+ in SQL: they must be called without trailing
+ parentheses. In PostgreSQL, parentheses can optionally be used with
+ current_schema, but not with the others.
+
+
+
+
+ The session_user is normally the user who initiated
+ the current database connection; but superusers can change this setting
+ with .
+ The current_user is the user identifier
+ that is applicable for permission checking. Normally it is equal
+ to the session user, but it can be changed with
+ .
+ It also changes during the execution of
+ functions with the attribute SECURITY DEFINER.
+ In Unix parlance, the session user is the real user and
+ the current user is the effective user.
+ current_role and user are
+ synonyms for current_user. (The SQL standard draws
+ a distinction between current_role
+ and current_user, but PostgreSQL
+ does not, since it unifies users and roles into a single kind of entity.)
+
+
+
+
+
+ Access Privilege Inquiry Functions
+
+
+ privilege
+ querying
+
+
+
+ lists functions that
+ allow querying object access privileges programmatically.
+ (See for more information about
+ privileges.)
+ In these functions, the user whose privileges are being inquired about
+ can be specified by name or by OID
+ (pg_authid.oid), or if
+ the name is given as public then the privileges of the
+ PUBLIC pseudo-role are checked. Also, the user
+ argument can be omitted entirely, in which case
+ the current_user 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., SELECT). Optionally, WITH GRANT
+ OPTION 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:
+
+SELECT has_table_privilege('myschema.mytable', 'select');
+SELECT has_table_privilege('joe', 'mytable', 'INSERT, SELECT WITH GRANT OPTION');
+
+
+
+
+ Access Privilege Inquiry Functions
+
+
+
+
+ Function
+
+
+ Description
+
+
+
+
+
+
+
+
+ has_any_column_privilege
+
+ has_any_column_privilege (
+ username or oid,
+ tabletext or oid,
+ privilegetext )
+ boolean
+
+
+ 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
+ SELECT, INSERT,
+ UPDATE, and REFERENCES.
+
+
+
+
+
+
+ has_column_privilege
+
+ has_column_privilege (
+ username or oid,
+ tabletext or oid,
+ columntext or smallint,
+ privilegetext )
+ boolean
+
+
+ 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
+ (pg_attribute.attnum).
+ Allowable privilege types are
+ SELECT, INSERT,
+ UPDATE, and REFERENCES.
+
+
+
+
+
+
+ has_database_privilege
+
+ has_database_privilege (
+ username or oid,
+ databasetext or oid,
+ privilegetext )
+ boolean
+
+
+ Does user have privilege for database?
+ Allowable privilege types are
+ CREATE,
+ CONNECT,
+ TEMPORARY, and
+ TEMP (which is equivalent to
+ TEMPORARY).
+
+
+
+
+
+
+ has_foreign_data_wrapper_privilege
+
+ has_foreign_data_wrapper_privilege (
+ username or oid,
+ fdwtext or oid,
+ privilegetext )
+ boolean
+
+
+ Does user have privilege for foreign-data wrapper?
+ The only allowable privilege type is USAGE.
+
+
+
+
+
+
+ has_function_privilege
+
+ has_function_privilege (
+ username or oid,
+ functiontext or oid,
+ privilegetext )
+ boolean
+
+
+ Does user have privilege for function?
+ The only allowable privilege type is EXECUTE.
+
+
+ When specifying a function by name rather than by OID, the allowed
+ input is the same as for the regprocedure data type (see
+ ).
+ An example is:
+
+SELECT has_function_privilege('joeuser', 'myfunc(int, text)', 'execute');
+
+
+
+
+
+
+
+ has_language_privilege
+
+ has_language_privilege (
+ username or oid,
+ languagetext or oid,
+ privilegetext )
+ boolean
+
+
+ Does user have privilege for language?
+ The only allowable privilege type is USAGE.
+
+
+
+
+
+
+ has_largeobject_privilege
+
+ has_largeobject_privilege (
+ username or oid,
+ largeobjectoid,
+ privilegetext )
+ boolean
+
+
+ Does user have privilege for large object?
+ Allowable privilege types are
+ SELECT and UPDATE.
+
+
+
+
+
+
+ has_parameter_privilege
+
+ has_parameter_privilege (
+ username or oid,
+ parametertext,
+ privilegetext )
+ boolean
+
+
+ Does user have privilege for configuration parameter?
+ The parameter name is case-insensitive.
+ Allowable privilege types are SET
+ and ALTER SYSTEM.
+
+
+
+
+
+
+ has_schema_privilege
+
+ has_schema_privilege (
+ username or oid,
+ schematext or oid,
+ privilegetext )
+ boolean
+
+
+ Does user have privilege for schema?
+ Allowable privilege types are
+ CREATE and
+ USAGE.
+
+
+
+
+
+
+ has_sequence_privilege
+
+ has_sequence_privilege (
+ username or oid,
+ sequencetext or oid,
+ privilegetext )
+ boolean
+
+
+ Does user have privilege for sequence?
+ Allowable privilege types are
+ USAGE,
+ SELECT, and
+ UPDATE.
+
+
+
+
+
+
+ has_server_privilege
+
+ has_server_privilege (
+ username or oid,
+ servertext or oid,
+ privilegetext )
+ boolean
+
+
+ Does user have privilege for foreign server?
+ The only allowable privilege type is USAGE.
+
+
+
+
+
+
+ has_table_privilege
+
+ has_table_privilege (
+ username or oid,
+ tabletext or oid,
+ privilegetext )
+ boolean
+
+
+ Does user have privilege for table?
+ Allowable privilege types
+ are SELECT, INSERT,
+ UPDATE, DELETE,
+ TRUNCATE, REFERENCES,
+ TRIGGER, and MAINTAIN.
+
+
+
+
+
+
+ has_tablespace_privilege
+
+ has_tablespace_privilege (
+ username or oid,
+ tablespacetext or oid,
+ privilegetext )
+ boolean
+
+
+ Does user have privilege for tablespace?
+ The only allowable privilege type is CREATE.
+
+
+
+
+
+
+ has_type_privilege
+
+ has_type_privilege (
+ username or oid,
+ typetext or oid,
+ privilegetext )
+ boolean
+
+
+ Does user have privilege for data type?
+ The only allowable privilege type is USAGE.
+ When specifying a type by name rather than by OID, the allowed input
+ is the same as for the regtype data type (see
+ ).
+
+
+
+
+
+
+ pg_has_role
+
+ pg_has_role (
+ username or oid,
+ roletext or oid,
+ privilegetext )
+ boolean
+
+
+ Does user have privilege for role?
+ Allowable privilege types are
+ MEMBER, USAGE,
+ and SET.
+ MEMBER denotes direct or indirect membership in
+ the role without regard to what specific privileges may be conferred.
+ USAGE denotes whether the privileges of the role
+ are immediately available without doing SET ROLE,
+ while SET denotes whether it is possible to change
+ to the role using the SET ROLE command.
+ WITH ADMIN OPTION or WITH GRANT
+ OPTION can be added to any of these privilege types to
+ test whether the ADMIN privilege is held (all
+ six spellings test the same thing).
+ This function does not allow the special case of
+ setting user to public,
+ because the PUBLIC pseudo-role can never be a member of real roles.
+
+
+
+
+
+
+ row_security_active
+
+ row_security_active (
+ tabletext or oid )
+ boolean
+
+
+ Is row-level security active for the specified table in the context of
+ the current user and current environment?
+
+
+
+
+
+
+
+ shows the operators
+ available for the aclitem type, which is the catalog
+ representation of access privileges. See
+ for information about how to read access privilege values.
+
+
+
+ <type>aclitem</type> Operators
+
+
+
+
+ Operator
+
+
+ Description
+
+
+ Example(s)
+
+
+
+
+
+
+
+
+ aclitemeq
+
+ aclitem=aclitem
+ boolean
+
+
+ Are aclitems equal? (Notice that
+ type aclitem lacks the usual set of comparison
+ operators; it has only equality. In turn, aclitem
+ arrays can only be compared for equality.)
+
+
+ 'calvin=r*w/hobbes'::aclitem = 'calvin=r*w*/hobbes'::aclitem
+ f
+
+
+
+
+
+
+ aclcontains
+
+ aclitem[]@>aclitem
+ boolean
+
+
+ Does array contain the specified privileges? (This is true if there
+ is an array entry that matches the aclitem's grantee and
+ grantor, and has at least the specified set of privileges.)
+
+
+ '{calvin=r*w/hobbes,hobbes=r*w*/postgres}'::aclitem[] @> 'calvin=r*/hobbes'::aclitem
+ t
+
+
+
+
+
+ aclitem[]~aclitem
+ boolean
+
+
+ This is a deprecated alias for @>.
+
+
+ '{calvin=r*w/hobbes,hobbes=r*w*/postgres}'::aclitem[] ~ 'calvin=r*/hobbes'::aclitem
+ t
+
+
+
+
+
+
+
+ shows some additional
+ functions to manage the aclitem type.
+
+
+
+ <type>aclitem</type> Functions
+
+
+
+
+ Function
+
+
+ Description
+
+
+
+
+
+
+
+
+ acldefault
+
+ acldefault (
+ type"char",
+ ownerIdoid )
+ aclitem[]
+
+
+ Constructs an aclitem array holding the default access
+ privileges for an object of type type belonging
+ to the role with OID ownerId. This represents
+ the access privileges that will be assumed when an object's
+ ACL entry is null. (The default access privileges
+ are described in .)
+ The type parameter must be one of
+ 'c' for COLUMN,
+ 'r' for TABLE and table-like objects,
+ 's' for SEQUENCE,
+ 'd' for DATABASE,
+ 'f' for FUNCTION or PROCEDURE,
+ 'l' for LANGUAGE,
+ 'L' for LARGE OBJECT,
+ 'n' for SCHEMA,
+ 'p' for PARAMETER,
+ 't' for TABLESPACE,
+ 'F' for FOREIGN DATA WRAPPER,
+ 'S' for FOREIGN SERVER,
+ or
+ 'T' for TYPE or DOMAIN.
+
+
+
+
+
+
+ aclexplode
+
+ aclexplode ( aclitem[] )
+ setof record
+ ( grantoroid,
+ granteeoid,
+ privilege_typetext,
+ is_grantableboolean )
+
+
+ Returns the aclitem array as a set of rows.
+ If the grantee is the pseudo-role PUBLIC, it is represented by zero in
+ the grantee column. Each granted privilege is
+ represented as SELECT, INSERT,
+ etc (see for a full list).
+ Note that each privilege is broken out as a separate row, so
+ only one keyword appears in the privilege_type
+ column.
+
+
+
+
+
+
+ makeaclitem
+
+ makeaclitem (
+ granteeoid,
+ grantoroid,
+ privilegestext,
+ is_grantableboolean )
+ aclitem
+
+
+ Constructs an aclitem with the given properties.
+ privileges is a comma-separated list of
+ privilege names such as SELECT,
+ INSERT, etc, all of which are set in the
+ result. (Case of the privilege string is not significant, and
+ extra whitespace is allowed between but not within privilege
+ names.)
+
+
+
+
+
+
+
+
+
+ Schema Visibility Inquiry Functions
+
+
+ shows functions that
+ determine whether a certain object is visible in the
+ current schema search path.
+ For example, a table is said to be visible if its
+ 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:
+
+SELECT relname FROM pg_class WHERE pg_table_is_visible(oid);
+
+ For functions and operators, an object in the search path is said to be
+ visible if there is no object of the same name and argument data
+ type(s) earlier in the path. For operator classes and families,
+ both the name and the associated index access method are considered.
+
+
+
+ search path
+ object visibility
+
+
+
+ Schema Visibility Inquiry Functions
+
+
+
+
+ Function
+
+
+ Description
+
+
+
+
+
+
+
+
+ pg_collation_is_visible
+
+ pg_collation_is_visible ( collationoid )
+ boolean
+
+
+ Is collation visible in search path?
+
+
+
+
+
+
+ pg_conversion_is_visible
+
+ pg_conversion_is_visible ( conversionoid )
+ boolean
+
+
+ Is conversion visible in search path?
+
+
+
+
+
+
+ pg_function_is_visible
+
+ pg_function_is_visible ( functionoid )
+ boolean
+
+
+ Is function visible in search path?
+ (This also works for procedures and aggregates.)
+
+
+
+
+
+
+ pg_opclass_is_visible
+
+ pg_opclass_is_visible ( opclassoid )
+ boolean
+
+
+ Is operator class visible in search path?
+
+
+
+
+
+
+ pg_operator_is_visible
+
+ pg_operator_is_visible ( operatoroid )
+ boolean
+
+
+ Is operator visible in search path?
+
+
+
+
+
+
+ pg_opfamily_is_visible
+
+ pg_opfamily_is_visible ( opclassoid )
+ boolean
+
+
+ Is operator family visible in search path?
+
+
+
+
+
+
+ pg_statistics_obj_is_visible
+
+ pg_statistics_obj_is_visible ( statoid )
+ boolean
+
+
+ Is statistics object visible in search path?
+
+
+
+
+
+
+ pg_table_is_visible
+
+ pg_table_is_visible ( tableoid )
+ boolean
+
+
+ Is table visible in search path?
+ (This works for all types of relations, including views, materialized
+ views, indexes, sequences and foreign tables.)
+
+
+
+
+
+
+ pg_ts_config_is_visible
+
+ pg_ts_config_is_visible ( configoid )
+ boolean
+
+
+ Is text search configuration visible in search path?
+
+
+
+
+
+
+ pg_ts_dict_is_visible
+
+ pg_ts_dict_is_visible ( dictoid )
+ boolean
+
+
+ Is text search dictionary visible in search path?
+
+
+
+
+
+
+ pg_ts_parser_is_visible
+
+ pg_ts_parser_is_visible ( parseroid )
+ boolean
+
+
+ Is text search parser visible in search path?
+
+
+
+
+
+
+ pg_ts_template_is_visible
+
+ pg_ts_template_is_visible ( templateoid )
+ boolean
+
+
+ Is text search template visible in search path?
+
+
+
+
+
+
+ pg_type_is_visible
+
+ pg_type_is_visible ( typeoid )
+ boolean
+
+
+ Is type (or domain) visible in search path?
+
+
+
+
+
+
+
+ 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 (regclass, regtype,
+ regprocedure, regoperator, regconfig,
+ or regdictionary),
+ for example:
+
+SELECT pg_type_is_visible('myschema.widget'::regtype);
+
+ 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.
+
+
+
+
+
+ System Catalog Information Functions
+
+
+ lists functions that
+ extract information from the system catalogs.
+
+
+
+ System Catalog Information Functions
+
+
+
+
+ Function
+
+
+ Description
+
+
+
+
+
+
+
+
+ format_type
+
+ format_type ( typeoid, typemodinteger )
+ text
+
+
+ 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.
+
+
+
+
+
+
+ pg_basetype
+
+ pg_basetype ( regtype )
+ regtype
+
+
+ Returns the OID of the base type of a domain identified by its
+ type OID. If the argument is the OID of a non-domain type,
+ returns the argument as-is. Returns NULL if the argument is
+ not a valid type OID. If there's a chain of domain dependencies,
+ it will recurse until finding the base type.
+
+
+ Assuming CREATE DOMAIN mytext AS text:
+
+
+ pg_basetype('mytext'::regtype)
+ text
+
+
+
+
+
+
+ pg_char_to_encoding
+
+ pg_char_to_encoding ( encodingname )
+ integer
+
+
+ Converts the supplied encoding name into an integer representing the
+ internal identifier used in some system catalog tables.
+ Returns -1 if an unknown encoding name is provided.
+
+
+
+
+
+
+ pg_encoding_to_char
+
+ pg_encoding_to_char ( encodinginteger )
+ name
+
+
+ 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.
+
+
+
+
+
+
+ pg_get_catalog_foreign_keys
+
+ pg_get_catalog_foreign_keys ()
+ setof record
+ ( fktableregclass,
+ fkcolstext[],
+ pktableregclass,
+ pkcolstext[],
+ is_arrayboolean,
+ is_optboolean )
+
+
+ Returns a set of records describing the foreign key relationships
+ that exist within the PostgreSQL system
+ catalogs.
+ The fktable column contains the name of the
+ referencing catalog, and the fkcols column
+ contains the name(s) of the referencing column(s). Similarly,
+ the pktable column contains the name of the
+ referenced catalog, and the pkcols column
+ contains the name(s) of the referenced column(s).
+ If is_array is true, the last referencing
+ column is an array, each of whose elements should match some entry
+ in the referenced catalog.
+ If is_opt is true, the referencing column(s)
+ are allowed to contain zeroes instead of a valid reference.
+
+
+
+
+
+
+ pg_get_constraintdef
+
+ pg_get_constraintdef ( constraintoid, prettyboolean )
+ text
+
+
+ Reconstructs the creating command for a constraint.
+ (This is a decompiled reconstruction, not the original text
+ of the command.)
+
+
+
+
+
+
+ pg_get_expr
+
+ pg_get_expr ( exprpg_node_tree, relationoid, prettyboolean )
+ text
+
+
+ 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.
+
+
+
+
+
+
+ pg_get_functiondef
+
+ pg_get_functiondef ( funcoid )
+ text
+
+
+ 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 CREATE OR REPLACE FUNCTION
+ or CREATE OR REPLACE PROCEDURE statement.
+
+
+
+
+
+
+ pg_get_function_arguments
+
+ pg_get_function_arguments ( funcoid )
+ text
+
+
+ Reconstructs the argument list of a function or procedure, in the form
+ it would need to appear in within CREATE FUNCTION
+ (including default values).
+
+
+
+
+
+
+ pg_get_function_identity_arguments
+
+ pg_get_function_identity_arguments ( funcoid )
+ text
+
+
+ Reconstructs the argument list necessary to identify a function or
+ procedure, in the form it would need to appear in within commands such
+ as ALTER FUNCTION. This form omits default values.
+
+
+
+
+
+
+ pg_get_function_result
+
+ pg_get_function_result ( funcoid )
+ text
+
+
+ Reconstructs the RETURNS clause of a function, in
+ the form it would need to appear in within CREATE
+ FUNCTION. Returns NULL for a procedure.
+
+
+
+
+
+
+ pg_get_indexdef
+
+ pg_get_indexdef ( indexoid, columninteger, prettyboolean )
+ text
+
+
+ Reconstructs the creating command for an index.
+ (This is a decompiled reconstruction, not the original text
+ of the command.) If column is supplied and is
+ not zero, only the definition of that column is reconstructed.
+
+
+
+
+
+
+ pg_get_keywords
+
+ pg_get_keywords ()
+ setof record
+ ( wordtext,
+ catcode"char",
+ barelabelboolean,
+ catdesctext,
+ baredesctext )
+
+
+ Returns a set of records describing the SQL keywords recognized by the
+ server. The word column contains the
+ keyword. The catcode column contains a
+ category code: U for an unreserved
+ keyword, C for a keyword that can be a column
+ name, T for a keyword that can be a type or
+ function name, or R for a fully reserved keyword.
+ The barelabel column
+ contains true if the keyword can be used as
+ a bare column label in SELECT lists,
+ or false if it can only be used
+ after AS.
+ The catdesc column contains a
+ possibly-localized string describing the keyword's category.
+ The baredesc column contains a
+ possibly-localized string describing the keyword's column label status.
+
+
+
+
+
+
+ pg_get_partkeydef
+
+ pg_get_partkeydef ( tableoid )
+ text
+
+
+ Reconstructs the definition of a partitioned table's partition
+ key, in the form it would have in the PARTITION
+ BY clause of CREATE TABLE.
+ (This is a decompiled reconstruction, not the original text
+ of the command.)
+
+
+
+
+
+
+ pg_get_ruledef
+
+ pg_get_ruledef ( ruleoid, prettyboolean )
+ text
+
+
+ Reconstructs the creating command for a rule.
+ (This is a decompiled reconstruction, not the original text
+ of the command.)
+
+
+
+
+
+
+ pg_get_serial_sequence
+
+ pg_get_serial_sequence ( tabletext, columntext )
+ text
+
+
+ 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
+ (serial, smallserial, bigserial),
+ it is the sequence created for that serial column definition.
+ In the latter case, the association can be modified or removed
+ with ALTER SEQUENCE OWNED BY.
+ (This function probably should have been
+ called pg_get_owned_sequence; 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 typical use is in reading the current value of the sequence for an
+ identity or serial column, for example:
+
+SELECT currval(pg_get_serial_sequence('sometable', 'id'));
+
+
+
+
+
+
+
+ pg_get_statisticsobjdef
+
+ pg_get_statisticsobjdef ( statobjoid )
+ text
+
+
+ Reconstructs the creating command for an extended statistics object.
+ (This is a decompiled reconstruction, not the original text
+ of the command.)
+
+
+
+
+
+
+ pg_get_triggerdef
+
+pg_get_triggerdef ( triggeroid, prettyboolean )
+ text
+
+
+ Reconstructs the creating command for a trigger.
+ (This is a decompiled reconstruction, not the original text
+ of the command.)
+
+
+
+
+
+
+ pg_get_userbyid
+
+ pg_get_userbyid ( roleoid )
+ name
+
+
+ Returns a role's name given its OID.
+
+
+
+
+
+
+ pg_get_viewdef
+
+ pg_get_viewdef ( viewoid, prettyboolean )
+ text
+
+
+ Reconstructs the underlying SELECT command for a
+ view or materialized view. (This is a decompiled reconstruction, not
+ the original text of the command.)
+
+
+
+
+
+ pg_get_viewdef ( viewoid, wrap_columninteger )
+ text
+
+
+ Reconstructs the underlying SELECT 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.
+
+
+
+
+
+ pg_get_viewdef ( viewtext, prettyboolean )
+ text
+
+
+ Reconstructs the underlying SELECT 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.)
+
+
+
+
+
+
+ pg_index_column_has_property
+
+ pg_index_column_has_property ( indexregclass, columninteger, propertytext )
+ boolean
+
+
+ Tests whether an index column has the named property.
+ Common index column properties are listed in
+ .
+ (Note that extension access methods can define additional property
+ names for their indexes.)
+ NULL is returned if the property name is not known
+ or does not apply to the particular object, or if the OID or column
+ number does not identify a valid object.
+
+
+
+
+
+
+ pg_index_has_property
+
+ pg_index_has_property ( indexregclass, propertytext )
+ boolean
+
+
+ Tests whether an index has the named property.
+ Common index properties are listed in
+ .
+ (Note that extension access methods can define additional property
+ names for their indexes.)
+ NULL 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.
+
+
+
+
+
+
+ pg_indexam_has_property
+
+ pg_indexam_has_property ( amoid, propertytext )
+ boolean
+
+
+ Tests whether an index access method has the named property.
+ Access method properties are listed in
+ .
+ NULL 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.
+
+
+
+
+
+
+ pg_options_to_table
+
+ pg_options_to_table ( options_arraytext[] )
+ setof record
+ ( option_nametext,
+ option_valuetext )
+
+
+ Returns the set of storage options represented by a value from
+ pg_class.reloptions or
+ pg_attribute.attoptions.
+
+
+
+
+
+
+ pg_settings_get_flags
+
+ pg_settings_get_flags ( guctext )
+ text[]
+
+
+ Returns an array of the flags associated with the given GUC, or
+ NULL 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
+ are exposed.
+
+
+
+
+
+
+ pg_tablespace_databases
+
+ pg_tablespace_databases ( tablespaceoid )
+ setof oid
+
+
+ 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 pg_tablespace_databases
+ and query their pg_class catalogs.
+
+
+
+
+
+
+ pg_tablespace_location
+
+ pg_tablespace_location ( tablespaceoid )
+ text
+
+
+ Returns the file system path that this tablespace is located in.
+
+
+
+
+
+
+ pg_typeof
+
+ pg_typeof ( "any" )
+ regtype
+
+
+ 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 regtype, which is an OID alias type (see
+ ); this means that it is the same as an
+ OID for comparison purposes but displays as a type name.
+
+
+ pg_typeof(33)
+ integer
+
+
+
+
+
+
+ COLLATION FOR
+
+ COLLATION FOR ( "any" )
+ text
+
+
+ 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 NULL is returned. If the argument is not of a
+ collatable data type, then an error is raised.
+
+
+ collation for ('foo'::text)
+ "default"
+
+
+ collation for ('foo' COLLATE "de_DE")
+ "de_DE"
+
+
+
+
+
+
+ to_regclass
+
+ to_regclass ( text )
+ regclass
+
+
+ Translates a textual relation name to its OID. A similar result is
+ obtained by casting the string to type regclass (see
+ ); however, this function will return
+ NULL rather than throwing an error if the name is
+ not found.
+
+
+
+
+
+
+ to_regdatabase
+
+ to_regdatabase ( text )
+ regdatabase
+
+
+ Translates a textual database name to its OID. A similar result is
+ obtained by casting the string to type regdatabase (see
+ ); however, this function will return
+ NULL rather than throwing an error if the name is
+ not found.
+
+
+
+
+
+
+ to_regcollation
+
+ to_regcollation ( text )
+ regcollation
+
+
+ Translates a textual collation name to its OID. A similar result is
+ obtained by casting the string to type regcollation (see
+ ); however, this function will return
+ NULL rather than throwing an error if the name is
+ not found.
+
+
+
+
+
+
+ to_regnamespace
+
+ to_regnamespace ( text )
+ regnamespace
+
+
+ Translates a textual schema name to its OID. A similar result is
+ obtained by casting the string to type regnamespace (see
+ ); however, this function will return
+ NULL rather than throwing an error if the name is
+ not found.
+
+
+
+
+
+
+ to_regoper
+
+ to_regoper ( text )
+ regoper
+
+
+ Translates a textual operator name to its OID. A similar result is
+ obtained by casting the string to type regoper (see
+ ); however, this function will return
+ NULL rather than throwing an error if the name is
+ not found or is ambiguous.
+
+
+
+
+
+
+ to_regoperator
+
+ to_regoperator ( text )
+ regoperator
+
+
+ Translates a textual operator name (with parameter types) to its OID. A similar result is
+ obtained by casting the string to type regoperator (see
+ ); however, this function will return
+ NULL rather than throwing an error if the name is
+ not found.
+
+
+
+
+
+
+ to_regproc
+
+ to_regproc ( text )
+ regproc
+
+
+ Translates a textual function or procedure name to its OID. A similar result is
+ obtained by casting the string to type regproc (see
+ ); however, this function will return
+ NULL rather than throwing an error if the name is
+ not found or is ambiguous.
+
+
+
+
+
+
+ to_regprocedure
+
+ to_regprocedure ( text )
+ regprocedure
+
+
+ Translates a textual function or procedure name (with argument types) to its OID. A similar result is
+ obtained by casting the string to type regprocedure (see
+ ); however, this function will return
+ NULL rather than throwing an error if the name is
+ not found.
+
+
+
+
+
+
+ to_regrole
+
+ to_regrole ( text )
+ regrole
+
+
+ Translates a textual role name to its OID. A similar result is
+ obtained by casting the string to type regrole (see
+ ); however, this function will return
+ NULL rather than throwing an error if the name is
+ not found.
+
+
+
+
+
+
+ to_regtype
+
+ to_regtype ( text )
+ regtype
+
+
+ Parses a string of text, extracts a potential type name from it,
+ and translates that name into a type OID. A syntax error in the
+ string will result in an error; but if the string is a
+ syntactically valid type name that happens not to be found in the
+ catalogs, the result is NULL. A similar result
+ is obtained by casting the string to type regtype
+ (see ), except that that will throw
+ error for name not found.
+
+
+
+
+
+
+ to_regtypemod
+
+ to_regtypemod ( text )
+ integer
+
+
+ Parses a string of text, extracts a potential type name from it,
+ and translates its type modifier, if any. A syntax error in the
+ string will result in an error; but if the string is a
+ syntactically valid type name that happens not to be found in the
+ catalogs, the result is NULL. The result is
+ -1 if no type modifier is present.
+
+
+ to_regtypemod can be combined with
+ to produce appropriate inputs for
+ , allowing a string representing a
+ type name to be canonicalized.
+
+
+ format_type(to_regtype('varchar(32)'), to_regtypemod('varchar(32)'))
+ character varying(32)
+
+
+
+
+
+
+
+ Most of the functions that reconstruct (decompile) database objects
+ have an optional pretty flag, which
+ if true causes the result to
+ be pretty-printed. 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
+ PostgreSQL; so avoid using pretty-printed output
+ for dump purposes. Passing false for
+ the pretty parameter yields the same result as
+ omitting the parameter.
+
+
+
+ Index Column Properties
+
+
+
+
+ NameDescription
+
+
+
+ asc
+ Does the column sort in ascending order on a forward scan?
+
+
+
+ desc
+ Does the column sort in descending order on a forward scan?
+
+
+
+ nulls_first
+ Does the column sort with nulls first on a forward scan?
+
+
+
+ nulls_last
+ Does the column sort with nulls last on a forward scan?
+
+
+
+ orderable
+ Does the column possess any defined sort ordering?
+
+
+
+ distance_orderable
+ Can the column be scanned in order by a distance
+ operator, for example ORDER BY col <-> constant ?
+
+
+
+ returnable
+ Can the column value be returned by an index-only scan?
+
+
+
+ search_array
+ Does the column natively support col = ANY(array)
+ searches?
+
+
+
+ search_nulls
+ Does the column support IS NULL and
+ IS NOT NULL searches?
+
+
+
+
+
+
+
+ Index Properties
+
+
+
+
+ NameDescription
+
+
+
+ clusterable
+ Can the index be used in a CLUSTER command?
+
+
+
+ index_scan
+ Does the index support plain (non-bitmap) scans?
+
+
+
+ bitmap_scan
+ Does the index support bitmap scans?
+
+
+
+ backward_scan
+ Can the scan direction be changed in mid-scan (to
+ support FETCH BACKWARD on a cursor without
+ needing materialization)?
+
+
+
+
+
+
+
+ Index Access Method Properties
+
+
+
+
+ NameDescription
+
+
+
+ can_order
+ Does the access method support ASC,
+ DESC and related keywords in
+ CREATE INDEX?
+
+
+
+ can_unique
+ Does the access method support unique indexes?
+
+
+
+ can_multi_col
+ Does the access method support indexes with multiple columns?
+
+
+
+ can_exclude
+ Does the access method support exclusion constraints?
+
+
+
+ can_include
+ Does the access method support the INCLUDE
+ clause of CREATE INDEX?
+
+
+
+
+
+
+
+ GUC Flags
+
+
+
+
+ FlagDescription
+
+
+
+ EXPLAIN
+ Parameters with this flag are included in
+ EXPLAIN (SETTINGS) commands.
+
+
+
+ NO_SHOW_ALL
+ Parameters with this flag are excluded from
+ SHOW ALL commands.
+
+
+
+ NO_RESET
+ Parameters with this flag do not support
+ RESET commands.
+
+
+
+ NO_RESET_ALL
+ Parameters with this flag are excluded from
+ RESET ALL commands.
+
+
+
+ NOT_IN_SAMPLE
+ Parameters with this flag are not included in
+ postgresql.conf by default.
+
+
+
+ RUNTIME_COMPUTED
+ Parameters with this flag are runtime-computed ones.
+
+
+
+
+
+
+
+
+
+ Object Information and Addressing Functions
+
+
+ lists functions related to
+ database object identification and addressing.
+
+
+
+ Object Information and Addressing Functions
+
+
+
+
+ Function
+
+
+ Description
+
+
+
+
+
+
+
+
+ pg_get_acl
+
+ pg_get_acl ( classidoid, objidoid, objsubidinteger )
+ aclitem[]
+
+
+ Returns the ACL for a database object, specified
+ by catalog OID, object OID and sub-object ID. This function returns
+ NULL values for undefined objects.
+
+
+
+
+
+
+ pg_describe_object
+
+ pg_describe_object ( classidoid, objidoid, objsubidinteger )
+ text
+
+
+ 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
+ pg_depend catalog. This function returns
+ NULL values for undefined objects.
+
+
+
+
+
+
+ pg_identify_object
+
+ pg_identify_object ( classidoid, objidoid, objsubidinteger )
+ record
+ ( typetext,
+ schematext,
+ nametext,
+ identitytext )
+
+
+ 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.
+ type identifies the type of database object;
+ schema is the schema name that the object
+ belongs in, or NULL for object types that do not
+ belong to schemas;
+ name 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 NULL;
+ identity 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 NULL values.
+
+
+
+
+
+
+ pg_identify_object_as_address
+
+ pg_identify_object_as_address ( classidoid, objidoid, objsubidinteger )
+ record
+ ( typetext,
+ object_namestext[],
+ object_argstext[] )
+
+
+ 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.
+ type identifies the type of database object;
+ object_names and
+ object_args
+ are text arrays that together form a reference to the object.
+ These three values can be passed
+ to pg_get_object_address to obtain the internal
+ address of the object.
+
+
+
+
+
+
+ pg_get_object_address
+
+ pg_get_object_address ( typetext, object_namestext[], object_argstext[] )
+ record
+ ( classidoid,
+ objidoid,
+ objsubidinteger )
+
+
+ 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 pg_depend; they can be passed to
+ other system functions such as pg_describe_object
+ or pg_identify_object.
+ classid is the OID of the system catalog
+ containing the object;
+ objid is the OID of the object itself, and
+ objsubid is the sub-object ID, or zero if none.
+ This function is the inverse
+ of pg_identify_object_as_address.
+ Undefined objects are identified with NULL values.
+
+
+
+
+
+
+
+ pg_get_acl is useful for retrieving and inspecting
+ the privileges associated with database objects without looking at
+ specific catalogs. For example, to retrieve all the granted privileges
+ on objects in the current database:
+
+postgres=# SELECT
+ (pg_identify_object(s.classid,s.objid,s.objsubid)).*,
+ pg_catalog.pg_get_acl(s.classid,s.objid,s.objsubid) AS acl
+FROM pg_catalog.pg_shdepend AS s
+JOIN pg_catalog.pg_database AS d
+ ON d.datname = current_database() AND
+ d.oid = s.dbid
+JOIN pg_catalog.pg_authid AS a
+ ON a.oid = s.refobjid AND
+ s.refclassid = 'pg_authid'::regclass
+WHERE s.deptype = 'a';
+-[ RECORD 1 ]-----------------------------------------
+type | table
+schema | public
+name | testtab
+identity | public.testtab
+acl | {postgres=arwdDxtm/postgres,foo=r/postgres}
+
+
+
+
+
+
+ Comment Information Functions
+
+
+ comment
+ about database objects
+
+
+
+ The functions shown in
+ extract comments previously stored with the
+ command. A null value is returned if no
+ comment could be found for the specified parameters.
+
+
+
+ Comment Information Functions
+
+
+
+
+ Function
+
+
+ Description
+
+
+
+
+
+
+
+
+ col_description
+
+ col_description ( tableoid, columninteger )
+ text
+
+
+ Returns the comment for a table column, which is specified by the OID
+ of its table and its column number.
+ (obj_description cannot be used for table
+ columns, since columns do not have OIDs of their own.)
+
+
+
+
+
+
+ obj_description
+
+ obj_description ( objectoid, catalogname )
+ text
+
+
+ Returns the comment for a database object specified by its OID and the
+ name of the containing system catalog. For
+ example, obj_description(123456, 'pg_class') would
+ retrieve the comment for the table with OID 123456.
+
+
+
+
+
+ obj_description ( objectoid )
+ text
+
+
+ Returns the comment for a database object specified by its OID alone.
+ This is deprecated since there is no guarantee
+ that OIDs are unique across different system catalogs; therefore, the
+ wrong comment might be returned.
+
+
+
+
+
+
+ shobj_description
+
+ shobj_description ( objectoid, catalogname )
+ text
+
+
+ Returns the comment for a shared database object specified by its OID
+ and the name of the containing system catalog. This is just
+ like obj_description 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.
+
+
+
+
+
+
+
+
+
+ Data Validity Checking Functions
+
+
+ The functions shown in
+ can be helpful for checking validity of proposed input data.
+
+
+
+ Data Validity Checking Functions
+
+
+
+
+ Function
+
+
+ Description
+
+
+ Example(s)
+
+
+
+
+
+
+
+
+ pg_input_is_valid
+
+ pg_input_is_valid (
+ stringtext,
+ typetext
+ )
+ boolean
+
+
+ Tests whether the given string is valid
+ input for the specified data type, returning true or false.
+
+
+ This function will only work as desired if the data type's input
+ function has been updated to report invalid input as
+ a soft error. Otherwise, invalid input will abort
+ the transaction, just as if the string had been cast to the type
+ directly.
+
+
+ pg_input_is_valid('42', 'integer')
+ t
+
+
+ pg_input_is_valid('42000000000', 'integer')
+ f
+
+
+ pg_input_is_valid('1234.567', 'numeric(7,4)')
+ f
+
+
+
+
+
+ pg_input_error_info
+
+ pg_input_error_info (
+ stringtext,
+ typetext
+ )
+ record
+ ( messagetext,
+ detailtext,
+ hinttext,
+ sql_error_codetext )
+
+
+ Tests whether the given string is valid
+ input for the specified data type; if not, return the details of
+ the error that would have been thrown. If the input is valid, the
+ results are NULL. The inputs are the same as
+ for pg_input_is_valid.
+
+
+ This function will only work as desired if the data type's input
+ function has been updated to report invalid input as
+ a soft error. Otherwise, invalid input will abort
+ the transaction, just as if the string had been cast to the type
+ directly.
+
+
+ SELECT * FROM pg_input_error_info('42000000000', 'integer')
+
+
+ message | detail | hint | sql_error_code
+------------------------------------------------------+--------+------+----------------
+ value "42000000000" is out of range for type integer | | | 22003
+
+
+
+
+
+
+
+
+
+
+ Transaction ID and Snapshot Information Functions
+
+
+ The functions shown in
+ provide server transaction information in an exportable form. The main
+ use of these functions is to determine which transactions were committed
+ between two snapshots.
+
+
+
+ Transaction ID and Snapshot Information Functions
+
+
+
+
+ Function
+
+
+ Description
+
+
+
+
+
+
+
+
+ age
+
+ age ( xid )
+ integer
+
+
+ Returns the number of transactions between the supplied
+ transaction id and the current transaction counter.
+
+
+
+
+
+
+ mxid_age
+
+ mxid_age ( xid )
+ integer
+
+
+ Returns the number of multixacts IDs between the supplied
+ multixact ID and the current multixacts counter.
+
+
+
+
+
+
+ pg_current_xact_id
+
+ pg_current_xact_id ()
+ xid8
+
+
+ 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); see for details. If executed in a
+ subtransaction, this will return the top-level transaction ID;
+ see for details.
+
+
+
+
+
+
+ pg_current_xact_id_if_assigned
+
+ pg_current_xact_id_if_assigned ()
+ xid8
+
+
+ Returns the current transaction's ID, or NULL 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.)
+ If executed in a subtransaction, this will return the top-level
+ transaction ID.
+
+
+
+
+
+
+ pg_xact_status
+
+ pg_xact_status ( xid8 )
+ text
+
+
+ Reports the commit status of a recent transaction.
+ The result is one of in progress,
+ committed, or aborted,
+ 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 NULL.
+ 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 COMMIT is in progress.
+ Note that prepared transactions are reported as in
+ progress; applications must check pg_prepared_xacts
+ if they need to determine whether a transaction ID belongs to a
+ prepared transaction.
+
+
+
+
+
+
+ pg_current_snapshot
+
+ pg_current_snapshot ()
+ pg_snapshot
+
+
+ Returns a current snapshot, a data structure
+ showing which transaction IDs are now in-progress.
+ Only top-level transaction IDs are included in the snapshot;
+ subtransaction IDs are not shown; see
+ for details.
+
+
+
+
+
+
+ pg_snapshot_xip
+
+ pg_snapshot_xip ( pg_snapshot )
+ setof xid8
+
+
+ Returns the set of in-progress transaction IDs contained in a snapshot.
+
+
+
+
+
+
+ pg_snapshot_xmax
+
+ pg_snapshot_xmax ( pg_snapshot )
+ xid8
+
+
+ Returns the xmax of a snapshot.
+
+
+
+
+
+
+ pg_snapshot_xmin
+
+ pg_snapshot_xmin ( pg_snapshot )
+ xid8
+
+
+ Returns the xmin of a snapshot.
+
+
+
+
+
+
+ pg_visible_in_snapshot
+
+ pg_visible_in_snapshot ( xid8, pg_snapshot )
+ boolean
+
+
+ Is the given transaction ID visible 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 (subxid); see for
+ details.
+
+
+
+
+
+
+ pg_get_multixact_members
+
+ pg_get_multixact_members ( multixidxid )
+ setof record
+ ( xidxid,
+ modetext )
+
+
+ Returns the transaction ID and lock mode for each member of the
+ specified multixact ID. The lock modes forupd,
+ fornokeyupd, sh, and
+ keysh correspond to the row-level locks
+ FOR UPDATE, FOR NO KEY UPDATE,
+ FOR SHARE, and FOR KEY SHARE,
+ respectively, as described in . Two
+ additional modes are specific to multixacts:
+ nokeyupd, used by updates that do not modify key
+ columns, and upd, used by updates or deletes that
+ modify key columns.
+
+
+
+
+
+
+
+ The internal transaction ID type xid is 32 bits wide and
+ wraps around every 4 billion transactions. However,
+ the functions shown in , except
+ age, mxid_age, and
+ pg_get_multixact_members, use a
+ 64-bit type xid8 that does not wrap around during the life
+ of an installation and can be converted to xid by casting if
+ required; see for details.
+ The data type pg_snapshot stores information about
+ transaction ID visibility at a particular moment in time. Its components
+ are described in .
+ pg_snapshot's textual representation is
+ xmin:xmax:xip_list.
+ For example 10:20:10,14,15 means
+ xmin=10, xmax=20, xip_list=10, 14, 15.
+
+
+
+ Snapshot Components
+
+
+
+
+
+ Name
+ Description
+
+
+
+
+
+ xmin
+
+ Lowest transaction ID that was still active. All transaction IDs
+ less than xmin are either committed and visible,
+ or rolled back and dead.
+
+
+
+
+ xmax
+
+ One past the highest completed transaction ID. All transaction IDs
+ greater than or equal to xmax had not yet
+ completed as of the time of the snapshot, and thus are invisible.
+
+
+
+
+ xip_list
+
+ Transactions in progress at the time of the snapshot. A transaction
+ ID that is xmin <= X <
+ xmax 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 (subxids).
+
+
+
+
+
+
+
+ In releases of PostgreSQL before 13 there was
+ no xid8 type, so variants of these functions were provided
+ that used bigint to represent a 64-bit XID, with a
+ correspondingly distinct snapshot data type txid_snapshot.
+ These older functions have txid in their names. They
+ are still supported for backward compatibility, but may be removed from a
+ future release. See .
+
+
+
+
+
+
+
+ Committed Transaction Information Functions
+
+
+ The functions shown in
+ provide information about when past transactions were committed.
+ They only provide useful data when the
+ configuration option is
+ enabled, and only for transactions that were committed after it was
+ enabled. Commit timestamp information is routinely removed during
+ vacuum.
+
+
+
+ Committed Transaction Information Functions
+
+
+
+
+ Function
+
+
+ Description
+
+
+
+
+
+
+
+
+ pg_xact_commit_timestamp
+
+ pg_xact_commit_timestamp ( xid )
+ timestamp with time zone
+
+
+ Returns the commit timestamp of a transaction.
+
+
+
+
+
+
+ pg_xact_commit_timestamp_origin
+
+ pg_xact_commit_timestamp_origin ( xid )
+ record
+ ( timestamptimestamp with time zone,
+ roidentoid)
+
+
+ Returns the commit timestamp and replication origin of a transaction.
+
+
+
+
+
+
+ pg_last_committed_xact
+
+ pg_last_committed_xact ()
+ record
+ ( xidxid,
+ timestamptimestamp with time zone,
+ roidentoid )
+
+
+ Returns the transaction ID, commit timestamp and replication origin
+ of the latest committed transaction.
+
+
+
+
+
+
+
+
+
+ Control Data Functions
+
+
+ The functions shown in
+ print information initialized during initdb, such
+ as the catalog version. They also show information about write-ahead
+ logging and checkpoint processing. This information is cluster-wide,
+ not specific to any one database. These functions provide most of the same
+ information, from the same source, as the
+ application.
+
+
+
+ Control Data Functions
+
+
+
+
+ Function
+
+
+ Description
+
+
+
+
+
+
+
+
+ pg_control_checkpoint
+
+ pg_control_checkpoint ()
+ record
+
+
+ Returns information about current checkpoint state, as shown in
+ .
+
+
+
+
+
+
+ pg_control_system
+
+ pg_control_system ()
+ record
+
+
+ Returns information about current control file state, as shown in
+ .
+
+
+
+
+
+
+ pg_control_init
+
+ pg_control_init ()
+ record
+
+
+ Returns information about cluster initialization state, as shown in
+ .
+
+
+
+
+
+
+ pg_control_recovery
+
+ pg_control_recovery ()
+ record
+
+
+ Returns information about recovery state, as shown in
+ .
+
+
+
+
+
+
+
+
+
+ Version Information Functions
+
+
+ The functions shown in
+ print version information.
+
+
+
+ Version Information Functions
+
+
+
+
+ Function
+
+
+ Description
+
+
+
+
+
+
+
+
+ version
+
+ version ()
+ text
+
+
+ Returns a string describing the PostgreSQL
+ server's version. You can also get this information from
+ , or for a machine-readable
+ version use . Software
+ developers should use server_version_num (available
+ since 8.2) or instead of
+ parsing the text version.
+
+
+
+
+
+
+ unicode_version
+
+ unicode_version ()
+ text
+
+
+ Returns a string representing the version of Unicode used by
+ PostgreSQL.
+
+
+
+
+
+ icu_unicode_version
+
+ icu_unicode_version ()
+ text
+
+
+ Returns a string representing the version of Unicode used by ICU, if
+ the server was built with ICU support; otherwise returns
+ NULL
+
+
+
+
+
+
+
+
+ WAL Summarization Information Functions
+
+
+ The functions shown in
+ print information about the status of WAL summarization.
+ See .
+
+
+
+ WAL Summarization Information Functions
+
+
+
+
+ Function
+
+
+ Description
+
+
+
+
+
+
+
+
+ pg_available_wal_summaries
+
+ pg_available_wal_summaries ()
+ setof record
+ ( tlibigint,
+ start_lsnpg_lsn,
+ end_lsnpg_lsn )
+
+
+ Returns information about the WAL summary files present in the
+ data directory, under pg_wal/summaries.
+ One row will be returned per WAL summary file. Each file summarizes
+ WAL on the indicated TLI within the indicated LSN range. This function
+ might be useful to determine whether enough WAL summaries are present
+ on the server to take an incremental backup based on some prior
+ backup whose start LSN is known.
+
+
+
+
+
+
+ pg_wal_summary_contents
+
+ pg_wal_summary_contents ( tlibigint, start_lsnpg_lsn, end_lsnpg_lsn )
+ setof record
+ ( relfilenodeoid,
+ reltablespaceoid,
+ reldatabaseoid,
+ relforknumbersmallint,
+ relblocknumberbigint,
+ is_limit_blockboolean )
+
+
+ Returns one information about the contents of a single WAL summary file
+ identified by TLI and starting and ending LSNs. Each row with
+ is_limit_block false indicates that the block
+ identified by the remaining output columns was modified by at least
+ one WAL record within the range of records summarized by this file.
+ Each row with is_limit_block true indicates either
+ that (a) the relation fork was truncated to the length given by
+ relblocknumber within the relevant range of WAL
+ records or (b) that the relation fork was created or dropped within
+ the relevant range of WAL records; in such cases,
+ relblocknumber will be zero.
+
+
+
+
+
+
+ pg_get_wal_summarizer_state
+
+ pg_get_wal_summarizer_state ()
+ record
+ ( summarized_tlibigint,
+ summarized_lsnpg_lsn,
+ pending_lsnpg_lsn,
+ summarizer_pidint )
+
+
+ Returns information about the progress of the WAL summarizer. If the
+ WAL summarizer has never run since the instance was started, then
+ summarized_tli and summarized_lsn
+ will be 0 and 0/00000000 respectively;
+ otherwise, they will be the TLI and ending LSN of the last WAL summary
+ file written to disk. If the WAL summarizer is currently running,
+ pending_lsn will be the ending LSN of the last
+ record that it has consumed, which must always be greater than or
+ equal to summarized_lsn; if the WAL summarizer is
+ not running, it will be equal to summarized_lsn.
+ summarizer_pid is the PID of the WAL summarizer
+ process, if it is running, and otherwise NULL.
+
+
+ As a special exception, the WAL summarizer will refuse to generate
+ WAL summary files if run on WAL generated under
+ wal_level=minimal, since such summaries would be
+ unsafe to use as the basis for an incremental backup. In this case,
+ the fields above will continue to advance as if summaries were being
+ generated, but nothing will be written to disk. Once the summarizer
+ reaches WAL generated while wal_level was set
+ to replica or higher, it will resume writing
+ summaries to disk.
+
+
+
+
+
+
+
+
+
diff --git a/doc/src/sgml/func/func-json.sgml b/doc/src/sgml/func/func-json.sgml
new file mode 100644
index 0000000000000..91f98a345d445
--- /dev/null
+++ b/doc/src/sgml/func/func-json.sgml
@@ -0,0 +1,3945 @@
+
+ JSON Functions and Operators
+
+
+ JSON
+ functions and operators
+
+
+ SQL/JSON
+ functions and expressions
+
+
+
+ This section describes:
+
+
+
+
+ functions and operators for processing and creating JSON data
+
+
+
+
+ the SQL/JSON path language
+
+
+
+
+ the SQL/JSON query functions
+
+
+
+
+
+
+ To provide native support for JSON data types within the SQL environment,
+ PostgreSQL implements the
+ SQL/JSON data model.
+ This model comprises sequences of items. Each item can hold SQL scalar
+ values, with an additional SQL/JSON null value, and composite data structures
+ that use JSON arrays and objects. The model is a formalization of the implied
+ data model in the JSON specification
+ RFC 7159.
+
+
+
+ SQL/JSON allows you to handle JSON data alongside regular SQL data,
+ with transaction support, including:
+
+
+
+
+ Uploading JSON data into the database and storing it in
+ regular SQL columns as character or binary strings.
+
+
+
+
+ Generating JSON objects and arrays from relational data.
+
+
+
+
+ Querying JSON data using SQL/JSON query functions and
+ SQL/JSON path language expressions.
+
+
+
+
+
+
+ To learn more about the SQL/JSON standard, see
+ . For details on JSON types
+ supported in PostgreSQL,
+ see .
+
+
+
+ Processing and Creating JSON Data
+
+
+ shows the operators that
+ are available for use with JSON data types (see ).
+ In addition, the usual comparison operators shown in are available for
+ jsonb, though not for json. The comparison
+ operators follow the ordering rules for B-tree operations outlined in
+ .
+ See also for the aggregate
+ function json_agg which aggregates record
+ values as JSON, the aggregate function
+ json_object_agg which aggregates pairs of values
+ into a JSON object, and their jsonb equivalents,
+ jsonb_agg and jsonb_object_agg.
+
+
+
+ <type>json</type> and <type>jsonb</type> Operators
+
+
+
+
+ Operator
+
+
+ Description
+
+
+ Example(s)
+
+
+
+
+
+
+
+ json->integer
+ json
+
+
+ jsonb->integer
+ jsonb
+
+
+ Extracts n'th element of JSON array
+ (array elements are indexed from zero, but negative integers count
+ from the end).
+
+
+ '[{"a":"foo"},{"b":"bar"},{"c":"baz"}]'::json -> 2
+ {"c":"baz"}
+
+
+ '[{"a":"foo"},{"b":"bar"},{"c":"baz"}]'::json -> -3
+ {"a":"foo"}
+
+
+
+
+
+ json->text
+ json
+
+
+ jsonb->text
+ jsonb
+
+
+ Extracts JSON object field with the given key.
+
+
+ '{"a": {"b":"foo"}}'::json -> 'a'
+ {"b":"foo"}
+
+
+
+
+
+ json->>integer
+ text
+
+
+ jsonb->>integer
+ text
+
+
+ Extracts n'th element of JSON array,
+ as text.
+
+
+ '[1,2,3]'::json ->> 2
+ 3
+
+
+
+
+
+ json->>text
+ text
+
+
+ jsonb->>text
+ text
+
+
+ Extracts JSON object field with the given key, as text.
+
+
+ '{"a":1,"b":2}'::json ->> 'b'
+ 2
+
+
+
+
+
+ json#>text[]
+ json
+
+
+ jsonb#>text[]
+ jsonb
+
+
+ Extracts JSON sub-object at the specified path, where path elements
+ can be either field keys or array indexes.
+
+
+ '{"a": {"b": ["foo","bar"]}}'::json #> '{a,b,1}'
+ "bar"
+
+
+
+
+
+ json#>>text[]
+ text
+
+
+ jsonb#>>text[]
+ text
+
+
+ Extracts JSON sub-object at the specified path as text.
+
+
+ '{"a": {"b": ["foo","bar"]}}'::json #>> '{a,b,1}'
+ bar
+
+
+
+
+
+
+
+
+ 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.
+
+
+
+
+ Some further operators exist only for jsonb, as shown
+ in .
+
+ describes how these operators can be used to effectively search indexed
+ jsonb data.
+
+
+
+ Additional <type>jsonb</type> Operators
+
+
+
+
+ Operator
+
+
+ Description
+
+
+ Example(s)
+
+
+
+
+
+
+
+ jsonb@>jsonb
+ boolean
+
+
+ Does the first JSON value contain the second?
+ (See for details about containment.)
+
+
+ '{"a":1, "b":2}'::jsonb @> '{"b":2}'::jsonb
+ t
+
+
+
+
+
+ jsonb<@jsonb
+ boolean
+
+
+ Is the first JSON value contained in the second?
+
+
+ '{"b":2}'::jsonb <@ '{"a":1, "b":2}'::jsonb
+ t
+
+
+
+
+
+ jsonb?text
+ boolean
+
+
+ Does the text string exist as a top-level key or array element within
+ the JSON value?
+
+
+ '{"a":1, "b":2}'::jsonb ? 'b'
+ t
+
+
+ '["a", "b", "c"]'::jsonb ? 'b'
+ t
+
+
+
+
+
+ jsonb?|text[]
+ boolean
+
+
+ Do any of the strings in the text array exist as top-level keys or
+ array elements?
+
+
+ '{"a":1, "b":2, "c":3}'::jsonb ?| array['b', 'd']
+ t
+
+
+
+
+
+ jsonb?&text[]
+ boolean
+
+
+ Do all of the strings in the text array exist as top-level keys or
+ array elements?
+
+
+ '["a", "b", "c"]'::jsonb ?& array['a', 'b']
+ t
+
+
+
+
+
+ jsonb||jsonb
+ jsonb
+
+
+ Concatenates two jsonb 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.
+
+
+ '["a", "b"]'::jsonb || '["a", "d"]'::jsonb
+ ["a", "b", "a", "d"]
+
+
+ '{"a": "b"}'::jsonb || '{"c": "d"}'::jsonb
+ {"a": "b", "c": "d"}
+
+
+ '[1, 2]'::jsonb || '3'::jsonb
+ [1, 2, 3]
+
+
+ '{"a": "b"}'::jsonb || '42'::jsonb
+ [{"a": "b"}, 42]
+
+
+ To append an array to another array as a single entry, wrap it
+ in an additional layer of array, for example:
+
+
+ '[1, 2]'::jsonb || jsonb_build_array('[3, 4]'::jsonb)
+ [1, 2, [3, 4]]
+
+
+
+
+
+ jsonb-text
+ jsonb
+
+
+ Deletes a key (and its value) from a JSON object, or matching string
+ value(s) from a JSON array.
+
+
+ '{"a": "b", "c": "d"}'::jsonb - 'a'
+ {"c": "d"}
+
+
+ '["a", "b", "c", "b"]'::jsonb - 'b'
+ ["a", "c"]
+
+
+
+
+
+ jsonb-text[]
+ jsonb
+
+
+ Deletes all matching keys or array elements from the left operand.
+
+
+ '{"a": "b", "c": "d"}'::jsonb - '{a,c}'::text[]
+ {}
+
+
+
+
+
+ jsonb-integer
+ jsonb
+
+
+ Deletes the array element with specified index (negative
+ integers count from the end). Throws an error if JSON value
+ is not an array.
+
+
+ '["a", "b"]'::jsonb - 1
+ ["a"]
+
+
+
+
+
+ jsonb#-text[]
+ jsonb
+
+
+ Deletes the field or array element at the specified path, where path
+ elements can be either field keys or array indexes.
+
+
+ '["a", {"b":1}]'::jsonb #- '{1,b}'
+ ["a", {}]
+
+
+
+
+
+ jsonb@?jsonpath
+ boolean
+
+
+ Does JSON path return any item for the specified JSON value?
+ (This is useful only with SQL-standard JSON path expressions, not
+ predicate check
+ expressions, since those always return a value.)
+
+
+ '{"a":[1,2,3,4,5]}'::jsonb @? '$.a[*] ? (@ > 2)'
+ t
+
+
+
+
+
+ jsonb@@jsonpath
+ boolean
+
+
+ Returns the result of a JSON path predicate check for the
+ specified JSON value.
+ (This is useful only
+ with predicate
+ check expressions, not SQL-standard JSON path expressions,
+ since it will return NULL if the path result is
+ not a single boolean value.)
+
+
+ '{"a":[1,2,3,4,5]}'::jsonb @@ '$.a[*] > 2'
+ t
+
+
+
+
+
+
+
+
+ The jsonpath operators @?
+ and @@ suppress the following errors: missing object
+ field or array element, unexpected JSON item type, datetime and numeric
+ errors. The jsonpath-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.
+
+
+
+
+ shows the functions that are
+ available for constructing json and jsonb values.
+ Some functions in this table have a RETURNING clause,
+ which specifies the data type returned. It must be one of json,
+ jsonb, bytea, a character string type (text,
+ char, or varchar), or a type
+ that can be cast to json.
+ By default, the json type is returned.
+
+
+
+ JSON Creation Functions
+
+
+
+
+ Function
+
+
+ Description
+
+
+ Example(s)
+
+
+
+
+
+
+
+
+ to_json
+
+ to_json ( anyelement )
+ json
+
+
+
+ to_jsonb
+
+ to_jsonb ( anyelement )
+ jsonb
+
+
+ Converts any SQL value to json or jsonb.
+ 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 json, the cast function will be used to perform the
+ conversion;
+
+ For example, the extension has a cast
+ from hstore to json, so that
+ hstore values converted via the JSON creation functions
+ will be represented as JSON objects, not as primitive string values.
+
+
+ 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.
+
+
+ to_json('Fred said "Hi."'::text)
+ "Fred said \"Hi.\""
+
+
+ to_jsonb(row(42, 'Fred said "Hi."'::text))
+ {"f1": 42, "f2": "Fred said \"Hi.\""}
+
+
+
+
+
+
+ array_to_json
+
+ array_to_json ( anyarray, boolean )
+ json
+
+
+ Converts an SQL array to a JSON array. The behavior is the same
+ as to_json except that line feeds will be added
+ between top-level array elements if the optional boolean parameter is
+ true.
+
+
+ array_to_json('{{1,5},{99,100}}'::int[])
+ [[1,5],[99,100]]
+
+
+
+
+
+
+ json_array
+ json_array (
+ { value_expressionFORMAT JSON } , ...
+ { NULL | ABSENT } ON NULL
+ RETURNINGdata_typeFORMAT JSONENCODING UTF8)
+
+
+ json_array (
+ query_expression
+ RETURNINGdata_typeFORMAT JSONENCODING UTF8)
+
+
+ Constructs a JSON array from either a series of
+ value_expression parameters or from the results
+ of query_expression,
+ which must be a SELECT query returning a single column. If
+ ABSENT ON NULL is specified, NULL values are ignored.
+ This is always the case if a
+ query_expression is used.
+
+
+ json_array(1,true,json '{"a":null}')
+ [1, true, {"a":null}]
+
+
+ json_array(SELECT * FROM (VALUES(1),(2)) t)
+ [1, 2]
+
+
+
+
+
+
+ row_to_json
+
+ row_to_json ( record, boolean )
+ json
+
+
+ Converts an SQL composite value to a JSON object. The behavior is the
+ same as to_json except that line feeds will be
+ added between top-level elements if the optional boolean parameter is
+ true.
+
+
+ row_to_json(row(1,'foo'))
+ {"f1":1,"f2":"foo"}
+
+
+
+
+
+
+ json_build_array
+
+ json_build_array ( VARIADIC"any" )
+ json
+
+
+
+ jsonb_build_array
+
+ jsonb_build_array ( VARIADIC"any" )
+ jsonb
+
+
+ Builds a possibly-heterogeneously-typed JSON array out of a variadic
+ argument list. Each argument is converted as
+ per to_json or to_jsonb.
+
+
+ json_build_array(1, 2, 'foo', 4, 5)
+ [1, 2, "foo", 4, 5]
+
+
+
+
+
+
+ json_build_object
+
+ json_build_object ( VARIADIC"any" )
+ json
+
+
+
+ jsonb_build_object
+
+ jsonb_build_object ( VARIADIC"any" )
+ jsonb
+
+
+ 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 to_json or to_jsonb.
+
+
+ json_build_object('foo', 1, 2, row(3,'bar'))
+ {"foo" : 1, "2" : {"f1":3,"f2":"bar"}}
+
+
+
+
+
+ json_object
+ json_object (
+ { key_expression { VALUE | ':' }
+ value_expressionFORMAT JSONENCODING UTF8 }, ...
+ { NULL | ABSENT } ON NULL
+ { WITH | WITHOUT } UNIQUEKEYS
+ RETURNINGdata_typeFORMAT JSONENCODING UTF8)
+
+
+ Constructs a JSON object of all the key/value pairs given,
+ or an empty object if none are given.
+ key_expression is a scalar expression
+ defining the JSON key, which is
+ converted to the text type.
+ It cannot be NULL nor can it
+ belong to a type that has a cast to the json type.
+ If WITH UNIQUE KEYS is specified, there must not
+ be any duplicate key_expression.
+ Any pair for which the value_expression
+ evaluates to NULL is omitted from the output
+ if ABSENT ON NULL is specified;
+ if NULL ON NULL is specified or the clause
+ omitted, the key is included with value NULL.
+
+
+ json_object('code' VALUE 'P123', 'title': 'Jaws')
+ {"code" : "P123", "title" : "Jaws"}
+
+
+
+
+
+
+ json_object
+
+ json_object ( text[] )
+ json
+
+
+
+ jsonb_object
+
+ jsonb_object ( text[] )
+ jsonb
+
+
+ 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.
+
+
+ json_object('{a, 1, b, "def", c, 3.5}')
+ {"a" : "1", "b" : "def", "c" : "3.5"}
+
+ json_object('{{a, 1}, {b, "def"}, {c, 3.5}}')
+ {"a" : "1", "b" : "def", "c" : "3.5"}
+
+
+
+
+
+ json_object ( keystext[], valuestext[] )
+ json
+
+
+ jsonb_object ( keystext[], valuestext[] )
+ jsonb
+
+
+ This form of json_object takes keys and values
+ pairwise from separate text arrays. Otherwise it is identical to
+ the one-argument form.
+
+
+ json_object('{a,b}', '{1,2}')
+ {"a": "1", "b": "2"}
+
+
+
+
+
+ json constructor
+ json (
+ expression
+ FORMAT JSONENCODING UTF8
+ { WITH | WITHOUT } UNIQUEKEYS )
+ json
+
+
+ Converts a given expression specified as text or
+ bytea string (in UTF8 encoding) into a JSON
+ value. If expression is NULL, an
+ SQL null value is returned.
+ If WITH UNIQUE is specified, the
+ expression must not contain any duplicate
+ object keys.
+
+
+ json('{"a":123, "b":[true,"foo"], "a":"bar"}')
+ {"a":123, "b":[true,"foo"], "a":"bar"}
+
+
+
+
+
+
+ json_scalar
+ json_scalar ( expression )
+
+
+ Converts a given SQL scalar value into a JSON scalar value.
+ If the input is NULL, an SQL null is returned. If
+ the input is number or a boolean value, a corresponding JSON number
+ or boolean value is returned. For any other value, a JSON string is
+ returned.
+
+
+ json_scalar(123.45)
+ 123.45
+
+
+ json_scalar(CURRENT_TIMESTAMP)
+ "2022-05-10T10:51:04.62128-04:00"
+
+
+
+
+
+ json_serialize (
+ expressionFORMAT JSONENCODING UTF8
+ RETURNINGdata_typeFORMAT JSONENCODING UTF8 )
+
+
+ Converts an SQL/JSON expression into a character or binary string. The
+ expression can be of any JSON type, any
+ character string type, or bytea in UTF8 encoding.
+ The returned type used in RETURNING can be any
+ character string type or bytea. The default is
+ text.
+
+
+ json_serialize('{ "a" : 1 } ' RETURNING bytea)
+ \x7b20226122203a2031207d20
+
+
+
+
+
+ SQL/JSON Testing Functions
+
+
+
+
+ Function signature
+
+
+ Description
+
+
+ Example(s)
+
+
+
+
+
+
+ IS JSON
+ expressionISNOTJSON
+ { VALUE | SCALAR | ARRAY | OBJECT }
+ { WITH | WITHOUT } UNIQUEKEYS
+
+
+ This predicate tests whether expression can be
+ parsed as JSON, possibly of a specified type.
+ If SCALAR or ARRAY or
+ OBJECT is specified, the
+ test is whether or not the JSON is of that particular type. If
+ WITH UNIQUE KEYS is specified, then any object in the
+ expression is also tested to see if it
+ has duplicate keys.
+
+
+
+SELECT js,
+ js IS JSON "json?",
+ js IS JSON SCALAR "scalar?",
+ js IS JSON OBJECT "object?",
+ js IS JSON ARRAY "array?"
+FROM (VALUES
+ ('123'), ('"abc"'), ('{"a": "b"}'), ('[1,2]'),('abc')) foo(js);
+ js | json? | scalar? | object? | array?
+------------+-------+---------+---------+--------
+ 123 | t | t | f | f
+ "abc" | t | t | f | f
+ {"a": "b"} | t | f | t | f
+ [1,2] | t | f | f | t
+ abc | f | f | f | f
+
+
+
+
+SELECT js,
+ js IS JSON OBJECT "object?",
+ js IS JSON ARRAY "array?",
+ js IS JSON ARRAY WITH UNIQUE KEYS "array w. UK?",
+ js IS JSON ARRAY WITHOUT UNIQUE KEYS "array w/o UK?"
+FROM (VALUES ('[{"a":"1"},
+ {"b":"2","b":"3"}]')) foo(js);
+-[ RECORD 1 ]-+--------------------
+js | [{"a":"1"}, +
+ | {"b":"2","b":"3"}]
+object? | f
+array? | t
+array w. UK? | f
+array w/o UK? | t
+
+
+
+
+
+
+
+
+ shows the functions that
+ are available for processing json and jsonb values.
+
+
+
+ JSON Processing Functions
+
+
+
+
+ Function
+
+
+ Description
+
+
+ Example(s)
+
+
+
+
+
+
+
+
+ json_array_elements
+
+ json_array_elements ( json )
+ setof json
+
+
+
+ jsonb_array_elements
+
+ jsonb_array_elements ( jsonb )
+ setof jsonb
+
+
+ Expands the top-level JSON array into a set of JSON values.
+
+
+ select * from json_array_elements('[1,true, [2,false]]')
+
+
+ value
+-----------
+ 1
+ true
+ [2,false]
+
+
+
+
+
+
+
+ json_array_elements_text
+
+ json_array_elements_text ( json )
+ setof text
+
+
+
+ jsonb_array_elements_text
+
+ jsonb_array_elements_text ( jsonb )
+ setof text
+
+
+ Expands the top-level JSON array into a set of text values.
+
+
+ select * from json_array_elements_text('["foo", "bar"]')
+
+
+ value
+-----------
+ foo
+ bar
+
+
+
+
+
+
+
+ json_array_length
+
+ json_array_length ( json )
+ integer
+
+
+
+ jsonb_array_length
+
+ jsonb_array_length ( jsonb )
+ integer
+
+
+ Returns the number of elements in the top-level JSON array.
+
+
+ json_array_length('[1,2,3,{"f1":1,"f2":[5,6]},4]')
+ 5
+
+
+ jsonb_array_length('[]')
+ 0
+
+
+
+
+
+
+ json_each
+
+ json_each ( json )
+ setof record
+ ( keytext,
+ valuejson )
+
+
+
+ jsonb_each
+
+ jsonb_each ( jsonb )
+ setof record
+ ( keytext,
+ valuejsonb )
+
+
+ Expands the top-level JSON object into a set of key/value pairs.
+
+
+ select * from json_each('{"a":"foo", "b":"bar"}')
+
+
+ key | value
+-----+-------
+ a | "foo"
+ b | "bar"
+
+
+
+
+
+
+
+ json_each_text
+
+ json_each_text ( json )
+ setof record
+ ( keytext,
+ valuetext )
+
+
+
+ jsonb_each_text
+
+ jsonb_each_text ( jsonb )
+ setof record
+ ( keytext,
+ valuetext )
+
+
+ Expands the top-level JSON object into a set of key/value pairs.
+ The returned values will be of
+ type text.
+
+
+ select * from json_each_text('{"a":"foo", "b":"bar"}')
+
+
+ key | value
+-----+-------
+ a | foo
+ b | bar
+
+
+
+
+
+
+
+ json_extract_path
+
+ json_extract_path ( from_jsonjson, VARIADICpath_elemstext[] )
+ json
+
+
+
+ jsonb_extract_path
+
+ jsonb_extract_path ( from_jsonjsonb, VARIADICpath_elemstext[] )
+ jsonb
+
+
+ Extracts JSON sub-object at the specified path.
+ (This is functionally equivalent to the #>
+ operator, but writing the path out as a variadic list can be more
+ convenient in some cases.)
+
+
+ json_extract_path('{"f2":{"f3":1},"f4":{"f5":99,"f6":"foo"}}', 'f4', 'f6')
+ "foo"
+
+
+
+
+
+
+ json_extract_path_text
+
+ json_extract_path_text ( from_jsonjson, VARIADICpath_elemstext[] )
+ text
+
+
+
+ jsonb_extract_path_text
+
+ jsonb_extract_path_text ( from_jsonjsonb, VARIADICpath_elemstext[] )
+ text
+
+
+ Extracts JSON sub-object at the specified path as text.
+ (This is functionally equivalent to the #>>
+ operator.)
+
+
+ json_extract_path_text('{"f2":{"f3":1},"f4":{"f5":99,"f6":"foo"}}', 'f4', 'f6')
+ foo
+
+
+
+
+
+
+ json_object_keys
+
+ json_object_keys ( json )
+ setof text
+
+
+
+ jsonb_object_keys
+
+ jsonb_object_keys ( jsonb )
+ setof text
+
+
+ Returns the set of keys in the top-level JSON object.
+
+
+ select * from json_object_keys('{"f1":"abc","f2":{"f3":"a", "f4":"b"}}')
+
+
+ json_object_keys
+------------------
+ f1
+ f2
+
+
+
+
+
+
+
+ json_populate_record
+
+ json_populate_record ( baseanyelement, from_jsonjson )
+ anyelement
+
+
+
+ jsonb_populate_record
+
+ jsonb_populate_record ( baseanyelement, from_jsonjsonb )
+ anyelement
+
+
+ Expands the top-level JSON object to a row having the composite type
+ of the base 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 base is just
+ NULL, which means that any output columns that do
+ not match any object field will be filled with nulls. However,
+ if base isn't NULL then
+ the values it contains will be used for unmatched columns.
+
+
+ To convert a JSON value to the SQL type of an output column, the
+ following rules are applied in sequence:
+
+
+
+ A JSON null value is converted to an SQL null in all cases.
+
+
+
+
+ If the output column is of type json
+ or jsonb, the JSON value is just reproduced exactly.
+
+
+
+
+ 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.
+
+
+
+
+ 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.
+
+
+
+
+ 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.
+
+
+
+
+ Otherwise, the ordinary text representation of the JSON value is
+ fed to the input conversion function for the column's data type.
+
+
+
+
+
+ While the example below uses a constant JSON value, typical use would
+ be to reference a json or jsonb column
+ laterally from another table in the query's FROM
+ clause. Writing json_populate_record in
+ the FROM clause is good practice, since all of the
+ extracted columns are available for use without duplicate function
+ calls.
+
+
+ create type subrowtype as (d int, e text);
+ create type myrowtype as (a int, b text[], c subrowtype);
+
+
+ select * from json_populate_record(null::myrowtype,
+ '{"a": 1, "b": ["2", "a b"], "c": {"d": 4, "e": "a b c"}, "x": "foo"}')
+
+
+ a | b | c
+---+-----------+-------------
+ 1 | {2,"a b"} | (4,"a b c")
+
+
+
+
+
+
+
+ jsonb_populate_record_valid
+
+ jsonb_populate_record_valid ( baseanyelement, from_jsonjson )
+ boolean
+
+
+ Function for testing jsonb_populate_record. Returns
+ true if the input jsonb_populate_record
+ would finish without an error for the given input JSON object; that is, it's
+ valid input, false otherwise.
+
+
+ create type jsb_char2 as (a char(2));
+
+
+ select jsonb_populate_record_valid(NULL::jsb_char2, '{"a": "aaa"}');
+
+
+ jsonb_populate_record_valid
+-----------------------------
+ f
+(1 row)
+
+
+ select * from jsonb_populate_record(NULL::jsb_char2, '{"a": "aaa"}') q;
+
+
+ERROR: value too long for type character(2)
+
+ select jsonb_populate_record_valid(NULL::jsb_char2, '{"a": "aa"}');
+
+
+ jsonb_populate_record_valid
+-----------------------------
+ t
+(1 row)
+
+
+ select * from jsonb_populate_record(NULL::jsb_char2, '{"a": "aa"}') q;
+
+
+ a
+----
+ aa
+(1 row)
+
+
+
+
+
+
+
+ json_populate_recordset
+
+ json_populate_recordset ( baseanyelement, from_jsonjson )
+ setof anyelement
+
+
+
+ jsonb_populate_recordset
+
+ jsonb_populate_recordset ( baseanyelement, from_jsonjsonb )
+ setof anyelement
+
+
+ Expands the top-level JSON array of objects to a set of rows having
+ the composite type of the base argument.
+ Each element of the JSON array is processed as described above
+ for json[b]_populate_record.
+
+
+ create type twoints as (a int, b int);
+
+
+ select * from json_populate_recordset(null::twoints, '[{"a":1,"b":2}, {"a":3,"b":4}]')
+
+
+ a | b
+---+---
+ 1 | 2
+ 3 | 4
+
+
+
+
+
+
+
+ json_to_record
+
+ json_to_record ( json )
+ record
+
+
+
+ jsonb_to_record
+
+ jsonb_to_record ( jsonb )
+ record
+
+
+ Expands the top-level JSON object to a row having the composite type
+ defined by an AS clause. (As with all functions
+ returning record, the calling query must explicitly
+ define the structure of the record with an AS
+ clause.) The output record is filled from fields of the JSON object,
+ in the same way as described above
+ for json[b]_populate_record. Since there is no
+ input record value, unmatched columns are always filled with nulls.
+
+
+ create type myrowtype as (a int, b text);
+
+
+ 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)
+
+
+ a | b | c | d | r
+---+---------+---------+---+---------------
+ 1 | [1,2,3] | {1,2,3} | | (123,"a b c")
+
+
+
+
+
+
+
+ json_to_recordset
+
+ json_to_recordset ( json )
+ setof record
+
+
+
+ jsonb_to_recordset
+
+ jsonb_to_recordset ( jsonb )
+ setof record
+
+
+ Expands the top-level JSON array of objects to a set of rows having
+ the composite type defined by an AS clause. (As
+ with all functions returning record, the calling query
+ must explicitly define the structure of the record with
+ an AS clause.) Each element of the JSON array is
+ processed as described above
+ for json[b]_populate_record.
+
+
+ select * from json_to_recordset('[{"a":1,"b":"foo"}, {"a":"2","c":"bar"}]') as x(a int, b text)
+
+
+ a | b
+---+-----
+ 1 | foo
+ 2 |
+
+
+
+
+
+
+
+ jsonb_set
+
+ jsonb_set ( targetjsonb, pathtext[], new_valuejsonb, create_if_missingboolean )
+ jsonb
+
+
+ Returns target
+ with the item designated by path
+ replaced by new_value, or with
+ new_value added if
+ create_if_missing is true (which is the
+ default) and the item designated by path
+ does not exist.
+ All earlier steps in the path must exist, or
+ the target is returned unchanged.
+ As with the path oriented operators, negative integers that
+ appear in the path count from the end
+ of JSON arrays.
+ If the last path step is an array index that is out of range,
+ and create_if_missing 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.
+
+
+ jsonb_set('[{"f1":1,"f2":null},2,null,3]', '{0,f1}', '[2,3,4]', false)
+ [{"f1": [2, 3, 4], "f2": null}, 2, null, 3]
+
+
+ jsonb_set('[{"f1":1,"f2":null},2]', '{0,f3}', '[2,3,4]')
+ [{"f1": 1, "f2": null, "f3": [2, 3, 4]}, 2]
+
+
+
+
+
+
+ jsonb_set_lax
+
+ jsonb_set_lax ( targetjsonb, pathtext[], new_valuejsonb, create_if_missingboolean, null_value_treatmenttext )
+ jsonb
+
+
+ If new_value is not NULL,
+ behaves identically to jsonb_set. Otherwise behaves
+ according to the value
+ of null_value_treatment which must be one
+ of 'raise_exception',
+ 'use_json_null', 'delete_key', or
+ 'return_target'. The default is
+ 'use_json_null'.
+
+
+ jsonb_set_lax('[{"f1":1,"f2":null},2,null,3]', '{0,f1}', null)
+ [{"f1": null, "f2": null}, 2, null, 3]
+
+
+ jsonb_set_lax('[{"f1":99,"f2":null},2]', '{0,f3}', null, true, 'return_target')
+ [{"f1": 99, "f2": null}, 2]
+
+
+
+
+
+
+ jsonb_insert
+
+ jsonb_insert ( targetjsonb, pathtext[], new_valuejsonb, insert_afterboolean )
+ jsonb
+
+
+ Returns target
+ with new_value inserted. If the item
+ designated by the path is an array
+ element, new_value will be inserted before
+ that item if insert_after is false (which
+ is the default), or after it
+ if insert_after is true. If the item
+ designated by the path is an object
+ field, new_value will be inserted only if
+ the object does not already contain that key.
+ All earlier steps in the path must exist, or
+ the target is returned unchanged.
+ As with the path oriented operators, negative integers that
+ appear in the path 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.
+
+
+ jsonb_insert('{"a": [0,1,2]}', '{a, 1}', '"new_value"')
+ {"a": [0, "new_value", 1, 2]}
+
+
+ jsonb_insert('{"a": [0,1,2]}', '{a, 1}', '"new_value"', true)
+ {"a": [0, 1, "new_value", 2]}
+
+
+
+
+
+
+ json_strip_nulls
+
+ json_strip_nulls ( targetjson,strip_in_arraysboolean )
+ json
+
+
+
+ jsonb_strip_nulls
+
+ jsonb_strip_nulls ( targetjsonb,strip_in_arraysboolean )
+ jsonb
+
+
+ Deletes all object fields that have null values from the given JSON
+ value, recursively.
+ If strip_in_arrays is true (the default is false),
+ null array elements are also stripped.
+ Otherwise they are not stripped. Bare null values are never stripped.
+
+
+ json_strip_nulls('[{"f1":1, "f2":null}, 2, null, 3]')
+ [{"f1":1},2,null,3]
+
+
+ jsonb_strip_nulls('[1,2,null,3,4]', true);
+ [1,2,3,4]
+
+
+
+
+
+
+
+ jsonb_path_exists
+
+ jsonb_path_exists ( targetjsonb, pathjsonpath, varsjsonb, silentboolean )
+ boolean
+
+
+ Checks whether the JSON path returns any item for the specified JSON
+ value.
+ (This is useful only with SQL-standard JSON path expressions, not
+ predicate check
+ expressions, since those always return a value.)
+ If the vars argument is specified, it must
+ be a JSON object, and its fields provide named values to be
+ substituted into the jsonpath expression.
+ If the silent argument is specified and
+ is true, the function suppresses the same errors
+ as the @? and @@ operators do.
+
+
+ jsonb_path_exists('{"a":[1,2,3,4,5]}', '$.a[*] ? (@ >= $min && @ <= $max)', '{"min":2, "max":4}')
+ t
+
+
+
+
+
+
+ jsonb_path_match
+
+ jsonb_path_match ( targetjsonb, pathjsonpath, varsjsonb, silentboolean )
+ boolean
+
+
+ Returns the SQL boolean result of a JSON path predicate check
+ for the specified JSON value.
+ (This is useful only
+ with predicate
+ check expressions, not SQL-standard JSON path expressions,
+ since it will either fail or return NULL if the
+ path result is not a single boolean value.)
+ The optional vars
+ and silent arguments act the same as
+ for jsonb_path_exists.
+
+
+ jsonb_path_match('{"a":[1,2,3,4,5]}', 'exists($.a[*] ? (@ >= $min && @ <= $max))', '{"min":2, "max":4}')
+ t
+
+
+
+
+
+
+ jsonb_path_query
+
+ jsonb_path_query ( targetjsonb, pathjsonpath, varsjsonb, silentboolean )
+ setof jsonb
+
+
+ Returns all JSON items returned by the JSON path for the specified
+ JSON value.
+ For SQL-standard JSON path expressions it returns the JSON
+ values selected from target.
+ For predicate
+ check expressions it returns the result of the predicate
+ check: true, false,
+ or null.
+ The optional vars
+ and silent arguments act the same as
+ for jsonb_path_exists.
+
+
+ select * from jsonb_path_query('{"a":[1,2,3,4,5]}', '$.a[*] ? (@ >= $min && @ <= $max)', '{"min":2, "max":4}')
+
+
+ jsonb_path_query
+------------------
+ 2
+ 3
+ 4
+
+
+
+
+
+
+
+ jsonb_path_query_array
+
+ jsonb_path_query_array ( targetjsonb, pathjsonpath, varsjsonb, silentboolean )
+ jsonb
+
+
+ Returns all JSON items returned by the JSON path for the specified
+ JSON value, as a JSON array.
+ The parameters are the same as
+ for jsonb_path_query.
+
+
+ jsonb_path_query_array('{"a":[1,2,3,4,5]}', '$.a[*] ? (@ >= $min && @ <= $max)', '{"min":2, "max":4}')
+ [2, 3, 4]
+
+
+
+
+
+
+ jsonb_path_query_first
+
+ jsonb_path_query_first ( targetjsonb, pathjsonpath, varsjsonb, silentboolean )
+ jsonb
+
+
+ Returns the first JSON item returned by the JSON path for the
+ specified JSON value, or NULL if there are no
+ results.
+ The parameters are the same as
+ for jsonb_path_query.
+
+
+ jsonb_path_query_first('{"a":[1,2,3,4,5]}', '$.a[*] ? (@ >= $min && @ <= $max)', '{"min":2, "max":4}')
+ 2
+
+
+
+
+
+
+ jsonb_path_exists_tz
+
+ jsonb_path_exists_tz ( targetjsonb, pathjsonpath, varsjsonb, silentboolean )
+ boolean
+
+
+
+ jsonb_path_match_tz
+
+ jsonb_path_match_tz ( targetjsonb, pathjsonpath, varsjsonb, silentboolean )
+ boolean
+
+
+
+ jsonb_path_query_tz
+
+ jsonb_path_query_tz ( targetjsonb, pathjsonpath, varsjsonb, silentboolean )
+ setof jsonb
+
+
+
+ jsonb_path_query_array_tz
+
+ jsonb_path_query_array_tz ( targetjsonb, pathjsonpath, varsjsonb, silentboolean )
+ jsonb
+
+
+
+ jsonb_path_query_first_tz
+
+ jsonb_path_query_first_tz ( targetjsonb, pathjsonpath, varsjsonb, silentboolean )
+ jsonb
+
+
+ These functions act like their counterparts described above without
+ the _tz 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 2015-08-02 as a timestamp with time
+ zone, so the result depends on the current
+ 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.
+
+
+ jsonb_path_exists_tz('["2015-08-01 12:00:00-05"]', '$[*] ? (@.datetime() < "2015-08-02".datetime())')
+ t
+
+
+
+
+
+
+ jsonb_pretty
+
+ jsonb_pretty ( jsonb )
+ text
+
+
+ Converts the given JSON value to pretty-printed, indented text.
+
+
+ jsonb_pretty('[{"f1":1,"f2":null}, 2]')
+
+
+[
+ {
+ "f1": 1,
+ "f2": null
+ },
+ 2
+]
+
+
+
+
+
+
+
+ json_typeof
+
+ json_typeof ( json )
+ text
+
+
+
+ jsonb_typeof
+
+ jsonb_typeof ( jsonb )
+ text
+
+
+ Returns the type of the top-level JSON value as a text string.
+ Possible types are
+ object, array,
+ string, number,
+ boolean, and null.
+ (The null result should not be confused
+ with an SQL NULL; see the examples.)
+
+
+ json_typeof('-123.4')
+ number
+
+
+ json_typeof('null'::json)
+ null
+
+
+ json_typeof(NULL::json) IS NULL
+ t
+
+
+
+
+
+
+
+
+ The SQL/JSON Path Language
+
+
+ SQL/JSON path language
+
+
+
+ SQL/JSON path expressions specify item(s) to be retrieved
+ from a JSON value, similarly to XPath expressions used
+ for access to XML content. In PostgreSQL,
+ path expressions are implemented as the jsonpath
+ data type and can use any elements described in
+ .
+
+
+
+ JSON query functions and operators
+ pass the provided path expression to the path engine
+ for evaluation. If the expression matches the queried JSON data,
+ the corresponding JSON item, or set of items, is returned.
+ If there is no match, the result will be NULL,
+ false, or an error, depending on the function.
+ Path expressions are written in the SQL/JSON path language
+ and can include arithmetic expressions and functions.
+
+
+
+ A path expression consists of a sequence of elements allowed
+ by the jsonpath 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.
+
+
+
+ To refer to the JSON value being queried (the
+ context item), use the $ variable
+ in the path expression. The first element of a path must always
+ be $. It can be followed by one or more
+ accessor operators,
+ which go down the JSON structure level by level to retrieve sub-items
+ of the context item. Each accessor operator acts on the
+ result(s) of the previous evaluation step, producing zero, one, or more
+ output items from each input item.
+
+
+
+ For example, suppose you have some JSON data from a GPS tracker that you
+ would like to parse, such as:
+
+SELECT '{
+ "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
+ }
+ ]
+ }
+}' AS json \gset
+
+ (The above example can be copied-and-pasted
+ into psql to set things up for the following
+ examples. Then psql will
+ expand :'json' into a suitably-quoted string
+ constant containing the JSON value.)
+
+
+
+ To retrieve the available track segments, you need to use the
+ .key accessor
+ operator to descend through surrounding JSON objects, for example:
+
+=>select jsonb_path_query(:'json', '$.track.segments');
+ jsonb_path_query
+-----------------------------------------------------------&zwsp;-----------------------------------------------------------&zwsp;---------------------------------------------
+ [{"HR": 73, "location": [47.763, 13.4034], "start time": "2018-10-14 10:05:14"}, {"HR": 135, "location": [47.706, 13.2635], "start time": "2018-10-14 10:39:21"}]
+
+
+
+
+ To retrieve the contents of an array, you typically use the
+ [*] operator.
+ The following example will return the location coordinates for all
+ the available track segments:
+
+=>select jsonb_path_query(:'json', '$.track.segments[*].location');
+ jsonb_path_query
+-------------------
+ [47.763, 13.4034]
+ [47.706, 13.2635]
+
+ Here we started with the whole JSON input value ($),
+ then the .track accessor selected the JSON object
+ associated with the "track" object key, then
+ the .segments accessor selected the JSON array
+ associated with the "segments" key within that
+ object, then the [*] accessor selected each element
+ of that array (producing a series of items), then
+ the .location accessor selected the JSON array
+ associated with the "location" key within each of
+ those objects. In this example, each of those objects had
+ a "location" key; but if any of them did not,
+ the .location accessor would have simply produced no
+ output for that input item.
+
+
+
+ To return the coordinates of the first segment only, you can
+ specify the corresponding subscript in the []
+ accessor operator. Recall that JSON array indexes are 0-relative:
+
+=>select jsonb_path_query(:'json', '$.track.segments[0].location');
+ jsonb_path_query
+-------------------
+ [47.763, 13.4034]
+
+
+
+
+ The result of each path evaluation step can be processed
+ by one or more of the jsonpath operators and methods
+ listed in .
+ Each method name must be preceded by a dot. For example,
+ you can get the size of an array:
+
+=>select jsonb_path_query(:'json', '$.track.segments.size()');
+ jsonb_path_query
+------------------
+ 2
+
+ More examples of using jsonpath operators
+ and methods within path expressions appear below in
+ .
+
+
+
+ A path can also contain
+ filter expressions that work similarly to the
+ WHERE clause in SQL. A filter expression begins with
+ a question mark and provides a condition in parentheses:
+
+
+? (condition)
+
+
+
+
+ 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
+ produce true, false,
+ or unknown. The unknown value
+ plays the same role as SQL NULL and can be tested
+ for with the is unknown predicate. Further path
+ evaluation steps use only those items for which the filter expression
+ returned true.
+
+
+
+ The functions and operators that can be used in filter expressions are
+ listed in . Within a
+ filter expression, the @ variable denotes the value
+ being considered (i.e., one result of the preceding path step). You can
+ write accessor operators after @ to retrieve component
+ items.
+
+
+
+ For example, suppose you would like to retrieve all heart rate values higher
+ than 130. You can achieve this as follows:
+
+=>select jsonb_path_query(:'json', '$.track.segments[*].HR ? (@ > 130)');
+ jsonb_path_query
+------------------
+ 135
+
+
+
+
+ To get the start times of segments with such values, you have to
+ filter out irrelevant segments before selecting the start times, so the
+ filter expression is applied to the previous step, and the path used
+ in the condition is different:
+
+=>select jsonb_path_query(:'json', '$.track.segments[*] ? (@.HR > 130)."start time"');
+ jsonb_path_query
+-----------------------
+ "2018-10-14 10:39:21"
+
+
+
+
+ You can use several filter expressions in sequence, if required.
+ The following example selects start times of all segments that
+ contain locations with relevant coordinates and high heart rate values:
+
+=>select jsonb_path_query(:'json', '$.track.segments[*] ? (@.location[1] < 13.4) ? (@.HR > 130)."start time"');
+ jsonb_path_query
+-----------------------
+ "2018-10-14 10:39:21"
+
+
+
+
+ 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:
+
+=>select jsonb_path_query(:'json', '$.track.segments[*] ? (@.location[1] < 13.4).HR ? (@ > 130)');
+ jsonb_path_query
+------------------
+ 135
+
+
+
+
+ You can also nest filter expressions within each other.
+ This example returns the size of the track if it contains any
+ segments with high heart rate values, or an empty sequence otherwise:
+
+=>select jsonb_path_query(:'json', '$.track ? (exists(@.segments[*] ? (@.HR > 130))).segments.size()');
+ jsonb_path_query
+------------------
+ 2
+
+
+
+
+ Deviations from the SQL Standard
+
+ PostgreSQL's implementation of the SQL/JSON path
+ language has the following deviations from the SQL/JSON standard.
+
+
+
+ Boolean Predicate Check Expressions
+
+ As an extension to the SQL standard,
+ a PostgreSQL path expression can be a
+ Boolean predicate, whereas the SQL standard allows predicates only within
+ filters. While SQL-standard path expressions return the relevant
+ element(s) of the queried JSON value, predicate check expressions
+ return the single three-valued jsonb result of the
+ predicate: true,
+ false, or null.
+ For example, we could write this SQL-standard filter expression:
+
+=>select jsonb_path_query(:'json', '$.track.segments ?(@[*].HR > 130)');
+ jsonb_path_query
+-----------------------------------------------------------&zwsp;----------------------
+ {"HR": 135, "location": [47.706, 13.2635], "start time": "2018-10-14 10:39:21"}
+
+ The similar predicate check expression simply
+ returns true, indicating that a match exists:
+
+=>select jsonb_path_query(:'json', '$.track.segments[*].HR > 130');
+ jsonb_path_query
+------------------
+ true
+
+
+
+
+
+ Predicate check expressions are required in the
+ @@ operator (and the
+ jsonb_path_match function), and should not be used
+ with the @? operator (or the
+ jsonb_path_exists function).
+
+
+
+
+
+ Regular Expression Interpretation
+
+ There are minor differences in the interpretation of regular
+ expression patterns used in like_regex filters, as
+ described in .
+
+
+
+
+
+ Strict and Lax Modes
+
+ 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 is defined as a
+ structural error. SQL/JSON path expressions have two modes
+ of handling structural errors:
+
+
+
+
+
+ lax (default) — the path engine implicitly adapts
+ the queried data to the specified path.
+ Any structural errors that cannot be fixed as described below
+ are suppressed, producing no match.
+
+
+
+
+ strict — if a structural error occurs, an error is raised.
+
+
+
+
+
+ Lax mode facilitates matching of a JSON document and path
+ expression when 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
+ the operation. Also, comparison operators automatically unwrap their
+ operands in 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 when:
+
+
+
+ The path expression contains type() or
+ size() methods that return the type
+ and the number of elements in the array, respectively.
+
+
+
+
+ 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.
+
+
+
+
+
+
+ For example, when querying the GPS data listed above, you can
+ abstract from the fact that it stores an array of segments
+ when using lax mode:
+
+=>select jsonb_path_query(:'json', 'lax $.track.segments.location');
+ jsonb_path_query
+-------------------
+ [47.763, 13.4034]
+ [47.706, 13.2635]
+
+
+
+
+ In strict mode, the specified path must exactly match the structure of
+ the queried JSON document, so using this path
+ expression will cause an error:
+
+=>select jsonb_path_query(:'json', 'strict $.track.segments.location');
+ERROR: jsonpath member accessor can only be applied to an object
+
+ To get the same result as in lax mode, you have to explicitly unwrap the
+ segments array:
+
+=>select jsonb_path_query(:'json', 'strict $.track.segments[*].location');
+ jsonb_path_query
+-------------------
+ [47.763, 13.4034]
+ [47.706, 13.2635]
+
+
+
+
+ The unwrapping behavior of lax mode can lead to surprising results. For
+ instance, the following query using the .** accessor
+ selects every HR value twice:
+
+=>select jsonb_path_query(:'json', 'lax $.**.HR');
+ jsonb_path_query
+------------------
+ 73
+ 135
+ 73
+ 135
+
+ This happens because the .** accessor selects both
+ the segments array and each of its elements, while
+ the .HR accessor automatically unwraps arrays when
+ using lax mode. To avoid surprising results, we recommend using
+ the .** accessor only in strict mode. The
+ following query selects each HR value just once:
+
+=>select jsonb_path_query(:'json', 'strict $.**.HR');
+ jsonb_path_query
+------------------
+ 73
+ 135
+
+
+
+
+ The unwrapping of arrays can also lead to unexpected results. Consider this
+ example, which selects all the location arrays:
+
+=>select jsonb_path_query(:'json', 'lax $.track.segments[*].location');
+ jsonb_path_query
+-------------------
+ [47.763, 13.4034]
+ [47.706, 13.2635]
+(2 rows)
+
+ As expected it returns the full arrays. But applying a filter expression
+ causes the arrays to be unwrapped to evaluate each item, returning only the
+ items that match the expression:
+
+=>select jsonb_path_query(:'json', 'lax $.track.segments[*].location ?(@[*] > 15)');
+ jsonb_path_query
+------------------
+ 47.763
+ 47.706
+(2 rows)
+
+ This despite the fact that the full arrays are selected by the path
+ expression. Use strict mode to restore selecting the arrays:
+
+=>select jsonb_path_query(:'json', 'strict $.track.segments[*].location ?(@[*] > 15)');
+ jsonb_path_query
+-------------------
+ [47.763, 13.4034]
+ [47.706, 13.2635]
+(2 rows)
+
+
+
+
+
+ SQL/JSON Path Operators and Methods
+
+
+ shows the operators and
+ methods available in jsonpath. 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. In lax mode, methods applied to an array will be
+ executed for each value in the array. The exceptions are
+ .type() and .size(), which apply to
+ the array itself.
+
+
+
+ <type>jsonpath</type> Operators and Methods
+
+
+
+
+ Operator/Method
+
+
+ Description
+
+
+ Example(s)
+
+
+
+
+
+
+
+ number+number
+ number
+
+
+ Addition
+
+
+ jsonb_path_query('[2]', '$[0] + 3')
+ 5
+
+
+
+
+
+ +number
+ number
+
+
+ Unary plus (no operation); unlike addition, this can iterate over
+ multiple values
+
+
+ jsonb_path_query_array('{"x": [2,3,4]}', '+ $.x')
+ [2, 3, 4]
+
+
+
+
+
+ number-number
+ number
+
+
+ Subtraction
+
+
+ jsonb_path_query('[2]', '7 - $[0]')
+ 5
+
+
+
+
+
+ -number
+ number
+
+
+ Negation; unlike subtraction, this can iterate over
+ multiple values
+
+
+ jsonb_path_query_array('{"x": [2,3,4]}', '- $.x')
+ [-2, -3, -4]
+
+
+
+
+
+ number*number
+ number
+
+
+ Multiplication
+
+
+ jsonb_path_query('[4]', '2 * $[0]')
+ 8
+
+
+
+
+
+ number/number
+ number
+
+
+ Division
+
+
+ jsonb_path_query('[8.5]', '$[0] / 2')
+ 4.2500000000000000
+
+
+
+
+
+ number%number
+ number
+
+
+ Modulo (remainder)
+
+
+ jsonb_path_query('[32]', '$[0] % 10')
+ 2
+
+
+
+
+
+ value.type()
+ string
+
+
+ Type of the JSON item (see json_typeof)
+
+
+ jsonb_path_query_array('[1, "2", {}]', '$[*].type()')
+ ["number", "string", "object"]
+
+
+
+
+
+ value.size()
+ number
+
+
+ Size of the JSON item (number of array elements, or 1 if not an
+ array)
+
+
+ jsonb_path_query('{"m": [11, 15]}', '$.m.size()')
+ 2
+
+
+
+
+
+ value.boolean()
+ boolean
+
+
+ Boolean value converted from a JSON boolean, number, or string
+
+
+ jsonb_path_query_array('[1, "yes", false]', '$[*].boolean()')
+ [true, true, false]
+
+
+
+
+
+ value.string()
+ string
+
+
+ String value converted from a JSON boolean, number, string, or
+ datetime
+
+
+ jsonb_path_query_array('[1.23, "xyz", false]', '$[*].string()')
+ ["1.23", "xyz", "false"]
+
+
+ jsonb_path_query('"2023-08-15 12:34:56"', '$.timestamp().string()')
+ "2023-08-15T12:34:56"
+
+
+
+
+
+ value.double()
+ number
+
+
+ Approximate floating-point number converted from a JSON number or
+ string
+
+
+ jsonb_path_query('{"len": "1.9"}', '$.len.double() * 2')
+ 3.8
+
+
+
+
+
+ number.ceiling()
+ number
+
+
+ Nearest integer greater than or equal to the given number
+
+
+ jsonb_path_query('{"h": 1.3}', '$.h.ceiling()')
+ 2
+
+
+
+
+
+ number.floor()
+ number
+
+
+ Nearest integer less than or equal to the given number
+
+
+ jsonb_path_query('{"h": 1.7}', '$.h.floor()')
+ 1
+
+
+
+
+
+ number.abs()
+ number
+
+
+ Absolute value of the given number
+
+
+ jsonb_path_query('{"z": -0.3}', '$.z.abs()')
+ 0.3
+
+
+
+
+
+ value.bigint()
+ bigint
+
+
+ Big integer value converted from a JSON number or string
+
+
+ jsonb_path_query('{"len": "9876543219"}', '$.len.bigint()')
+ 9876543219
+
+
+
+
+
+ value.decimal( [ precision [ , scale ] ] )
+ decimal
+
+
+ Rounded decimal value converted from a JSON number or string
+ (precision and scale must be
+ integer values)
+
+
+ jsonb_path_query('1234.5678', '$.decimal(6, 2)')
+ 1234.57
+
+
+
+
+
+ value.integer()
+ integer
+
+
+ Integer value converted from a JSON number or string
+
+
+ jsonb_path_query('{"len": "12345"}', '$.len.integer()')
+ 12345
+
+
+
+
+
+ value.number()
+ numeric
+
+
+ Numeric value converted from a JSON number or string
+
+
+ jsonb_path_query('{"len": "123.45"}', '$.len.number()')
+ 123.45
+
+
+
+
+
+ string.datetime()
+ datetime_type
+ (see note)
+
+
+ Date/time value converted from a string
+
+
+ jsonb_path_query('["2015-8-1", "2015-08-12"]', '$[*] ? (@.datetime() < "2015-08-2".datetime())')
+ "2015-8-1"
+
+
+
+
+
+ string.datetime(template)
+ datetime_type
+ (see note)
+
+
+ Date/time value converted from a string using the
+ specified to_timestamp template
+
+
+ jsonb_path_query_array('["12:30", "18:40"]', '$[*].datetime("HH24:MI")')
+ ["12:30:00", "18:40:00"]
+
+
+
+
+
+ string.date()
+ date
+
+
+ Date value converted from a string
+
+
+ jsonb_path_query('"2023-08-15"', '$.date()')
+ "2023-08-15"
+
+
+
+
+
+ string.time()
+ time without time zone
+
+
+ Time without time zone value converted from a string
+
+
+ jsonb_path_query('"12:34:56"', '$.time()')
+ "12:34:56"
+
+
+
+
+
+ string.time(precision)
+ time without time zone
+
+
+ Time without time zone value converted from a string, with fractional
+ seconds adjusted to the given precision
+
+
+ jsonb_path_query('"12:34:56.789"', '$.time(2)')
+ "12:34:56.79"
+
+
+
+
+
+ string.time_tz()
+ time with time zone
+
+
+ Time with time zone value converted from a string
+
+
+ jsonb_path_query('"12:34:56 +05:30"', '$.time_tz()')
+ "12:34:56+05:30"
+
+
+
+
+
+ string.time_tz(precision)
+ time with time zone
+
+
+ Time with time zone value converted from a string, with fractional
+ seconds adjusted to the given precision
+
+
+ jsonb_path_query('"12:34:56.789 +05:30"', '$.time_tz(2)')
+ "12:34:56.79+05:30"
+
+
+
+
+
+ string.timestamp()
+ timestamp without time zone
+
+
+ Timestamp without time zone value converted from a string
+
+
+ jsonb_path_query('"2023-08-15 12:34:56"', '$.timestamp()')
+ "2023-08-15T12:34:56"
+
+
+
+
+
+ string.timestamp(precision)
+ timestamp without time zone
+
+
+ Timestamp without time zone value converted from a string, with
+ fractional seconds adjusted to the given precision
+
+
+ jsonb_path_query('"2023-08-15 12:34:56.789"', '$.timestamp(2)')
+ "2023-08-15T12:34:56.79"
+
+
+
+
+
+ string.timestamp_tz()
+ timestamp with time zone
+
+
+ Timestamp with time zone value converted from a string
+
+
+ jsonb_path_query('"2023-08-15 12:34:56 +05:30"', '$.timestamp_tz()')
+ "2023-08-15T12:34:56+05:30"
+
+
+
+
+
+ string.timestamp_tz(precision)
+ timestamp with time zone
+
+
+ Timestamp with time zone value converted from a string, with fractional
+ seconds adjusted to the given precision
+
+
+ jsonb_path_query('"2023-08-15 12:34:56.789 +05:30"', '$.timestamp_tz(2)')
+ "2023-08-15T12:34:56.79+05:30"
+
+
+
+
+
+ object.keyvalue()
+ array
+
+
+ The object's key-value pairs, represented as an array of objects
+ containing three fields: "key",
+ "value", and "id";
+ "id" is a unique identifier of the object the
+ key-value pair belongs to
+
+
+ jsonb_path_query_array('{"x": "20", "y": 32}', '$.keyvalue()')
+ [{"id": 0, "key": "x", "value": "20"}, {"id": 0, "key": "y", "value": 32}]
+
+
+
+
+
+
+
+
+ The result type of the datetime() and
+ datetime(template)
+ methods can be date, timetz, time,
+ timestamptz, or timestamp.
+ Both methods determine their result type dynamically.
+
+
+ The datetime() method sequentially tries to
+ match its input string to the ISO formats
+ for date, timetz, time,
+ timestamptz, and timestamp. It stops on
+ the first matching format and emits the corresponding data type.
+
+
+ The datetime(template)
+ method determines the result type according to the fields used in the
+ provided template string.
+
+
+ The datetime() and
+ datetime(template) methods
+ use the same parsing rules as the to_timestamp SQL
+ function does (see ), 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.
+
+
+ If different date/time types need to be compared, an implicit cast is
+ applied. A date value can be cast to timestamp
+ or timestamptz, timestamp can be cast to
+ timestamptz, and time to timetz.
+ However, all but the first of these conversions depend on the current
+ setting, and thus can only be performed
+ within timezone-aware jsonpath functions. Similarly, other
+ date/time-related methods that convert strings to date/time types
+ also do this casting, which may involve the current
+ setting. Therefore, these conversions can
+ also only be performed within timezone-aware jsonpath
+ functions.
+
+
+
+
+ shows the available
+ filter expression elements.
+
+
+
+
+
+
+
+ SQL/JSON Regular Expressions
+
+
+ LIKE_REGEX
+ in SQL/JSON
+
+
+
+ SQL/JSON path expressions allow matching text to a regular expression
+ with the like_regex filter. For example, the
+ following SQL/JSON path query would case-insensitively match all
+ strings in an array that start with an English vowel:
+
+$[*] ? (@ like_regex "^[aeiou]" flag "i")
+
+
+
+
+ The optional flag string may include one or more of
+ the characters
+ i for case-insensitive match,
+ m to allow ^
+ and $ to match at newlines,
+ s to allow . to match a newline,
+ and q to quote the whole pattern (reducing the
+ behavior to a simple substring match).
+
+
+
+ The SQL/JSON standard borrows its definition for regular expressions
+ from the LIKE_REGEX operator, which in turn uses the
+ XQuery standard. PostgreSQL does not currently support the
+ LIKE_REGEX operator. Therefore,
+ the like_regex filter is implemented using the
+ POSIX regular expression engine described in
+ . This leads to various minor
+ discrepancies from standard SQL/JSON behavior, which are cataloged in
+ .
+ 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.
+
+
+
+ Keep in mind that the pattern argument of like_regex
+ is a JSON path string literal, written according to the rules given in
+ . 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:
+
+$.* ? (@ like_regex "^\\d+$")
+
+
+
+
+
+
+ SQL/JSON Query Functions
+
+ SQL/JSON functions JSON_EXISTS(),
+ JSON_QUERY(), and JSON_VALUE()
+ described in can be used
+ to query JSON documents. Each of these functions apply a
+ path_expression (an SQL/JSON path query) to a
+ context_item (the document). See
+ for more details on what
+ the path_expression can contain. The
+ path_expression can also reference variables,
+ whose values are specified with their respective names in the
+ PASSING clause that is supported by each function.
+ context_item can be a jsonb value
+ or a character string that can be successfully cast to jsonb.
+
+
+
+ SQL/JSON Query Functions
+
+
+
+
+ Function signature
+
+
+ Description
+
+
+ Example(s)
+
+
+
+
+
+
+ json_exists
+
+JSON_EXISTS (
+context_item, path_expression
+PASSING { valueASvarname } , ...
+{ TRUE | FALSE | UNKNOWN | ERROR } ON ERROR) boolean
+
+
+
+
+
+ Returns true if the SQL/JSON path_expression
+ applied to the context_item yields any
+ items, false otherwise.
+
+
+
+
+ The ON ERROR clause specifies the behavior if
+ an error occurs during path_expression
+ evaluation. Specifying ERROR will cause an error to
+ be thrown with the appropriate message. Other options include
+ returning boolean values FALSE or
+ TRUE or the value UNKNOWN which
+ is actually an SQL NULL. The default when no ON ERROR
+ clause is specified is to return the boolean value
+ FALSE.
+
+
+
+
+ Examples:
+
+
+ JSON_EXISTS(jsonb '{"key1": [1,2,3]}', 'strict $.key1[*] ? (@ > $x)' PASSING 2 AS x)
+ t
+
+
+ JSON_EXISTS(jsonb '{"a": [1,2,3]}', 'lax $.a[5]' ERROR ON ERROR)
+ f
+
+
+ JSON_EXISTS(jsonb '{"a": [1,2,3]}', 'strict $.a[5]' ERROR ON ERROR)
+
+
+ERROR: jsonpath array subscript is out of bounds
+
+
+
+
+
+ json_query
+
+JSON_QUERY (
+context_item, path_expression
+PASSING { valueASvarname } , ...
+RETURNINGdata_typeFORMAT JSONENCODING UTF8
+ { WITHOUT | WITH { CONDITIONAL | UNCONDITIONAL } } ARRAYWRAPPER
+ { KEEP | OMIT } QUOTESON SCALAR STRING
+ { ERROR | NULL | EMPTY { ARRAY | OBJECT } | DEFAULTexpression } ON EMPTY
+ { ERROR | NULL | EMPTY { ARRAY | OBJECT } | DEFAULTexpression } ON ERROR) jsonb
+
+
+
+
+
+ Returns the result of applying the SQL/JSON
+ path_expression to the
+ context_item.
+
+
+
+
+ By default, the result is returned as a value of type jsonb,
+ though the RETURNING clause can be used to return
+ as some other type to which it can be successfully coerced.
+
+
+
+
+ If the path expression may return multiple values, it might be necessary
+ to wrap those values using the WITH WRAPPER clause to
+ make it a valid JSON string, because the default behavior is to not wrap
+ them, as if WITHOUT WRAPPER were specified. The
+ WITH WRAPPER clause is by default taken to mean
+ WITH UNCONDITIONAL WRAPPER, which means that even a
+ single result value will be wrapped. To apply the wrapper only when
+ multiple values are present, specify WITH CONDITIONAL WRAPPER.
+ Getting multiple values in result will be treated as an error if
+ WITHOUT WRAPPER is specified.
+
+
+
+
+ If the result is a scalar string, by default, the returned value will
+ be surrounded by quotes, making it a valid JSON value. It can be made
+ explicit by specifying KEEP QUOTES. Conversely,
+ quotes can be omitted by specifying OMIT QUOTES.
+ To ensure that the result is a valid JSON value, OMIT QUOTES
+ cannot be specified when WITH WRAPPER is also
+ specified.
+
+
+
+
+ The ON EMPTY clause specifies the behavior if
+ evaluating path_expression yields an empty
+ set. The ON ERROR clause specifies the behavior
+ if an error occurs when evaluating path_expression,
+ when coercing the result value to the RETURNING type,
+ or when evaluating the ON EMPTY expression if the
+ path_expression evaluation returns an empty
+ set.
+
+
+
+
+ For both ON EMPTY and ON ERROR,
+ specifying ERROR will cause an error to be thrown with
+ the appropriate message. Other options include returning an SQL NULL, an
+ empty array (EMPTY ARRAY),
+ an empty object (EMPTY OBJECT), or a user-specified
+ expression (DEFAULTexpression)
+ that can be coerced to jsonb or the type specified in RETURNING.
+ The default when ON EMPTY or ON ERROR
+ is not specified is to return an SQL NULL value.
+
+
+
+
+ Examples:
+
+
+ JSON_QUERY(jsonb '[1,[2,3],null]', 'lax $[*][$off]' PASSING 1 AS off WITH CONDITIONAL WRAPPER)
+ 3
+
+
+ JSON_QUERY(jsonb '{"a": "[1, 2]"}', 'lax $.a' OMIT QUOTES)
+ [1, 2]
+
+
+ JSON_QUERY(jsonb '{"a": "[1, 2]"}', 'lax $.a' RETURNING int[] OMIT QUOTES ERROR ON ERROR)
+
+
+ERROR: malformed array literal: "[1, 2]"
+DETAIL: Missing "]" after array dimensions.
+
+
+
+
+
+
+ json_value
+
+JSON_VALUE (
+context_item, path_expression
+PASSING { valueASvarname } , ...
+RETURNINGdata_type
+ { ERROR | NULL | DEFAULTexpression } ON EMPTY
+ { ERROR | NULL | DEFAULTexpression } ON ERROR) text
+
+
+
+
+
+ Returns the result of applying the SQL/JSON
+ path_expression to the
+ context_item.
+
+
+
+
+ Only use JSON_VALUE() if the extracted value is
+ expected to be a single SQL/JSON scalar item;
+ getting multiple values will be treated as an error. If you expect that
+ extracted value might be an object or an array, use the
+ JSON_QUERY function instead.
+
+
+
+
+ By default, the result, which must be a single scalar value, is
+ returned as a value of type text, though the
+ RETURNING clause can be used to return as some
+ other type to which it can be successfully coerced.
+
+
+
+
+ The ON ERROR and ON EMPTY
+ clauses have similar semantics as mentioned in the description of
+ JSON_QUERY, except the set of values returned in
+ lieu of throwing an error is different.
+
+
+
+
+ Note that scalar strings returned by JSON_VALUE
+ always have their quotes removed, equivalent to specifying
+ OMIT QUOTES in JSON_QUERY.
+
+
+
+
+ Examples:
+
+
+ JSON_VALUE(jsonb '"123.45"', '$' RETURNING float)
+ 123.45
+
+
+ JSON_VALUE(jsonb '"03:04 2015-02-01"', '$.datetime("HH24:MI YYYY-MM-DD")' RETURNING date)
+ 2015-02-01
+
+
+ JSON_VALUE(jsonb '[1,2]', 'strict $[$off]' PASSING 1 as off)
+ 2
+
+
+ JSON_VALUE(jsonb '[1,2]', 'strict $[*]' DEFAULT 9 ON ERROR)
+ 9
+
+
+
+
+
+
+
+
+ The context_item expression is converted to
+ jsonb by an implicit cast if the expression is not already of
+ type jsonb. Note, however, that any parsing errors that occur
+ during that conversion are thrown unconditionally, that is, are not
+ handled according to the (specified or implicit) ON ERROR
+ clause.
+
+
+
+
+ JSON_VALUE() returns an SQL NULL if
+ path_expression returns a JSON
+ null, whereas JSON_QUERY() returns
+ the JSON null as is.
+
+
+
+
+
+ JSON_TABLE
+
+ json_table
+
+
+
+ JSON_TABLE is an SQL/JSON function which
+ queries JSON data
+ and presents the results as a relational view, which can be accessed as a
+ regular SQL table. You can use JSON_TABLE inside
+ the FROM clause of a SELECT,
+ UPDATE, or DELETE and as data source
+ in a MERGE statement.
+
+
+
+ Taking JSON data as input, JSON_TABLE uses a JSON path
+ expression to extract a part of the provided data to use as a
+ row pattern for the constructed view. Each SQL/JSON
+ value given by the row pattern serves as source for a separate row in the
+ constructed view.
+
+
+
+ To split the row pattern into columns, JSON_TABLE
+ provides the COLUMNS clause that defines the
+ schema of the created view. For each column, a separate JSON path expression
+ can be specified to be evaluated against the row pattern to get an SQL/JSON
+ value that will become the value for the specified column in a given output
+ row.
+
+
+
+ JSON data stored at a nested level of the row pattern can be extracted using
+ the NESTED PATH clause. Each
+ NESTED PATH clause can be used to generate one or more
+ columns using the data from a nested level of the row pattern. Those
+ columns can be specified using a COLUMNS clause that
+ looks similar to the top-level COLUMNS clause. Rows constructed from
+ NESTED COLUMNS are called child rows and are joined
+ against the row constructed from the columns specified in the parent
+ COLUMNS clause to get the row in the final view. Child
+ columns themselves may contain a NESTED PATH
+ specification thus allowing to extract data located at arbitrary nesting
+ levels. Columns produced by multiple NESTED PATHs at the
+ same level are considered to be siblings of each
+ other and their rows after joining with the parent row are combined using
+ UNION.
+
+
+
+ The rows produced by JSON_TABLE are laterally
+ joined to the row that generated them, so you do not have to explicitly join
+ the constructed view with the original table holding JSON
+ data.
+
+
+
+ The syntax is:
+
+
+
+JSON_TABLE (
+ context_item, path_expression AS json_path_name PASSING { value AS varname } , ...
+ COLUMNS ( json_table_column, ... )
+ { ERROR | EMPTYARRAY} ON ERROR
+)
+
+
+where json_table_column is:
+
+ name FOR ORDINALITY
+ | nametype
+ FORMAT JSON ENCODING UTF8
+ PATH path_expression
+ { WITHOUT | WITH { CONDITIONAL | UNCONDITIONAL } } ARRAY WRAPPER
+ { KEEP | OMIT } QUOTES ON SCALAR STRING
+ { ERROR | NULL | EMPTY { ARRAY | OBJECT } | DEFAULT expression } ON EMPTY
+ { ERROR | NULL | EMPTY { ARRAY | OBJECT } | DEFAULT expression } ON ERROR
+ | nametype EXISTS PATH path_expression
+ { ERROR | TRUE | FALSE | UNKNOWN } ON ERROR
+ | NESTED PATH path_expression AS json_path_name COLUMNS ( json_table_column, ... )
+
+
+
+ Each syntax element is described below in more detail.
+
+
+
+
+
+ context_item, path_expressionASjson_path_namePASSING { valueASvarname } , ...
+
+
+
+ The context_item specifies the input document
+ to query, the path_expression is an SQL/JSON
+ path expression defining the query, and json_path_name
+ is an optional name for the path_expression.
+ The optional PASSING clause provides data values for
+ the variables mentioned in the path_expression.
+ The result of the input data evaluation using the aforementioned elements
+ is called the row pattern, which is used as the
+ source for row values in the constructed view.
+
+
+
+
+
+
+ COLUMNS ( json_table_column, ... )
+
+
+
+
+ The COLUMNS clause defining the schema of the
+ constructed view. In this clause, you can specify each column to be
+ filled with an SQL/JSON value obtained by applying a JSON path expression
+ against the row pattern. json_table_column has
+ the following variants:
+
+
+
+
+
+ nameFOR ORDINALITY
+
+
+
+ Adds an ordinality column that provides sequential row numbering starting
+ from 1. Each NESTED PATH (see below) gets its own
+ counter for any nested ordinality columns.
+
+
+
+
+
+
+ nametype
+ FORMAT JSONENCODING UTF8
+ PATHpath_expression
+
+
+
+ Inserts an SQL/JSON value obtained by applying
+ path_expression against the row pattern into
+ the view's output row after coercing it to specified
+ type.
+
+
+ Specifying FORMAT JSON makes it explicit that you
+ expect the value to be a valid json object. It only
+ makes sense to specify FORMAT JSON if
+ type is one of bpchar,
+ bytea, character varying, name,
+ json, jsonb, text, or a domain over
+ these types.
+
+
+ Optionally, you can specify WRAPPER and
+ QUOTES clauses to format the output. Note that
+ specifying OMIT QUOTES overrides
+ FORMAT JSON if also specified, because unquoted
+ literals do not constitute valid json values.
+
+
+ Optionally, you can use ON EMPTY and
+ ON ERROR clauses to specify whether to throw the error
+ or return the specified value when the result of JSON path evaluation is
+ empty and when an error occurs during JSON path evaluation or when
+ coercing the SQL/JSON value to the specified type, respectively. The
+ default for both is to return a NULL value.
+
+
+
+ This clause is internally turned into and has the same semantics as
+ JSON_VALUE or JSON_QUERY.
+ The latter if the specified type is not a scalar type or if either of
+ FORMAT JSON, WRAPPER, or
+ QUOTES clause is present.
+
+
+
+
+
+
+
+ nametype
+ EXISTSPATHpath_expression
+
+
+
+ Inserts a boolean value obtained by applying
+ path_expression against the row pattern
+ into the view's output row after coercing it to specified
+ type.
+
+
+ The value corresponds to whether applying the PATH
+ expression to the row pattern yields any values.
+
+
+ The specified type should have a cast from the
+ boolean type.
+
+
+ Optionally, you can use ON ERROR to specify whether to
+ throw the error or return the specified value when an error occurs during
+ JSON path evaluation or when coercing SQL/JSON value to the specified
+ type. The default is to return a boolean value
+ FALSE.
+
+
+
+ This clause is internally turned into and has the same semantics as
+ JSON_EXISTS.
+
+
+
+
+
+
+
+ NESTED PATH path_expressionASjson_path_name
+ COLUMNS ( json_table_column, ... )
+
+
+
+
+ Extracts SQL/JSON values from nested levels of the row pattern,
+ generates one or more columns as defined by the COLUMNS
+ subclause, and inserts the extracted SQL/JSON values into those
+ columns. The json_table_column
+ expression in the COLUMNS subclause uses the same
+ syntax as in the parent COLUMNS clause.
+
+
+
+ The NESTED PATH syntax is recursive,
+ so you can go down multiple nested levels by specifying several
+ NESTED PATH subclauses within each other.
+ It allows to unnest the hierarchy of JSON objects and arrays
+ in a single function invocation rather than chaining several
+ JSON_TABLE expressions in an SQL statement.
+
+
+
+
+
+
+
+ In each variant of json_table_column described
+ above, if the PATH clause is omitted, path expression
+ $.name is used, where
+ name is the provided column name.
+
+
+
+
+
+
+
+
+ ASjson_path_name
+
+
+
+
+ The optional json_path_name serves as an
+ identifier of the provided path_expression.
+ The name must be unique and distinct from the column names.
+
+
+
+
+
+
+ { ERROR | EMPTY } ON ERROR
+
+
+
+
+ The optional ON ERROR can be used to specify how to
+ handle errors when evaluating the top-level
+ path_expression. Use ERROR
+ if you want the errors to be thrown and EMPTY to
+ return an empty table, that is, a table containing 0 rows. Note that
+ this clause does not affect the errors that occur when evaluating
+ columns, for which the behavior depends on whether the
+ ON ERROR clause is specified against a given column.
+
+
+
+
+
+ Examples
+
+
+ In the examples that follow, the following table containing JSON data
+ will be used:
+
+
+CREATE TABLE my_films ( js jsonb );
+
+INSERT INTO my_films VALUES (
+'{ "favorites" : [
+ { "kind" : "comedy", "films" : [
+ { "title" : "Bananas",
+ "director" : "Woody Allen"},
+ { "title" : "The Dinner Game",
+ "director" : "Francis Veber" } ] },
+ { "kind" : "horror", "films" : [
+ { "title" : "Psycho",
+ "director" : "Alfred Hitchcock" } ] },
+ { "kind" : "thriller", "films" : [
+ { "title" : "Vertigo",
+ "director" : "Alfred Hitchcock" } ] },
+ { "kind" : "drama", "films" : [
+ { "title" : "Yojimbo",
+ "director" : "Akira Kurosawa" } ] }
+ ] }');
+
+
+
+
+ The following query shows how to use JSON_TABLE to
+ turn the JSON objects in the my_films table
+ to a view containing columns for the keys kind,
+ title, and director contained in
+ the original JSON along with an ordinality column:
+
+
+SELECT jt.* FROM
+ my_films,
+ JSON_TABLE (js, '$.favorites[*]' COLUMNS (
+ id FOR ORDINALITY,
+ kind text PATH '$.kind',
+ title text PATH '$.films[*].title' WITH WRAPPER,
+ director text PATH '$.films[*].director' WITH WRAPPER)) AS jt;
+
+
+
+ id | kind | title | director
+----+----------+--------------------------------+----------------------------------
+ 1 | comedy | ["Bananas", "The Dinner Game"] | ["Woody Allen", "Francis Veber"]
+ 2 | horror | ["Psycho"] | ["Alfred Hitchcock"]
+ 3 | thriller | ["Vertigo"] | ["Alfred Hitchcock"]
+ 4 | drama | ["Yojimbo"] | ["Akira Kurosawa"]
+(4 rows)
+
+
+
+
+ The following is a modified version of the above query to show the
+ usage of PASSING arguments in the filter specified in
+ the top-level JSON path expression and the various options for the
+ individual columns:
+
+
+SELECT jt.* FROM
+ my_films,
+ JSON_TABLE (js, '$.favorites[*] ? (@.films[*].director == $filter)'
+ PASSING 'Alfred Hitchcock' AS filter
+ COLUMNS (
+ id FOR ORDINALITY,
+ kind text PATH '$.kind',
+ title text FORMAT JSON PATH '$.films[*].title' OMIT QUOTES,
+ director text PATH '$.films[*].director' KEEP QUOTES)) AS jt;
+
+
+
+ id | kind | title | director
+----+----------+---------+--------------------
+ 1 | horror | Psycho | "Alfred Hitchcock"
+ 2 | thriller | Vertigo | "Alfred Hitchcock"
+(2 rows)
+
+
+
+
+ The following is a modified version of the above query to show the usage
+ of NESTED PATH for populating title and director
+ columns, illustrating how they are joined to the parent columns id and
+ kind:
+
+
+SELECT jt.* FROM
+ my_films,
+ JSON_TABLE ( js, '$.favorites[*] ? (@.films[*].director == $filter)'
+ PASSING 'Alfred Hitchcock' AS filter
+ COLUMNS (
+ id FOR ORDINALITY,
+ kind text PATH '$.kind',
+ NESTED PATH '$.films[*]' COLUMNS (
+ title text FORMAT JSON PATH '$.title' OMIT QUOTES,
+ director text PATH '$.director' KEEP QUOTES))) AS jt;
+
+
+
+ id | kind | title | director
+----+----------+---------+--------------------
+ 1 | horror | Psycho | "Alfred Hitchcock"
+ 2 | thriller | Vertigo | "Alfred Hitchcock"
+(2 rows)
+
+
+
+
+
+ The following is the same query but without the filter in the root
+ path:
+
+
+SELECT jt.* FROM
+ my_films,
+ JSON_TABLE ( js, '$.favorites[*]'
+ COLUMNS (
+ id FOR ORDINALITY,
+ kind text PATH '$.kind',
+ NESTED PATH '$.films[*]' COLUMNS (
+ title text FORMAT JSON PATH '$.title' OMIT QUOTES,
+ director text PATH '$.director' KEEP QUOTES))) AS jt;
+
+
+
+ id | kind | title | director
+----+----------+-----------------+--------------------
+ 1 | comedy | Bananas | "Woody Allen"
+ 1 | comedy | The Dinner Game | "Francis Veber"
+ 2 | horror | Psycho | "Alfred Hitchcock"
+ 3 | thriller | Vertigo | "Alfred Hitchcock"
+ 4 | drama | Yojimbo | "Akira Kurosawa"
+(5 rows)
+
+
+
+
+
+ The following shows another query using a different JSON
+ object as input. It shows the UNION "sibling join" between
+ NESTED paths $.movies[*] and
+ $.books[*] and also the usage of
+ FOR ORDINALITY column at NESTED
+ levels (columns movie_id, book_id,
+ and author_id):
+
+
+SELECT * FROM JSON_TABLE (
+'{"favorites":
+ [{"movies":
+ [{"name": "One", "director": "John Doe"},
+ {"name": "Two", "director": "Don Joe"}],
+ "books":
+ [{"name": "Mystery", "authors": [{"name": "Brown Dan"}]},
+ {"name": "Wonder", "authors": [{"name": "Jun Murakami"}, {"name":"Craig Doe"}]}]
+}]}'::json, '$.favorites[*]'
+COLUMNS (
+ user_id FOR ORDINALITY,
+ NESTED '$.movies[*]'
+ COLUMNS (
+ movie_id FOR ORDINALITY,
+ mname text PATH '$.name',
+ director text),
+ NESTED '$.books[*]'
+ COLUMNS (
+ book_id FOR ORDINALITY,
+ bname text PATH '$.name',
+ NESTED '$.authors[*]'
+ COLUMNS (
+ author_id FOR ORDINALITY,
+ author_name text PATH '$.name'))));
+
+
+
+ user_id | movie_id | mname | director | book_id | bname | author_id | author_name
+---------+----------+-------+----------+---------+---------+-----------+--------------
+ 1 | 1 | One | John Doe | | | |
+ 1 | 2 | Two | Don Joe | | | |
+ 1 | | | | 1 | Mystery | 1 | Brown Dan
+ 1 | | | | 2 | Wonder | 1 | Jun Murakami
+ 1 | | | | 2 | Wonder | 2 | Craig Doe
+(5 rows)
+
+
+
+
+
diff --git a/doc/src/sgml/func/func-logical.sgml b/doc/src/sgml/func/func-logical.sgml
new file mode 100644
index 0000000000000..65e50e65a8117
--- /dev/null
+++ b/doc/src/sgml/func/func-logical.sgml
@@ -0,0 +1,146 @@
+
+ Logical Operators
+
+
+ operator
+ logical
+
+
+
+ Boolean
+ operators
+ operators, logical
+
+
+
+ The usual logical operators are available:
+
+
+ AND (operator)
+
+
+
+ OR (operator)
+
+
+
+ NOT (operator)
+
+
+
+ conjunction
+
+
+
+ disjunction
+
+
+
+ negation
+
+
+
+booleanANDbooleanboolean
+booleanORbooleanboolean
+NOTbooleanboolean
+
+
+ SQL uses a three-valued logic system with true,
+ false, and null, which represents unknown.
+ Observe the following truth tables:
+
+
+
+
+
+ a
+ b
+ a AND b
+ a OR b
+
+
+
+
+
+ TRUE
+ TRUE
+ TRUE
+ TRUE
+
+
+
+ TRUE
+ FALSE
+ FALSE
+ TRUE
+
+
+
+ TRUE
+ NULL
+ NULL
+ TRUE
+
+
+
+ FALSE
+ FALSE
+ FALSE
+ FALSE
+
+
+
+ FALSE
+ NULL
+ FALSE
+ NULL
+
+
+
+ NULL
+ NULL
+ NULL
+ NULL
+
+
+
+
+
+
+
+
+
+ a
+ NOT a
+
+
+
+
+
+ TRUE
+ FALSE
+
+
+
+ FALSE
+ TRUE
+
+
+
+ NULL
+ NULL
+
+
+
+
+
+
+
+ The operators AND and OR 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 for more information about the
+ order of evaluation of subexpressions.)
+
+
diff --git a/doc/src/sgml/func/func-matching.sgml b/doc/src/sgml/func/func-matching.sgml
new file mode 100644
index 0000000000000..ebe0b22c8f60f
--- /dev/null
+++ b/doc/src/sgml/func/func-matching.sgml
@@ -0,0 +1,2487 @@
+
+ Pattern Matching
+
+
+ pattern matching
+
+
+
+ There are three separate approaches to pattern matching provided
+ by PostgreSQL: the traditional
+ SQL LIKE operator, the
+ more recent SIMILAR TO operator (added in
+ SQL:1999), and POSIX-style regular
+ expressions. Aside from the basic does this string match
+ this pattern? operators, functions are available to extract
+ or replace matching substrings and to split a string at matching
+ locations.
+
+
+
+
+ If you have pattern matching needs that go beyond this,
+ consider writing a user-defined function in Perl or Tcl.
+
+
+
+
+
+ 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.
+
+
+
+ Searches using SIMILAR TO patterns have the same
+ security hazards, since SIMILAR TO provides many
+ of the same capabilities as POSIX-style regular
+ expressions.
+
+
+
+ LIKE searches, being much simpler than the other
+ two options, are safer to use with possibly-hostile pattern sources.
+
+
+
+
+ SIMILAR TO and POSIX-style regular
+ expressions do not support nondeterministic collations. If required, use
+ LIKE or apply a different collation to the expression
+ to work around this limitation.
+
+
+
+ <function>LIKE</function>
+
+
+ LIKE
+
+
+
+string LIKE patternESCAPE escape-character
+string NOT LIKE patternESCAPE escape-character
+
+
+
+ The LIKE expression returns true if the
+ string matches the supplied
+ pattern. (As
+ expected, the NOT LIKE expression returns
+ false if LIKE returns true, and vice versa.
+ An equivalent expression is
+ NOT (string LIKE
+ pattern).)
+
+
+
+ If pattern does not contain percent
+ signs or underscores, then the pattern only represents the string
+ itself; in that case LIKE acts like the
+ equals operator. An underscore (_) in
+ pattern stands for (matches) any single
+ character; a percent sign (%) matches any sequence
+ of zero or more characters.
+
+
+
+ Some examples:
+
+'abc' LIKE 'abc' true
+'abc' LIKE 'a%' true
+'abc' LIKE '_b_' true
+'abc' LIKE 'c' false
+
+
+
+
+ LIKE pattern matching supports nondeterministic
+ collations (see ), such as
+ case-insensitive collations or collations that, say, ignore punctuation.
+ So with a case-insensitive collation, one could have:
+
+'AbC' LIKE 'abc' COLLATE case_insensitive true
+'AbC' LIKE 'a%' COLLATE case_insensitive true
+
+ With collations that ignore certain characters or in general that consider
+ strings of different lengths equal, the semantics can become a bit more
+ complicated. Consider these examples:
+
+'.foo.' LIKE 'foo' COLLATE ign_punct true
+'.foo.' LIKE 'f_o' COLLATE ign_punct true
+'.foo.' LIKE '_oo' COLLATE ign_punct false
+
+ The way the matching works is that the pattern is partitioned into
+ sequences of wildcards and non-wildcard strings (wildcards being
+ _ and %). For example, the pattern
+ f_o is partitioned into f, _, o, the
+ pattern _oo is partitioned into _,
+ oo. The input string matches the pattern if it can be
+ partitioned in such a way that the wildcards match one character or any
+ number of characters respectively and the non-wildcard partitions are
+ equal under the applicable collation. So for example, '.foo.'
+ LIKE 'f_o' COLLATE ign_punct is true because one can partition
+ .foo. into .f, o, o., and then
+ '.f' = 'f' COLLATE ign_punct, 'o'
+ matches the _ wildcard, and 'o.' = 'o' COLLATE
+ ign_punct. But '.foo.' LIKE '_oo' COLLATE
+ ign_punct is false because .foo. cannot be
+ partitioned in a way that the first character is any character and the
+ rest of the string compares equal to oo. (Note that
+ the single-character wildcard always matches exactly one character,
+ independent of the collation. So in this example, the
+ _ would match ., but then the rest
+ of the input string won't match the rest of the pattern.)
+
+
+
+ LIKE 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.
+
+
+
+ To match a literal underscore or percent sign without matching
+ other characters, the respective character in
+ pattern must be
+ preceded by the escape character. The default escape
+ character is the backslash but a different one can be selected by
+ using the ESCAPE clause. To match the escape
+ character itself, write two escape characters.
+
+
+
+
+ If you have turned off,
+ any backslashes you write in literal string constants will need to be
+ doubled. See for more information.
+
+
+
+
+ It's also possible to select no escape character by writing
+ ESCAPE ''. This effectively disables the
+ escape mechanism, which makes it impossible to turn off the
+ special meaning of underscore and percent signs in the pattern.
+
+
+
+ According to the SQL standard, omitting ESCAPE
+ means there is no escape character (rather than defaulting to a
+ backslash), and a zero-length ESCAPE value is
+ disallowed. PostgreSQL's behavior in
+ this regard is therefore slightly nonstandard.
+
+
+
+ The key word ILIKE can be used instead of
+ LIKE to make the match case-insensitive according to the
+ active locale. (But this does not support nondeterministic collations.)
+ This is not in the SQL standard but is a
+ PostgreSQL extension.
+
+
+
+ The operator ~~ is equivalent to
+ LIKE, and ~~* corresponds to
+ ILIKE. There are also
+ !~~ and !~~* operators that
+ represent NOT LIKE and NOT
+ ILIKE, respectively. All of these operators are
+ PostgreSQL-specific. You may see these
+ operator names in EXPLAIN output and similar
+ places, since the parser actually translates LIKE
+ et al. to these operators.
+
+
+
+ The phrases LIKE, ILIKE,
+ NOT LIKE, and NOT ILIKE are
+ generally treated as operators
+ in PostgreSQL syntax; for example they can
+ be used in expression
+ operator ANY
+ (subquery) constructs, although
+ an ESCAPE clause cannot be included there. In some
+ obscure cases it may be necessary to use the underlying operator names
+ instead.
+
+
+
+ Also see the starts-with operator ^@ and the
+ corresponding starts_with() function, which are
+ useful in cases where simply matching the beginning of a string is
+ needed.
+
+
+
+
+
+ <function>SIMILAR TO</function> Regular Expressions
+
+
+ regular expression
+
+
+
+
+ SIMILAR TO
+
+
+ substring
+
+
+
+string SIMILAR TO patternESCAPE escape-character
+string NOT SIMILAR TO patternESCAPE escape-character
+
+
+
+ The SIMILAR TO operator returns true or
+ false depending on whether its pattern matches the given string.
+ It is similar to LIKE, except that it
+ interprets the pattern using the SQL standard's definition of a
+ regular expression. SQL regular expressions are a curious cross
+ between LIKE notation and common (POSIX) regular
+ expression notation.
+
+
+
+ Like LIKE, the SIMILAR TO
+ 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
+ LIKE, SIMILAR TO uses
+ _ and % as wildcard characters denoting
+ any single character and any string, respectively (these are
+ comparable to . and .* in POSIX regular
+ expressions).
+
+
+
+ In addition to these facilities borrowed from LIKE,
+ SIMILAR TO supports these pattern-matching
+ metacharacters borrowed from POSIX regular expressions:
+
+
+
+
+ | denotes alternation (either of two alternatives).
+
+
+
+
+ * denotes repetition of the previous item zero
+ or more times.
+
+
+
+
+ + denotes repetition of the previous item one
+ or more times.
+
+
+
+
+ ? denotes repetition of the previous item zero
+ or one time.
+
+
+
+
+ {m} denotes repetition
+ of the previous item exactly m times.
+
+
+
+
+ {m,} denotes repetition
+ of the previous item m or more times.
+
+
+
+
+ {m,n}
+ denotes repetition of the previous item at least m and
+ not more than n times.
+
+
+
+
+ Parentheses () can be used to group items into
+ a single logical item.
+
+
+
+
+ A bracket expression [...] specifies a character
+ class, just as in POSIX regular expressions.
+
+
+
+
+ Notice that the period (.) is not a metacharacter
+ for SIMILAR TO.
+
+
+
+ As with LIKE, a backslash disables the special
+ meaning of any of these metacharacters. A different escape character
+ can be specified with ESCAPE, or the escape
+ capability can be disabled by writing ESCAPE ''.
+
+
+
+ According to the SQL standard, omitting ESCAPE
+ means there is no escape character (rather than defaulting to a
+ backslash), and a zero-length ESCAPE value is
+ disallowed. PostgreSQL's behavior in
+ this regard is therefore slightly nonstandard.
+
+
+
+ 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
+ ,
+ , and
+ below.
+
+
+
+ Some examples:
+
+'abc' SIMILAR TO 'abc' true
+'abc' SIMILAR TO 'a' false
+'abc' SIMILAR TO '%(b|d)%' true
+'abc' SIMILAR TO '(b|c)%' false
+'-abc-' SIMILAR TO '%\mabc\M%' true
+'xabcy' SIMILAR TO '%\mabc\M%' false
+
+
+
+
+ The substring 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:
+
+substring(string similar pattern escape escape-character)
+
+ or using the now obsolete SQL:1999 syntax:
+
+substring(string from pattern for escape-character)
+
+ or as a plain three-argument function:
+
+substring(string, pattern, escape-character)
+
+ As with SIMILAR TO, 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
+ (").
+ The text matching the portion of the pattern
+ between these separators is returned when the match is successful.
+
+
+
+ The escape-double-quote separators actually
+ divide substring's pattern into three independent
+ regular expressions; for example, a vertical bar (|)
+ 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.)
+
+
+
+ As an extension to the SQL standard, PostgreSQL
+ 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.
+
+
+
+ Some examples, with #" delimiting the return string:
+
+substring('foobar' similar '%#"o_b#"%' escape '#') oob
+substring('foobar' similar '#"o_b#"%' escape '#') NULL
+
+
+
+
+
+ <acronym>POSIX</acronym> Regular Expressions
+
+
+ regular expression
+ pattern matching
+
+
+ substring
+
+
+ regexp_count
+
+
+ regexp_instr
+
+
+ regexp_like
+
+
+ regexp_match
+
+
+ regexp_matches
+
+
+ regexp_replace
+
+
+ regexp_split_to_table
+
+
+ regexp_split_to_array
+
+
+ regexp_substr
+
+
+
+ lists the available
+ operators for pattern matching using POSIX regular expressions.
+
+
+
+
+
+ POSIX regular expressions provide a more
+ powerful means for pattern matching than the LIKE and
+ SIMILAR TO operators.
+ Many Unix tools such as egrep,
+ sed, or awk use a pattern
+ matching language that is similar to the one described here.
+
+
+
+ A regular expression is a character sequence that is an
+ abbreviated definition of a set of strings (a regular
+ set). 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 LIKE, pattern characters
+ match string characters exactly unless they are special characters
+ in the regular expression language — but regular expressions use
+ different special characters than LIKE does.
+ Unlike LIKE 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.
+
+
+
+ Some examples:
+
+'abcd' ~ 'bc' true
+'abcd' ~ 'a.c' true — dot matches any character
+'abcd' ~ 'a.*d' true — * repeats the preceding pattern item
+'abcd' ~ '(b|x)' true — | means OR, parentheses group
+'abcd' ~ '^a' true — ^ anchors to start of string
+'abcd' ~ '^(b|c)' false — would match except for anchoring
+
+
+
+
+ The POSIX pattern language is described in much
+ greater detail below.
+
+
+
+ The substring function with two parameters,
+ substring(string from
+ pattern), 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.
+
+
+
+ Some examples:
+
+substring('foobar' from 'o.b') oob
+substring('foobar' from 'o(.)b') o
+
+
+
+
+ The regexp_count function counts the number of
+ places where a POSIX regular expression pattern matches a string.
+ It has the syntax
+ regexp_count(string,
+ pattern
+ , start
+ , flags
+ ).
+ pattern is searched for
+ in string, normally from the beginning of
+ the string, but if the start parameter is
+ provided then beginning from that character index.
+ The flags parameter is an optional text
+ string containing zero or more single-letter flags that change the
+ function's behavior. For example, including i in
+ flags specifies case-insensitive matching.
+ Supported flags are described in
+ .
+
+
+
+ Some examples:
+
+regexp_count('ABCABCAXYaxy', 'A.') 3
+regexp_count('ABCABCAXYaxy', 'A.', 1, 'i') 4
+
+
+
+
+ The regexp_instr function returns the starting or
+ ending position of the N'th match of a
+ POSIX regular expression pattern to a string, or zero if there is no
+ such match. It has the syntax
+ regexp_instr(string,
+ pattern
+ , start
+ , N
+ , endoption
+ , flags
+ , subexpr
+ ).
+ pattern is searched for
+ in string, normally from the beginning of
+ the string, but if the start parameter is
+ provided then beginning from that character index.
+ If N is specified
+ then the N'th match of the pattern
+ is located, otherwise the first match is located.
+ If the endoption parameter is omitted or
+ specified as zero, the function returns the position of the first
+ character of the match. Otherwise, endoption
+ must be one, and the function returns the position of the character
+ following the match.
+ The flags parameter is an optional text
+ string containing zero or more single-letter flags that change the
+ function's behavior. Supported flags are described
+ in .
+ For a pattern containing parenthesized
+ subexpressions, subexpr 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 subexpr is omitted or zero, the result
+ identifies the position of the whole match regardless of
+ parenthesized subexpressions.
+
+
+
+ Some examples:
+
+regexp_instr('number of your street, town zip, FR', '[^,]+', 1, 2)
+ 23
+regexp_instr(string=>'ABCDEFGHI', pattern=>'(c..)(...)', start=>1, "N"=>1, endoption=>0, flags=>'i', subexpr=>2)
+ 6
+
+
+
+
+ The regexp_like function checks whether a match
+ of a POSIX regular expression pattern occurs within a string,
+ returning boolean true or false. It has the syntax
+ regexp_like(string,
+ pattern
+ , flags).
+ The flags parameter is an optional text
+ string containing zero or more single-letter flags that change the
+ function's behavior. Supported flags are described
+ in .
+ This function has the same results as the ~
+ operator if no flags are specified. If only the i
+ flag is specified, it has the same results as
+ the ~* operator.
+
+
+
+ Some examples:
+
+regexp_like('Hello World', 'world') false
+regexp_like('Hello World', 'world', 'i') true
+
+
+
+
+ The regexp_match 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
+ regexp_match(string,
+ pattern, flags).
+ If there is no match, the result is NULL.
+ If a match is found, and the pattern contains no
+ parenthesized subexpressions, then the result is a single-element text
+ array containing the substring matching the whole pattern.
+ If a match is found, and the pattern contains
+ parenthesized subexpressions, then the result is a text array
+ whose n'th element is the substring matching
+ the n'th parenthesized subexpression of
+ the pattern (not counting non-capturing
+ parentheses; see below for details).
+ The flags parameter is an optional text string
+ containing zero or more single-letter flags that change the function's
+ behavior. Supported flags are described
+ in .
+
+
+
+ Some examples:
+
+SELECT regexp_match('foobarbequebaz', 'bar.*que');
+ regexp_match
+--------------
+ {barbeque}
+(1 row)
+
+SELECT regexp_match('foobarbequebaz', '(bar)(beque)');
+ regexp_match
+--------------
+ {bar,beque}
+(1 row)
+
+
+
+
+
+ In the common case where you just want the whole matching substring
+ or NULL for no match, the best solution is to
+ use regexp_substr().
+ However, regexp_substr() only exists
+ in PostgreSQL version 15 and up. When
+ working in older versions, you can extract the first element
+ of regexp_match()'s result, for example:
+
+SELECT (regexp_match('foobarbequebaz', 'bar.*que'))[1];
+ regexp_match
+--------------
+ barbeque
+(1 row)
+
+
+
+
+
+ The regexp_matches 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
+ regexp_match.
+ This function returns no rows if there is no match, one row if there is
+ a match and the g flag is not given, or N
+ rows if there are N matches and the g flag
+ is given. Each returned row is a text array containing the whole
+ matched substring or the substrings matching parenthesized
+ subexpressions of the pattern, just as described above
+ for regexp_match.
+ regexp_matches accepts all the flags shown
+ in , plus
+ the g flag which commands it to return all matches, not
+ just the first one.
+
+
+
+ Some examples:
+
+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)
+
+
+
+
+
+ In most cases regexp_matches() should be used with
+ the g flag, since if you only want the first match, it's
+ easier and more efficient to use regexp_match().
+ However, regexp_match() only exists
+ in PostgreSQL version 10 and up. When working in older
+ versions, a common trick is to place a regexp_matches()
+ call in a sub-select, for example:
+
+SELECT col1, (SELECT regexp_matches(col2, '(bar)(beque)')) FROM tab;
+
+ This produces a text array if there's a match, or NULL if
+ not, the same as regexp_match() would do. Without the
+ sub-select, this query would produce no output at all for table rows
+ without a match, which is typically not the desired behavior.
+
+
+
+
+ The regexp_replace function provides substitution of
+ new text for substrings that match POSIX regular expression patterns.
+ It has the syntax
+ regexp_replace(string,
+ pattern, replacement
+ , flags)
+ or
+ regexp_replace(string,
+ pattern, replacement,
+ start
+ , N
+ , flags).
+ The source string is returned unchanged if
+ there is no match to the pattern. If there is a
+ match, the string is returned with the
+ replacement string substituted for the matching
+ substring. The replacement string can contain
+ \n, where n is 1
+ through 9, to indicate that the source substring matching the
+ n'th parenthesized subexpression of the pattern should be
+ inserted, and it can contain \& to indicate that the
+ substring matching the entire pattern should be inserted. Write
+ \\ if you need to put a literal backslash in the replacement
+ text.
+ pattern is searched for
+ in string, normally from the beginning of
+ the string, but if the start parameter is
+ provided then beginning from that character index.
+ By default, only the first match of the pattern is replaced.
+ If N is specified and is greater than zero,
+ then the N'th match of the pattern
+ is replaced.
+ If the g flag is given, or
+ if N is specified and is zero, then all
+ matches at or after the start position are
+ replaced. (The g flag is ignored
+ when N is specified.)
+ The flags parameter is an optional text
+ string containing zero or more single-letter flags that change the
+ function's behavior. Supported flags (though
+ not g) are
+ described in .
+
+
+
+ Some examples:
+
+regexp_replace('foobarbaz', 'b..', 'X')
+ fooXbaz
+regexp_replace('foobarbaz', 'b..', 'X', 'g')
+ fooXX
+regexp_replace('foobarbaz', 'b(..)', 'X\1Y', 'g')
+ fooXarYXazY
+regexp_replace('A PostgreSQL function', 'a|e|i|o|u', 'X', 1, 0, 'i')
+ X PXstgrXSQL fXnctXXn
+regexp_replace(string=>'A PostgreSQL function', pattern=>'a|e|i|o|u', replacement=>'X', start=>1, "N"=>3, flags=>'i')
+ A PostgrXSQL function
+
+
+
+
+ The regexp_split_to_table function splits a string using a POSIX
+ regular expression pattern as a delimiter. It has the syntax
+ regexp_split_to_table(string, pattern
+ , flags).
+ If there is no match to the pattern, the function returns the
+ string. 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 flags parameter is an optional text string containing
+ zero or more single-letter flags that change the function's behavior.
+ regexp_split_to_table supports the flags described in
+ .
+
+
+
+ The regexp_split_to_array function behaves the same as
+ regexp_split_to_table, except that regexp_split_to_array
+ returns its result as an array of text. It has the syntax
+ regexp_split_to_array(string, pattern
+ , flags).
+ The parameters are the same as for regexp_split_to_table.
+
+
+
+ Some examples:
+
+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)
+
+
+
+
+ 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.
+
+
+
+ The regexp_substr function returns the substring
+ that matches a POSIX regular expression pattern,
+ or NULL if there is no match. It has the syntax
+ regexp_substr(string,
+ pattern
+ , start
+ , N
+ , flags
+ , subexpr
+ ).
+ pattern is searched for
+ in string, normally from the beginning of
+ the string, but if the start parameter is
+ provided then beginning from that character index.
+ If N is specified
+ then the N'th match of the pattern
+ is returned, otherwise the first match is returned.
+ The flags parameter is an optional text
+ string containing zero or more single-letter flags that change the
+ function's behavior. Supported flags are described
+ in .
+ For a pattern containing parenthesized
+ subexpressions, subexpr 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 subexpr is omitted or zero, the result
+ is the whole match regardless of parenthesized subexpressions.
+
+
+
+ Some examples:
+
+regexp_substr('number of your street, town zip, FR', '[^,]+', 1, 2)
+ town zip
+regexp_substr('ABCDEFGHI', '(c..)(...)', 1, 1, 'i', 2)
+ FGH
+
+
+
+
+
+
+ Regular Expression Details
+
+
+ PostgreSQL'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.
+
+
+
+ Regular expressions (REs), as defined in
+ POSIX 1003.2, come in two forms:
+ extended REs or EREs
+ (roughly those of egrep), and
+ basic REs or BREs
+ (roughly those of ed).
+ PostgreSQL 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.
+ REs using these non-POSIX extensions are called
+ advanced REs or AREs
+ 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.
+
+
+
+
+ PostgreSQL always initially presumes that a regular
+ expression follows the ARE rules. However, the more limited ERE or
+ BRE rules can be chosen by prepending an embedded option
+ to the RE pattern, as described in .
+ This can be useful for compatibility with applications that expect
+ exactly the POSIX 1003.2 rules.
+
+
+
+
+ A regular expression is defined as one or more
+ branches, separated by
+ |. It matches anything that matches one of the
+ branches.
+
+
+
+ A branch is zero or more quantified atoms or
+ constraints, concatenated.
+ It matches a match for the first, followed by a match for the second, etc.;
+ an empty branch matches the empty string.
+
+
+
+ A quantified atom is an atom possibly followed
+ by a single quantifier.
+ Without a quantifier, it matches a match for the atom.
+ With a quantifier, it can match some number of matches of the atom.
+ An atom can be any of the possibilities
+ shown in .
+ The possible quantifiers and their meanings are shown in
+ .
+
+
+
+ A constraint 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
+ ;
+ some more constraints are described later.
+
+
+
+
+ Regular Expression Atoms
+
+
+
+
+
+
+ Atom
+ Description
+
+
+
+
+
+ (re)
+ (where re is any regular expression)
+ matches a match for
+ re, with the match noted for possible reporting
+
+
+
+ (?:re)
+ as above, but the match is not noted for reporting
+ (a non-capturing set of parentheses)
+ (AREs only)
+
+
+
+ .
+ matches any single character
+
+
+
+ [chars]
+ a bracket expression,
+ matching any one of the chars (see
+ for more detail)
+
+
+
+ \k
+ (where k is a non-alphanumeric character)
+ matches that character taken as an ordinary character,
+ e.g., \\ matches a backslash character
+
+
+
+ \c
+ where c is alphanumeric
+ (possibly followed by other characters)
+ is an escape, see
+ (AREs only; in EREs and BREs, this matches c)
+
+
+
+ {
+ when followed by a character other than a digit,
+ matches the left-brace character {;
+ when followed by a digit, it is the beginning of a
+ bound (see below)
+
+
+
+ x
+ where x is a single character with no other
+ significance, matches that character
+
+
+
+
+
+
+ An RE cannot end with a backslash (\).
+
+
+
+
+ If you have turned off,
+ any backslashes you write in literal string constants will need to be
+ doubled. See for more information.
+
+
+
+
+ Regular Expression Quantifiers
+
+
+
+
+
+
+ Quantifier
+ Matches
+
+
+
+
+
+ *
+ a sequence of 0 or more matches of the atom
+
+
+
+ +
+ a sequence of 1 or more matches of the atom
+
+
+
+ ?
+ a sequence of 0 or 1 matches of the atom
+
+
+
+ {m}
+ a sequence of exactly m matches of the atom
+
+
+
+ {m,}
+ a sequence of m or more matches of the atom
+
+
+
+
+ {m,n}
+ a sequence of m through n
+ (inclusive) matches of the atom; m cannot exceed
+ n
+
+
+
+ *?
+ non-greedy version of *
+
+
+
+ +?
+ non-greedy version of +
+
+
+
+ ??
+ non-greedy version of ?
+
+
+
+ {m}?
+ non-greedy version of {m}
+
+
+
+ {m,}?
+ non-greedy version of {m,}
+
+
+
+
+ {m,n}?
+ non-greedy version of {m,n}
+
+
+
+
+
+
+ The forms using {...}
+ are known as bounds.
+ The numbers m and n within a bound are
+ unsigned decimal integers with permissible values from 0 to 255 inclusive.
+
+
+
+ Non-greedy quantifiers (available in AREs only) match the
+ same possibilities as their corresponding normal (greedy)
+ counterparts, but prefer the smallest number rather than the largest
+ number of matches.
+ See for more detail.
+
+
+
+
+ A quantifier cannot immediately follow another quantifier, e.g.,
+ ** is invalid.
+ A quantifier cannot
+ begin an expression or subexpression or follow
+ ^ or |.
+
+
+
+
+ Regular Expression Constraints
+
+
+
+
+
+
+ Constraint
+ Description
+
+
+
+
+
+ ^
+ matches at the beginning of the string
+
+
+
+ $
+ matches at the end of the string
+
+
+
+ (?=re)
+ positive lookahead matches at any point
+ where a substring matching re begins
+ (AREs only)
+
+
+
+ (?!re)
+ negative lookahead matches at any point
+ where no substring matching re begins
+ (AREs only)
+
+
+
+ (?<=re)
+ positive lookbehind matches at any point
+ where a substring matching re ends
+ (AREs only)
+
+
+
+ (?<!re)
+ negative lookbehind matches at any point
+ where no substring matching re ends
+ (AREs only)
+
+
+
+
+
+
+ Lookahead and lookbehind constraints cannot contain back
+ references (see ),
+ and all parentheses within them are considered non-capturing.
+
+
+
+
+ Bracket Expressions
+
+
+ A bracket expression is a list of
+ characters enclosed in []. It normally matches
+ any single character from the list (but see below). If the list
+ begins with ^, it matches any single character
+ not from the rest of the list.
+ If two characters
+ in the list are separated by -, this is
+ shorthand for the full range of characters between those two
+ (inclusive) in the collating sequence,
+ e.g., [0-9] in ASCII matches
+ any decimal digit. It is illegal for two ranges to share an
+ endpoint, e.g., a-c-e. Ranges are very
+ collating-sequence-dependent, so portable programs should avoid
+ relying on them.
+
+
+
+ To include a literal ] in the list, make it the
+ first character (after ^, if that is used). To
+ include a literal -, make it the first or last
+ character, or the second endpoint of a range. To use a literal
+ - as the first endpoint of a range, enclose it
+ in [. and .] to make it a
+ collating element (see below). With the exception of these characters,
+ some combinations using [
+ (see next paragraphs), and escapes (AREs only), all other special
+ characters lose their special significance within a bracket expression.
+ In particular, \ is not special when following
+ ERE or BRE rules, though it is special (as introducing an escape)
+ in AREs.
+
+
+
+ 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
+ [. and .] 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 ch collating element, then the RE
+ [[.ch.]]*c matches the first five characters of
+ chchcc.
+
+
+
+
+ PostgreSQL currently does not support multi-character collating
+ elements. This information describes possible future behavior.
+
+
+
+
+ Within a bracket expression, a collating element enclosed in
+ [= and =] is an equivalence
+ class, 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 [. and
+ .].) For example, if o and
+ ^ are the members of an equivalence class, then
+ [[=o=]], [[=^=]], and
+ [o^] are all synonymous. An equivalence class
+ cannot be an endpoint of a range.
+
+
+
+ Within a bracket expression, the name of a character class
+ enclosed in [: and :] stands
+ for the list of all characters belonging to that class. A character
+ class cannot be used as an endpoint of a range.
+ The POSIX standard defines these character class
+ names:
+ alnum (letters and numeric digits),
+ alpha (letters),
+ blank (space and tab),
+ cntrl (control characters),
+ digit (numeric digits),
+ graph (printable characters except space),
+ lower (lower-case letters),
+ print (printable characters including space),
+ punct (punctuation),
+ space (any white space),
+ upper (upper-case letters),
+ and xdigit (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 collation
+ that is used for the regular-expression function or operator
+ (see ), or by default on the
+ database's LC_CTYPE locale setting (see
+ ). The classification of non-ASCII
+ characters can vary across platforms even in similarly-named
+ locales. (But the C locale never considers any
+ non-ASCII characters to belong to any of these classes.)
+ In addition to these standard character
+ classes, PostgreSQL defines
+ the word character class, which is the same as
+ alnum plus the underscore (_)
+ character, and
+ the ascii character class, which contains exactly
+ the 7-bit ASCII set.
+
+
+
+ There are two special cases of bracket expressions: the bracket
+ expressions [[:<:]] and
+ [[:>:]] 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
+ word character class, that is, any letter, digit,
+ or underscore. This is an extension, compatible with but not
+ specified by POSIX 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.
+
+
+
+
+ Regular Expression Escapes
+
+
+ Escapes are special sequences beginning with \
+ followed by an alphanumeric character. Escapes come in several varieties:
+ character entry, class shorthands, constraint escapes, and back references.
+ A \ 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 \ followed by an alphanumeric character merely stands for
+ that character as an ordinary character, and inside a bracket expression,
+ \ is an ordinary character.
+ (The latter is the one actual incompatibility between EREs and AREs.)
+
+
+
+ Character-entry escapes exist to make it easier to specify
+ non-printing and other inconvenient characters in REs. They are
+ shown in .
+
+
+
+ Class-shorthand escapes provide shorthands for certain
+ commonly-used character classes. They are
+ shown in .
+
+
+
+ A constraint escape is a constraint,
+ matching the empty string if specific conditions are met,
+ written as an escape. They are
+ shown in .
+
+
+
+ A back reference (\n) matches the
+ same string matched by the previous parenthesized subexpression specified
+ by the number n
+ (see ). For example,
+ ([bc])\1 matches bb or cc
+ but not bc or cb.
+ The subexpression must entirely precede the back reference in the RE.
+ 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, (^\d)\1 will match 22.
+
+
+
+ Regular Expression Character-Entry Escapes
+
+
+
+
+
+
+ Escape
+ Description
+
+
+
+
+
+ \a
+ alert (bell) character, as in C
+
+
+
+ \b
+ backspace, as in C
+
+
+
+ \B
+ synonym for backslash (\) to help reduce the need for backslash
+ doubling
+
+
+
+ \cX
+ (where X is any character) the character whose
+ low-order 5 bits are the same as those of
+ X, and whose other bits are all zero
+
+
+
+ \e
+ the character whose collating-sequence name
+ is ESC,
+ or failing that, the character with octal value 033
+
+
+
+ \f
+ form feed, as in C
+
+
+
+ \n
+ newline, as in C
+
+
+
+ \r
+ carriage return, as in C
+
+
+
+ \t
+ horizontal tab, as in C
+
+
+
+ \uwxyz
+ (where wxyz is exactly four hexadecimal digits)
+ the character whose hexadecimal value is
+ 0xwxyz
+
+
+
+
+ \Ustuvwxyz
+ (where stuvwxyz is exactly eight hexadecimal
+ digits)
+ the character whose hexadecimal value is
+ 0xstuvwxyz
+
+
+
+
+ \v
+ vertical tab, as in C
+
+
+
+ \xhhh
+ (where hhh is any sequence of hexadecimal
+ digits)
+ the character whose hexadecimal value is
+ 0xhhh
+ (a single character no matter how many hexadecimal digits are used)
+
+
+
+
+ \0
+ the character whose value is 0 (the null byte)
+
+
+
+ \xy
+ (where xy is exactly two octal digits,
+ and is not a back reference)
+ the character whose octal value is
+ 0xy
+
+
+
+ \xyz
+ (where xyz is exactly three octal digits,
+ and is not a back reference)
+ the character whose octal value is
+ 0xyz
+
+
+
+
+
+
+ Hexadecimal digits are 0-9,
+ a-f, and A-F.
+ Octal digits are 0-7.
+
+
+
+ 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 \u1234 means the character U+1234.
+ 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.
+
+
+
+ The character-entry escapes are always taken as ordinary characters.
+ For example, \135 is ] in ASCII, but
+ \135 does not terminate a bracket expression.
+
+
+
+ Regular Expression Class-Shorthand Escapes
+
+
+
+
+
+
+ Escape
+ Description
+
+
+
+
+
+ \d
+ matches any digit, like
+ [[:digit:]]
+
+
+
+ \s
+ matches any whitespace character, like
+ [[:space:]]
+
+
+
+ \w
+ matches any word character, like
+ [[:word:]]
+
+
+
+ \D
+ matches any non-digit, like
+ [^[:digit:]]
+
+
+
+ \S
+ matches any non-whitespace character, like
+ [^[:space:]]
+
+
+
+ \W
+ matches any non-word character, like
+ [^[:word:]]
+
+
+
+
+
+
+ The class-shorthand escapes also work within bracket expressions,
+ although the definitions shown above are not quite syntactically
+ valid in that context.
+ For example, [a-c\d] is equivalent to
+ [a-c[:digit:]].
+
+
+
+ Regular Expression Constraint Escapes
+
+
+
+
+
+
+ Escape
+ Description
+
+
+
+
+
+ \A
+ matches only at the beginning of the string
+ (see for how this differs from
+ ^)
+
+
+
+ \m
+ matches only at the beginning of a word
+
+
+
+ \M
+ matches only at the end of a word
+
+
+
+ \y
+ matches only at the beginning or end of a word
+
+
+
+ \Y
+ matches only at a point that is not the beginning or end of a
+ word
+
+
+
+ \Z
+ matches only at the end of the string
+ (see for how this differs from
+ $)
+
+
+
+
+
+
+ A word is defined as in the specification of
+ [[:<:]] and [[:>:]] above.
+ Constraint escapes are illegal within bracket expressions.
+
+
+
+ Regular Expression Back References
+
+
+
+
+
+
+ Escape
+ Description
+
+
+
+
+
+ \m
+ (where m is a nonzero digit)
+ a back reference to the m'th subexpression
+
+
+
+ \mnn
+ (where m is a nonzero digit, and
+ nn is some more digits, and the decimal value
+ mnn is not greater than the number of closing capturing
+ parentheses seen so far)
+ a back reference to the mnn'th subexpression
+
+
+
+
+
+
+
+ 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.
+
+
+
+
+
+ Regular Expression Metasyntax
+
+
+ In addition to the main syntax described above, there are some special
+ forms and miscellaneous syntactic facilities available.
+
+
+
+ An RE can begin with one of two special director prefixes.
+ If an RE begins with ***:,
+ the rest of the RE is taken as an ARE. (This normally has no effect in
+ PostgreSQL, since REs are assumed to be AREs;
+ but it does have an effect if ERE or BRE mode had been specified by
+ the flags parameter to a regex function.)
+ If an RE begins with ***=,
+ the rest of the RE is taken to be a literal string,
+ with all characters considered ordinary characters.
+
+
+
+ An ARE can begin with embedded options:
+ a sequence (?xyz)
+ (where xyz 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 flags parameter to a regex
+ function.
+ The available option letters are
+ shown in .
+ Note that these same option letters are used in the flags
+ parameters of regex functions.
+
+
+
+ ARE Embedded-Option Letters
+
+
+
+
+
+
+ Option
+ Description
+
+
+
+
+
+ b
+ rest of RE is a BRE
+
+
+
+ c
+ case-sensitive matching (overrides operator type)
+
+
+
+ e
+ rest of RE is an ERE
+
+
+
+ i
+ case-insensitive matching (see
+ ) (overrides operator type)
+
+
+
+ m
+ historical synonym for n
+
+
+
+ n
+ newline-sensitive matching (see
+ )
+
+
+
+ p
+ partial newline-sensitive matching (see
+ )
+
+
+
+ q
+ rest of RE is a literal (quoted) string, all ordinary
+ characters
+
+
+
+ s
+ non-newline-sensitive matching (default)
+
+
+
+ t
+ tight syntax (default; see below)
+
+
+
+ w
+ inverse partial newline-sensitive (weird) matching
+ (see )
+
+
+
+ x
+ expanded syntax (see below)
+
+
+
+
+
+
+ Embedded options take effect at the ) terminating the sequence.
+ They can appear only at the start of an ARE (after the
+ ***: director if any).
+
+
+
+ In addition to the usual (tight) RE syntax, in which all
+ characters are significant, there is an expanded syntax,
+ available by specifying the embedded x option.
+ In the expanded syntax,
+ white-space characters in the RE are ignored, as are
+ all characters between a #
+ 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:
+
+
+
+
+ a white-space character or # preceded by \ is
+ retained
+
+
+
+
+ white space or # within a bracket expression is retained
+
+
+
+
+ white space and comments cannot appear within multi-character symbols,
+ such as (?:
+
+
+
+
+ For this purpose, white-space characters are blank, tab, newline, and
+ any character that belongs to the space character class.
+
+
+
+ Finally, in an ARE, outside bracket expressions, the sequence
+ (?#ttt)
+ (where ttt is any text not containing a ))
+ is a comment, completely ignored.
+ Again, this is not allowed between the characters of
+ multi-character symbols, like (?:.
+ Such comments are more a historical artifact than a useful facility,
+ and their use is deprecated; use the expanded syntax instead.
+
+
+
+ None of these metasyntax extensions is available if
+ an initial ***= director
+ has specified that the user's input be treated as a literal string
+ rather than as an RE.
+
+
+
+
+ Regular Expression Matching Rules
+
+
+ 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 greedy or
+ non-greedy.
+
+
+
+ Whether an RE is greedy or not is determined by the following rules:
+
+
+
+ Most atoms, and all constraints, have no greediness attribute (because
+ they cannot match variable amounts of text anyway).
+
+
+
+
+ Adding parentheses around an RE does not change its greediness.
+
+
+
+
+ A quantified atom with a fixed-repetition quantifier
+ ({m}
+ or
+ {m}?)
+ has the same greediness (possibly none) as the atom itself.
+
+
+
+
+ A quantified atom with other normal quantifiers (including
+ {m,n}
+ with m equal to n)
+ is greedy (prefers longest match).
+
+
+
+
+ A quantified atom with a non-greedy quantifier (including
+ {m,n}?
+ with m equal to n)
+ is non-greedy (prefers shortest match).
+
+
+
+
+ A branch — that is, an RE that has no top-level
+ | operator — has the same greediness as the first
+ quantified atom in it that has a greediness attribute.
+
+
+
+
+ An RE consisting of two or more branches connected by the
+ | operator is always greedy.
+
+
+
+
+
+
+ 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 as a whole. 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.
+
+
+
+ An example of what this means:
+
+SELECT SUBSTRING('XY1234Z', 'Y*([0-9]{1,3})');
+Result: 123
+SELECT SUBSTRING('XY1234Z', 'Y*?([0-9]{1,3})');
+Result: 1
+
+ In the first case, the RE as a whole is greedy because Y*
+ is greedy. It can match beginning at the Y, and it matches
+ the longest possible string starting there, i.e., Y123.
+ The output is the parenthesized part of that, or 123.
+ In the second case, the RE as a whole is non-greedy because Y*?
+ is non-greedy. It can match beginning at the Y, and it matches
+ the shortest possible string starting there, i.e., Y1.
+ The subexpression [0-9]{1,3} is greedy but it cannot change
+ the decision as to the overall match length; so it is forced to match
+ just 1.
+
+
+
+ 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 eat relative to each other.
+
+
+
+ The quantifiers {1,1} and {1,1}?
+ 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:
+
+SELECT regexp_match('abc01234xyz', '(.*)(\d+)(.*)');
+Result: {abc0123,4,xyz}
+
+ That didn't work: the first .* is greedy so
+ it eats as much as it can, leaving the \d+ to
+ match at the last possible place, the last digit. We might try to fix
+ that by making it non-greedy:
+
+SELECT regexp_match('abc01234xyz', '(.*?)(\d+)(.*)');
+Result: {abc,0,""}
+
+ 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:
+
+SELECT regexp_match('abc01234xyz', '(?:(.*?)(\d+)(.*)){1,1}');
+Result: {abc,01234,xyz}
+
+ Controlling the RE's overall greediness separately from its components'
+ greediness allows great flexibility in handling variable-length patterns.
+
+
+
+ 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:
+ bb*
+ matches the three middle characters of abbbc;
+ (week|wee)(night|knights)
+ matches all ten characters of weeknights;
+ when (.*).*
+ is matched against abc the parenthesized subexpression
+ matches all three characters; and when
+ (a*)* is matched against bc
+ both the whole RE and the parenthesized
+ subexpression match an empty string.
+
+
+
+ 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., x becomes [xX].
+ When it appears inside a bracket expression, all case counterparts
+ of it are added to the bracket expression, e.g.,
+ [x] becomes [xX]
+ and [^x] becomes [^xX].
+
+
+
+ If newline-sensitive matching is specified, .
+ and bracket expressions using ^
+ will never match the newline character
+ (so that matches will not cross lines unless the RE
+ explicitly includes a newline)
+ and ^ and $
+ 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 \A and \Z
+ continue to match beginning or end of string only.
+ Also, the character class shorthands \D
+ and \W will match a newline regardless of this mode.
+ (Before PostgreSQL 14, they did not match
+ newlines when in newline-sensitive mode.
+ Write [^[:digit:]]
+ or [^[:word:]] to get the old behavior.)
+
+
+
+ If partial newline-sensitive matching is specified,
+ this affects . and bracket expressions
+ as with newline-sensitive matching, but not ^
+ and $.
+
+
+
+ If inverse partial newline-sensitive matching is specified,
+ this affects ^ and $
+ as with newline-sensitive matching, but not .
+ and bracket expressions.
+ This isn't very useful but is provided for symmetry.
+
+
+
+
+ Limits and Compatibility
+
+
+ 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.
+
+
+
+ The only feature of AREs that is actually incompatible with
+ POSIX EREs is that \ 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 *** syntax of directors likewise is outside the POSIX
+ syntax for both BREs and EREs.
+
+
+
+ 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 \b, \B,
+ 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.
+
+
+
+
+ Basic Regular Expressions
+
+
+ BREs differ from EREs in several respects.
+ In BREs, |, +, and ?
+ are ordinary characters and there is no equivalent
+ for their functionality.
+ The delimiters for bounds are
+ \{ and \},
+ with { and }
+ by themselves ordinary characters.
+ The parentheses for nested subexpressions are
+ \( and \),
+ with ( and ) by themselves ordinary characters.
+ ^ is an ordinary character except at the beginning of the
+ RE or the beginning of a parenthesized subexpression,
+ $ is an ordinary character except at the end of the
+ RE or the end of a parenthesized subexpression,
+ and * is an ordinary character if it appears at the beginning
+ of the RE or the beginning of a parenthesized subexpression
+ (after a possible leading ^).
+ Finally, single-digit back references are available, and
+ \< and \>
+ are synonyms for
+ [[:<:]] and [[:>:]]
+ respectively; no other escapes are available in BREs.
+
+
+
+
+
+
+ Differences from SQL Standard and XQuery
+
+
+ LIKE_REGEX
+
+
+
+ OCCURRENCES_REGEX
+
+
+
+ POSITION_REGEX
+
+
+
+ SUBSTRING_REGEX
+
+
+
+ TRANSLATE_REGEX
+
+
+
+ XQuery regular expressions
+
+
+
+ Since SQL:2008, the SQL standard includes regular expression operators
+ and functions that performs pattern
+ matching according to the XQuery regular expression
+ standard:
+
+ LIKE_REGEX
+ OCCURRENCES_REGEX
+ POSITION_REGEX
+ SUBSTRING_REGEX
+ TRANSLATE_REGEX
+
+ PostgreSQL does not currently implement these
+ operators and functions. You can get approximately equivalent
+ functionality in each case as shown in . (Various optional clauses on
+ both sides have been omitted in this table.)
+
+
+
+
+
+ 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.
+
+
+
+ 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:
+
+
+
+
+ XQuery character class subtraction is not supported. An example of
+ this feature is using the following to match only English
+ consonants: [a-z-[aeiou]].
+
+
+
+
+ XQuery character class shorthands \c,
+ \C, \i,
+ and \I are not supported.
+
+
+
+
+ XQuery character class elements
+ using \p{UnicodeProperty} or the
+ inverse \P{UnicodeProperty} are not supported.
+
+
+
+
+ POSIX interprets character classes such as \w
+ (see )
+ according to the prevailing locale (which you can control by
+ attaching a COLLATE 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.
+
+
+
+
+ The SQL standard (not XQuery itself) attempts to cater for more
+ variants of newline than POSIX does. The
+ newline-sensitive matching options described above consider only
+ ASCII NL (\n) to be a newline, but SQL would have
+ us treat CR (\r), CRLF (\r\n)
+ (a Windows-style newline), and some Unicode-only characters like
+ LINE SEPARATOR (U+2028) as newlines as well.
+ Notably, . and \s should
+ count \r\n as one character not two according to
+ SQL.
+
+
+
+
+ Of the character-entry escapes described in
+ ,
+ XQuery supports only \n, \r,
+ and \t.
+
+
+
+
+ XQuery does not support
+ the [:name:] syntax
+ for character classes within bracket expressions.
+
+
+
+
+ XQuery does not have lookahead or lookbehind constraints,
+ nor any of the constraint escapes described in
+ .
+
+
+
+
+ The metasyntax forms described in
+ do not exist in XQuery.
+
+
+
+
+ The regular expression flag letters defined by XQuery are
+ related to but not the same as the option letters for POSIX
+ (). While the
+ i and q options behave the
+ same, others do not:
+
+
+
+ XQuery's s (allow dot to match newline)
+ and m (allow ^
+ and $ to match at newlines) flags provide
+ access to the same behaviors as
+ POSIX's n, p
+ and w flags, but they
+ do not match the behavior of
+ POSIX's s and m flags.
+ Note in particular that dot-matches-newline is the default
+ behavior in POSIX but not XQuery.
+
+
+
+
+ XQuery's x (ignore whitespace in pattern) flag
+ is noticeably different from POSIX's expanded-mode flag.
+ POSIX's x flag also
+ allows # to begin a comment in the pattern,
+ and POSIX will not ignore a whitespace character after a
+ backslash.
+
+
+
+
+
+
+
+
+
+
+
diff --git a/doc/src/sgml/func/func-math.sgml b/doc/src/sgml/func/func-math.sgml
new file mode 100644
index 0000000000000..9dcf97e7c9e06
--- /dev/null
+++ b/doc/src/sgml/func/func-math.sgml
@@ -0,0 +1,1616 @@
+
+ Mathematical Functions and Operators
+
+
+ Mathematical operators are provided for many
+ PostgreSQL types. For types without
+ standard mathematical conventions
+ (e.g., date/time types) we
+ describe the actual behavior in subsequent sections.
+
+
+
+ shows the mathematical
+ operators that are available for the standard numeric types.
+ Unless otherwise noted, operators shown as
+ accepting numeric_type are available for all
+ the types smallint, integer,
+ bigint, numeric, real,
+ and double precision.
+ Operators shown as accepting integral_type
+ are available for the types smallint, integer,
+ and bigint.
+ 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 integer+numeric,
+ are resolved by using the type appearing later in these lists.
+
+
+
+
+
+ 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 double precision 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.
+
+
+
+ Mathematical Functions
+
+
+
+
+ Function
+
+
+ Description
+
+
+ Example(s)
+
+
+
+
+
+
+
+
+ abs
+
+ abs ( numeric_type )
+ numeric_type
+
+
+ Absolute value
+
+
+ abs(-17.4)
+ 17.4
+
+
+
+
+
+
+ cbrt
+
+ cbrt ( double precision )
+ double precision
+
+
+ Cube root
+
+
+ cbrt(64.0)
+ 4
+
+
+
+
+
+
+ ceil
+
+ ceil ( numeric )
+ numeric
+
+
+ ceil ( double precision )
+ double precision
+
+
+ Nearest integer greater than or equal to argument
+
+
+ ceil(42.2)
+ 43
+
+
+ ceil(-42.8)
+ -42
+
+
+
+
+
+
+ ceiling
+
+ ceiling ( numeric )
+ numeric
+
+
+ ceiling ( double precision )
+ double precision
+
+
+ Nearest integer greater than or equal to argument (same
+ as ceil)
+
+
+ ceiling(95.3)
+ 96
+
+
+
+
+
+
+ degrees
+
+ degrees ( double precision )
+ double precision
+
+
+ Converts radians to degrees
+
+
+ degrees(0.5)
+ 28.64788975654116
+
+
+
+
+
+
+ div
+
+ div ( ynumeric,
+ xnumeric )
+ numeric
+
+
+ Integer quotient of y/x
+ (truncates towards zero)
+
+
+ div(9, 4)
+ 2
+
+
+
+
+
+
+ erf
+
+ erf ( double precision )
+ double precision
+
+
+ Error function
+
+
+ erf(1.0)
+ 0.8427007929497149
+
+
+
+
+
+
+ erfc
+
+ erfc ( double precision )
+ double precision
+
+
+ Complementary error function (1 - erf(x), without
+ loss of precision for large inputs)
+
+
+ erfc(1.0)
+ 0.15729920705028513
+
+
+
+
+
+
+ exp
+
+ exp ( numeric )
+ numeric
+
+
+ exp ( double precision )
+ double precision
+
+
+ Exponential (e raised to the given power)
+
+
+ exp(1.0)
+ 2.7182818284590452
+
+
+
+
+
+
+ factorial
+
+ factorial ( bigint )
+ numeric
+
+
+ Factorial
+
+
+ factorial(5)
+ 120
+
+
+
+
+
+
+ floor
+
+ floor ( numeric )
+ numeric
+
+
+ floor ( double precision )
+ double precision
+
+
+ Nearest integer less than or equal to argument
+
+
+ floor(42.8)
+ 42
+
+
+ floor(-42.8)
+ -43
+
+
+
+
+
+
+ gamma
+
+ gamma ( double precision )
+ double precision
+
+
+ Gamma function
+
+
+ gamma(0.5)
+ 1.772453850905516
+
+
+ gamma(6)
+ 120
+
+
+
+
+
+
+ gcd
+
+ gcd ( numeric_type, numeric_type )
+ numeric_type
+
+
+ Greatest common divisor (the largest positive number that divides both
+ inputs with no remainder); returns 0 if both inputs
+ are zero; available for integer, bigint,
+ and numeric
+
+
+ gcd(1071, 462)
+ 21
+
+
+
+
+
+
+ lcm
+
+ lcm ( numeric_type, numeric_type )
+ numeric_type
+
+
+ Least common multiple (the smallest strictly positive number that is
+ an integral multiple of both inputs); returns 0 if
+ either input is zero; available for integer,
+ bigint, and numeric
+
+
+ lcm(1071, 462)
+ 23562
+
+
+
+
+
+
+ lgamma
+
+ lgamma ( double precision )
+ double precision
+
+
+ Natural logarithm of the absolute value of the gamma function
+
+
+ lgamma(1000)
+ 5905.220423209181
+
+
+
+
+
+
+ ln
+
+ ln ( numeric )
+ numeric
+
+
+ ln ( double precision )
+ double precision
+
+
+ Natural logarithm
+
+
+ ln(2.0)
+ 0.6931471805599453
+
+
+
+
+
+
+ log
+
+ log ( numeric )
+ numeric
+
+
+ log ( double precision )
+ double precision
+
+
+ Base 10 logarithm
+
+
+ log(100)
+ 2
+
+
+
+
+
+
+ log10
+
+ log10 ( numeric )
+ numeric
+
+
+ log10 ( double precision )
+ double precision
+
+
+ Base 10 logarithm (same as log)
+
+
+ log10(1000)
+ 3
+
+
+
+
+
+ log ( bnumeric,
+ xnumeric )
+ numeric
+
+
+ Logarithm of x to base b
+
+
+ log(2.0, 64.0)
+ 6.0000000000000000
+
+
+
+
+
+
+ min_scale
+
+ min_scale ( numeric )
+ integer
+
+
+ Minimum scale (number of fractional decimal digits) needed
+ to represent the supplied value precisely
+
+
+ min_scale(8.4100)
+ 2
+
+
+
+
+
+
+ mod
+
+ mod ( ynumeric_type,
+ xnumeric_type )
+ numeric_type
+
+
+ Remainder of y/x;
+ available for smallint, integer,
+ bigint, and numeric
+
+
+ mod(9, 4)
+ 1
+
+
+
+
+
+
+ pi
+
+ pi ( )
+ double precision
+
+
+ Approximate value of π
+
+
+ pi()
+ 3.141592653589793
+
+
+
+
+
+
+ power
+
+ power ( anumeric,
+ bnumeric )
+ numeric
+
+
+ power ( adouble precision,
+ bdouble precision )
+ double precision
+
+
+ a raised to the power of b
+
+
+ power(9, 3)
+ 729
+
+
+
+
+
+
+ radians
+
+ radians ( double precision )
+ double precision
+
+
+ Converts degrees to radians
+
+
+ radians(45.0)
+ 0.7853981633974483
+
+
+
+
+
+
+ round
+
+ round ( numeric )
+ numeric
+
+
+ round ( double precision )
+ double precision
+
+
+ Rounds to nearest integer. For numeric, ties are
+ broken by rounding away from zero. For double precision,
+ the tie-breaking behavior is platform dependent, but
+ round to nearest even is the most common rule.
+
+
+ round(42.4)
+ 42
+
+
+
+
+
+ round ( vnumeric, sinteger )
+ numeric
+
+
+ Rounds v to s decimal
+ places. Ties are broken by rounding away from zero.
+
+
+ round(42.4382, 2)
+ 42.44
+
+
+ round(1234.56, -1)
+ 1230
+
+
+
+
+
+
+ scale
+
+ scale ( numeric )
+ integer
+
+
+ Scale of the argument (the number of decimal digits in the fractional part)
+
+
+ scale(8.4100)
+ 4
+
+
+
+
+
+
+ sign
+
+ sign ( numeric )
+ numeric
+
+
+ sign ( double precision )
+ double precision
+
+
+ Sign of the argument (-1, 0, or +1)
+
+
+ sign(-8.4)
+ -1
+
+
+
+
+
+
+ sqrt
+
+ sqrt ( numeric )
+ numeric
+
+
+ sqrt ( double precision )
+ double precision
+
+
+ Square root
+
+
+ sqrt(2)
+ 1.4142135623730951
+
+
+
+
+
+
+ trim_scale
+
+ trim_scale ( numeric )
+ numeric
+
+
+ Reduces the value's scale (number of fractional decimal digits) by
+ removing trailing zeroes
+
+
+ trim_scale(8.4100)
+ 8.41
+
+
+
+
+
+
+ trunc
+
+ trunc ( numeric )
+ numeric
+
+
+ trunc ( double precision )
+ double precision
+
+
+ Truncates to integer (towards zero)
+
+
+ trunc(42.8)
+ 42
+
+
+ trunc(-42.8)
+ -42
+
+
+
+
+
+ trunc ( vnumeric, sinteger )
+ numeric
+
+
+ Truncates v to s
+ decimal places
+
+
+ trunc(42.4382, 2)
+ 42.43
+
+
+
+
+
+
+ width_bucket
+
+ width_bucket ( operandnumeric, lownumeric, highnumeric, countinteger )
+ integer
+
+
+ width_bucket ( operanddouble precision, lowdouble precision, highdouble precision, countinteger )
+ integer
+
+
+ Returns the number of the bucket in
+ which operand falls in a histogram
+ having count equal-width buckets spanning the
+ range low to high.
+ The buckets have inclusive lower bounds and exclusive upper bounds.
+ Returns 0 for an input less
+ than low,
+ or count+1 for an input
+ greater than or equal to high.
+ If low > high,
+ the behavior is mirror-reversed, with bucket 1
+ now being the one just below low, and the
+ inclusive bounds now being on the upper side.
+
+
+ width_bucket(5.35, 0.024, 10.06, 5)
+ 3
+
+
+ width_bucket(9, 10, 0, 10)
+ 2
+
+
+
+
+
+ width_bucket ( operandanycompatible, thresholdsanycompatiblearray )
+ integer
+
+
+ Returns the number of the bucket in
+ which operand falls given an array listing the
+ inclusive lower bounds of the buckets.
+ Returns 0 for an input less than the first lower
+ bound. operand and the array elements can be
+ of any type having standard comparison operators.
+ The thresholds array must be
+ sorted, smallest first, or unexpected results will be
+ obtained.
+
+
+ width_bucket(now(), array['yesterday', 'today', 'tomorrow']::timestamptz[])
+ 2
+
+
+
+
+
+
+
+ shows functions for
+ generating random numbers.
+
+
+
+ Random Functions
+
+
+
+
+
+ Function
+
+
+ Description
+
+
+ Example(s)
+
+
+
+
+
+
+
+
+ random
+
+ random ( )
+ double precision
+
+
+ Returns a random value in the range 0.0 <= x < 1.0
+
+
+ random()
+ 0.897124072839091
+
+
+
+
+
+
+ random
+
+ random ( mininteger, maxinteger )
+ integer
+
+
+ random ( minbigint, maxbigint )
+ bigint
+
+
+ random ( minnumeric, maxnumeric )
+ numeric
+
+
+ Returns a random value in the range
+ min <= x <= max.
+ For type numeric, the result will have the same number of
+ fractional decimal digits as min or
+ max, whichever has more.
+
+
+ random(1, 10)
+ 7
+
+
+ random(-0.499, 0.499)
+ 0.347
+
+
+
+
+
+
+ random_normal
+
+
+ random_normal (
+ meandouble precision
+ , stddevdouble precision )
+ double precision
+
+
+ Returns a random value from the normal distribution with the given
+ parameters; mean defaults to 0.0
+ and stddev defaults to 1.0
+
+
+ random_normal(0.0, 1.0)
+ 0.051285419
+
+
+
+
+
+
+ setseed
+
+ setseed ( double precision )
+ void
+
+
+ Sets the seed for subsequent random() and
+ random_normal() calls;
+ argument must be between -1.0 and 1.0, inclusive
+
+
+ setseed(0.12345)
+
+
+
+
+
+
+
+ The random() and random_normal()
+ functions listed in and
+ use a
+ deterministic pseudo-random number generator.
+ It is fast but not suitable for cryptographic
+ applications; see the module for a more
+ secure alternative.
+ If setseed() is called, the series of results of
+ subsequent calls to these functions in the current session
+ can be repeated by re-issuing setseed() with the same
+ argument.
+ Without any prior setseed() call in the same
+ session, the first call to any of these functions obtains a seed
+ from a platform-dependent source of random bits.
+
+
+
+ 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.
+
+
+
+
+
+
+ Another way to work with angles measured in degrees is to use the unit
+ transformation functions radians()
+ and degrees() shown earlier.
+ However, using the degree-based trigonometric functions is preferred,
+ as that way avoids round-off error for special cases such
+ as sind(30).
+
+
+
+
+ shows the
+ available hyperbolic functions.
+
+
+
+
+
diff --git a/doc/src/sgml/func/func-merge-support.sgml b/doc/src/sgml/func/func-merge-support.sgml
new file mode 100644
index 0000000000000..7f084271c13ae
--- /dev/null
+++ b/doc/src/sgml/func/func-merge-support.sgml
@@ -0,0 +1,78 @@
+
+ Merge Support Functions
+
+
+ MERGE
+ RETURNING
+
+
+
+ PostgreSQL includes one merge support function
+ that may be used in the RETURNING list of a
+ command to identify the action taken for each
+ row; see .
+
+
+
+ Merge Support Functions
+
+
+
+
+
+ Function
+
+
+ Description
+
+
+
+
+
+
+
+
+ merge_action
+
+ merge_action ( )
+ text
+
+
+ Returns the merge action command executed for the current row. This
+ will be 'INSERT', 'UPDATE', or
+ 'DELETE'.
+
+
+
+
+
+
+
+ Example:
+ 0 THEN
+ UPDATE SET in_stock = true, quantity = s.quantity
+ WHEN MATCHED THEN
+ UPDATE SET in_stock = false, quantity = 0
+ WHEN NOT MATCHED THEN
+ INSERT (product_id, in_stock, quantity)
+ VALUES (s.product_id, true, s.quantity)
+ RETURNING merge_action(), p.*;
+
+ merge_action | product_id | in_stock | quantity
+--------------+------------+----------+----------
+ UPDATE | 1001 | t | 50
+ UPDATE | 1002 | f | 0
+ INSERT | 1003 | t | 10
+]]>
+
+
+
+ Note that this function can only be used in the RETURNING
+ list of a MERGE command. It is an error to use it in any
+ other part of a query.
+
+
+
diff --git a/doc/src/sgml/func/func-net.sgml b/doc/src/sgml/func/func-net.sgml
new file mode 100644
index 0000000000000..1361a44c19767
--- /dev/null
+++ b/doc/src/sgml/func/func-net.sgml
@@ -0,0 +1,592 @@
+
+ Network Address Functions and Operators
+
+
+ The IP network address types, cidr and inet,
+ support the usual comparison operators shown in
+
+ as well as the specialized operators and functions shown in
+ and
+ .
+
+
+
+ Any cidr value can be cast to inet implicitly;
+ therefore, the operators and functions shown below as operating on
+ inet also work on cidr values. (Where there are
+ separate functions for inet and cidr, it is
+ because the behavior should be different for the two cases.)
+ Also, it is permitted to cast an inet value
+ to cidr. When this is done, any bits to the right of the
+ netmask are silently zeroed to create a valid cidr value.
+
+
+
+ IP Address Operators
+
+
+
+
+ Operator
+
+
+ Description
+
+
+ Example(s)
+
+
+
+
+
+
+
+ inet<<inet
+ boolean
+
+
+ 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.
+
+
+ inet '192.168.1.5' << inet '192.168.1/24'
+ t
+
+
+ inet '192.168.0.5' << inet '192.168.1/24'
+ f
+
+
+ inet '192.168.1/24' << inet '192.168.1/24'
+ f
+
+
+
+
+
+ inet<<=inet
+ boolean
+
+
+ Is subnet contained by or equal to subnet?
+
+
+ inet '192.168.1/24' <<= inet '192.168.1/24'
+ t
+
+
+
+
+
+ inet>>inet
+ boolean
+
+
+ Does subnet strictly contain subnet?
+
+
+ inet '192.168.1/24' >> inet '192.168.1.5'
+ t
+
+
+
+
+
+ inet>>=inet
+ boolean
+
+
+ Does subnet contain or equal subnet?
+
+
+ inet '192.168.1/24' >>= inet '192.168.1/24'
+ t
+
+
+
+
+
+ inet&&inet
+ boolean
+
+
+ Does either subnet contain or equal the other?
+
+
+ inet '192.168.1/24' && inet '192.168.1.80/28'
+ t
+
+
+ inet '192.168.1/24' && inet '192.168.2.0/28'
+ f
+
+
+
+
+
+ ~inet
+ inet
+
+
+ Computes bitwise NOT.
+
+
+ ~ inet '192.168.1.6'
+ 63.87.254.249
+
+
+
+
+
+ inet&inet
+ inet
+
+
+ Computes bitwise AND.
+
+
+ inet '192.168.1.6' & inet '0.0.0.255'
+ 0.0.0.6
+
+
+
+
+
+ inet|inet
+ inet
+
+
+ Computes bitwise OR.
+
+
+ inet '192.168.1.6' | inet '0.0.0.255'
+ 192.168.1.255
+
+
+
+
+
+ inet+bigint
+ inet
+
+
+ Adds an offset to an address.
+
+
+ inet '192.168.1.6' + 25
+ 192.168.1.31
+
+
+
+
+
+ bigint+inet
+ inet
+
+
+ Adds an offset to an address.
+
+
+ 200 + inet '::ffff:fff0:1'
+ ::ffff:255.240.0.201
+
+
+
+
+
+ inet-bigint
+ inet
+
+
+ Subtracts an offset from an address.
+
+
+ inet '192.168.1.43' - 36
+ 192.168.1.7
+
+
+
+
+
+ inet-inet
+ bigint
+
+
+ Computes the difference of two addresses.
+
+
+ inet '192.168.1.43' - inet '192.168.1.19'
+ 24
+
+
+ inet '::1' - inet '::ffff:1'
+ -4294901760
+
+
+
+
+
+
+
+ IP Address Functions
+
+
+
+
+ Function
+
+
+ Description
+
+
+ Example(s)
+
+
+
+
+
+
+
+
+ abbrev
+
+ abbrev ( inet )
+ text
+
+
+ Creates an abbreviated display format as text.
+ (The result is the same as the inet output function
+ produces; it is abbreviated only in comparison to the
+ result of an explicit cast to text, which for historical
+ reasons will never suppress the netmask part.)
+
+
+ abbrev(inet '10.1.0.0/32')
+ 10.1.0.0
+
+
+
+
+
+ abbrev ( cidr )
+ text
+
+
+ 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
+ .)
+
+
+ abbrev(cidr '10.1.0.0/16')
+ 10.1/16
+
+
+
+
+
+
+ broadcast
+
+ broadcast ( inet )
+ inet
+
+
+ Computes the broadcast address for the address's network.
+
+
+ broadcast(inet '192.168.1.5/24')
+ 192.168.1.255/24
+
+
+
+
+
+
+ family
+
+ family ( inet )
+ integer
+
+
+ Returns the address's family: 4 for IPv4,
+ 6 for IPv6.
+
+
+ family(inet '::1')
+ 6
+
+
+
+
+
+
+ host
+
+ host ( inet )
+ text
+
+
+ Returns the IP address as text, ignoring the netmask.
+
+
+ host(inet '192.168.1.0/24')
+ 192.168.1.0
+
+
+
+
+
+
+ hostmask
+
+ hostmask ( inet )
+ inet
+
+
+ Computes the host mask for the address's network.
+
+
+ hostmask(inet '192.168.23.20/30')
+ 0.0.0.3
+
+
+
+
+
+
+ inet_merge
+
+ inet_merge ( inet, inet )
+ cidr
+
+
+ Computes the smallest network that includes both of the given networks.
+
+
+ inet_merge(inet '192.168.1.5/24', inet '192.168.2.5/24')
+ 192.168.0.0/22
+
+
+
+
+
+
+ inet_same_family
+
+ inet_same_family ( inet, inet )
+ boolean
+
+
+ Tests whether the addresses belong to the same IP family.
+
+
+ inet_same_family(inet '192.168.1.5/24', inet '::1')
+ f
+
+
+
+
+
+
+ masklen
+
+ masklen ( inet )
+ integer
+
+
+ Returns the netmask length in bits.
+
+
+ masklen(inet '192.168.1.5/24')
+ 24
+
+
+
+
+
+
+ netmask
+
+ netmask ( inet )
+ inet
+
+
+ Computes the network mask for the address's network.
+
+
+ netmask(inet '192.168.1.5/24')
+ 255.255.255.0
+
+
+
+
+
+
+ network
+
+ network ( inet )
+ cidr
+
+
+ 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 cidr.)
+
+
+ network(inet '192.168.1.5/24')
+ 192.168.1.0/24
+
+
+
+
+
+
+ set_masklen
+
+ set_masklen ( inet, integer )
+ inet
+
+
+ Sets the netmask length for an inet value.
+ The address part does not change.
+
+
+ set_masklen(inet '192.168.1.5/24', 16)
+ 192.168.1.5/16
+
+
+
+
+
+ set_masklen ( cidr, integer )
+ cidr
+
+
+ Sets the netmask length for a cidr value.
+ Address bits to the right of the new netmask are set to zero.
+
+
+ set_masklen(cidr '192.168.1.0/24', 16)
+ 192.168.0.0/16
+
+
+
+
+
+
+ text
+
+ text ( inet )
+ text
+
+
+ Returns the unabbreviated IP address and netmask length as text.
+ (This has the same result as an explicit cast to text.)
+
+
+ text(inet '192.168.1.5')
+ 192.168.1.5/32
+
+
+
+
+
+
+
+
+ The abbrev, host,
+ and text functions are primarily intended to offer
+ alternative display formats for IP addresses.
+
+
+
+
+ The MAC address types, macaddr and macaddr8,
+ support the usual comparison operators shown in
+
+ as well as the specialized functions shown in
+ .
+ In addition, they support the bitwise logical operators
+ ~, & and |
+ (NOT, AND and OR), just as shown above for IP addresses.
+
+
+
+ MAC Address Functions
+
+
+
+
+ Function
+
+
+ Description
+
+
+ Example(s)
+
+
+
+
+
+
+
+
+ trunc
+
+ trunc ( macaddr )
+ macaddr
+
+
+ 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 PostgreSQL).
+
+
+ trunc(macaddr '12:34:56:78:90:ab')
+ 12:34:56:00:00:00
+
+
+
+
+
+ trunc ( macaddr8 )
+ macaddr8
+
+
+ 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 PostgreSQL).
+
+
+ trunc(macaddr8 '12:34:56:78:90:ab:cd:ef')
+ 12:34:56:00:00:00:00:00
+
+
+
+
+
+
+ macaddr8_set7bit
+
+ macaddr8_set7bit ( macaddr8 )
+ macaddr8
+
+
+ Sets the 7th bit of the address to one, creating what is known as
+ modified EUI-64, for inclusion in an IPv6 address.
+
+
+ macaddr8_set7bit(macaddr8 '00:34:56:ab:cd:ef')
+ 02:34:56:ff:fe:ab:cd:ef
+
+
+
+
+
+
+
diff --git a/doc/src/sgml/func/func-range.sgml b/doc/src/sgml/func/func-range.sgml
new file mode 100644
index 0000000000000..2dc40348a57f4
--- /dev/null
+++ b/doc/src/sgml/func/func-range.sgml
@@ -0,0 +1,1053 @@
+
+ Range/Multirange Functions and Operators
+
+
+ See for an overview of range types.
+
+
+
+ shows the specialized operators
+ available for range types.
+ shows the specialized operators
+ available for multirange types.
+ In addition to those, the usual comparison operators shown in
+ 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.
+
+
+
+ Range Operators
+
+
+
+
+ Operator
+
+
+ Description
+
+
+ Example(s)
+
+
+
+
+
+
+
+ anyrange@>anyrange
+ boolean
+
+
+ Does the first range contain the second?
+
+
+ int4range(2,4) @> int4range(2,3)
+ t
+
+
+
+
+
+ anyrange@>anyelement
+ boolean
+
+
+ Does the range contain the element?
+
+
+ '[2011-01-01,2011-03-01)'::tsrange @> '2011-01-10'::timestamp
+ t
+
+
+
+
+
+ anyrange<@anyrange
+ boolean
+
+
+ Is the first range contained by the second?
+
+
+ int4range(2,4) <@ int4range(1,7)
+ t
+
+
+
+
+
+ anyelement<@anyrange
+ boolean
+
+
+ Is the element contained in the range?
+
+
+ 42 <@ int4range(1,7)
+ f
+
+
+
+
+
+ anyrange&&anyrange
+ boolean
+
+
+ Do the ranges overlap, that is, have any elements in common?
+
+
+ int8range(3,7) && int8range(4,12)
+ t
+
+
+
+
+
+ anyrange<<anyrange
+ boolean
+
+
+ Is the first range strictly left of the second?
+
+
+ int8range(1,10) << int8range(100,110)
+ t
+
+
+
+
+
+ anyrange>>anyrange
+ boolean
+
+
+ Is the first range strictly right of the second?
+
+
+ int8range(50,60) >> int8range(20,30)
+ t
+
+
+
+
+
+ anyrange&<anyrange
+ boolean
+
+
+ Does the first range not extend to the right of the second?
+
+
+ int8range(1,20) &< int8range(18,20)
+ t
+
+
+
+
+
+ anyrange&>anyrange
+ boolean
+
+
+ Does the first range not extend to the left of the second?
+
+
+ int8range(7,20) &> int8range(5,10)
+ t
+
+
+
+
+
+ anyrange-|-anyrange
+ boolean
+
+
+ Are the ranges adjacent?
+
+
+ numrange(1.1,2.2) -|- numrange(2.2,3.3)
+ t
+
+
+
+
+
+ anyrange+anyrange
+ anyrange
+
+
+ Computes the union of the ranges. The ranges must overlap or be
+ adjacent, so that the union is a single range (but
+ see range_merge()).
+
+
+ numrange(5,15) + numrange(10,20)
+ [5,20)
+
+
+
+
+
+ anyrange*anyrange
+ anyrange
+
+
+ Computes the intersection of the ranges.
+
+
+ int8range(5,15) * int8range(10,20)
+ [10,15)
+
+
+
+
+
+ anyrange-anyrange
+ anyrange
+
+
+ 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.
+
+
+ int8range(5,15) - int8range(10,20)
+ [5,10)
+
+
+
+
+
+
+
+ Multirange Operators
+
+
+
+
+ Operator
+
+
+ Description
+
+
+ Example(s)
+
+
+
+
+
+
+
+ anymultirange@>anymultirange
+ boolean
+
+
+ Does the first multirange contain the second?
+
+
+ '{[2,4)}'::int4multirange @> '{[2,3)}'::int4multirange
+ t
+
+
+
+
+
+ anymultirange@>anyrange
+ boolean
+
+
+ Does the multirange contain the range?
+
+
+ '{[2,4)}'::int4multirange @> int4range(2,3)
+ t
+
+
+
+
+
+ anymultirange@>anyelement
+ boolean
+
+
+ Does the multirange contain the element?
+
+
+ '{[2011-01-01,2011-03-01)}'::tsmultirange @> '2011-01-10'::timestamp
+ t
+
+
+
+
+
+ anyrange@>anymultirange
+ boolean
+
+
+ Does the range contain the multirange?
+
+
+ '[2,4)'::int4range @> '{[2,3)}'::int4multirange
+ t
+
+
+
+
+
+ anymultirange<@anymultirange
+ boolean
+
+
+ Is the first multirange contained by the second?
+
+
+ '{[2,4)}'::int4multirange <@ '{[1,7)}'::int4multirange
+ t
+
+
+
+
+
+ anymultirange<@anyrange
+ boolean
+
+
+ Is the multirange contained by the range?
+
+
+ '{[2,4)}'::int4multirange <@ int4range(1,7)
+ t
+
+
+
+
+
+ anyrange<@anymultirange
+ boolean
+
+
+ Is the range contained by the multirange?
+
+
+ int4range(2,4) <@ '{[1,7)}'::int4multirange
+ t
+
+
+
+
+
+ anyelement<@anymultirange
+ boolean
+
+
+ Is the element contained by the multirange?
+
+
+ 4 <@ '{[1,7)}'::int4multirange
+ t
+
+
+
+
+
+ anymultirange&&anymultirange
+ boolean
+
+
+ Do the multiranges overlap, that is, have any elements in common?
+
+
+ '{[3,7)}'::int8multirange && '{[4,12)}'::int8multirange
+ t
+
+
+
+
+
+ anymultirange&&anyrange
+ boolean
+
+
+ Does the multirange overlap the range?
+
+
+ '{[3,7)}'::int8multirange && int8range(4,12)
+ t
+
+
+
+
+
+ anyrange&&anymultirange
+ boolean
+
+
+ Does the range overlap the multirange?
+
+
+ int8range(3,7) && '{[4,12)}'::int8multirange
+ t
+
+
+
+
+
+ anymultirange<<anymultirange
+ boolean
+
+
+ Is the first multirange strictly left of the second?
+
+
+ '{[1,10)}'::int8multirange << '{[100,110)}'::int8multirange
+ t
+
+
+
+
+
+ anymultirange<<anyrange
+ boolean
+
+
+ Is the multirange strictly left of the range?
+
+
+ '{[1,10)}'::int8multirange << int8range(100,110)
+ t
+
+
+
+
+
+ anyrange<<anymultirange
+ boolean
+
+
+ Is the range strictly left of the multirange?
+
+
+ int8range(1,10) << '{[100,110)}'::int8multirange
+ t
+
+
+
+
+
+ anymultirange>>anymultirange
+ boolean
+
+
+ Is the first multirange strictly right of the second?
+
+
+ '{[50,60)}'::int8multirange >> '{[20,30)}'::int8multirange
+ t
+
+
+
+
+
+ anymultirange>>anyrange
+ boolean
+
+
+ Is the multirange strictly right of the range?
+
+
+ '{[50,60)}'::int8multirange >> int8range(20,30)
+ t
+
+
+
+
+
+ anyrange>>anymultirange
+ boolean
+
+
+ Is the range strictly right of the multirange?
+
+
+ int8range(50,60) >> '{[20,30)}'::int8multirange
+ t
+
+
+
+
+
+ anymultirange&<anymultirange
+ boolean
+
+
+ Does the first multirange not extend to the right of the second?
+
+
+ '{[1,20)}'::int8multirange &< '{[18,20)}'::int8multirange
+ t
+
+
+
+
+
+ anymultirange&<anyrange
+ boolean
+
+
+ Does the multirange not extend to the right of the range?
+
+
+ '{[1,20)}'::int8multirange &< int8range(18,20)
+ t
+
+
+
+
+
+ anyrange&<anymultirange
+ boolean
+
+
+ Does the range not extend to the right of the multirange?
+
+
+ int8range(1,20) &< '{[18,20)}'::int8multirange
+ t
+
+
+
+
+
+ anymultirange&>anymultirange
+ boolean
+
+
+ Does the first multirange not extend to the left of the second?
+
+
+ '{[7,20)}'::int8multirange &> '{[5,10)}'::int8multirange
+ t
+
+
+
+
+
+ anymultirange&>anyrange
+ boolean
+
+
+ Does the multirange not extend to the left of the range?
+
+
+ '{[7,20)}'::int8multirange &> int8range(5,10)
+ t
+
+
+
+
+
+ anyrange&>anymultirange
+ boolean
+
+
+ Does the range not extend to the left of the multirange?
+
+
+ int8range(7,20) &> '{[5,10)}'::int8multirange
+ t
+
+
+
+
+
+ anymultirange-|-anymultirange
+ boolean
+
+
+ Are the multiranges adjacent?
+
+
+ '{[1.1,2.2)}'::nummultirange -|- '{[2.2,3.3)}'::nummultirange
+ t
+
+
+
+
+
+ anymultirange-|-anyrange
+ boolean
+
+
+ Is the multirange adjacent to the range?
+
+
+ '{[1.1,2.2)}'::nummultirange -|- numrange(2.2,3.3)
+ t
+
+
+
+
+
+ anyrange-|-anymultirange
+ boolean
+
+
+ Is the range adjacent to the multirange?
+
+
+ numrange(1.1,2.2) -|- '{[2.2,3.3)}'::nummultirange
+ t
+
+
+
+
+
+ anymultirange+anymultirange
+ anymultirange
+
+
+ Computes the union of the multiranges. The multiranges need not overlap
+ or be adjacent.
+
+
+ '{[5,10)}'::nummultirange + '{[15,20)}'::nummultirange
+ {[5,10), [15,20)}
+
+
+
+
+
+ anymultirange*anymultirange
+ anymultirange
+
+
+ Computes the intersection of the multiranges.
+
+
+ '{[5,15)}'::int8multirange * '{[10,20)}'::int8multirange
+ {[10,15)}
+
+
+
+
+
+ anymultirange-anymultirange
+ anymultirange
+
+
+ Computes the difference of the multiranges.
+
+
+ '{[5,20)}'::int8multirange - '{[10,15)}'::int8multirange
+ {[5,10), [15,20)}
+
+
+
+
+
+
+
+ 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.
+
+
+
+ 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.
+
+
+
+ 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.
+
+
+
+ shows the functions
+ available for use with range types.
+ shows the functions
+ available for use with multirange types.
+
+
+
+ Range Functions
+
+
+
+
+ Function
+
+
+ Description
+
+
+ Example(s)
+
+
+
+
+
+
+
+
+ lower
+
+ lower ( anyrange )
+ anyelement
+
+
+ Extracts the lower bound of the range (NULL if the
+ range is empty or has no lower bound).
+
+
+ lower(numrange(1.1,2.2))
+ 1.1
+
+
+
+
+
+
+ upper
+
+ upper ( anyrange )
+ anyelement
+
+
+ Extracts the upper bound of the range (NULL if the
+ range is empty or has no upper bound).
+
+
+ upper(numrange(1.1,2.2))
+ 2.2
+
+
+
+
+
+
+ isempty
+
+ isempty ( anyrange )
+ boolean
+
+
+ Is the range empty?
+
+
+ isempty(numrange(1.1,2.2))
+ f
+
+
+
+
+
+
+ lower_inc
+
+ lower_inc ( anyrange )
+ boolean
+
+
+ Is the range's lower bound inclusive?
+
+
+ lower_inc(numrange(1.1,2.2))
+ t
+
+
+
+
+
+
+ upper_inc
+
+ upper_inc ( anyrange )
+ boolean
+
+
+ Is the range's upper bound inclusive?
+
+
+ upper_inc(numrange(1.1,2.2))
+ f
+
+
+
+
+
+
+ lower_inf
+
+ lower_inf ( anyrange )
+ boolean
+
+
+ Does the range have no lower bound? (A lower bound of
+ -Infinity returns false.)
+
+
+ lower_inf('(,)'::daterange)
+ t
+
+
+
+
+
+
+ upper_inf
+
+ upper_inf ( anyrange )
+ boolean
+
+
+ Does the range have no upper bound? (An upper bound of
+ Infinity returns false.)
+
+
+ upper_inf('(,)'::daterange)
+ t
+
+
+
+
+
+
+ range_merge
+
+ range_merge ( anyrange, anyrange )
+ anyrange
+
+
+ Computes the smallest range that includes both of the given ranges.
+
+
+ range_merge('[1,2)'::int4range, '[3,4)'::int4range)
+ [1,4)
+
+
+
+
+
+
+
+ Multirange Functions
+
+
+
+
+ Function
+
+
+ Description
+
+
+ Example(s)
+
+
+
+
+
+
+
+ lower
+
+ lower ( anymultirange )
+ anyelement
+
+
+ Extracts the lower bound of the multirange (NULL if the
+ multirange is empty or has no lower bound).
+
+
+ lower('{[1.1,2.2)}'::nummultirange)
+ 1.1
+
+
+
+
+
+
+ upper
+
+ upper ( anymultirange )
+ anyelement
+
+
+ Extracts the upper bound of the multirange (NULL if the
+ multirange is empty or has no upper bound).
+
+
+ upper('{[1.1,2.2)}'::nummultirange)
+ 2.2
+
+
+
+
+
+
+ isempty
+
+ isempty ( anymultirange )
+ boolean
+
+
+ Is the multirange empty?
+
+
+ isempty('{[1.1,2.2)}'::nummultirange)
+ f
+
+
+
+
+
+
+ lower_inc
+
+ lower_inc ( anymultirange )
+ boolean
+
+
+ Is the multirange's lower bound inclusive?
+
+
+ lower_inc('{[1.1,2.2)}'::nummultirange)
+ t
+
+
+
+
+
+
+ upper_inc
+
+ upper_inc ( anymultirange )
+ boolean
+
+
+ Is the multirange's upper bound inclusive?
+
+
+ upper_inc('{[1.1,2.2)}'::nummultirange)
+ f
+
+
+
+
+
+
+ lower_inf
+
+ lower_inf ( anymultirange )
+ boolean
+
+
+ Does the multirange have no lower bound? (A lower bound of
+ -Infinity returns false.)
+
+
+ lower_inf('{(,)}'::datemultirange)
+ t
+
+
+
+
+
+
+ upper_inf
+
+ upper_inf ( anymultirange )
+ boolean
+
+
+ Does the multirange have no upper bound? (An upper bound of
+ Infinity returns false.)
+
+
+ upper_inf('{(,)}'::datemultirange)
+ t
+
+
+
+
+
+
+ range_merge
+
+ range_merge ( anymultirange )
+ anyrange
+
+
+ Computes the smallest range that includes the entire multirange.
+
+
+ range_merge('{[1,2), [3,4)}'::int4multirange)
+ [1,4)
+
+
+
+
+
+
+ multirange (function)
+
+ multirange ( anyrange )
+ anymultirange
+
+
+ Returns a multirange containing just the given range.
+
+
+ multirange('[1,2)'::int4range)
+ {[1,2)}
+
+
+
+
+
+
+ unnest
+ for multirange
+
+ unnest ( anymultirange )
+ setof anyrange
+
+
+ Expands a multirange into a set of ranges in ascending order.
+
+
+ unnest('{[1,2), [3,4)}'::int4multirange)
+
+
+ [1,2)
+ [3,4)
+
+
+
+
+
+
+
+
+ The lower_inc, upper_inc,
+ lower_inf, and upper_inf
+ functions all return false for an empty range or multirange.
+
+
diff --git a/doc/src/sgml/func/func-sequence.sgml b/doc/src/sgml/func/func-sequence.sgml
new file mode 100644
index 0000000000000..e9f5b4e8e6b27
--- /dev/null
+++ b/doc/src/sgml/func/func-sequence.sgml
@@ -0,0 +1,195 @@
+
+ Sequence Manipulation Functions
+
+
+ sequence
+
+
+
+ This section describes functions for operating on sequence
+ objects, also called sequence generators or just sequences.
+ Sequence objects are special single-row tables created with .
+ Sequence objects are commonly used to generate unique identifiers
+ for rows of a table. The sequence functions, listed in , provide simple, multiuser-safe
+ methods for obtaining successive sequence values from sequence
+ objects.
+
+
+
+ Sequence Functions
+
+
+
+
+ Function
+
+
+ Description
+
+
+
+
+
+
+
+
+ nextval
+
+ nextval ( regclass )
+ bigint
+
+
+ Advances the sequence object to its next value and returns that value.
+ This is done atomically: even if multiple sessions
+ execute nextval concurrently, each will safely
+ receive a distinct sequence value.
+ If the sequence object has been created with default parameters,
+ successive nextval calls will return successive
+ values beginning with 1. Other behaviors can be obtained by using
+ appropriate parameters in the
+ command.
+
+
+ This function requires USAGE
+ or UPDATE privilege on the sequence.
+
+
+
+
+
+
+ setval
+
+ setval ( regclass, bigint, boolean )
+ bigint
+
+
+ Sets the sequence object's current value, and optionally
+ its is_called flag. The two-parameter
+ form sets the sequence's last_value field to the
+ specified value and sets its is_called field to
+ true, meaning that the next
+ nextval will advance the sequence before
+ returning a value. The value that will be reported
+ by currval is also set to the specified value.
+ In the three-parameter form, is_called can be set
+ to either true
+ or false. true has the same
+ effect as the two-parameter form. If it is set
+ to false, the next nextval
+ will return exactly the specified value, and sequence advancement
+ commences with the following nextval.
+ Furthermore, the value reported by currval is not
+ changed in this case. For example,
+
+SELECT setval('myseq', 42); Next nextval will return 43
+SELECT setval('myseq', 42, true); Same as above
+SELECT setval('myseq', 42, false); Next nextval will return 42
+
+ The result returned by setval is just the value of its
+ second argument.
+
+
+ This function requires UPDATE privilege on the
+ sequence.
+
+
+
+
+
+
+ currval
+
+ currval ( regclass )
+ bigint
+
+
+ Returns the value most recently obtained
+ by nextval for this sequence in the current
+ session. (An error is reported if nextval 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 nextval since
+ the current session did.
+
+
+ This function requires USAGE
+ or SELECT privilege on the sequence.
+
+
+
+
+
+
+ lastval
+
+ lastval ()
+ bigint
+
+
+ Returns the value most recently returned by
+ nextval in the current session. This function is
+ identical to currval, except that instead
+ of taking the sequence name as an argument it refers to whichever
+ sequence nextval was most recently applied to
+ in the current session. It is an error to call
+ lastval if nextval
+ has not yet been called in the current session.
+
+
+ This function requires USAGE
+ or SELECT privilege on the last used sequence.
+
+
+
+
+
+
+
+
+ To avoid blocking concurrent transactions that obtain numbers from
+ the same sequence, the value obtained by nextval
+ 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 INSERT with
+ an ON CONFLICT clause will compute the to-be-inserted
+ tuple, including doing any required nextval
+ calls, before detecting any conflict that would cause it to follow
+ the ON CONFLICT rule instead.
+ Thus, PostgreSQL sequence
+ objects cannot be used to obtain gapless
+ sequences.
+
+
+
+ Likewise, sequence state changes made by setval
+ are immediately visible to other transactions, and are not undone if
+ the calling transaction rolls back.
+
+
+
+ If the database cluster crashes before committing a transaction
+ containing a nextval
+ or setval 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
+ nextval call has been committed before doing so.
+
+
+
+
+ The sequence to be operated on by a sequence function is specified by
+ a regclass argument, which is simply the OID of the sequence in the
+ pg_class system catalog. You do not have to look up the
+ OID by hand, however, since the regclass data type's input
+ converter will do the work for you. See
+ for details.
+
+
diff --git a/doc/src/sgml/func/func-srf.sgml b/doc/src/sgml/func/func-srf.sgml
new file mode 100644
index 0000000000000..eafc961c9f909
--- /dev/null
+++ b/doc/src/sgml/func/func-srf.sgml
@@ -0,0 +1,306 @@
+
+ Set Returning Functions
+
+
+ set returning functions
+ functions
+
+
+
+ This section describes functions that possibly return more than one row.
+ The most widely used functions in this class are series generating
+ functions, as detailed in and
+ . Other, more specialized
+ set-returning functions are described elsewhere in this manual.
+ See for ways to combine multiple
+ set-returning functions.
+
+
+
+ Series Generating Functions
+
+
+
+
+ Function
+
+
+ Description
+
+
+
+
+
+
+
+
+ generate_series
+
+ generate_series ( startinteger, stopinteger, stepinteger )
+ setof integer
+
+
+ generate_series ( startbigint, stopbigint, stepbigint )
+ setof bigint
+
+
+ generate_series ( startnumeric, stopnumeric, stepnumeric )
+ setof numeric
+
+
+ Generates a series of values from start
+ to stop, with a step size
+ of step. step
+ defaults to 1.
+
+
+
+
+
+ generate_series ( starttimestamp, stoptimestamp, stepinterval )
+ setof timestamp
+
+
+ generate_series ( starttimestamp with time zone, stoptimestamp with time zone, stepinterval, timezonetext )
+ setof timestamp with time zone
+
+
+ Generates a series of values from start
+ to stop, with a step size
+ of step.
+ In the timezone-aware form, times of day and daylight-savings
+ adjustments are computed according to the time zone named by
+ the timezone argument, or the current
+ setting if that is omitted.
+
+
+
+
+
+
+
+ When step is positive, zero rows are returned if
+ start is greater than stop.
+ Conversely, when step is negative, zero rows are
+ returned if start is less than stop.
+ Zero rows are also returned if any input is NULL.
+ It is an error
+ for step to be zero. Some examples follow:
+
+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)
+
+-- this example assumes that TimeZone is set to UTC; note the DST transition:
+SELECT * FROM generate_series('2001-10-22 00:00 -04:00'::timestamptz,
+ '2001-11-01 00:00 -05:00'::timestamptz,
+ '1 day'::interval, 'America/New_York');
+ generate_series
+------------------------
+ 2001-10-22 04:00:00+00
+ 2001-10-23 04:00:00+00
+ 2001-10-24 04:00:00+00
+ 2001-10-25 04:00:00+00
+ 2001-10-26 04:00:00+00
+ 2001-10-27 04:00:00+00
+ 2001-10-28 04:00:00+00
+ 2001-10-29 05:00:00+00
+ 2001-10-30 05:00:00+00
+ 2001-10-31 05:00:00+00
+ 2001-11-01 05:00:00+00
+(11 rows)
+
+
+
+
+ Subscript Generating Functions
+
+
+
+
+ Function
+
+
+ Description
+
+
+
+
+
+
+
+
+ generate_subscripts
+
+ generate_subscripts ( arrayanyarray, diminteger )
+ setof integer
+
+
+ Generates a series comprising the valid subscripts of
+ the dim'th dimension of the given array.
+
+
+
+
+
+ generate_subscripts ( arrayanyarray, diminteger, reverseboolean )
+ setof integer
+
+
+ Generates a series comprising the valid subscripts of
+ the dim'th dimension of the given array.
+ When reverse is true, returns the series in
+ reverse order.
+
+
+
+
+
+
+
+ generate_subscripts 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 NULL.
+ Some examples follow:
+
+-- 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)
+
+
+
+
+ ordinality
+
+
+
+ When a function in the FROM clause is suffixed
+ by WITH ORDINALITY, a bigint 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 unnest().
+
+
+-- 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)
+
+
+
+
diff --git a/doc/src/sgml/func/func-statistics.sgml b/doc/src/sgml/func/func-statistics.sgml
new file mode 100644
index 0000000000000..22dee263cc2a0
--- /dev/null
+++ b/doc/src/sgml/func/func-statistics.sgml
@@ -0,0 +1,85 @@
+
+ Statistics Information Functions
+
+
+ function
+ statistics
+
+
+
+ PostgreSQL provides a function to inspect complex
+ statistics defined using the CREATE STATISTICS command.
+
+
+
+ Inspecting MCV Lists
+
+
+ pg_mcv_list_items
+
+
+
+pg_mcv_list_items ( pg_mcv_list ) setof record
+
+
+
+ pg_mcv_list_items returns a set of records describing
+ all items stored in a multi-column MCV list. It
+ returns the following columns:
+
+
+
+
+
+ Name
+ Type
+ Description
+
+
+
+
+
+ index
+ integer
+ index of the item in the MCV list
+
+
+ values
+ text[]
+ values stored in the MCV item
+
+
+ nulls
+ boolean[]
+ flags identifying NULL values
+
+
+ frequency
+ double precision
+ frequency of this MCV item
+
+
+ base_frequency
+ double precision
+ base frequency of this MCV item
+
+
+
+
+
+
+
+ The pg_mcv_list_items function can be used like this:
+
+
+SELECT m.* FROM pg_statistic_ext join pg_statistic_ext_data on (oid = stxoid),
+ pg_mcv_list_items(stxdmcv) m WHERE stxname = 'stts';
+
+
+ Values of the pg_mcv_list type can be obtained only from the
+ pg_statistic_ext_data.stxdmcv
+ column.
+
+
+
+
diff --git a/doc/src/sgml/func/func-string.sgml b/doc/src/sgml/func/func-string.sgml
new file mode 100644
index 0000000000000..01cc94c234e62
--- /dev/null
+++ b/doc/src/sgml/func/func-string.sgml
@@ -0,0 +1,1827 @@
+
+ String Functions and Operators
+
+
+ This section describes functions and operators for examining and
+ manipulating string values. Strings in this context include values
+ of the types character, character varying,
+ and text. Except where noted, these functions and operators
+ are declared to accept and return type text. They will
+ interchangeably accept character varying arguments.
+ Values of type character will be converted
+ to text before the function or operator is applied, resulting
+ in stripping any trailing spaces in the character value.
+
+
+
+ SQL defines some string functions that use
+ key words, rather than commas, to separate
+ arguments. Details are in
+ .
+ PostgreSQL also provides versions of these functions
+ that use the regular function invocation syntax
+ (see ).
+
+
+
+
+ The string concatenation operator (||) will accept
+ non-string input, so long as at least one input is of string type, as shown
+ in . For other cases, inserting an
+ explicit coercion to text can be used to have non-string input
+ accepted.
+
+
+
+
+ <acronym>SQL</acronym> String Functions and Operators
+
+
+
+
+ Function/Operator
+
+
+ Description
+
+
+ Example(s)
+
+
+
+
+
+
+
+
+ character string
+ concatenation
+
+ text||text
+ text
+
+
+ Concatenates the two strings.
+
+
+ 'Post' || 'greSQL'
+ PostgreSQL
+
+
+
+
+
+ text||anynonarray
+ text
+
+
+ anynonarray||text
+ text
+
+
+ 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 ||
+ operators. If you want to concatenate an array's text equivalent,
+ cast it to text explicitly.)
+
+
+ 'Value: ' || 42
+ Value: 42
+
+
+
+
+
+
+ btrim
+
+ btrim ( stringtext
+ , characterstext )
+ text
+
+
+ Removes the longest string containing only characters
+ in characters (a space by default)
+ from the start and end of string.
+
+
+ btrim('xyxtrimyyx', 'xyz')
+ trim
+
+
+
+
+
+
+ normalized
+
+
+ Unicode normalization
+
+ textISNOTformNORMALIZED
+ boolean
+
+
+ Checks whether the string is in the specified Unicode normalization
+ form. The optional form key word specifies the
+ form: NFC (the default), NFD,
+ NFKC, or NFKD. This expression can
+ only be used when the server encoding is UTF8. Note
+ that checking for normalization using this expression is often faster
+ than normalizing possibly already normalized strings.
+
+
+ U&'\0061\0308bc' IS NFD NORMALIZED
+ t
+
+
+
+
+
+
+ bit_length
+
+ bit_length ( text )
+ integer
+
+
+ Returns number of bits in the string (8
+ times the octet_length).
+
+
+ bit_length('jose')
+ 32
+
+
+
+
+
+
+ char_length
+
+
+ character string
+ length
+
+
+ length
+ of a character string
+ character string, length
+
+ char_length ( text )
+ integer
+
+
+
+ character_length
+
+ character_length ( text )
+ integer
+
+
+ Returns number of characters in the string.
+
+
+ char_length('josé')
+ 4
+
+
+
+
+
+
+ lower
+
+ lower ( text )
+ text
+
+
+ Converts the string to all lower case, according to the rules of the
+ database's locale.
+
+
+ lower('TOM')
+ tom
+
+
+
+
+
+
+ lpad
+
+ lpad ( stringtext,
+ lengthinteger
+ , filltext )
+ text
+
+
+ Extends the string to length
+ length by prepending the characters
+ fill (a space by default). If the
+ string is already longer than
+ length then it is truncated (on the right).
+
+
+ lpad('hi', 5, 'xy')
+ xyxhi
+
+
+
+
+
+
+ ltrim
+
+ ltrim ( stringtext
+ , characterstext )
+ text
+
+
+ Removes the longest string containing only characters in
+ characters (a space by default) from the start of
+ string.
+
+
+ ltrim('zzzytest', 'xyz')
+ test
+
+
+
+
+
+
+ normalize
+
+
+ Unicode normalization
+
+ normalize ( text
+ , form )
+ text
+
+
+ Converts the string to the specified Unicode
+ normalization form. The optional form key word
+ specifies the form: NFC (the default),
+ NFD, NFKC, or
+ NFKD. This function can only be used when the
+ server encoding is UTF8.
+
+
+ normalize(U&'\0061\0308bc', NFC)
+ U&'\00E4bc'
+
+
+
+
+
+
+ octet_length
+
+ octet_length ( text )
+ integer
+
+
+ Returns number of bytes in the string.
+
+
+ octet_length('josé')
+ 5 (if server encoding is UTF8)
+
+
+
+
+
+
+ octet_length
+
+ octet_length ( character )
+ integer
+
+
+ Returns number of bytes in the string. Since this version of the
+ function accepts type character directly, it will not
+ strip trailing spaces.
+
+
+ octet_length('abc '::character(4))
+ 4
+
+
+
+
+
+
+ overlay
+
+ overlay ( stringtextPLACINGnewsubstringtextFROMstartintegerFORcountinteger )
+ text
+
+
+ Replaces the substring of string that starts at
+ the start'th character and extends
+ for count characters
+ with newsubstring.
+ If count is omitted, it defaults to the length
+ of newsubstring.
+
+
+ overlay('Txxxxas' placing 'hom' from 2 for 4)
+ Thomas
+
+
+
+
+
+
+ position
+
+ position ( substringtextINstringtext )
+ integer
+
+
+ Returns first starting index of the specified
+ substring within
+ string, or zero if it's not present.
+
+
+ position('om' in 'Thomas')
+ 3
+
+
+
+
+
+
+ rpad
+
+ rpad ( stringtext,
+ lengthinteger
+ , filltext )
+ text
+
+
+ Extends the string to length
+ length by appending the characters
+ fill (a space by default). If the
+ string is already longer than
+ length then it is truncated.
+
+
+ rpad('hi', 5, 'xy')
+ hixyx
+
+
+
+
+
+
+ rtrim
+
+ rtrim ( stringtext
+ , characterstext )
+ text
+
+
+ Removes the longest string containing only characters in
+ characters (a space by default) from the end of
+ string.
+
+
+ rtrim('testxxzx', 'xyz')
+ test
+
+
+
+
+
+
+ substring
+
+ substring ( stringtextFROMstartintegerFORcountinteger )
+ text
+
+
+ Extracts the substring of string starting at
+ the start'th character if that is specified,
+ and stopping after count characters if that is
+ specified. Provide at least one of start
+ and count.
+
+
+ substring('Thomas' from 2 for 3)
+ hom
+
+
+ substring('Thomas' from 3)
+ omas
+
+
+ substring('Thomas' for 2)
+ Th
+
+
+
+
+
+ substring ( stringtextFROMpatterntext )
+ text
+
+
+ Extracts the first substring matching POSIX regular expression; see
+ .
+
+
+ substring('Thomas' from '...$')
+ mas
+
+
+
+
+
+ substring ( stringtextSIMILARpatterntextESCAPEescapetext )
+ text
+
+
+ substring ( stringtextFROMpatterntextFORescapetext )
+ text
+
+
+ Extracts the first substring matching SQL regular expression;
+ see . The first form has
+ been specified since SQL:2003; the second form was only in SQL:1999
+ and should be considered obsolete.
+
+
+ substring('Thomas' similar '%#"o_a#"_' escape '#')
+ oma
+
+
+
+
+
+
+ trim
+
+ trim ( LEADING | TRAILING | BOTH
+ characterstextFROM
+ stringtext )
+ text
+
+
+ Removes the longest string containing only characters in
+ characters (a space by default) from the
+ start, end, or both ends (BOTH is the default)
+ of string.
+
+
+ trim(both 'xyz' from 'yxTomxx')
+ Tom
+
+
+
+
+
+ trim ( LEADING | TRAILING | BOTHFROM
+ stringtext,
+ characterstext )
+ text
+
+
+ This is a non-standard syntax for trim().
+
+
+ trim(both from 'yxTomxx', 'xyz')
+ Tom
+
+
+
+
+
+
+ unicode_assigned
+
+ unicode_assigned ( text )
+ boolean
+
+
+ Returns true if all characters in the string are
+ assigned Unicode codepoints; false otherwise. This
+ function can only be used when the server encoding is
+ UTF8.
+
+
+
+
+
+
+ upper
+
+ upper ( text )
+ text
+
+
+ Converts the string to all upper case, according to the rules of the
+ database's locale.
+
+
+ upper('tom')
+ TOM
+
+
+
+
+
+
+
+ Additional string manipulation functions and operators are available
+ and are listed in . (Some of
+ these are used internally to implement
+ the SQL-standard string functions listed in
+ .)
+ There are also pattern-matching operators, which are described in
+ , and operators for full-text
+ search, which are described in .
+
+
+
+ Other String Functions and Operators
+
+
+
+
+ Function/Operator
+
+
+ Description
+
+
+ Example(s)
+
+
+
+
+
+
+
+
+ character string
+ prefix test
+
+ text^@text
+ boolean
+
+
+ Returns true if the first string starts with the second string
+ (equivalent to the starts_with() function).
+
+
+ 'alphabet' ^@ 'alph'
+ t
+
+
+
+
+
+
+ ascii
+
+ ascii ( text )
+ integer
+
+
+ Returns the numeric code of the first character of the argument.
+ In UTF8 encoding, returns the Unicode code point
+ of the character. In other multibyte encodings, the argument must
+ be an ASCII character.
+
+
+ ascii('x')
+ 120
+
+
+
+
+
+
+ chr
+
+ chr ( integer )
+ text
+
+
+ Returns the character with the given code. In UTF8
+ encoding the argument is treated as a Unicode code point. In other
+ multibyte encodings the argument must designate
+ an ASCII character. chr(0) is
+ disallowed because text data types cannot store that character.
+
+
+ chr(65)
+ A
+
+
+
+
+
+
+ concat
+
+ concat ( val1"any"
+ , val2"any", ... )
+ text
+
+
+ Concatenates the text representations of all the arguments.
+ NULL arguments are ignored.
+
+
+ concat('abcde', 2, NULL, 22)
+ abcde222
+
+
+
+
+
+
+ concat_ws
+
+ concat_ws ( septext,
+ val1"any"
+ , val2"any", ... )
+ text
+
+
+ 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.
+
+
+ concat_ws(',', 'abcde', 2, NULL, 22)
+ abcde,2,22
+
+
+
+
+
+
+ format
+
+ format ( formatstrtext
+ , formatarg"any", ... )
+ text
+
+
+ Formats arguments according to a format string;
+ see .
+ This function is similar to the C function sprintf.
+
+
+ format('Hello %s, %1$s', 'World')
+ Hello World, World
+
+
+
+
+
+
+ initcap
+
+ initcap ( text )
+ text
+
+
+ Converts the first letter of each word to upper case (or title case
+ if the letter is a digraph and locale is ICU or
+ builtinPG_UNICODE_FAST)
+ and the rest to lower case. When using the libc or
+ builtin locale provider, words are sequences of
+ alphanumeric characters separated by non-alphanumeric characters;
+ when using the ICU locale provider, words are separated according to
+ u_strToTitle ICU function.
+
+
+ This function is primarily used for convenient
+ display, and the specific result should not be relied upon because of
+ the differences between locale providers and between different
+ ICU versions. If specific word boundary rules are desired,
+ it is recommended to write a custom function.
+
+
+ initcap('hi THOMAS')
+ Hi Thomas
+
+
+
+
+
+
+ casefold
+
+ casefold ( text )
+ text
+
+
+ Performs case folding of the input string according to the collation.
+ Case folding is similar to case conversion, but the purpose of case
+ folding is to facilitate case-insensitive matching of strings,
+ whereas the purpose of case conversion is to convert to a particular
+ cased form. This function can only be used when the server encoding
+ is UTF8.
+
+
+ Ordinarily, case folding simply converts to lowercase, but there may
+ be exceptions depending on the collation. For instance, some
+ characters have more than two lowercase variants, or fold to uppercase.
+
+
+ Case folding may change the length of the string. For instance, in
+ the PG_UNICODE_FAST collation, ß
+ (U+00DF) folds to ss.
+
+
+ casefold can be used for Unicode Default Caseless
+ Matching. It does not always preserve the normalized form of the
+ input string (see ).
+
+
+ The libc provider doesn't support case folding, so
+ casefold is identical to .
+
+
+
+
+
+
+ left
+
+ left ( stringtext,
+ ninteger )
+ text
+
+
+ Returns first n characters in the
+ string, or when n is negative, returns
+ all but last |n| characters.
+
+
+ left('abcde', 2)
+ ab
+
+
+
+
+
+
+ length
+
+ length ( text )
+ integer
+
+
+ Returns the number of characters in the string.
+
+
+ length('jose')
+ 4
+
+
+
+
+
+
+ md5
+
+ md5 ( text )
+ text
+
+
+ Computes the MD5 hash of
+ the argument, with the result written in hexadecimal.
+
+
+ md5('abc')
+ 900150983cd24fb0&zwsp;d6963f7d28e17f72
+
+
+
+
+
+
+ parse_ident
+
+ parse_ident ( qualified_identifiertext
+ , strict_modebooleanDEFAULTtrue )
+ text[]
+
+
+ Splits qualified_identifier 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 false, 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 name[].
+
+
+ parse_ident('"SomeSchema".someTable')
+ {SomeSchema,sometable}
+
+
+
+
+
+
+ pg_client_encoding
+
+ pg_client_encoding ( )
+ name
+
+
+ Returns current client encoding name.
+
+
+ pg_client_encoding()
+ UTF8
+
+
+
+
+
+
+ quote_ident
+
+ quote_ident ( text )
+ text
+
+
+ Returns 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.
+ See also .
+
+
+ quote_ident('Foo bar')
+ "Foo bar"
+
+
+
+
+
+
+ quote_literal
+
+ quote_literal ( text )
+ text
+
+
+ Returns 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 quote_literal returns null on null
+ input; if the argument might be null,
+ quote_nullable is often more suitable.
+ See also .
+
+
+ quote_literal(E'O\'Reilly')
+ 'O''Reilly'
+
+
+
+
+
+ quote_literal ( anyelement )
+ text
+
+
+ Converts the given value to text and then quotes it as a literal.
+ Embedded single-quotes and backslashes are properly doubled.
+
+
+ quote_literal(42.5)
+ '42.5'
+
+
+
+
+
+
+ quote_nullable
+
+ quote_nullable ( text )
+ text
+
+
+ Returns the given string suitably quoted to be used as a string literal
+ in an SQL statement string; or, if the argument
+ is null, returns NULL.
+ Embedded single-quotes and backslashes are properly doubled.
+ See also .
+
+
+ quote_nullable(NULL)
+ NULL
+
+
+
+
+
+ quote_nullable ( anyelement )
+ text
+
+
+ Converts the given value to text and then quotes it as a literal;
+ or, if the argument is null, returns NULL.
+ Embedded single-quotes and backslashes are properly doubled.
+
+
+ quote_nullable(42.5)
+ '42.5'
+
+
+
+
+
+
+ regexp_count
+
+ regexp_count ( stringtext, patterntext
+ , startinteger
+ , flagstext )
+ integer
+
+
+ Returns the number of times the POSIX regular
+ expression pattern matches in
+ the string; see
+ .
+
+
+ regexp_count('123456789012', '\d\d\d', 2)
+ 3
+
+
+
+
+
+
+ regexp_instr
+
+ regexp_instr ( stringtext, patterntext
+ , startinteger
+ , Ninteger
+ , endoptioninteger
+ , flagstext
+ , subexprinteger )
+ integer
+
+
+ Returns the position within string where
+ the N'th match of the POSIX regular
+ expression pattern occurs, or zero if there is
+ no such match; see .
+
+
+ regexp_instr('ABCDEF', 'c(.)(..)', 1, 1, 0, 'i')
+ 3
+
+
+ regexp_instr('ABCDEF', 'c(.)(..)', 1, 1, 0, 'i', 2)
+ 5
+
+
+
+
+
+
+ regexp_like
+
+ regexp_like ( stringtext, patterntext
+ , flagstext )
+ boolean
+
+
+ Checks whether a match of the POSIX regular
+ expression pattern occurs
+ within string; see
+ .
+
+
+ regexp_like('Hello World', 'world$', 'i')
+ t
+
+
+
+
+
+
+ regexp_match
+
+ regexp_match ( stringtext, patterntext, flagstext )
+ text[]
+
+
+ Returns substrings within the first match of the POSIX regular
+ expression pattern to
+ the string; see
+ .
+
+
+ regexp_match('foobarbequebaz', '(bar)(beque)')
+ {bar,beque}
+
+
+
+
+
+
+ regexp_matches
+
+ regexp_matches ( stringtext, patterntext, flagstext )
+ setof text[]
+
+
+ Returns substrings within the first match of the POSIX regular
+ expression pattern to
+ the string, or substrings within all
+ such matches if the g flag is used;
+ see .
+
+
+ regexp_matches('foobarbequebaz', 'ba.', 'g')
+
+
+ {bar}
+ {baz}
+
+
+
+
+
+
+
+ regexp_replace
+
+ regexp_replace ( stringtext, patterntext, replacementtext
+ , flagstext )
+ text
+
+
+ Replaces the substring that is the first match to the POSIX
+ regular expression pattern, or all such
+ matches if the g flag is used; see
+ .
+
+
+ regexp_replace('Thomas', '.[mN]a.', 'M')
+ ThM
+
+
+
+
+
+ regexp_replace ( stringtext, patterntext, replacementtext,
+ startinteger
+ , Ninteger
+ , flagstext )
+ text
+
+
+ Replaces the substring that is the N'th
+ match to the POSIX regular expression pattern,
+ or all such matches if N is zero, with the
+ search beginning at the start'th character
+ of string. If N is
+ omitted, it defaults to 1. See
+ .
+
+
+ regexp_replace('Thomas', '.', 'X', 3, 2)
+ ThoXas
+
+
+ regexp_replace(string=>'hello world', pattern=>'l', replacement=>'XX', start=>1, "N"=>2)
+ helXXo world
+
+
+
+
+
+
+ regexp_split_to_array
+
+ regexp_split_to_array ( stringtext, patterntext, flagstext )
+ text[]
+
+
+ Splits string using a POSIX regular
+ expression as the delimiter, producing an array of results; see
+ .
+
+
+ regexp_split_to_array('hello world', '\s+')
+ {hello,world}
+
+
+
+
+
+
+ regexp_split_to_table
+
+ regexp_split_to_table ( stringtext, patterntext, flagstext )
+ setof text
+
+
+ Splits string using a POSIX regular
+ expression as the delimiter, producing a set of results; see
+ .
+
+
+ regexp_split_to_table('hello world', '\s+')
+
+
+ hello
+ world
+
+
+
+
+
+
+
+ regexp_substr
+
+ regexp_substr ( stringtext, patterntext
+ , startinteger
+ , Ninteger
+ , flagstext
+ , subexprinteger )
+ text
+
+
+ Returns the substring within string that
+ matches the N'th occurrence of the POSIX
+ regular expression pattern,
+ or NULL if there is no such match; see
+ .
+
+
+ regexp_substr('ABCDEF', 'c(.)(..)', 1, 1, 'i')
+ CDEF
+
+
+ regexp_substr('ABCDEF', 'c(.)(..)', 1, 1, 'i', 2)
+ EF
+
+
+
+
+
+
+ repeat
+
+ repeat ( stringtext, numberinteger )
+ text
+
+
+ Repeats string the specified
+ number of times.
+
+
+ repeat('Pg', 4)
+ PgPgPgPg
+
+
+
+
+
+
+ replace
+
+ replace ( stringtext,
+ fromtext,
+ totext )
+ text
+
+
+ Replaces all occurrences in string of
+ substring from with
+ substring to.
+
+
+ replace('abcdefabcdef', 'cd', 'XX')
+ abXXefabXXef
+
+
+
+
+
+
+ reverse
+
+ reverse ( text )
+ text
+
+
+ Reverses the order of the characters in the string.
+
+
+ reverse('abcde')
+ edcba
+
+
+
+
+
+
+ right
+
+ right ( stringtext,
+ ninteger )
+ text
+
+
+ Returns last n characters in the string,
+ or when n is negative, returns all but
+ first |n| characters.
+
+
+ right('abcde', 2)
+ de
+
+
+
+
+
+
+ split_part
+
+ split_part ( stringtext,
+ delimitertext,
+ ninteger )
+ text
+
+
+ Splits string at occurrences
+ of delimiter and returns
+ the n'th field (counting from one),
+ or when n is negative, returns
+ the |n|'th-from-last field.
+
+
+ split_part('abc~@~def~@~ghi', '~@~', 2)
+ def
+
+
+ split_part('abc,def,ghi,jkl', ',', -2)
+ ghi
+
+
+
+
+
+
+ starts_with
+
+ starts_with ( stringtext, prefixtext )
+ boolean
+
+
+ Returns true if string starts
+ with prefix.
+
+
+ starts_with('alphabet', 'alph')
+ t
+
+
+
+
+
+
+ string_to_array
+
+ string_to_array ( stringtext, delimitertext, null_stringtext )
+ text[]
+
+
+ Splits the string at occurrences
+ of delimiter and forms the resulting fields
+ into a text array.
+ If delimiter is NULL,
+ each character in the string will become a
+ separate element in the array.
+ If delimiter is an empty string, then
+ the string is treated as a single field.
+ If null_string is supplied and is
+ not NULL, fields matching that string are
+ replaced by NULL.
+ See also array_to_string.
+
+
+ string_to_array('xx~~yy~~zz', '~~', 'yy')
+ {xx,NULL,zz}
+
+
+
+
+
+
+ string_to_table
+
+ string_to_table ( stringtext, delimitertext, null_stringtext )
+ setof text
+
+
+ Splits the string at occurrences
+ of delimiter and returns the resulting fields
+ as a set of text rows.
+ If delimiter is NULL,
+ each character in the string will become a
+ separate row of the result.
+ If delimiter is an empty string, then
+ the string is treated as a single field.
+ If null_string is supplied and is
+ not NULL, fields matching that string are
+ replaced by NULL.
+
+
+ string_to_table('xx~^~yy~^~zz', '~^~', 'yy')
+
+
+ xx
+ NULL
+ zz
+
+
+
+
+
+
+
+ strpos
+
+ strpos ( stringtext, substringtext )
+ integer
+
+
+ Returns first starting index of the specified substring
+ within string, or zero if it's not present.
+ (Same as position(substring in
+ string), but note the reversed
+ argument order.)
+
+
+ strpos('high', 'ig')
+ 2
+
+
+
+
+
+
+ substr
+
+ substr ( stringtext, startinteger, countinteger )
+ text
+
+
+ Extracts the substring of string starting at
+ the start'th character,
+ and extending for count characters if that is
+ specified. (Same
+ as substring(string
+ from start
+ for count).)
+
+
+ substr('alphabet', 3)
+ phabet
+
+
+ substr('alphabet', 3, 2)
+ ph
+
+
+
+
+
+
+ to_ascii
+
+ to_ascii ( stringtext )
+ text
+
+
+ to_ascii ( stringtext,
+ encodingname )
+ text
+
+
+ to_ascii ( stringtext,
+ encodinginteger )
+ text
+
+
+ Converts string to ASCII
+ from another encoding, which may be identified by name or number.
+ If encoding 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 LATIN1, LATIN2,
+ LATIN9, and WIN1250 encodings.
+ (See the module for another, more flexible
+ solution.)
+
+
+ to_ascii('Karél')
+ Karel
+
+
+
+
+
+
+ to_bin
+
+ to_bin ( integer )
+ text
+
+
+ to_bin ( bigint )
+ text
+
+
+ Converts the number to its equivalent two's complement binary
+ representation.
+
+
+ to_bin(2147483647)
+ 1111111111111111111111111111111
+
+
+ to_bin(-1234)
+ 11111111111111111111101100101110
+
+
+
+
+
+
+ to_hex
+
+ to_hex ( integer )
+ text
+
+
+ to_hex ( bigint )
+ text
+
+
+ Converts the number to its equivalent two's complement hexadecimal
+ representation.
+
+
+ to_hex(2147483647)
+ 7fffffff
+
+
+ to_hex(-1234)
+ fffffb2e
+
+
+
+
+
+
+ to_oct
+
+ to_oct ( integer )
+ text
+
+
+ to_oct ( bigint )
+ text
+
+
+ Converts the number to its equivalent two's complement octal
+ representation.
+
+
+ to_oct(2147483647)
+ 17777777777
+
+
+ to_oct(-1234)
+ 37777775456
+
+
+
+
+
+
+ translate
+
+ translate ( stringtext,
+ fromtext,
+ totext )
+ text
+
+
+ Replaces each character in string that
+ matches a character in the from set with the
+ corresponding character in the to
+ set. If from is longer than
+ to, occurrences of the extra characters in
+ from are deleted.
+
+
+ translate('12345', '143', 'ax')
+ a2x5
+
+
+
+
+
+
+ unistr
+
+ unistr ( text )
+ text
+
+
+ Evaluate escaped Unicode characters in the argument. Unicode characters
+ can be specified as
+ \XXXX (4 hexadecimal
+ digits), \+XXXXXX (6
+ hexadecimal digits),
+ \uXXXX (4 hexadecimal
+ digits), or \UXXXXXXXX
+ (8 hexadecimal digits). To specify a backslash, write two
+ backslashes. All other characters are taken literally.
+
+
+
+ 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.
+
+
+
+ This function provides a (non-standard) alternative to string
+ constants with Unicode escapes (see ).
+
+
+
+ unistr('d\0061t\+000061')
+ data
+
+
+ unistr('d\u0061t\U00000061')
+ data
+
+
+
+
+
+
+
+
+ The concat, concat_ws and
+ format functions are variadic, so it is possible to
+ pass the values to be concatenated or formatted as an array marked with
+ the VARIADIC keyword (see ). The array's elements are
+ treated as if they were separate ordinary arguments to the function.
+ If the variadic array argument is NULL, concat
+ and concat_ws return NULL, but
+ format treats a NULL as a zero-element array.
+
+
+
+ See also the aggregate function string_agg in
+ , and the functions for
+ converting between strings and the bytea type in
+ .
+
+
+
+ <function>format</function>
+
+
+ format
+
+
+
+ The function format produces output formatted according to
+ a format string, in a style similar to the C function
+ sprintf.
+
+
+
+
+format(formatstrtext, formatarg"any", ...)
+
+ formatstr 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 format specifiers are
+ used. Format specifiers act as placeholders in the string, defining how
+ subsequent function arguments should be formatted and inserted into the
+ result. Each formatarg 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).
+
+
+
+ Format specifiers are introduced by a % character and have
+ the form
+
+%[position][flags][width]type
+
+ where the component fields are:
+
+
+
+ position (optional)
+
+
+ A string of the form n$ where
+ n is the index of the argument to print.
+ Index 1 means the first argument after
+ formatstr. If the position is
+ omitted, the default is to use the next argument in sequence.
+
+
+
+
+
+ flags (optional)
+
+
+ Additional options controlling how the format specifier's output is
+ formatted. Currently the only supported flag is a minus sign
+ (-) which will cause the format specifier's output to be
+ left-justified. This has no effect unless the width
+ field is also specified.
+
+
+
+
+
+ width (optional)
+
+
+ Specifies the minimum number of characters to use to
+ display the format specifier's output. The output is padded on the
+ left or right (depending on the - 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 (*) to use the next function argument as the
+ width; or a string of the form *n$ to
+ use the nth function argument as the width.
+
+
+
+ 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 - flag had been specified) within a
+ field of length abs(width).
+
+
+
+
+
+ type (required)
+
+
+ The type of format conversion to use to produce the format
+ specifier's output. The following types are supported:
+
+
+
+ s formats the argument value as a simple
+ string. A null value is treated as an empty string.
+
+
+
+
+ I 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
+ quote_ident).
+
+
+
+
+ L quotes the argument value as an SQL literal.
+ A null value is displayed as the string NULL, without
+ quotes (equivalent to quote_nullable).
+
+
+
+
+
+
+
+
+
+
+ In addition to the format specifiers described above, the special sequence
+ %% may be used to output a literal % character.
+
+
+
+ Here are some examples of the basic format conversions:
+
+
+SELECT format('Hello %s', 'World');
+Result: Hello World
+
+SELECT format('Testing %s, %s, %s, %%', 'one', 'two', 'three');
+Result: Testing one, two, three, %
+
+SELECT format('INSERT INTO %I VALUES(%L)', 'Foo bar', E'O\'Reilly');
+Result: INSERT INTO "Foo bar" VALUES('O''Reilly')
+
+SELECT format('INSERT INTO %I VALUES(%L)', 'locations', 'C:\Program Files');
+Result: INSERT INTO locations VALUES('C:\Program Files')
+
+
+
+
+ Here are examples using width fields
+ and the - flag:
+
+
+SELECT format('|%10s|', 'foo');
+Result: | foo|
+
+SELECT format('|%-10s|', 'foo');
+Result: |foo |
+
+SELECT format('|%*s|', 10, 'foo');
+Result: | foo|
+
+SELECT format('|%*s|', -10, 'foo');
+Result: |foo |
+
+SELECT format('|%-*s|', 10, 'foo');
+Result: |foo |
+
+SELECT format('|%-*s|', -10, 'foo');
+Result: |foo |
+
+
+
+
+ These examples show use of position fields:
+
+
+SELECT format('Testing %3$s, %2$s, %1$s', 'one', 'two', 'three');
+Result: Testing three, two, one
+
+SELECT format('|%*2$s|', 'foo', 10, 'bar');
+Result: | bar|
+
+SELECT format('|%1$*2$s|', 'foo', 10, 'bar');
+Result: | foo|
+
+
+
+
+ Unlike the standard C function sprintf,
+ PostgreSQL's format function allows format
+ specifiers with and without position fields to be mixed
+ in the same format string. A format specifier without a
+ position field always uses the next argument after the
+ last argument consumed.
+ In addition, the format function does not require all
+ function arguments to be used in the format string.
+ For example:
+
+
+SELECT format('Testing %3$s, %2$s, %s', 'one', 'two', 'three');
+Result: Testing three, two, three
+
+
+
+
+ The %I and %L format specifiers are particularly
+ useful for safely constructing dynamic SQL statements. See
+ .
+
+
+
+
diff --git a/doc/src/sgml/func/func-subquery.sgml b/doc/src/sgml/func/func-subquery.sgml
new file mode 100644
index 0000000000000..a9f2b12e48c66
--- /dev/null
+++ b/doc/src/sgml/func/func-subquery.sgml
@@ -0,0 +1,349 @@
+
+ Subquery Expressions
+
+
+ EXISTS
+
+
+
+ IN
+
+
+
+ NOT IN
+
+
+
+ ANY
+
+
+
+ ALL
+
+
+
+ SOME
+
+
+
+ subquery
+
+
+
+ This section describes the SQL-compliant subquery
+ expressions available in PostgreSQL.
+ All of the expression forms documented in this section return
+ Boolean (true/false) results.
+
+
+
+ <literal>EXISTS</literal>
+
+
+EXISTS (subquery)
+
+
+
+ The argument of EXISTS is an arbitrary SELECT statement,
+ or subquery. The
+ subquery is evaluated to determine whether it returns any rows.
+ If it returns at least one row, the result of EXISTS is
+ true; if the subquery returns no rows, the result of EXISTS
+ is false.
+
+
+
+ The subquery can refer to variables from the surrounding query,
+ which will act as constants during any one evaluation of the subquery.
+
+
+
+ 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.
+
+
+
+ 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 EXISTS tests in the form
+ EXISTS(SELECT 1 WHERE ...). There are exceptions to
+ this rule however, such as subqueries that use INTERSECT.
+
+
+
+ This simple example is like an inner join on col2, but
+ it produces at most one output row for each tab1 row,
+ even if there are several matching tab2 rows:
+
+SELECT col1
+FROM tab1
+WHERE EXISTS (SELECT 1 FROM tab2 WHERE col2 = tab1.col2);
+
+
+
+
+
+ <literal>IN</literal>
+
+
+expression IN (subquery)
+
+
+
+ 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 IN is true if any equal subquery row is found.
+ The result is false if no equal row is found (including the
+ case where the subquery returns no rows).
+
+
+
+ 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 IN construct will be null, not false.
+ This is in accordance with SQL's normal rules for Boolean combinations
+ of null values.
+
+
+
+ As with EXISTS, it's unwise to assume that the subquery will
+ be evaluated completely.
+
+
+
+row_constructor IN (subquery)
+
+
+
+ The left-hand side of this form of IN is a row constructor,
+ as described in .
+ The right-hand side is a parenthesized
+ subquery, which must return exactly as many columns as there are
+ expressions in the left-hand row. The left-hand expressions are
+ evaluated and compared row-wise to each row of the subquery result.
+ The result of IN is true if any equal subquery row is found.
+ The result is false if no equal row is found (including the
+ case where the subquery returns no rows).
+
+
+
+ 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 IN is null.
+
+
+
+
+ <literal>NOT IN</literal>
+
+
+expression NOT IN (subquery)
+
+
+
+ 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 NOT IN is true if only unequal subquery rows
+ are found (including the case where the subquery returns no rows).
+ The result is false if any equal row is found.
+
+
+
+ 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 NOT IN construct will be null, not true.
+ This is in accordance with SQL's normal rules for Boolean combinations
+ of null values.
+
+
+
+ As with EXISTS, it's unwise to assume that the subquery will
+ be evaluated completely.
+
+
+
+row_constructor NOT IN (subquery)
+
+
+
+ The left-hand side of this form of NOT IN is a row constructor,
+ as described in .
+ The right-hand side is a parenthesized
+ subquery, which must return exactly as many columns as there are
+ expressions in the left-hand row. The left-hand expressions are
+ evaluated and compared row-wise to each row of the subquery result.
+ The result of NOT IN is true if only unequal subquery rows
+ are found (including the case where the subquery returns no rows).
+ The result is false if any equal row is found.
+
+
+
+ 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 NOT IN is null.
+
+
+
+
+ <literal>ANY</literal>/<literal>SOME</literal>
+
+
+expressionoperator ANY (subquery)
+expressionoperator SOME (subquery)
+
+
+
+ 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 operator, which must yield a Boolean
+ result.
+ The result of ANY is true if any true result is obtained.
+ The result is false if no true result is found (including the
+ case where the subquery returns no rows).
+
+
+
+ SOME is a synonym for ANY.
+ IN is equivalent to = ANY.
+
+
+
+ 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 ANY construct
+ will be null, not false.
+ This is in accordance with SQL's normal rules for Boolean combinations
+ of null values.
+
+
+
+ As with EXISTS, it's unwise to assume that the subquery will
+ be evaluated completely.
+
+
+
+row_constructoroperator ANY (subquery)
+row_constructoroperator SOME (subquery)
+
+
+
+ The left-hand side of this form of ANY is a row constructor,
+ as described in .
+ The right-hand side is a parenthesized
+ subquery, which must return exactly as many columns as there are
+ expressions in the left-hand row. The left-hand expressions are
+ evaluated and compared row-wise to each row of the subquery result,
+ using the given operator.
+ The result of ANY is true if the comparison
+ returns true for any subquery row.
+ The result is false 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.
+
+
+
+ See for details about the meaning
+ of a row constructor comparison.
+
+
+
+
+ <literal>ALL</literal>
+
+
+expressionoperator ALL (subquery)
+
+
+
+ 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 operator, which must yield a Boolean
+ result.
+ The result of ALL is true if all rows yield true
+ (including the case where the subquery returns no rows).
+ The result is false 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.
+
+
+
+ NOT IN is equivalent to <> ALL.
+
+
+
+ As with EXISTS, it's unwise to assume that the subquery will
+ be evaluated completely.
+
+
+
+row_constructoroperator ALL (subquery)
+
+
+
+ The left-hand side of this form of ALL is a row constructor,
+ as described in .
+ The right-hand side is a parenthesized
+ subquery, which must return exactly as many columns as there are
+ expressions in the left-hand row. The left-hand expressions are
+ evaluated and compared row-wise to each row of the subquery result,
+ using the given operator.
+ The result of ALL is true if the comparison
+ returns true for all subquery rows (including the
+ case where the subquery returns no rows).
+ The result is false 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.
+
+
+
+ See for details about the meaning
+ of a row constructor comparison.
+
+
+
+
+ Single-Row Comparison
+
+
+ comparison
+ subquery result row
+
+
+
+row_constructoroperator (subquery)
+
+
+
+ The left-hand side is a row constructor,
+ as described in .
+ The right-hand side is a parenthesized subquery, which must return exactly
+ as many columns as there are expressions in the left-hand row. Furthermore,
+ the subquery cannot return more than one row. (If it returns zero rows,
+ the result is taken to be null.) The left-hand side is evaluated and
+ compared row-wise to the single subquery result row.
+
+
+
+ See for details about the meaning
+ of a row constructor comparison.
+
+
+
diff --git a/doc/src/sgml/func/func-textsearch.sgml b/doc/src/sgml/func/func-textsearch.sgml
new file mode 100644
index 0000000000000..a06a58f14983a
--- /dev/null
+++ b/doc/src/sgml/func/func-textsearch.sgml
@@ -0,0 +1,1046 @@
+
+ Text Search Functions and Operators
+
+
+ full text search
+ functions and operators
+
+
+
+ text search
+ functions and operators
+
+
+
+ ,
+ and
+
+ summarize the functions and operators that are provided
+ for full text searching. See for a detailed
+ explanation of PostgreSQL's text search
+ facility.
+
+
+
+ Text Search Operators
+
+
+
+
+ Operator
+
+
+ Description
+
+
+ Example(s)
+
+
+
+
+
+
+
+ tsvector@@tsquery
+ boolean
+
+
+ tsquery@@tsvector
+ boolean
+
+
+ Does tsvector match tsquery?
+ (The arguments can be given in either order.)
+
+
+ to_tsvector('fat cats ate rats') @@ to_tsquery('cat & rat')
+ t
+
+
+
+
+
+ text@@tsquery
+ boolean
+
+
+ Does text string, after implicit invocation
+ of to_tsvector(), match tsquery?
+
+
+ 'fat cats ate rats' @@ to_tsquery('cat & rat')
+ t
+
+
+
+
+
+ tsvector||tsvector
+ tsvector
+
+
+ Concatenates two tsvectors. If both inputs contain
+ lexeme positions, the second input's positions are adjusted
+ accordingly.
+
+
+ 'a:1 b:2'::tsvector || 'c:1 d:2 b:3'::tsvector
+ 'a':1 'b':2,5 'c':3 'd':4
+
+
+
+
+
+ tsquery&&tsquery
+ tsquery
+
+
+ ANDs two tsquerys together, producing a query that
+ matches documents that match both input queries.
+
+
+ 'fat | rat'::tsquery && 'cat'::tsquery
+ ( 'fat' | 'rat' ) & 'cat'
+
+
+
+
+
+ tsquery||tsquery
+ tsquery
+
+
+ ORs two tsquerys together, producing a query that
+ matches documents that match either input query.
+
+
+ 'fat | rat'::tsquery || 'cat'::tsquery
+ 'fat' | 'rat' | 'cat'
+
+
+
+
+
+ !!tsquery
+ tsquery
+
+
+ Negates a tsquery, producing a query that matches
+ documents that do not match the input query.
+
+
+ !! 'cat'::tsquery
+ !'cat'
+
+
+
+
+
+ tsquery<->tsquery
+ tsquery
+
+
+ Constructs a phrase query, which matches if the two input queries
+ match at successive lexemes.
+
+
+ to_tsquery('fat') <-> to_tsquery('rat')
+ 'fat' <-> 'rat'
+
+
+
+
+
+ tsquery@>tsquery
+ boolean
+
+
+ Does first tsquery contain the second? (This considers
+ only whether all the lexemes appearing in one query appear in the
+ other, ignoring the combining operators.)
+
+
+ 'cat'::tsquery @> 'cat & rat'::tsquery
+ f
+
+
+
+
+
+ tsquery<@tsquery
+ boolean
+
+
+ Is first tsquery contained in the second? (This
+ considers only whether all the lexemes appearing in one query appear
+ in the other, ignoring the combining operators.)
+
+
+ 'cat'::tsquery <@ 'cat & rat'::tsquery
+ t
+
+
+ 'cat'::tsquery <@ '!cat & rat'::tsquery
+ t
+
+
+
+
+
+
+
+ In addition to these specialized operators, the usual comparison
+ operators shown in are
+ available for types tsvector and tsquery.
+ These are not very
+ useful for text searching but allow, for example, unique indexes to be
+ built on columns of these types.
+
+
+
+ Text Search Functions
+
+
+
+
+ Function
+
+
+ Description
+
+
+ Example(s)
+
+
+
+
+
+
+
+
+ array_to_tsvector
+
+ array_to_tsvector ( text[] )
+ tsvector
+
+
+ Converts an array of text strings to a tsvector.
+ The given strings are used as lexemes as-is, without further
+ processing. Array elements must not be empty strings
+ or NULL.
+
+
+ array_to_tsvector('{fat,cat,rat}'::text[])
+ 'cat' 'fat' 'rat'
+
+
+
+
+
+
+ get_current_ts_config
+
+ get_current_ts_config ( )
+ regconfig
+
+
+ Returns the OID of the current default text search configuration
+ (as set by ).
+
+
+ get_current_ts_config()
+ english
+
+
+
+
+
+
+ length
+
+ length ( tsvector )
+ integer
+
+
+ Returns the number of lexemes in the tsvector.
+
+
+ length('fat:2,4 cat:3 rat:5A'::tsvector)
+ 3
+
+
+
+
+
+
+ numnode
+
+ numnode ( tsquery )
+ integer
+
+
+ Returns the number of lexemes plus operators in
+ the tsquery.
+
+
+ numnode('(fat & rat) | cat'::tsquery)
+ 5
+
+
+
+
+
+
+ plainto_tsquery
+
+ plainto_tsquery (
+ configregconfig,
+ querytext )
+ tsquery
+
+
+ Converts text to a tsquery, 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.
+
+
+ plainto_tsquery('english', 'The Fat Rats')
+ 'fat' & 'rat'
+
+
+
+
+
+
+ phraseto_tsquery
+
+ phraseto_tsquery (
+ configregconfig,
+ querytext )
+ tsquery
+
+
+ Converts text to a tsquery, 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.
+
+
+ phraseto_tsquery('english', 'The Fat Rats')
+ 'fat' <-> 'rat'
+
+
+ phraseto_tsquery('english', 'The Cat and Rats')
+ 'cat' <2> 'rat'
+
+
+
+
+
+
+ websearch_to_tsquery
+
+ websearch_to_tsquery (
+ configregconfig,
+ querytext )
+ tsquery
+
+
+ Converts text to a tsquery, normalizing words according
+ to the specified or default configuration. Quoted word sequences are
+ converted to phrase tests. The word or 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.
+
+
+ websearch_to_tsquery('english', '"fat rat" or cat dog')
+ 'fat' <-> 'rat' | 'cat' & 'dog'
+
+
+
+
+
+
+ querytree
+
+ querytree ( tsquery )
+ text
+
+
+ Produces a representation of the indexable portion of
+ a tsquery. A result that is empty or
+ just T indicates a non-indexable query.
+
+
+ querytree('foo & ! bar'::tsquery)
+ 'foo'
+
+
+
+
+
+
+ setweight
+
+ setweight ( vectortsvector, weight"char" )
+ tsvector
+
+
+ Assigns the specified weight to each element
+ of the vector.
+
+
+ setweight('fat:2,4 cat:3 rat:5B'::tsvector, 'A')
+ 'cat':3A 'fat':2A,4A 'rat':5A
+
+
+
+
+
+
+ setweight
+ setweight for specific lexeme(s)
+
+ setweight ( vectortsvector, weight"char", lexemestext[] )
+ tsvector
+
+
+ Assigns the specified weight to elements
+ of the vector that are listed
+ in lexemes.
+ The strings in lexemes are taken as lexemes
+ as-is, without further processing. Strings that do not match any
+ lexeme in vector are ignored.
+
+
+ setweight('fat:2,4 cat:3 rat:5,6B'::tsvector, 'A', '{cat,rat}')
+ 'cat':3A 'fat':2,4 'rat':5A,6A
+
+
+
+
+
+
+ strip
+
+ strip ( tsvector )
+ tsvector
+
+
+ Removes positions and weights from the tsvector.
+
+
+ strip('fat:2,4 cat:3 rat:5A'::tsvector)
+ 'cat' 'fat' 'rat'
+
+
+
+
+
+
+ to_tsquery
+
+ to_tsquery (
+ configregconfig,
+ querytext )
+ tsquery
+
+
+ Converts text to a tsquery, normalizing words according to
+ the specified or default configuration. The words must be combined
+ by valid tsquery operators.
+
+
+ to_tsquery('english', 'The & Fat & Rats')
+ 'fat' & 'rat'
+
+
+
+
+
+
+ to_tsvector
+
+ to_tsvector (
+ configregconfig,
+ documenttext )
+ tsvector
+
+
+ Converts text to a tsvector, normalizing words according
+ to the specified or default configuration. Position information is
+ included in the result.
+
+
+ to_tsvector('english', 'The Fat Rats')
+ 'fat':2 'rat':3
+
+
+
+
+
+ to_tsvector (
+ configregconfig,
+ documentjson )
+ tsvector
+
+
+ to_tsvector (
+ configregconfig,
+ documentjsonb )
+ tsvector
+
+
+ Converts each string value in the JSON document to
+ a tsvector, 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 document order of the fields of a
+ JSON object is implementation-dependent when the input
+ is jsonb; observe the difference in the examples.)
+
+
+ to_tsvector('english', '{"aa": "The Fat Rats", "b": "dog"}'::json)
+ 'dog':5 'fat':2 'rat':3
+
+
+ to_tsvector('english', '{"aa": "The Fat Rats", "b": "dog"}'::jsonb)
+ 'dog':1 'fat':4 'rat':5
+
+
+
+
+
+
+ json_to_tsvector
+
+ json_to_tsvector (
+ configregconfig,
+ documentjson,
+ filterjsonb )
+ tsvector
+
+
+
+ jsonb_to_tsvector
+
+ jsonb_to_tsvector (
+ configregconfig,
+ documentjsonb,
+ filterjsonb )
+ tsvector
+
+
+ Selects each item in the JSON document that is requested by
+ the filter and converts each one to
+ a tsvector, 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 document order of the fields of a
+ JSON object is implementation-dependent when the input
+ is jsonb.)
+ The filter must be a jsonb
+ array containing zero or more of these keywords:
+ "string" (to include all string values),
+ "numeric" (to include all numeric values),
+ "boolean" (to include all boolean values),
+ "key" (to include all keys), or
+ "all" (to include all the above).
+ As a special case, the filter can also be a
+ simple JSON value that is one of these keywords.
+
+
+ json_to_tsvector('english', '{"a": "The Fat Rats", "b": 123}'::json, '["string", "numeric"]')
+ '123':5 'fat':2 'rat':3
+
+
+ json_to_tsvector('english', '{"cat": "The Fat Rats", "dog": 123}'::json, '"all"')
+ '123':9 'cat':1 'dog':7 'fat':4 'rat':5
+
+
+
+
+
+
+ ts_delete
+
+ ts_delete ( vectortsvector, lexemetext )
+ tsvector
+
+
+ Removes any occurrence of the given lexeme
+ from the vector.
+ The lexeme string is treated as a lexeme as-is,
+ without further processing.
+
+
+ ts_delete('fat:2,4 cat:3 rat:5A'::tsvector, 'fat')
+ 'cat':3 'rat':5A
+
+
+
+
+
+ ts_delete ( vectortsvector, lexemestext[] )
+ tsvector
+
+
+ Removes any occurrences of the lexemes
+ in lexemes
+ from the vector.
+ The strings in lexemes are taken as lexemes
+ as-is, without further processing. Strings that do not match any
+ lexeme in vector are ignored.
+
+
+ ts_delete('fat:2,4 cat:3 rat:5A'::tsvector, ARRAY['fat','rat'])
+ 'cat':3
+
+
+
+
+
+
+ ts_filter
+
+ ts_filter ( vectortsvector, weights"char"[] )
+ tsvector
+
+
+ Selects only elements with the given weights
+ from the vector.
+
+
+ ts_filter('fat:2,4 cat:3b,7c rat:5A'::tsvector, '{a,b}')
+ 'cat':3B 'rat':5A
+
+
+
+
+
+
+ ts_headline
+
+ ts_headline (
+ configregconfig,
+ documenttext,
+ querytsquery
+ , optionstext )
+ text
+
+
+ Displays, in an abbreviated form, the match(es) for
+ the query in
+ the document, which must be raw text not
+ a tsvector. 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
+ , which also describes the
+ available options.
+
+
+ ts_headline('The fat cat ate the rat.', 'cat')
+ The fat <b>cat</b> ate the rat.
+
+
+
+
+
+ ts_headline (
+ configregconfig,
+ documentjson,
+ querytsquery
+ , optionstext )
+ text
+
+
+ ts_headline (
+ configregconfig,
+ documentjsonb,
+ querytsquery
+ , optionstext )
+ text
+
+
+ Displays, in an abbreviated form, match(es) for
+ the query that occur in string values
+ within the JSON document.
+ See for more details.
+
+
+ ts_headline('{"cat":"raining cats and dogs"}'::jsonb, 'cat')
+ {"cat": "raining <b>cats</b> and dogs"}
+
+
+
+
+
+
+ ts_rank
+
+ ts_rank (
+ weightsreal[],
+ vectortsvector,
+ querytsquery
+ , normalizationinteger )
+ real
+
+
+ Computes a score showing how well
+ the vector matches
+ the query. See
+ for details.
+
+
+ ts_rank(to_tsvector('raining cats and dogs'), 'cat')
+ 0.06079271
+
+
+
+
+
+
+ ts_rank_cd
+
+ ts_rank_cd (
+ weightsreal[],
+ vectortsvector,
+ querytsquery
+ , normalizationinteger )
+ real
+
+
+ Computes a score showing how well
+ the vector matches
+ the query, using a cover density
+ algorithm. See for details.
+
+
+ ts_rank_cd(to_tsvector('raining cats and dogs'), 'cat')
+ 0.1
+
+
+
+
+
+
+ ts_rewrite
+
+ ts_rewrite ( querytsquery,
+ targettsquery,
+ substitutetsquery )
+ tsquery
+
+
+ Replaces occurrences of target
+ with substitute
+ within the query.
+ See for details.
+
+
+ ts_rewrite('a & b'::tsquery, 'a'::tsquery, 'foo|bar'::tsquery)
+ 'b' & ( 'foo' | 'bar' )
+
+
+
+
+
+ ts_rewrite ( querytsquery,
+ selecttext )
+ tsquery
+
+
+ Replaces portions of the query according to
+ target(s) and substitute(s) obtained by executing
+ a SELECT command.
+ See for details.
+
+
+ SELECT ts_rewrite('a & b'::tsquery, 'SELECT t,s FROM aliases')
+ 'b' & ( 'foo' | 'bar' )
+
+
+
+
+
+
+ tsquery_phrase
+
+ tsquery_phrase ( query1tsquery, query2tsquery )
+ tsquery
+
+
+ Constructs a phrase query that searches
+ for matches of query1
+ and query2 at successive lexemes (same
+ as <-> operator).
+
+
+ tsquery_phrase(to_tsquery('fat'), to_tsquery('cat'))
+ 'fat' <-> 'cat'
+
+
+
+
+
+ tsquery_phrase ( query1tsquery, query2tsquery, distanceinteger )
+ tsquery
+
+
+ Constructs a phrase query that searches
+ for matches of query1 and
+ query2 that occur exactly
+ distance lexemes apart.
+
+
+ tsquery_phrase(to_tsquery('fat'), to_tsquery('cat'), 10)
+ 'fat' <10> 'cat'
+
+
+
+
+
+
+ tsvector_to_array
+
+ tsvector_to_array ( tsvector )
+ text[]
+
+
+ Converts a tsvector to an array of lexemes.
+
+
+ tsvector_to_array('fat:2,4 cat:3 rat:5A'::tsvector)
+ {cat,fat,rat}
+
+
+
+
+
+
+ unnest
+ for tsvector
+
+ unnest ( tsvector )
+ setof record
+ ( lexemetext,
+ positionssmallint[],
+ weightstext )
+
+
+ Expands a tsvector into a set of rows, one per lexeme.
+
+
+ select * from unnest('cat:3 fat:2,4 rat:5A'::tsvector)
+
+
+ lexeme | positions | weights
+--------+-----------+---------
+ cat | {3} | {D}
+ fat | {2,4} | {D,D}
+ rat | {5} | {A}
+
+
+
+
+
+
+
+
+
+ All the text search functions that accept an optional regconfig
+ argument will use the configuration specified by
+
+ when that argument is omitted.
+
+
+
+
+ The functions in
+
+ are listed separately because they are not usually used in everyday text
+ searching operations. They are primarily helpful for development and
+ debugging of new text search configurations.
+
+
+
+ Text Search Debugging Functions
+
+
+
+
+ Function
+
+
+ Description
+
+
+ Example(s)
+
+
+
+
+
+
+
+
+ ts_debug
+
+ ts_debug (
+ configregconfig,
+ documenttext )
+ setof record
+ ( aliastext,
+ descriptiontext,
+ tokentext,
+ dictionariesregdictionary[],
+ dictionaryregdictionary,
+ lexemestext[] )
+
+
+ Extracts and normalizes tokens from
+ the document according to the specified or
+ default text search configuration, and returns information about how
+ each token was processed.
+ See for details.
+
+
+ ts_debug('english', 'The Brightest supernovaes')
+ (asciiword,"Word, all ASCII",The,{english_stem},english_stem,{}) ...
+
+
+
+
+
+
+ ts_lexize
+
+ ts_lexize ( dictregdictionary, tokentext )
+ text[]
+
+
+ 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 for details.
+
+
+ ts_lexize('english_stem', 'stars')
+ {star}
+
+
+
+
+
+
+ ts_parse
+
+ ts_parse ( parser_nametext,
+ documenttext )
+ setof record
+ ( tokidinteger,
+ tokentext )
+
+
+ Extracts tokens from the document using the
+ named parser.
+ See for details.
+
+
+ ts_parse('default', 'foo - bar')
+ (1,foo) ...
+
+
+
+
+
+ ts_parse ( parser_oidoid,
+ documenttext )
+ setof record
+ ( tokidinteger,
+ tokentext )
+
+
+ Extracts tokens from the document using a
+ parser specified by OID.
+ See for details.
+
+
+ ts_parse(3722, 'foo - bar')
+ (1,foo) ...
+
+
+
+
+
+
+ ts_token_type
+
+ ts_token_type ( parser_nametext )
+ setof record
+ ( tokidinteger,
+ aliastext,
+ descriptiontext )
+
+
+ Returns a table that describes each type of token the named parser can
+ recognize.
+ See for details.
+
+
+ ts_token_type('default')
+ (1,asciiword,"Word, all ASCII") ...
+
+
+
+
+
+ ts_token_type ( parser_oidoid )
+ setof record
+ ( tokidinteger,
+ aliastext,
+ descriptiontext )
+
+
+ Returns a table that describes each type of token a parser specified
+ by OID can recognize.
+ See for details.
+
+
+ ts_token_type(3722)
+ (1,asciiword,"Word, all ASCII") ...
+
+
+
+
+
+
+ ts_stat
+
+ ts_stat ( sqlquerytext
+ , weightstext )
+ setof record
+ ( wordtext,
+ ndocinteger,
+ nentryinteger )
+
+
+ Executes the sqlquery, which must return a
+ single tsvector column, and returns statistics about each
+ distinct lexeme contained in the data.
+ See for details.
+
+
+ ts_stat('SELECT vector FROM apod')
+ (foo,10,15) ...
+
+
+
+
+
+
+
diff --git a/doc/src/sgml/func/func-trigger.sgml b/doc/src/sgml/func/func-trigger.sgml
new file mode 100644
index 0000000000000..94b40adbdb84a
--- /dev/null
+++ b/doc/src/sgml/func/func-trigger.sgml
@@ -0,0 +1,135 @@
+
+ Trigger Functions
+
+
+ While many uses of triggers involve user-written trigger functions,
+ PostgreSQL provides a few built-in trigger
+ functions that can be used directly in user-defined triggers. These
+ are summarized in .
+ (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.)
+
+
+
+ For more information about creating triggers, see
+ .
+
+
+
+ Built-In Trigger Functions
+
+
+
+
+ Function
+
+
+ Description
+
+
+ Example Usage
+
+
+
+
+
+
+
+
+ suppress_redundant_updates_trigger
+
+ suppress_redundant_updates_trigger ( )
+ trigger
+
+
+ Suppresses do-nothing update operations. See below for details.
+
+
+ CREATE TRIGGER ... suppress_redundant_updates_trigger()
+
+
+
+
+
+
+ tsvector_update_trigger
+
+ tsvector_update_trigger ( )
+ trigger
+
+
+ Automatically updates a tsvector column from associated
+ plain-text document column(s). The text search configuration to use
+ is specified by name as a trigger argument. See
+ for details.
+
+
+ CREATE TRIGGER ... tsvector_update_trigger(tsvcol, 'pg_catalog.swedish', title, body)
+
+
+
+
+
+
+ tsvector_update_trigger_column
+
+ tsvector_update_trigger_column ( )
+ trigger
+
+
+ Automatically updates a tsvector column from associated
+ plain-text document column(s). The text search configuration to use
+ is taken from a regconfig column of the table. See
+ for details.
+
+
+ CREATE TRIGGER ... tsvector_update_trigger_column(tsvcol, tsconfigcol, title, body)
+
+
+
+
+
+
+
+ The suppress_redundant_updates_trigger function,
+ when applied as a row-level BEFORE UPDATE 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.)
+
+
+
+ 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
+ suppress_redundant_updates_trigger, 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.
+
+
+
+ The suppress_redundant_updates_trigger function can be
+ added to a table like this:
+
+CREATE TRIGGER z_min_update
+BEFORE UPDATE ON tablename
+FOR EACH ROW EXECUTE FUNCTION suppress_redundant_updates_trigger();
+
+ 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 z prefix in the
+ example.)
+
+
diff --git a/doc/src/sgml/func/func-uuid.sgml b/doc/src/sgml/func/func-uuid.sgml
new file mode 100644
index 0000000000000..65c5ddec6b7dc
--- /dev/null
+++ b/doc/src/sgml/func/func-uuid.sgml
@@ -0,0 +1,188 @@
+
+ UUID Functions
+
+
+ UUID
+ generating
+
+
+
+ gen_random_uuid
+
+
+
+ uuidv4
+
+
+
+ uuidv7
+
+
+
+ uuid_extract_timestamp
+
+
+
+ uuid_extract_version
+
+
+
+ shows the PostgreSQL
+ functions that can be used to generate UUIDs.
+
+
+
+ <acronym>UUID</acronym> Generation Functions
+
+
+
+
+
+ Function
+
+
+ Description
+
+
+ Example(s)
+
+
+
+
+
+
+
+
+
+ gen_random_uuid
+ uuid
+
+
+ uuidv4
+ uuid
+
+
+ Generate a version 4 (random) UUID.
+
+
+ gen_random_uuid()
+ 5b30857f-0bfa-48b5-ac0b-5c64e28078d1
+
+
+ uuidv4()
+ b42410ee-132f-42ee-9e4f-09a6485c95b8
+
+
+
+
+
+
+ uuidv7
+ ( shiftinterval )
+ uuid
+
+
+ Generate a version 7 (time-ordered) UUID. The timestamp is computed using UNIX timestamp
+ with millisecond precision + sub-millisecond timestamp + random. The optional parameter
+ shift will shift the computed timestamp by the given interval.
+
+
+ uuidv7()
+ 019535d9-3df7-79fb-b466-fa907fa17f9e
+
+
+
+
+
+
+
+
+
+ The module provides additional functions that
+ implement other standard algorithms for generating UUIDs.
+
+
+
+
+ shows the PostgreSQL
+ functions that can be used to extract information from UUIDs.
+
+
+
+ <acronym>UUID</acronym> Extraction Functions
+
+
+
+
+
+ Function
+
+
+ Description
+
+
+ Example(s)
+
+
+
+
+
+
+
+
+
+ uuid_extract_timestamp
+ ( uuid )
+ timestamp with time zone
+
+
+ Extracts a timestamp with time zone from UUID
+ version 1 and 7. For other versions, this function returns null. Note that
+ the extracted timestamp is not necessarily exactly equal to the time the
+ UUID was generated; this depends on the implementation that generated the
+ UUID.
+
+
+ uuid_extract_timestamp('019535d9-3df7-79fb-b466-&zwsp;fa907fa17f9e'::uuid)
+ 2025-02-23 21:46:24.503-05
+
+
+
+
+
+
+ uuid_extract_version
+ ( uuid )
+ smallint
+
+
+ Extracts the version from a UUID of the variant described by
+ RFC 9562. For
+ other variants, this function returns null. For example, for a UUID
+ generated by gen_random_uuid, this function will
+ return 4.
+
+
+ uuid_extract_version('41db1265-8bc1-4ab3-992f-&zwsp;885799a4af1d'::uuid)
+ 4
+
+
+ uuid_extract_version('019535d9-3df7-79fb-b466-&zwsp;fa907fa17f9e'::uuid)
+ 7
+
+
+
+
+
+
+
+
+ PostgreSQL also provides the usual comparison
+ operators shown in for
+ UUIDs.
+
+
+ See for details on the data type
+ uuid in PostgreSQL.
+
+
diff --git a/doc/src/sgml/func/func-window.sgml b/doc/src/sgml/func/func-window.sgml
new file mode 100644
index 0000000000000..cce0165b9526e
--- /dev/null
+++ b/doc/src/sgml/func/func-window.sgml
@@ -0,0 +1,284 @@
+
+ Window Functions
+
+
+ window function
+ built-in
+
+
+
+ Window functions provide the ability to perform
+ calculations across sets of rows that are related to the current query
+ row. See for an introduction to this
+ feature, and for syntax
+ details.
+
+
+
+ The built-in window functions are listed in
+ . Note that these functions
+ must be invoked using window function syntax, i.e., an
+ OVER clause is required.
+
+
+
+ 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
+ for a list of the built-in aggregates.
+ Aggregate functions act as window functions only when an OVER
+ clause follows the call; otherwise they act as plain aggregates
+ and return a single row for the entire set.
+
+
+
+ General-Purpose Window Functions
+
+
+
+
+ Function
+
+
+ Description
+
+
+
+
+
+
+
+
+ row_number
+
+ row_number ()
+ bigint
+
+
+ Returns the number of the current row within its partition, counting
+ from 1.
+
+
+
+
+
+
+ rank
+
+ rank ()
+ bigint
+
+
+ Returns the rank of the current row, with gaps; that is,
+ the row_number of the first row in its peer
+ group.
+
+
+
+
+
+
+ dense_rank
+
+ dense_rank ()
+ bigint
+
+
+ Returns the rank of the current row, without gaps; this function
+ effectively counts peer groups.
+
+
+
+
+
+
+ percent_rank
+
+ percent_rank ()
+ double precision
+
+
+ Returns the relative rank of the current row, that is
+ (rank - 1) / (total partition rows - 1).
+ The value thus ranges from 0 to 1 inclusive.
+
+
+
+
+
+
+ cume_dist
+
+ cume_dist ()
+ double precision
+
+
+ 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/N to 1.
+
+
+
+
+
+
+ ntile
+
+ ntile ( num_bucketsinteger )
+ integer
+
+
+ Returns an integer ranging from 1 to the argument value, dividing the
+ partition as equally as possible.
+
+
+
+
+
+
+ lag
+
+ lag ( valueanycompatible
+ , offsetinteger
+ , defaultanycompatible )
+ anycompatible
+
+
+ Returns value evaluated at
+ the row that is offset
+ rows before the current row within the partition; if there is no such
+ row, instead returns default
+ (which must be of a type compatible with
+ value).
+ Both offset and
+ default are evaluated
+ with respect to the current row. If omitted,
+ offset defaults to 1 and
+ default to NULL.
+
+
+
+
+
+
+ lead
+
+ lead ( valueanycompatible
+ , offsetinteger
+ , defaultanycompatible )
+ anycompatible
+
+
+ Returns value evaluated at
+ the row that is offset
+ rows after the current row within the partition; if there is no such
+ row, instead returns default
+ (which must be of a type compatible with
+ value).
+ Both offset and
+ default are evaluated
+ with respect to the current row. If omitted,
+ offset defaults to 1 and
+ default to NULL.
+
+
+
+
+
+
+ first_value
+
+ first_value ( valueanyelement )
+ anyelement
+
+
+ Returns value evaluated
+ at the row that is the first row of the window frame.
+
+
+
+
+
+
+ last_value
+
+ last_value ( valueanyelement )
+ anyelement
+
+
+ Returns value evaluated
+ at the row that is the last row of the window frame.
+
+
+
+
+
+
+ nth_value
+
+ nth_value ( valueanyelement, ninteger )
+ anyelement
+
+
+ Returns value evaluated
+ at the row that is the n'th
+ row of the window frame (counting from 1);
+ returns NULL if there is no such row.
+
+
+
+
+
+
+
+ All of the functions listed in
+ depend on the sort ordering
+ specified by the ORDER BY clause of the associated window
+ definition. Rows that are not distinct when considering only the
+ ORDER BY columns are said to be peers.
+ The four ranking functions (including cume_dist) are
+ defined so that they give the same answer for all rows of a peer group.
+
+
+
+ Note that first_value, last_value, and
+ nth_value consider only the rows within the window
+ frame, 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 last_value and
+ sometimes also nth_value. You can redefine the frame by
+ adding a suitable frame specification (RANGE,
+ ROWS or GROUPS) to
+ the OVER clause.
+ See for more information
+ about frame specifications.
+
+
+
+ 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 ORDER BY and the default window frame
+ definition produces a running sum type of behavior, which may or
+ may not be what's wanted. To obtain
+ aggregation over the whole partition, omit ORDER BY or use
+ ROWS BETWEEN UNBOUNDED PRECEDING AND UNBOUNDED FOLLOWING.
+ Other frame specifications can be used to obtain other effects.
+
+
+
+
+ The SQL standard defines a RESPECT NULLS or
+ IGNORE NULLS option for lead, lag,
+ first_value, last_value, and
+ nth_value. This is not implemented in
+ PostgreSQL: the behavior is always the
+ same as the standard's default, namely RESPECT NULLS.
+ Likewise, the standard's FROM FIRST or FROM LAST
+ option for nth_value is not implemented: only the
+ default FROM FIRST behavior is supported. (You can achieve
+ the result of FROM LAST by reversing the ORDER BY
+ ordering.)
+
+
+
+
diff --git a/doc/src/sgml/func/func-xml.sgml b/doc/src/sgml/func/func-xml.sgml
new file mode 100644
index 0000000000000..21f34467a4f8a
--- /dev/null
+++ b/doc/src/sgml/func/func-xml.sgml
@@ -0,0 +1,1283 @@
+
+
+ XML Functions
+
+
+ XML Functions
+
+
+
+ The functions and function-like expressions described in this
+ section operate on values of type xml. See for information about the xml
+ type. The function-like expressions xmlparse
+ and xmlserialize for converting to and from
+ type xml are documented there, not in this section.
+
+
+
+ Use of most of these functions
+ requires PostgreSQL to have been built
+ with configure --with-libxml.
+
+
+
+ Producing XML Content
+
+
+ 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.
+
+
+
+ <literal>xmltext</literal>
+
+
+ xmltext
+
+
+
+xmltext ( text ) xml
+
+
+
+ The function xmltext returns an XML value with a single
+ text node containing the input argument as its content. Predefined entities
+ like ampersand (), left and right angle brackets
+ (]]>), and quotation marks ()
+ are escaped.
+
+
+
+ Example:
+');
+ xmltext
+-------------------------
+ < foo & bar >
+]]>
+
+
+
+
+ <literal>xmlcomment</literal>
+
+
+ xmlcomment
+
+
+
+xmlcomment ( text ) xml
+
+
+
+ The function xmlcomment creates an XML value
+ containing an XML comment with the specified text as content.
+ The text cannot contain -- or end with a
+ -, otherwise the resulting construct
+ would not be a valid XML comment.
+ If the argument is null, the result is null.
+
+
+
+ Example:
+
+]]>
+
+
+
+
+ <literal>xmlconcat</literal>
+
+
+ xmlconcat
+
+
+
+xmlconcat ( xml, ... ) xml
+
+
+
+ The function xmlconcat 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.
+
+
+
+ Example:
+', 'foo');
+
+ xmlconcat
+----------------------
+ foo
+]]>
+
+
+
+ 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
+ yes, then that value is used in the result. If
+ all argument values have a standalone declaration value and at
+ least one is no, 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.
+
+
+
+ Example:
+', '');
+
+ xmlconcat
+-----------------------------------
+
+]]>
+
+
+
+
+ <literal>xmlelement</literal>
+
+
+ xmlelement
+
+
+
+xmlelement ( NAMEname, XMLATTRIBUTES ( attvalueASattname, ... ) , content, ... ) xml
+
+
+
+ The xmlelement expression produces an XML
+ element with the given name, attributes, and content.
+ The name
+ and attname items shown in the syntax are
+ simple identifiers, not values. The attvalue
+ and content items are expressions, which can
+ yield any PostgreSQL data type. The
+ argument(s) within XMLATTRIBUTES generate attributes
+ of the XML element; the content value(s) are
+ concatenated to form its content.
+
+
+
+ Examples:
+
+
+SELECT xmlelement(name foo, xmlattributes('xyz' as bar));
+
+ xmlelement
+------------------
+
+
+SELECT xmlelement(name foo, xmlattributes(current_date as bar), 'cont', 'ent');
+
+ xmlelement
+-------------------------------------
+ content
+]]>
+
+
+
+ Element and attribute names that are not valid XML names are
+ escaped by replacing the offending characters by the sequence
+ _xHHHH_, where
+ HHHH is the character's Unicode
+ codepoint in hexadecimal notation. For example:
+
+]]>
+
+
+
+ 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:
+
+CREATE TABLE test (a xml, b xml);
+SELECT xmlelement(name test, xmlattributes(a, b)) FROM test;
+
+ But these are not:
+
+SELECT xmlelement(name test, xmlattributes('constant'), a, b) FROM test;
+SELECT xmlelement(name test, xmlattributes(func(a, b))) FROM test;
+
+
+
+
+ Element content, if specified, will be formatted according to
+ its data type. If the content is itself of type xml,
+ complex XML documents can be constructed. For example:
+
+]]>
+
+ Content of other types will be formatted into valid XML character
+ data. This means in particular that the characters <, >,
+ and & will be converted to entities. Binary data (data type
+ bytea) will be represented in base64 or hex
+ encoding, depending on the setting of the configuration parameter
+ . The particular behavior for
+ 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 .
+
+
+
+
+ <literal>xmlforest</literal>
+
+
+ xmlforest
+
+
+
+xmlforest ( contentASname, ... ) xml
+
+
+
+ The xmlforest expression produces an XML
+ forest (sequence) of elements using the given names and content.
+ As for xmlelement,
+ each name must be a simple identifier, while
+ the content expressions can have any data
+ type.
+
+
+
+ Examples:
+
+SELECT xmlforest('abc' AS foo, 123 AS bar);
+
+ xmlforest
+------------------------------
+ <foo>abc</foo><bar>123</bar>
+
+
+SELECT xmlforest(table_name, column_name)
+FROM information_schema.columns
+WHERE table_schema = 'pg_catalog';
+
+ xmlforest
+------------------------------------&zwsp;-----------------------------------
+ <table_name>pg_authid</table_name>&zwsp;<column_name>rolname</column_name>
+ <table_name>pg_authid</table_name>&zwsp;<column_name>rolsuper</column_name>
+ ...
+
+
+ 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.
+
+
+
+ Element names that are not valid XML names are escaped as shown
+ for xmlelement above. Similarly, content
+ data is escaped to make valid XML content, unless it is already
+ of type xml.
+
+
+
+ Note that XML forests are not valid XML documents if they consist
+ of more than one element, so it might be useful to wrap
+ xmlforest expressions in
+ xmlelement.
+
+
+
+
+ <literal>xmlpi</literal>
+
+
+ xmlpi
+
+
+
+xmlpi ( NAMEname, content ) xml
+
+
+
+ The xmlpi expression creates an XML
+ processing instruction.
+ As for xmlelement,
+ the name must be a simple identifier, while
+ the content expression can have any data type.
+ The content, if present, must not contain the
+ character sequence ?>.
+
+
+
+ Example:
+
+]]>
+
+
+
+
+ <literal>xmlroot</literal>
+
+
+ xmlroot
+
+
+
+xmlroot ( xml, VERSION {text|NO VALUE} , STANDALONE {YES|NO|NO VALUE} ) xml
+
+
+
+ The xmlroot 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.
+
+
+
+abc'),
+ version '1.0', standalone yes);
+
+ xmlroot
+----------------------------------------
+
+ abc
+]]>
+
+
+
+
+ <literal>xmlagg</literal>
+
+
+ xmlagg
+
+
+
+xmlagg ( xml ) xml
+
+
+
+ The function xmlagg is, unlike the other
+ functions described here, an aggregate function. It concatenates the
+ input values to the aggregate function call,
+ much like xmlconcat does, except that concatenation
+ occurs across rows rather than across expressions in a single row.
+ See for additional information
+ about aggregate functions.
+
+
+
+ Example:
+abc');
+INSERT INTO test VALUES (2, '');
+SELECT xmlagg(x) FROM test;
+ xmlagg
+----------------------
+ abc
+]]>
+
+
+
+ To determine the order of the concatenation, an ORDER BY
+ clause may be added to the aggregate call as described in
+ . For example:
+
+abc
+]]>
+
+
+
+ The following non-standard approach used to be recommended
+ in previous versions, and may still be useful in specific
+ cases:
+
+abc
+]]>
+
+
+
+
+
+ XML Predicates
+
+
+ The expressions described in this section check properties
+ of xml values.
+
+
+
+ <literal>IS DOCUMENT</literal>
+
+
+ IS DOCUMENT
+
+
+
+xmlIS DOCUMENTboolean
+
+
+
+ The expression IS DOCUMENT returns true if the
+ argument XML value is a proper XML document, false if it is not
+ (that is, it is a content fragment), or null if the argument is
+ null. See about the difference
+ between documents and content fragments.
+
+
+
+
+ <literal>IS NOT DOCUMENT</literal>
+
+
+ IS NOT DOCUMENT
+
+
+
+xmlIS NOT DOCUMENTboolean
+
+
+
+ The expression IS NOT DOCUMENT 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.
+
+
+
+
+ <literal>XMLEXISTS</literal>
+
+
+ XMLEXISTS
+
+
+
+XMLEXISTS ( textPASSINGBY {REF|VALUE}xmlBY {REF|VALUE} ) boolean
+
+
+
+ The function xmlexists 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.
+
+
+
+ Example:
+ TorontoOttawa');
+
+ xmlexists
+------------
+ t
+(1 row)
+]]>
+
+
+
+ The BY REF and BY VALUE clauses
+ are accepted in PostgreSQL, but are ignored,
+ as discussed in .
+
+
+
+ In the SQL standard, the xmlexists function
+ evaluates an expression in the XML Query language,
+ but PostgreSQL allows only an XPath 1.0
+ expression, as discussed in
+ .
+
+
+
+
+ <literal>xml_is_well_formed</literal>
+
+
+ xml_is_well_formed
+
+
+
+ xml_is_well_formed_document
+
+
+
+ xml_is_well_formed_content
+
+
+
+xml_is_well_formed ( text ) boolean
+xml_is_well_formed_document ( text ) boolean
+xml_is_well_formed_content ( text ) boolean
+
+
+
+ These functions check whether a text string represents
+ well-formed XML, returning a Boolean result.
+ xml_is_well_formed_document checks for a well-formed
+ document, while xml_is_well_formed_content checks
+ for well-formed content. xml_is_well_formed does
+ the former if the configuration
+ parameter is set to DOCUMENT, or the latter if it is set to
+ CONTENT. This means that
+ xml_is_well_formed is useful for seeing whether
+ a simple cast to type xml will succeed, whereas the other two
+ functions are useful for seeing whether the corresponding variants of
+ XMLPARSE will succeed.
+
+
+
+ Examples:
+
+');
+ xml_is_well_formed
+--------------------
+ f
+(1 row)
+
+SELECT xml_is_well_formed('');
+ 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('bar');
+ xml_is_well_formed_document
+-----------------------------
+ t
+(1 row)
+
+SELECT xml_is_well_formed_document('bar');
+ xml_is_well_formed_document
+-----------------------------
+ f
+(1 row)
+]]>
+
+ The last example shows that the checks include whether
+ namespaces are correctly matched.
+
+
+
+
+
+ Processing XML
+
+
+ To process values of data type xml, PostgreSQL offers
+ the functions xpath and
+ xpath_exists, which evaluate XPath 1.0
+ expressions, and the XMLTABLE
+ table function.
+
+
+
+ <literal>xpath</literal>
+
+
+ XPath
+
+
+
+xpath ( xpathtext, xmlxml, nsarraytext[] ) xml[]
+
+
+
+ The function xpath evaluates the XPath 1.0
+ expression xpath (given as text)
+ against the XML value
+ xml. 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.
+
+
+
+ The second argument must be a well formed XML document. In particular,
+ it must have a single root node element.
+
+
+
+ The optional third argument of the function is an array of namespace
+ mappings. This array should be a two-dimensional text array with
+ the length of the second axis being equal to 2 (i.e., it should be an
+ array of arrays, each of which consists of exactly 2 elements).
+ The first element of each array entry is the namespace name (alias), the
+ second the namespace URI. It is not required that aliases provided in
+ this array be the same as those being used in the XML document itself (in
+ other words, both in the XML document and in the xpath
+ function context, aliases are local).
+
+
+
+ Example:
+test',
+ ARRAY[ARRAY['my', 'http://example.com']]);
+
+ xpath
+--------
+ {test}
+(1 row)
+]]>
+
+
+
+ To deal with default (anonymous) namespaces, do something like this:
+test',
+ ARRAY[ARRAY['mydefns', 'http://example.com']]);
+
+ xpath
+--------
+ {test}
+(1 row)
+]]>
+
+
+
+
+ <literal>xpath_exists</literal>
+
+
+ xpath_exists
+
+
+
+xpath_exists ( xpathtext, xmlxml, nsarraytext[] ) boolean
+
+
+
+ The function xpath_exists is a specialized form
+ of the xpath 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 XMLEXISTS predicate,
+ except that it also offers support for a namespace mapping argument.
+
+
+
+ Example:
+test',
+ ARRAY[ARRAY['my', 'http://example.com']]);
+
+ xpath_exists
+--------------
+ t
+(1 row)
+]]>
+
+
+
+
+ <literal>xmltable</literal>
+
+
+ xmltable
+
+
+
+ table function
+ XMLTABLE
+
+
+
+XMLTABLE (
+ XMLNAMESPACES ( namespace_uriASnamespace_name, ... ),
+ row_expressionPASSINGBY {REF|VALUE}document_expressionBY {REF|VALUE}
+ COLUMNSname { typePATHcolumn_expressionDEFAULTdefault_expressionNOT NULL | NULL
+ | FOR ORDINALITY }
+ , ...
+) setof record
+
+
+
+ The xmltable 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 FROM clause.
+
+
+
+ The optional XMLNAMESPACES clause gives a
+ comma-separated list of namespace definitions, where
+ each namespace_uri is a text
+ expression and each namespace_name is a simple
+ identifier. It specifies the XML namespaces used in the document and
+ their aliases. A default namespace specification is not currently
+ supported.
+
+
+
+ The required row_expression argument is an
+ XPath 1.0 expression (given as text) that is evaluated,
+ passing the XML value document_expression as
+ its context item, to obtain a set of XML nodes. These nodes are what
+ xmltable transforms into output rows. No rows
+ will be produced if the document_expression
+ is null, nor if the row_expression produces
+ an empty node-set or any value other than a node-set.
+
+
+
+ document_expression provides the context
+ item for the row_expression. It must be a
+ well-formed XML document; fragments/forests are not accepted.
+ The BY REF and BY VALUE clauses
+ are accepted but ignored, as discussed in
+ .
+
+
+
+ In the SQL standard, the xmltable function
+ evaluates expressions in the XML Query language,
+ but PostgreSQL allows only XPath 1.0
+ expressions, as discussed in
+ .
+
+
+
+ The required COLUMNS 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 FOR ORDINALITY is specified, in which case
+ type integer is implicit). The path, default and
+ nullability clauses are optional.
+
+
+
+ A column marked FOR ORDINALITY will be populated
+ with row numbers, starting with 1, in the order of nodes retrieved from
+ the row_expression's result node-set.
+ At most one column may be marked FOR ORDINALITY.
+
+
+
+
+ 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
+ .
+
+
+
+
+ The column_expression for a column is an
+ XPath 1.0 expression that is evaluated for each row, with the current
+ node from the row_expression result as its
+ context item, to find the value of the column. If
+ no column_expression is given, then the
+ column name is used as an implicit path.
+
+
+
+ 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 xml, 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 1 or 0 if the output
+ column's type category is numeric, otherwise true or
+ false.)
+
+
+
+ If a column's XPath expression returns a non-empty set of XML nodes
+ and the column's PostgreSQL type is xml, the column will
+ be assigned the expression result exactly, if it is of document or
+ content form.
+
+
+ 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
+ string function.
+
+
+
+
+
+ A non-XML result assigned to an xml 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 string function)
+ to the PostgreSQL type.
+
+
+
+ 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 NULL).
+ Any xsi:nil attributes are ignored.
+ Note that the whitespace-only text() node between two non-text
+ elements is preserved, and that leading whitespace on a text()
+ node is not flattened.
+ The XPath 1.0 string function may be consulted for the
+ rules defining the string value of other XML node types and non-XML values.
+
+
+
+ The conversion rules presented here are not exactly those of the SQL
+ standard, as discussed in .
+
+
+
+ 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 NULL, unless
+ a default_expression is specified; then the
+ value resulting from evaluating that expression is used.
+
+
+
+ A default_expression, rather than being
+ evaluated immediately when xmltable 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
+ nextval in
+ default_expression.
+
+
+
+ Columns may be marked NOT NULL. If the
+ column_expression for a NOT
+ NULL column does not match anything and there is
+ no DEFAULT or
+ the default_expression also evaluates to null,
+ an error is reported.
+
+
+
+ Examples:
+
+
+ AU
+ Australia
+
+
+ JP
+ Japan
+ Shinzo Abe
+ 145935
+
+
+ SG
+ Singapore
+ 697
+
+
+$$ 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
+]]>
+
+ 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:
+
+
+ Hello2a2 bbbxxxCC
+
+$$ AS data;
+
+SELECT xmltable.*
+ FROM xmlelements, XMLTABLE('/root' PASSING data COLUMNS element text);
+ element
+-------------------------
+ Hello2a2 bbbxxxCC
+]]>
+
+
+
+ The following example illustrates how
+ the XMLNAMESPACES clause can be used to specify
+ a list of namespaces
+ used in the XML document as well as in the XPath expressions:
+
+
+
+
+
+'::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)
+]]>
+
+
+
+
+
+ Mapping Tables to XML
+
+
+ XML export
+
+
+
+ The following functions map the contents of relational tables to
+ XML values. They can be thought of as XML export functionality:
+
+table_to_xml ( tableregclass, nullsboolean,
+ tableforestboolean, targetnstext ) xml
+query_to_xml ( querytext, nullsboolean,
+ tableforestboolean, targetnstext ) xml
+cursor_to_xml ( cursorrefcursor, countinteger, nullsboolean,
+ tableforestboolean, targetnstext ) xml
+
+
+
+
+ table_to_xml maps the content of the named
+ table, passed as parameter table. The
+ regclass type accepts strings identifying tables using the
+ usual notation, including optional schema qualification and
+ double quotes (see for details).
+ query_to_xml executes the
+ query whose text is passed as parameter
+ query and maps the result set.
+ cursor_to_xml fetches the indicated number of
+ rows from the cursor specified by the parameter
+ cursor. This variant is recommended if
+ large tables have to be mapped, because the result value is built
+ up in memory by each function.
+
+
+
+ If tableforest is false, then the resulting
+ XML document looks like this:
+
+
+ data
+ data
+
+
+
+ ...
+
+
+ ...
+
+]]>
+
+ If tableforest is true, the result is an
+ XML content fragment that looks like this:
+
+ data
+ data
+
+
+
+ ...
+
+
+...
+]]>
+
+ If no table name is available, that is, when mapping a query or a
+ cursor, the string table is used in the first
+ format, row in the second format.
+
+
+
+ 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
+ cursor_to_xml function if the result values are to be
+ reassembled into one document later on. The functions for
+ producing XML content discussed above, in particular
+ xmlelement, can be used to alter the results
+ to taste.
+
+
+
+ The data values are mapped in the same way as described for the
+ function xmlelement above.
+
+
+
+ The parameter nulls determines whether null
+ values should be included in the output. If true, null values in
+ columns are represented as:
+
+]]>
+ where xsi 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.
+
+
+
+ The parameter targetns specifies the
+ desired XML namespace of the result. If no particular namespace
+ is wanted, an empty string should be passed.
+
+
+
+ The following functions return XML Schema documents describing the
+ mappings performed by the corresponding functions above:
+
+table_to_xmlschema ( tableregclass, nullsboolean,
+ tableforestboolean, targetnstext ) xml
+query_to_xmlschema ( querytext, nullsboolean,
+ tableforestboolean, targetnstext ) xml
+cursor_to_xmlschema ( cursorrefcursor, nullsboolean,
+ tableforestboolean, targetnstext ) xml
+
+ It is essential that the same parameters are passed in order to
+ obtain matching XML data mappings and XML Schema documents.
+
+
+
+ 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:
+
+table_to_xml_and_xmlschema ( tableregclass, nullsboolean,
+ tableforestboolean, targetnstext ) xml
+query_to_xml_and_xmlschema ( querytext, nullsboolean,
+ tableforestboolean, targetnstext ) xml
+
+
+
+
+ In addition, the following functions are available to produce
+ analogous mappings of entire schemas or the entire current
+ database:
+
+schema_to_xml ( schemaname, nullsboolean,
+ tableforestboolean, targetnstext ) xml
+schema_to_xmlschema ( schemaname, nullsboolean,
+ tableforestboolean, targetnstext ) xml
+schema_to_xml_and_xmlschema ( schemaname, nullsboolean,
+ tableforestboolean, targetnstext ) xml
+
+database_to_xml ( nullsboolean,
+ tableforestboolean, targetnstext ) xml
+database_to_xmlschema ( nullsboolean,
+ tableforestboolean, targetnstext ) xml
+database_to_xml_and_xmlschema ( nullsboolean,
+ tableforestboolean, targetnstext ) xml
+
+
+ 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 USAGE (lookup) privilege for.
+
+
+
+ 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.
+
+
+
+ The result of a schema content mapping looks like this:
+
+
+
+table1-mapping
+
+table2-mapping
+
+...
+
+]]>
+
+ where the format of a table mapping depends on the
+ tableforest parameter as explained above.
+
+
+
+ The result of a database content mapping looks like this:
+
+
+
+
+ ...
+
+
+
+ ...
+
+
+...
+
+]]>
+
+ where the schema mapping is as above.
+
+
+
+ As an example of using the output produced by these functions,
+ shows an XSLT stylesheet that
+ converts the output of
+ table_to_xml_and_xmlschema to an HTML
+ document containing a tabular rendition of the table data. In a
+ similar manner, the results from these functions can be
+ converted into other XML-based formats.
+
+
+
+ XSLT Stylesheet for Converting SQL/XML Output to HTML
+
+
+
+
+
+
+
+
+
+
+
+
+ <xsl:value-of select="name(current())"/>
+
+
+
+ Replication Result Summary
+
+
+
+
+ Publish generated columns?
+ Publisher table column
+ Subscriber table column
+ Result
+
+
+
+
+
+ No
+ GENERATED
+ GENERATED
+ Publisher table column is not replicated. Use the subscriber table generated column value.
+
+
+
+ No
+ GENERATED
+ regular
+ Publisher table column is not replicated. Use the subscriber table regular column default value.
+
+
+
+ No
+ GENERATED
+ --missing--
+ Publisher table column is not replicated. Nothing happens.
+
+
+
+ Yes
+ GENERATED
+ GENERATED
+ ERROR. Not supported.
+
+
+
+ Yes
+ GENERATED
+ regular
+ Publisher table column value is replicated to the subscriber table column.
+
+
+
+ Yes
+ GENERATED
+ --missing--
+ ERROR. The column is reported as missing from the subscriber table.
+
+
+
+
+
+
+
+ There's currently no support for subscriptions comprising several
+ publications where the same table has been published with different column
+ lists. See .
+
+
+
+ This same situation can occur if one publication is publishing generated
+ columns, while another publication in the same subscription is not
+ publishing generated columns for the same table.
+
+
+
+
+
+ If the subscriber is from a release prior to 18, then initial table
+ synchronization won't copy generated columns even if they are defined in
+ the publisher.
+
+
+
+
Conflicts
@@ -1470,8 +1752,236 @@ test_sub=# SELECT * FROM t1 ORDER BY id;
node. If incoming data violates any constraints the replication will
stop. This is referred to as a conflict. When
replicating UPDATE or DELETE
- operations, missing data will not produce a conflict and such operations
- will simply be skipped.
+ operations, missing data is also considered as a
+ conflict, but does not result in an error and such
+ operations will simply be skipped.
+
+
+
+ Additional logging is triggered, and the conflict statistics are collected (displayed in the
+ pg_stat_subscription_stats view)
+ in the following conflict cases:
+
+
+ insert_exists
+
+
+ Inserting a row that violates a NOT DEFERRABLE
+ unique constraint. Note that to log the origin and commit
+ timestamp details of the conflicting key,
+ track_commit_timestamp
+ should be enabled on the subscriber. In this case, an error will be
+ raised until the conflict is resolved manually.
+
+
+
+
+ update_origin_differs
+
+
+ Updating a row that was previously modified by another origin.
+ Note that this conflict can only be detected when
+ track_commit_timestamp
+ is enabled on the subscriber. Currently, the update is always applied
+ regardless of the origin of the local row.
+
+
+
+
+ update_exists
+
+
+ The updated value of a row violates a NOT DEFERRABLE
+ unique constraint. Note that to log the origin and commit
+ timestamp details of the conflicting key,
+ track_commit_timestamp
+ should be enabled on the subscriber. In this case, an error will be
+ raised until the conflict is resolved manually. Note that when updating a
+ partitioned table, if the updated row value satisfies another partition
+ constraint resulting in the row being inserted into a new partition, the
+ insert_exists conflict may arise if the new row
+ violates a NOT DEFERRABLE unique constraint.
+
+
+
+
+ update_deleted
+
+
+ The tuple to be updated was concurrently deleted by another origin. The
+ update will simply be skipped in this scenario. Note that this conflict
+ can only be detected when
+ track_commit_timestamp
+ and retain_dead_tuples
+ are enabled. Note that if a tuple cannot be found due to the table being
+ truncated, only a update_missing conflict will
+ arise. Additionally, if the tuple was deleted by the same origin, an
+ update_missing conflict will arise.
+
+
+
+
+ update_missing
+
+
+ The row to be updated was not found. The update will simply be
+ skipped in this scenario.
+
+
+
+
+ delete_origin_differs
+
+
+ Deleting a row that was previously modified by another origin. Note that
+ this conflict can only be detected when
+ track_commit_timestamp
+ is enabled on the subscriber. Currently, the delete is always applied
+ regardless of the origin of the local row.
+
+
+
+
+ delete_missing
+
+
+ The row to be deleted was not found. The delete will simply be
+ skipped in this scenario.
+
+
+
+
+ multiple_unique_conflicts
+
+
+ Inserting or updating a row violates multiple
+ NOT DEFERRABLE unique constraints. Note that to log
+ the origin and commit timestamp details of conflicting keys, ensure
+ that track_commit_timestamp
+ is enabled on the subscriber. In this case, an error will be raised until
+ the conflict is resolved manually.
+
+
+
+
+ Note that there are other conflict scenarios, such as exclusion constraint
+ violations. Currently, we do not provide additional details for them in the
+ log.
+
+
+
+ The log format for logical replication conflicts is as follows:
+
+LOG: conflict detected on relation "schemaname.tablename": conflict=conflict_type
+DETAIL: detailed_explanation.
+{detail_values [; ... ]}.
+
+where detail_values is one of:
+
+ Key (column_name, ...)=(column_value, ...)
+ existing local row(column_name, ...)=(column_value, ...)
+ remote row(column_name, ...)=(column_value, ...)
+ replica identity {(column_name, ...)=(column_value, ...) | full (column_name, ...)=(column_value, ...)}
+
+
+ The log provides the following information:
+
+
+ LOG
+
+
+
+
+ schemaname.tablename
+ identifies the local relation involved in the conflict.
+
+
+
+
+ conflict_type is the type of conflict that occurred
+ (e.g., insert_exists, update_exists).
+
+
+
+
+
+
+
+ DETAIL
+
+
+
+
+ detailed_explanation includes
+ the origin, transaction ID, and commit timestamp of the transaction that
+ modified the existing local row, if available.
+
+
+
+
+ The Key section includes the key values of the local
+ row that violated a unique constraint for
+ insert_exists, update_exists or
+ multiple_unique_conflicts conflicts.
+
+
+
+
+ The existing local row section includes the local
+ row if its origin differs from the remote row for
+ update_origin_differs or delete_origin_differs
+ conflicts, or if the key value conflicts with the remote row for
+ insert_exists, update_exists or
+ multiple_unique_conflicts conflicts.
+
+
+
+
+ The remote row section includes the new row from
+ the remote insert or update operation that caused the conflict. Note that
+ for an update operation, the column value of the new row will be null
+ if the value is unchanged and toasted.
+
+
+
+
+ The replica identity section includes the replica
+ identity key values that were used to search for the existing local
+ row to be updated or deleted. This may include the full row value
+ if the local relation is marked with
+ REPLICA IDENTITY FULL.
+
+
+
+
+ column_name is the column name.
+ For existing local row, remote row,
+ and replica identity full cases, column names are
+ logged only if the user lacks the privilege to access all columns of
+ the table. If column names are present, they appear in the same order
+ as the corresponding column values.
+
+
+
+
+ column_value is the column value.
+ The large column values are truncated to 64 bytes.
+
+
+
+
+ Note that in case of multiple_unique_conflicts conflict,
+ multiple detailed_explanation
+ and detail_values lines
+ will be generated, each detailing the conflict information associated
+ with distinct unique
+ constraints.
+
+
+
+
+
+
@@ -1488,7 +1998,7 @@ test_sub=# SELECT * FROM t1 ORDER BY id;
- A conflict will produce an error and will stop the replication; it must be
+ A conflict that produces an error 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.
@@ -1500,17 +2010,18 @@ test_sub=# SELECT * FROM t1 ORDER BY id;
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:
-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
+ERROR: conflict detected on relation "public.test": conflict=insert_exists
+DETAIL: Key already exists in unique index "t_pkey", which was modified locally in transaction 740 at 2024-06-26 10:47:04.727375+08.
+Key (c)=(1); existing local row (1, 'local'); remote row (1, 'remote').
+CONTEXT: processing remote data for replication origin "pg_16395" during "INSERT" for replication target relation "public.test" in transaction 725 finished at 0/014C0378
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
+ the replication origin name can be found from the server log (LSN 0/014C0378 and
replication origin pg_16395 in the above case). The
transaction that produced the conflict can be skipped by using
ALTER SUBSCRIPTION ... SKIP
with the finish LSN
- (i.e., LSN 0/14C0378). The finish LSN could be an LSN at which the transaction
+ (i.e., LSN 0/014C0378). 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
pg_replication_origin_advance() function.
@@ -1521,12 +2032,21 @@ CONTEXT: processing remote data for replication origin "pg_16395" during "INSER
disable_on_error
option. Then, you can use pg_replication_origin_advance()
function with the node_name (i.e., pg_16395)
- and the next LSN of the finish LSN (i.e., 0/14C0379). The current position of
+ and the next LSN of the finish LSN (i.e., 0/014C0379). The current position of
origins can be seen in the
pg_replication_origin_status 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.
+ The additional details regarding conflicting rows, such as their origin and
+ commit timestamp can be seen in the DETAIL line of the
+ log. But note that this information is only available when
+ track_commit_timestamp
+ is enabled on the subscriber. Users can use this information to decide
+ whether to retain the local change or adopt the remote alteration. For
+ instance, the DETAIL line in the above log indicates that
+ the existing row was modified locally. Users can manually perform a
+ remote-change-win.
@@ -1647,23 +2167,14 @@ CONTEXT: processing remote data for replication origin "pg_16395" during "INSER
Architecture
-
- 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.
-
-
Logical replication is built with an architecture similar to physical
streaming replication (see ). It is
implemented by walsender and apply
processes. The walsender process starts logical decoding (described
in ) of the WAL and loads the standard
- logical decoding output plugin (pgoutput). The plugin
- transforms the changes read
+ logical decoding output plugin ().
+ The plugin transforms the changes read
from WAL to the logical replication protocol
(see ) and filters the data
according to the publication specification. The data is then continuously
@@ -1694,18 +2205,20 @@ CONTEXT: processing remote data for replication origin "pg_16395" during "INSER
Initial Snapshot
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.
+ copied in parallel instances of a special kind of apply process.
+ These special apply processes are dedicated table synchronization
+ workers, spawned for each table to be synchronized. Each table
+ synchronization 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.
@@ -1716,6 +2229,15 @@ CONTEXT: processing remote data for replication origin "pg_16395" during "INSER
when copying the existing table data.
+
+
+ If a table synchronization worker fails during copy, the apply worker
+ detects the failure and respawns the table synchronization worker to
+ continue the synchronization process. This behaviour ensures that
+ transient errors do not permanently disrupt the replication setup. See
+ also wal_retrieve_retry_interval.
+
+
@@ -1844,10 +2366,8 @@ CONTEXT: processing remote data for replication origin "pg_16395" during "INSER
Configuration Settings
- Logical replication requires several configuration options to be set. Most
- options are relevant only on one side of the replication. However,
- max_replication_slots is used on both the publisher and
- the subscriber, but it has a different meaning for each.
+ Logical replication requires several configuration options to be set. These
+ options are relevant only on one side of the replication.
@@ -1864,6 +2384,11 @@ CONTEXT: processing remote data for replication origin "pg_16395" during "INSER
plus some reserve for table synchronization.
+
+ Logical replication slots are also affected by
+ idle_replication_slot_timeout.
+
+
max_wal_senders
should be set to at least the same as
@@ -1882,11 +2407,17 @@ CONTEXT: processing remote data for replication origin "pg_16395" during "INSER
Subscribers
- max_replication_slots
+ max_active_replication_origins
must be set to at least the number of subscriptions that will be added to
the subscriber, plus some reserve for table synchronization.
+
+ max_replication_slots
+ must be set to at least 1 when retain_dead_tuples
+ is enabled for any subscription.
+
+
max_logical_replication_workers
must be set to at least the number of subscriptions (for leader apply
@@ -1926,6 +2457,795 @@ CONTEXT: processing remote data for replication origin "pg_16395" during "INSER
+
+ Upgrade
+
+
+ Migration of logical replication clusters
+ is possible only when all the members of the old logical replication
+ clusters are version 17.0 or later.
+
+
+
+ Prepare for Publisher Upgrades
+
+
+ pg_upgrade attempts to migrate logical
+ slots. This helps avoid the need for manually defining the same
+ logical slots on the new publisher. Migration of logical slots is
+ only supported when the old cluster is version 17.0 or later.
+ Logical slots on clusters before version 17.0 will silently be
+ ignored.
+
+
+
+ Before you start upgrading the publisher cluster, ensure that the
+ subscription is temporarily disabled, by executing
+ ALTER SUBSCRIPTION ... DISABLE.
+ Re-enable the subscription after the upgrade.
+
+
+
+ There are some prerequisites for pg_upgrade to
+ be able to upgrade the logical slots. If these are not met an error
+ will be reported.
+
+
+
+
+
+ The new cluster must have
+ wal_level as
+ logical.
+
+
+
+
+ The new cluster must have
+ max_replication_slots
+ configured to a value greater than or equal to the number of slots
+ present in the old cluster.
+
+
+
+
+ The output plugins referenced by the slots on the old cluster must be
+ installed in the new PostgreSQL executable directory.
+
+
+
+
+ The old cluster has replicated all the transactions and logical decoding
+ messages to subscribers.
+
+
+
+
+ All slots on the old cluster must be usable, i.e., there are no slots
+ whose
+ pg_replication_slots.conflicting
+ is not true.
+
+
+
+
+ The new cluster must not have permanent logical slots, i.e.,
+ there must be no slots where
+ pg_replication_slots.temporary
+ is false.
+
+
+
+
+
+
+ Prepare for Subscriber Upgrades
+
+
+ Setup the
+ subscriber configurations in the new subscriber.
+ pg_upgrade attempts to migrate subscription
+ dependencies which includes the subscription's table information present in
+ pg_subscription_rel
+ system catalog and also the subscription's replication origin. This allows
+ logical replication on the new subscriber to continue from where the
+ old subscriber was up to. Migration of subscription dependencies is only
+ supported when the old cluster is version 17.0 or later. Subscription
+ dependencies on clusters before version 17.0 will silently be ignored.
+
+
+
+
+ Commit timestamps and origin data are not preserved during the upgrade.
+ As a result, even if
+ retain_dead_tuples
+ is enabled, the upgraded subscriber may be unable to detect conflicts or
+ log relevant commit timestamps and origins when applying changes from the
+ publisher occurred before the upgrade. Additionally, immediately after the
+ upgrade, the vacuum may remove the deleted rows that are required for
+ conflict detection. This can affect the changes that were not replicated
+ before the upgrade. To ensure consistent conflict tracking, users should
+ ensure that all potentially conflicting changes are replicated to the
+ subscriber before initiating the upgrade.
+
+
+
+
+ There are some prerequisites for pg_upgrade to
+ be able to upgrade the subscriptions. If these are not met an error
+ will be reported.
+
+
+
+
+
+ All the subscription tables in the old subscriber should be in state
+ i (initialize) or r (ready). This
+ can be verified by checking pg_subscription_rel.srsubstate.
+
+
+
+
+ The replication origin entry corresponding to each of the subscriptions
+ should exist in the old cluster. This can be found by checking
+ pg_subscription and
+ pg_replication_origin
+ system tables.
+
+
+
+
+ The new cluster must have
+ max_active_replication_origins
+ configured to a value greater than or equal to the number of
+ subscriptions present in the old cluster.
+
+
+
+
+ If there are subscriptions with retain_dead_tuples enabled, the reserved
+ replication slot pg_conflict_detection
+ must not exist on the new cluster. Additionally, the
+ wal_level on the
+ new cluster must be set to replica or
+ logical.
+
+
+
+
+
+
+ Upgrading Logical Replication Clusters
+
+
+ While upgrading a subscriber, write operations can be performed in the
+ publisher. These changes will be replicated to the subscriber once the
+ subscriber upgrade is completed.
+
+
+
+
+ The logical replication restrictions apply to logical replication cluster
+ upgrades also. See for
+ details.
+
+
+ The prerequisites of publisher upgrade apply to logical replication
+ cluster upgrades also. See
+ for details.
+
+
+ The prerequisites of subscriber upgrade apply to logical replication
+ cluster upgrades also. See
+ for details.
+
+
+
+
+
+ Upgrading logical replication cluster requires multiple steps to be
+ performed on various nodes. Because not all operations are
+ transactional, the user is advised to take backups as described in
+ .
+
+
+
+
+ The steps to upgrade the following logical replication clusters are
+ detailed below:
+
+
+
+ Follow the steps specified in
+ to upgrade
+ a two-node logical replication cluster.
+
+
+
+
+ Follow the steps specified in
+ to upgrade
+ a cascaded logical replication cluster.
+
+
+
+
+ Follow the steps specified in
+
+ to upgrade a two-node circular logical replication cluster.
+
+
+
+
+
+
+ Steps to Upgrade a Two-node Logical Replication Cluster
+
+ Let's say publisher is in node1 and subscriber is
+ in node2. The subscriber node2 has
+ a subscription sub1_node1_node2 which is subscribing
+ the changes from node1.
+
+
+
+
+
+ Disable all the subscriptions on node2 that are
+ subscribing the changes from node1 by using
+ ALTER SUBSCRIPTION ... DISABLE,
+ e.g.:
+
+/* node2 # */ ALTER SUBSCRIPTION sub1_node1_node2 DISABLE;
+
+
+
+
+
+ Stop the publisher server in node1, e.g.:
+
+pg_ctl -D /opt/PostgreSQL/data1 stop
+
+
+
+
+
+
+ Initialize data1_upgraded instance by using the
+ required newer version.
+
+
+
+
+
+ Upgrade the publisher node1's server to the
+ required newer version, e.g.:
+
+pg_upgrade
+ --old-datadir "/opt/PostgreSQL/postgres/17/data1"
+ --new-datadir "/opt/PostgreSQL/postgres/18/data1_upgraded"
+ --old-bindir "/opt/PostgreSQL/postgres/17/bin"
+ --new-bindir "/opt/PostgreSQL/postgres/18/bin"
+
+
+
+
+
+
+ Start the upgraded publisher server in node1, e.g.:
+
+pg_ctl -D /opt/PostgreSQL/data1_upgraded start -l logfile
+
+
+
+
+
+
+ Stop the subscriber server in node2, e.g.:
+
+pg_ctl -D /opt/PostgreSQL/data2 stop
+
+
+
+
+
+
+ Initialize data2_upgraded instance by using the
+ required newer version.
+
+
+
+
+
+ Upgrade the subscriber node2's server to
+ the required new version, e.g.:
+
+pg_upgrade
+ --old-datadir "/opt/PostgreSQL/postgres/17/data2"
+ --new-datadir "/opt/PostgreSQL/postgres/18/data2_upgraded"
+ --old-bindir "/opt/PostgreSQL/postgres/17/bin"
+ --new-bindir "/opt/PostgreSQL/postgres/18/bin"
+
+
+
+
+
+
+ Start the upgraded subscriber server in node2, e.g.:
+
+pg_ctl -D /opt/PostgreSQL/data2_upgraded start -l logfile
+
+
+
+
+
+
+ On node2, create any tables that were created in
+ the upgraded publisher node1 server between
+
+ and now, e.g.:
+
+/* node2 # */ CREATE TABLE distributors (did integer PRIMARY KEY, name varchar(40));
+
+
+
+
+
+
+ Enable all the subscriptions on node2 that are
+ subscribing the changes from node1 by using
+ ALTER SUBSCRIPTION ... ENABLE,
+ e.g.:
+
+/* node2 # */ ALTER SUBSCRIPTION sub1_node1_node2 ENABLE;
+
+
+
+
+
+
+ Refresh the node2 subscription's publications using
+ ALTER SUBSCRIPTION ... REFRESH PUBLICATION,
+ e.g.:
+
+/* node2 # */ ALTER SUBSCRIPTION sub1_node1_node2 REFRESH PUBLICATION;
+
+
+
+
+
+
+
+ In the steps described above, the publisher is upgraded first, followed
+ by the subscriber. Alternatively, the user can use similar steps to
+ upgrade the subscriber first, followed by the publisher.
+
+
+
+
+
+ Steps to Upgrade a Cascaded Logical Replication Cluster
+
+ Let's say we have a cascaded logical replication setup
+ node1->node2->node3.
+ Here node2 is subscribing the changes from
+ node1 and node3 is subscribing
+ the changes from node2. The node2
+ has a subscription sub1_node1_node2 which is
+ subscribing the changes from node1. The
+ node3 has a subscription
+ sub1_node2_node3 which is subscribing the changes from
+ node2.
+
+
+
+
+
+ Disable all the subscriptions on node2 that are
+ subscribing the changes from node1 by using
+ ALTER SUBSCRIPTION ... DISABLE,
+ e.g.:
+
+/* node2 # */ ALTER SUBSCRIPTION sub1_node1_node2 DISABLE;
+
+
+
+
+
+
+ Stop the server in node1, e.g.:
+
+pg_ctl -D /opt/PostgreSQL/data1 stop
+
+
+
+
+
+
+ Initialize data1_upgraded instance by using the
+ required newer version.
+
+
+
+
+
+ Upgrade the node1's server to the required newer
+ version, e.g.:
+
+pg_upgrade
+ --old-datadir "/opt/PostgreSQL/postgres/17/data1"
+ --new-datadir "/opt/PostgreSQL/postgres/18/data1_upgraded"
+ --old-bindir "/opt/PostgreSQL/postgres/17/bin"
+ --new-bindir "/opt/PostgreSQL/postgres/18/bin"
+
+
+
+
+
+
+ Start the upgraded server in node1, e.g.:
+
+pg_ctl -D /opt/PostgreSQL/data1_upgraded start -l logfile
+
+
+
+
+
+
+ Disable all the subscriptions on node3 that are
+ subscribing the changes from node2 by using
+ ALTER SUBSCRIPTION ... DISABLE,
+ e.g.:
+
+/* node3 # */ ALTER SUBSCRIPTION sub1_node2_node3 DISABLE;
+
+
+
+
+
+
+ Stop the server in node2, e.g.:
+
+pg_ctl -D /opt/PostgreSQL/data2 stop
+
+
+
+
+
+
+ Initialize data2_upgraded instance by using the
+ required newer version.
+
+
+
+
+
+ Upgrade the node2's server to the required
+ new version, e.g.:
+
+pg_upgrade
+ --old-datadir "/opt/PostgreSQL/postgres/17/data2"
+ --new-datadir "/opt/PostgreSQL/postgres/18/data2_upgraded"
+ --old-bindir "/opt/PostgreSQL/postgres/17/bin"
+ --new-bindir "/opt/PostgreSQL/postgres/18/bin"
+
+
+
+
+
+
+ Start the upgraded server in node2, e.g.:
+
+pg_ctl -D /opt/PostgreSQL/data2_upgraded start -l logfile
+
+
+
+
+
+
+ On node2, create any tables that were created in
+ the upgraded publisher node1 server between
+
+ and now, e.g.:
+
+/* node2 # */ CREATE TABLE distributors (did integer PRIMARY KEY, name varchar(40));
+
+
+
+
+
+
+ Enable all the subscriptions on node2 that are
+ subscribing the changes from node1 by using
+ ALTER SUBSCRIPTION ... ENABLE,
+ e.g.:
+
+/* node2 # */ ALTER SUBSCRIPTION sub1_node1_node2 ENABLE;
+
+
+
+
+
+
+ Refresh the node2 subscription's publications using
+ ALTER SUBSCRIPTION ... REFRESH PUBLICATION,
+ e.g.:
+
+/* node2 # */ ALTER SUBSCRIPTION sub1_node1_node2 REFRESH PUBLICATION;
+
+
+
+
+
+
+ Stop the server in node3, e.g.:
+
+pg_ctl -D /opt/PostgreSQL/data3 stop
+
+
+
+
+
+
+ Initialize data3_upgraded instance by using the
+ required newer version.
+
+
+
+
+
+ Upgrade the node3's server to the required
+ new version, e.g.:
+
+pg_upgrade
+ --old-datadir "/opt/PostgreSQL/postgres/17/data3"
+ --new-datadir "/opt/PostgreSQL/postgres/18/data3_upgraded"
+ --old-bindir "/opt/PostgreSQL/postgres/17/bin"
+ --new-bindir "/opt/PostgreSQL/postgres/18/bin"
+
+
+
+
+
+
+ Start the upgraded server in node3, e.g.:
+
+pg_ctl -D /opt/PostgreSQL/data3_upgraded start -l logfile
+
+
+
+
+
+
+ On node3, create any tables that were created in
+ the upgraded node2 between
+ and now,
+ e.g.:
+
+/* node3 # */ CREATE TABLE distributors (did integer PRIMARY KEY, name varchar(40));
+
+
+
+
+
+
+ Enable all the subscriptions on node3 that are
+ subscribing the changes from node2 by using
+ ALTER SUBSCRIPTION ... ENABLE,
+ e.g.:
+
+/* node3 # */ ALTER SUBSCRIPTION sub1_node2_node3 ENABLE;
+
+
+
+
+
+
+ Refresh the node3 subscription's publications using
+ ALTER SUBSCRIPTION ... REFRESH PUBLICATION,
+ e.g.:
+
+/* node3 # */ ALTER SUBSCRIPTION sub1_node2_node3 REFRESH PUBLICATION;
+
+
+
+
+
+
+
+ Steps to Upgrade a Two-node Circular Logical Replication Cluster
+
+ Let's say we have a circular logical replication setup
+ node1->node2 and
+ node2->node1. Here
+ node2 is subscribing the changes from
+ node1 and node1 is subscribing
+ the changes from node2. The node1
+ has a subscription sub1_node2_node1 which is
+ subscribing the changes from node2. The
+ node2 has a subscription
+ sub1_node1_node2 which is subscribing the changes from
+ node1.
+
+
+
+
+
+ Disable all the subscriptions on node2 that are
+ subscribing the changes from node1 by using
+ ALTER SUBSCRIPTION ... DISABLE,
+ e.g.:
+
+/* node2 # */ ALTER SUBSCRIPTION sub1_node1_node2 DISABLE;
+
+
+
+
+
+
+ Stop the server in node1, e.g.:
+
+pg_ctl -D /opt/PostgreSQL/data1 stop
+
+
+
+
+
+
+ Initialize data1_upgraded instance by using the
+ required newer version.
+
+
+
+
+
+ Upgrade the node1's server to the required
+ newer version, e.g.:
+
+pg_upgrade
+ --old-datadir "/opt/PostgreSQL/postgres/17/data1"
+ --new-datadir "/opt/PostgreSQL/postgres/18/data1_upgraded"
+ --old-bindir "/opt/PostgreSQL/postgres/17/bin"
+ --new-bindir "/opt/PostgreSQL/postgres/18/bin"
+
+
+
+
+
+
+ Start the upgraded server in node1, e.g.:
+
+pg_ctl -D /opt/PostgreSQL/data1_upgraded start -l logfile
+
+
+
+
+
+
+ Enable all the subscriptions on node2 that are
+ subscribing the changes from node1 by using
+ ALTER SUBSCRIPTION ... ENABLE,
+ e.g.:
+
+/* node2 # */ ALTER SUBSCRIPTION sub1_node1_node2 ENABLE;
+
+
+
+
+
+
+ On node1, create any tables that were created in
+ node2 between
+ and now, e.g.:
+
+/* node1 # */ CREATE TABLE distributors (did integer PRIMARY KEY, name varchar(40));
+
+
+
+
+
+
+
+ Refresh the node1 subscription's publications to
+ copy initial table data from node2 using
+ ALTER SUBSCRIPTION ... REFRESH PUBLICATION,
+ e.g.:
+
+/* node1 # */ ALTER SUBSCRIPTION sub1_node2_node1 REFRESH PUBLICATION;
+
+
+
+
+
+
+ Disable all the subscriptions on node1 that are
+ subscribing the changes from node2 by using
+ ALTER SUBSCRIPTION ... DISABLE,
+ e.g.:
+
+/* node1 # */ ALTER SUBSCRIPTION sub1_node2_node1 DISABLE;
+
+
+
+
+
+
+ Stop the server in node2, e.g.:
+
+pg_ctl -D /opt/PostgreSQL/data2 stop
+
+
+
+
+
+
+ Initialize data2_upgraded instance by using the
+ required newer version.
+
+
+
+
+
+ Upgrade the node2's server to the required
+ new version, e.g.:
+
+pg_upgrade
+ --old-datadir "/opt/PostgreSQL/postgres/17/data2"
+ --new-datadir "/opt/PostgreSQL/postgres/18/data2_upgraded"
+ --old-bindir "/opt/PostgreSQL/postgres/17/bin"
+ --new-bindir "/opt/PostgreSQL/postgres/18/bin"
+
+
+
+
+
+
+ Start the upgraded server in node2, e.g.:
+
+pg_ctl -D /opt/PostgreSQL/data2_upgraded start -l logfile
+
+
+
+
+
+
+ Enable all the subscriptions on node1 that are
+ subscribing the changes from node2 by using
+ ALTER SUBSCRIPTION ... ENABLE,
+ e.g.:
+
+/* node1 # */ ALTER SUBSCRIPTION sub1_node2_node1 ENABLE;
+
+
+
+
+
+
+ On node2, create any tables that were created in
+ the upgraded node1 between
+ and now, e.g.:
+
+/* node2 # */ CREATE TABLE distributors (did integer PRIMARY KEY, name varchar(40));
+
+
+
+
+
+
+ Refresh the node2 subscription's publications to
+ copy initial table data from node1 using
+ ALTER SUBSCRIPTION ... REFRESH PUBLICATION,
+ e.g.:
+
+/* node2 # */ ALTER SUBSCRIPTION sub1_node1_node2 REFRESH PUBLICATION;
+
+
+
+
+
+
+
+
+
Quick Setup
diff --git a/doc/src/sgml/logicaldecoding.sgml b/doc/src/sgml/logicaldecoding.sgml
index 5a15bbc580c28..b803a819cf1f2 100644
--- a/doc/src/sgml/logicaldecoding.sgml
+++ b/doc/src/sgml/logicaldecoding.sgml
@@ -57,14 +57,14 @@
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
+-----------------+------------
+ regression_slot | 0/016B1970
(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
+-----------------+---------------+-----------+----------+--------+-------------+---------------------
+ regression_slot | test_decoding | logical | postgres | f | 0/016A4408 | 0/016A4440
(1 row)
postgres=# -- There are no changes to see yet
@@ -78,10 +78,10 @@ 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
+ lsn | xid | data
+------------+-------+--------------
+ 0/0BA2DA58 | 10297 | BEGIN 10297
+ 0/0BA5A5A0 | 10297 | COMMIT 10297
(2 rows)
postgres=# -- Once changes are read, they're consumed and not emitted
@@ -97,41 +97,41 @@ 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
+ lsn | xid | data
+------------+-------+---------------------------------------------------------
+ 0/0BA5A688 | 10298 | BEGIN 10298
+ 0/0BA5A6F0 | 10298 | table public.data: INSERT: id[integer]:1 data[text]:'1'
+ 0/0BA5A7F8 | 10298 | table public.data: INSERT: id[integer]:2 data[text]:'2'
+ 0/0BA5A8A8 | 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
+ lsn | xid | data
+------------+-------+---------------------------------------------------------
+ 0/0BA5A8E0 | 10299 | BEGIN 10299
+ 0/0BA5A8E0 | 10299 | table public.data: INSERT: id[integer]:3 data[text]:'3'
+ 0/0BA5A990 | 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
+ lsn | xid | data
+------------+-------+---------------------------------------------------------
+ 0/0BA5A8E0 | 10299 | BEGIN 10299
+ 0/0BA5A8E0 | 10299 | table public.data: INSERT: id[integer]:3 data[text]:'3'
+ 0/0BA5A990 | 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)
+ lsn | xid | data
+------------+-------+---------------------------------------------------------
+ 0/0BA5A8E0 | 10299 | BEGIN 10299
+ 0/0BA5A8E0 | 10299 | table public.data: INSERT: id[integer]:3 data[text]:'3'
+ 0/0BA5A990 | 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
@@ -169,7 +169,7 @@ COMMIT 693
$ 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 --create-slot --enable-two-phase
$ pg_recvlogical -d postgres --slot=test --start -f -
ControlZ
$ psql -d postgres -c "BEGIN;INSERT INTO data(data) VALUES('5');PREPARE TRANSACTION 'test';"
@@ -200,18 +200,18 @@ 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
+ lsn | xid | data
+------------+-----+---------------------------------------------------------
+ 0/01689DC0 | 529 | BEGIN 529
+ 0/01689DC0 | 529 | table public.data: INSERT: id[integer]:3 data[text]:'5'
+ 0/01689FC0 | 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
+ lsn | xid | data
+------------+-----+--------------------------------------------
+ 0/0168A060 | 529 | COMMIT PREPARED 'test_prepared1', txid 529
(4 row)
postgres=#-- you can also rollback a prepared transaction
@@ -219,18 +219,18 @@ 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
+ lsn | xid | data
+------------+-----+---------------------------------------------------------
+ 0/0168A180 | 530 | BEGIN 530
+ 0/0168A1E8 | 530 | table public.data: INSERT: id[integer]:4 data[text]:'6'
+ 0/0168A430 | 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
+ lsn | xid | data
+------------+-----+----------------------------------------------
+ 0/0168A4B8 | 530 | ROLLBACK PREPARED 'test_prepared2', txid 530
(1 row)
@@ -290,7 +290,7 @@ postgres=# select * from pg_logical_slot_get_changes('regression_slot', NULL, NU
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
+ the case of a crash the slot might 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
@@ -370,10 +370,10 @@ postgres=# select * from pg_logical_slot_get_changes('regression_slot', NULL, NU
pg_create_logical_replication_slot, or by
using the
failover option of
- CREATE SUBSCRIPTION during slot creation, and then calling
-
- pg_sync_replication_slots
- on the standby. By setting
+ CREATE SUBSCRIPTION during slot creation.
+ Additionally, enabling
+ sync_replication_slots on the standby
+ is required. By enabling
sync_replication_slots
on the standby, the failover slots can be synchronized periodically in
the slotsync worker. For the synchronization to work, it is mandatory to
@@ -385,19 +385,65 @@ postgres=# select * from pg_logical_slot_get_changes('regression_slot', NULL, NU
dbname in the
primary_conninfo.
It's highly recommended that the said physical replication slot is named in
- standby_slot_names
+ synchronized_standby_slots
list on the primary, to prevent the subscriber from consuming changes
faster than the hot standby. Even when correctly configured, some latency
is expected when sending changes to logical subscribers due to the waiting
on slots named in
- standby_slot_names.
- When standby_slot_names is utilized, the
+ synchronized_standby_slots.
+ When synchronized_standby_slots is utilized, the
primary server will not completely shut down until the corresponding
standbys, associated with the physical replication slots specified
- in standby_slot_names, have confirmed
+ in synchronized_standby_slots, have confirmed
receiving the WAL up to the latest flushed position on the primary server.
+
+
+ While enabling
+ sync_replication_slots allows for automatic
+ periodic synchronization of failover slots, they can also be manually
+ synchronized using the
+ pg_sync_replication_slots function on the standby.
+ However, this function is primarily intended for testing and debugging and
+ should be used with caution. Unlike automatic synchronization, it does not
+ include cyclic retries, making it more prone to synchronization failures,
+ particularly during initial sync scenarios where the required WAL files
+ or catalog rows for the slot might have already been removed or are at risk
+ of being removed on the standby. In contrast, automatic synchronization
+ via sync_replication_slots provides continuous slot
+ updates, enabling seamless failover and supporting high availability.
+ Therefore, it is the recommended method for synchronizing slots.
+
+
+
+
+ When slot synchronization is configured as recommended,
+ and the initial synchronization is performed either automatically or
+ manually via pg_sync_replication_slots, the standby
+ can persist the synchronized slot only if the following condition is met:
+ The logical replication slot on the primary must retain WALs and system
+ catalog rows that are still available on the standby. This ensures data
+ integrity and allows logical replication to continue smoothly after
+ promotion.
+ If the required WALs or catalog rows have already been purged from the
+ standby, the slot will not be persisted to avoid data loss. In such
+ cases, the following log message may appear:
+
+LOG: could not synchronize replication slot "failover_slot"
+DETAIL: Synchronization could lead to data loss, because the remote slot needs WAL at LSN 0/03003F28 and catalog xmin 754, but the standby has LSN 0/03003F28 and catalog xmin 756.
+
+ If the logical replication slot is actively used by a consumer, no
+ manual intervention is needed; the slot will advance automatically,
+ and synchronization will resume in the next cycle. However, if no
+ consumer is configured, it is advisable to manually advance the slot
+ on the primary using
+ pg_logical_slot_get_changes or
+
+ pg_logical_slot_get_binary_changes,
+ allowing synchronization to proceed.
+
+
The ability to resume logical replication after failover depends upon the
pg_replication_slots.synced
@@ -455,9 +501,8 @@ postgres=# select * from pg_logical_slot_get_changes('regression_slot', NULL, NU
using the slot's contents without losing any changes.
- 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 NOEXPORT_SNAPSHOT
+ Applications that do not require
+ snapshot export may suppress it with the SNAPSHOT 'nothing'
option.
@@ -529,6 +574,170 @@ postgres=# select * from pg_logical_slot_get_changes('regression_slot', NULL, NU
Logical Decoding Output Plugins
+
+
+ PostgreSQL provides two logical decoding
+ output plugins, and
+ . You can also develop custom output plugins
+ (see for details).
+
+
+
+ pgoutput — Standard Logical Decoding Output Plugin
+
+
+ pgoutput
+
+
+
+ pgoutput is the standard logical decoding output
+ plugin provided by PostgreSQL.
+ It's used for the built-in
+ logical replication.
+
+
+
+ Options
+
+
+
+ proto_version (integer)
+
+
+ Specifies the protocol version.
+ Currently versions 1, 2,
+ 3, and 4 are supported. A valid
+ version is required.
+
+
+ Version 2 is supported on server version 14
+ and above, and is required when streaming
+ is set to on to stream large in-progress
+ transactions.
+
+
+ Version 3 is supported on server version 15
+ and above, and is required when two_phase
+ is enabled to stream two-phase commits.
+
+
+ Version 4 is supported on server version 16
+ and above, and is required when streaming
+ is set to parallel to stream large in-progress
+ transactions to be applied in parallel.
+
+
+
+
+
+ publication_names (string)
+
+
+ A comma-separated list of publication names to subscribe to.
+ The individual publication names are treated
+ as standard objects names and can be quoted the same as needed.
+ At least one publication name is required.
+
+
+
+
+
+ binary (boolean)
+
+
+ Enables binary transfer mode. Binary mode is faster
+ than the text mode but slightly less robust.
+ The default is off.
+
+
+
+
+
+ messages (boolean)
+
+
+ Enables sending the messages that are written by
+ pg_logical_emit_message.
+ The default is off.
+
+
+
+
+
+ streaming (enum)
+
+
+ Enables streaming of in-progress transactions. Valid values are
+ off (the default), on and
+ parallel.
+
+
+ When set to off, pgoutput
+ fully decodes a transaction before sending it as a whole.
+ This mode works with any protocol version.
+
+
+ When set to on, pgoutput
+ streams large in-progress transactions.
+ This requires protocol version 2 or higher.
+
+
+ When set to parallel, pgoutput
+ streams large in-progress transactions and also sends
+ extra information in some messages to support parallel processing.
+ This requires protocol version 4 or higher.
+
+
+
+
+
+ two_phase (boolean)
+
+
+ Enables sending two-phase transactions.
+ Minimum protocol version 3 is required to turn it on.
+ The default is off.
+
+
+
+
+
+ origin (enum)
+
+
+ Specifies whether to send changes by their origin. Possible values are
+ none to only send the changes that have no origin
+ associated, or any
+ to send the changes regardless of their origin. This can be used
+ to avoid loops (infinite replication of the same data) among
+ replication nodes.
+ The default is any.
+
+
+
+
+
+
+
+
+ Notes
+
+
+ pgoutput produces binary output,
+ so functions expecting textual data (
+ pg_logical_slot_peek_changes and
+ pg_logical_slot_get_changes)
+ cannot be used with it. Use
+ pg_logical_slot_peek_binary_changes or
+ pg_logical_slot_get_binary_changes
+ instead.
+
+
+
+
+
+
+ Writing Logical Decoding Output Plugins
An example output plugin can be found in the
@@ -898,7 +1107,6 @@ typedef void (*LogicalDecodeMessageCB) (struct LogicalDecodingContext *ctx,
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 prefix is arbitrary null-terminated prefix
which can be used for identifying interesting messages for the current
plugin. And finally the message parameter holds
@@ -1368,7 +1576,7 @@ commit_prepared_cb(...); <-- commit of the prepared transaction
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
+ complete tuple e.g., only decoded TOAST table insert but not the main table
insert.
diff --git a/doc/src/sgml/ltree.sgml b/doc/src/sgml/ltree.sgml
index 9584105b03b39..1c3543303f0ab 100644
--- a/doc/src/sgml/ltree.sgml
+++ b/doc/src/sgml/ltree.sgml
@@ -841,15 +841,6 @@ ltreetest=> SELECT ins_label(path,2,'Space') FROM test WHERE path <@ 'Top.
creating a function, ltree values are mapped to Python lists.
(The reverse is currently not supported, however.)
-
-
-
- It is strongly recommended that the transform extension be installed in
- the same schema as ltree. Otherwise there are
- installation-time security hazards if a transform extension's schema
- contains objects defined by a hostile user.
-
-
diff --git a/doc/src/sgml/maintenance.sgml b/doc/src/sgml/maintenance.sgml
index 0be90bdc7efe1..e7a9f58c01582 100644
--- a/doc/src/sgml/maintenance.sgml
+++ b/doc/src/sgml/maintenance.sgml
@@ -496,9 +496,25 @@
When that happens, VACUUM will eventually need to perform an
aggressive vacuum, 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.
+
+
+
+ If a table is building up a backlog of all-visible but not all-frozen
+ pages, a normal vacuum may choose to scan skippable pages in an effort to
+ freeze them. Doing so decreases the number of pages the next aggressive
+ vacuum must scan. These are referred to as eagerly
+ scanned pages. Eager scanning can be tuned to attempt to freeze
+ more all-visible pages by increasing . Even if eager
+ scanning has kept the number of all-visible but not all-frozen pages to a
+ minimum, most tables still require periodic aggressive vacuuming. However,
+ any pages successfully eager frozen may be skipped during an aggressive
+ vacuum, so eager freezing may minimize the overhead of aggressive vacuums.
+
+
+
- controls when VACUUM does that: all-visible but not all-frozen
+ controls when a table is aggressively vacuumed. All 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 vacuum_freeze_table_age minus
vacuum_freeze_min_age. Setting
@@ -626,10 +642,12 @@ SELECT datname, age(datfrozenxid) FROM pg_database;
- VACUUM normally only scans pages that have been modified
- since the last vacuum, but relfrozenxid can only be
- advanced when every page of the table
- that might contain unfrozen XIDs is scanned. This happens when
+ While VACUUM scans mostly pages that have been
+ modified since the last vacuum, it may also eagerly scan some
+ all-visible but not all-frozen pages in an attempt to freeze them, but
+ the relfrozenxid will only be advanced when
+ every page of the table that might contain unfrozen XIDs is scanned.
+ This happens when
relfrozenxid is more than
vacuum_freeze_table_age transactions old, when
VACUUM's FREEZE option is used, or when all
@@ -761,7 +779,10 @@ HINT: Execute a database-wide VACUUM in that database.
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.
+ be managed. The system function
+ pg_get_multixact_members() described in
+ can be used to examine the
+ transaction IDs associated with a multixact ID.
@@ -793,10 +814,11 @@ HINT: Execute a database-wide VACUUM in that database.
As a safety device, an aggressive vacuum scan will
occur for any table whose multixact-age is greater than . Also, if the
- storage occupied by multixacts members exceeds 2GB, aggressive vacuum
+ storage occupied by multixacts members exceeds about 10GB, 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.
+ scans will occur even if autovacuum is nominally disabled. The members storage
+ area can grow up to about 20GB before reaching wraparound.
@@ -895,9 +917,11 @@ HINT: Execute a database-wide VACUUM in that database.
VACUUM exceeds the vacuum threshold, the
table is vacuumed. The vacuum threshold is defined as:
-vacuum threshold = vacuum base threshold + vacuum scale factor * number of tuples
+vacuum threshold = Minimum(vacuum max threshold, vacuum base threshold + vacuum scale factor * number of tuples)
- where the vacuum base threshold is
+ where the vacuum max threshold is
+ ,
+ the vacuum base threshold is
,
the vacuum scale factor is
,
@@ -929,8 +953,7 @@ vacuum insert threshold = vacuum base insert threshold + vacuum insert scale fac
If the relfrozenxid value of the table
is more than vacuum_freeze_table_age transactions old,
an aggressive vacuum is performed to freeze old tuples and advance
- relfrozenxid; otherwise, only pages that have been modified
- since the last vacuum are scanned.
+ relfrozenxid.
diff --git a/doc/src/sgml/manage-ag.sgml b/doc/src/sgml/manage-ag.sgml
index a8a70a1fc4242..fe4cb4410cd51 100644
--- a/doc/src/sgml/manage-ag.sgml
+++ b/doc/src/sgml/manage-ag.sgml
@@ -530,9 +530,11 @@ CREATE TABLE foo(i int);
pg_tablespace
system catalog, for example
-SELECT spcname FROM pg_tablespace;
+SELECT spcname, spcowner::regrole, pg_tablespace_location(oid) FROM pg_tablespace;
- The program's \db meta-command
+ It is possible to find which databases use which tablespaces;
+ see . The program's \db meta-command
is also useful for listing the existing tablespaces.
@@ -541,10 +543,7 @@ SELECT spcname FROM pg_tablespace;
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 pg_tablespace
- catalog with the new locations. (If you do not, pg_dump will
- continue to output the old tablespace locations.)
+ this operation while the server is running.
diff --git a/doc/src/sgml/meson.build b/doc/src/sgml/meson.build
index e418de83a76e1..6ae192eac68a4 100644
--- a/doc/src/sgml/meson.build
+++ b/doc/src/sgml/meson.build
@@ -1,4 +1,4 @@
-# Copyright (c) 2022-2024, PostgreSQL Global Development Group
+# Copyright (c) 2022-2025, PostgreSQL Global Development Group
docs = []
installdocs = []
diff --git a/doc/src/sgml/monitoring.sgml b/doc/src/sgml/monitoring.sgml
index 053da8d6e40a0..3f4a27a736e27 100644
--- a/doc/src/sgml/monitoring.sgml
+++ b/doc/src/sgml/monitoring.sgml
@@ -168,6 +168,11 @@ postgres 27093 0.0 0.0 30096 2752 ? Ss 11:34 0:00 postgres: ser
of the current command being executed by any server process.
+
+ The parameter enables
+ monitoring of cost-based vacuum delay.
+
+
The parameter controls whether
cumulative statistics are collected about table and index accesses.
@@ -180,12 +185,12 @@ postgres 27093 0.0 0.0 30096 2752 ? Ss 11:34 0:00 postgres: ser
The parameter enables monitoring
- of block read and write times.
+ of block read, write, extend, and fsync times.
The parameter enables monitoring
- of WAL write times.
+ of WAL read, write and fsync times.
@@ -286,8 +291,8 @@ postgres 27093 0.0 0.0 30096 2752 ? Ss 11:34 0:00 postgres: ser
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 pg_read_all_stats (see also ) can see all the information about all sessions.
+ built-in role pg_read_all_stats
+ can see all the information about all sessions.
@@ -507,7 +512,7 @@ postgres 27093 0.0 0.0 30096 2752 ? Ss 11:34 0:00 postgres: ser
pg_stat_subscription_statspg_stat_subscription_stats
- One row per subscription, showing statistics about errors.
+ One row per subscription, showing statistics about errors and conflicts.
See
pg_stat_subscription_stats for details.
@@ -899,6 +904,12 @@ postgres 27093 0.0 0.0 30096 2752 ? Ss 11:34 0:00 postgres: ser
Current overall state of this backend.
Possible values are:
+
+
+ starting: The backend is in initial startup. Client
+ authentication is performed during this phase.
+
+ active: The backend is executing a query.
@@ -1016,7 +1027,9 @@ postgres 27093 0.0 0.0 30096 2752 ? Ss 11:34 0:00 postgres: ser
it may or may not be waiting on some event. If the state
is active and wait_event is non-null, it
means that a query is being executed, but is being blocked somewhere
- in the system.
+ in the system. To keep the reporting overhead low, the system does not
+ attempt to synchronize different aspects of activity data for a backend.
+ As a result, ephemeral discrepancies may exist between the view's columns.
@@ -1063,6 +1076,14 @@ postgres 27093 0.0 0.0 30096 2752 ? Ss 11:34 0:00 postgres: ser
See .
+
+ InjectionPoint
+ The server process is waiting for an injection point to reach an
+ outcome defined in a test. See
+ for more details. This
+ type has no predefined wait points.
+
+ IOThe server process is waiting for an I/O operation to complete.
@@ -1139,8 +1160,8 @@ description | Waiting for a newly initialized WAL file to reach durable storage
- Extensions can add Extension and
- LWLock events
+ Extensions can add Extension,
+ InjectionPoint, and LWLock events
to the lists shown in and
. In some cases, the name
of an LWLock assigned by an extension will not be
@@ -2149,7 +2170,10 @@ description | Waiting for a newly initialized WAL file to reach durable storage
apply_error_countbigint
- Number of times an error occurred while applying changes
+ Number of times an error occurred while applying changes. Note that any
+ conflict resulting in an apply error will be counted in both
+ apply_error_count and the corresponding conflict
+ count (e.g., confl_*).
@@ -2163,6 +2187,99 @@ description | Waiting for a newly initialized WAL file to reach durable storage
+
+
+ confl_insert_existsbigint
+
+
+ Number of times a row insertion violated a
+ NOT DEFERRABLE unique constraint during the
+ application of changes. See
+ for details about this conflict.
+
+
+
+
+
+ confl_update_origin_differsbigint
+
+
+ Number of times an update was applied to a row that had been previously
+ modified by another source during the application of changes. See
+ for details about this
+ conflict.
+
+
+
+
+
+ confl_update_existsbigint
+
+
+ Number of times that an updated row value violated a
+ NOT DEFERRABLE unique constraint during the
+ application of changes. See
+ for details about this conflict.
+
+
+
+
+
+ confl_update_deletedbigint
+
+
+ Number of times the tuple to be updated was concurrently deleted by
+ another source during the application of changes. See
+ for details about this conflict.
+
+
+
+
+
+ confl_update_missingbigint
+
+
+ Number of times the tuple to be updated was not found during the
+ application of changes. See
+ for details about this conflict.
+
+
+
+
+
+ confl_delete_origin_differsbigint
+
+
+ Number of times a delete operation was applied to row that had been
+ previously modified by another source during the application of changes.
+ See for details about
+ this conflict.
+
+
+
+
+
+ confl_delete_missingbigint
+
+
+ Number of times the tuple to be deleted was not found during the application
+ of changes. See for details
+ about this conflict.
+
+
+
+
+
+ confl_multiple_unique_conflictsbigint
+
+
+ Number of times a row insertion or an updated row values violated multiple
+ NOT DEFERRABLE unique constraints during the
+ application of changes. See
+ for details about this conflict.
+
+
+
stats_resettimestamp with time zone
@@ -2500,9 +2617,10 @@ description | Waiting for a newly initialized WAL file to reach durable storage
- Currently, I/O on relations (e.g. tables, indexes) is tracked. However,
- relation I/O which bypasses shared buffers (e.g. when moving a table from one
- tablespace to another) is currently not tracked.
+ Currently, I/O on relations (e.g. tables, indexes) and WAL activity are
+ tracked. However, relation I/O which bypasses shared buffers
+ (e.g. when moving a table from one tablespace to another) is currently
+ not tracked.
@@ -2555,6 +2673,11 @@ description | Waiting for a newly initialized WAL file to reach durable storage
temp relation: Temporary relations.
+
+
+ wal: Write Ahead Logs.
+
+
@@ -2579,6 +2702,13 @@ description | Waiting for a newly initialized WAL file to reach durable storage
normal.
+
+
+ init: I/O operations performed while creating the
+ WAL segments are tracked in context
+ init.
+
+ vacuum: I/O operations performed outside of shared
@@ -2611,8 +2741,18 @@ description | Waiting for a newly initialized WAL file to reach durable storage
readsbigint
- Number of read operations, each of the size specified in
- op_bytes.
+ Number of read operations.
+
+
+
+
+
+
+
+ read_bytesnumeric
+
+
+ The total size of read operations in bytes.
@@ -2623,8 +2763,12 @@ description | Waiting for a newly initialized WAL file to reach durable storage
read_timedouble precision
- Time spent in read operations in milliseconds (if
- is enabled, otherwise zero)
+ Time spent waiting for read operations in milliseconds (if
+ is enabled and
+ object is not wal,
+ or if is enabled
+ and object is wal,
+ otherwise zero)
@@ -2635,8 +2779,18 @@ description | Waiting for a newly initialized WAL file to reach durable storage
writesbigint
- Number of write operations, each of the size specified in
- op_bytes.
+ Number of write operations.
+
+
+
+
+
+
+
+ write_bytesnumeric
+
+
+ The total size of write operations in bytes.
@@ -2647,8 +2801,12 @@ description | Waiting for a newly initialized WAL file to reach durable storage
write_timedouble precision
- Time spent in write operations in milliseconds (if
- is enabled, otherwise zero)
+ Time spent waiting for write operations in milliseconds (if
+ is enabled and
+ object is not wal,
+ or if is enabled
+ and object is wal,
+ otherwise zero)
@@ -2659,8 +2817,8 @@ description | Waiting for a newly initialized WAL file to reach durable storage
writebacksbigint
- Number of units of size op_bytes which the process
- requested the kernel write out to permanent storage.
+ Number of units of size BLCKSZ (typically 8kB) which
+ the process requested the kernel write out to permanent storage.
@@ -2671,7 +2829,7 @@ description | Waiting for a newly initialized WAL file to reach durable storage
writeback_timedouble precision
- Time spent in writeback operations in milliseconds (if
+ Time spent waiting for writeback operations in milliseconds (if
is enabled, otherwise zero). This
includes the time spent queueing write-out requests and, potentially,
the time spent to write out the dirty data.
@@ -2685,8 +2843,7 @@ description | Waiting for a newly initialized WAL file to reach durable storage
extendsbigint
- Number of relation extend operations, each of the size specified in
- op_bytes.
+ Number of relation extend operations.
@@ -2694,11 +2851,10 @@ description | Waiting for a newly initialized WAL file to reach durable storage
- extend_timedouble precision
+ extend_bytesnumeric
- Time spent in extend operations in milliseconds (if
- is enabled, otherwise zero)
+ The total size of relation extend operations in bytes.
@@ -2706,16 +2862,15 @@ description | Waiting for a newly initialized WAL file to reach durable storage
- op_bytesbigint
-
-
- The number of bytes per unit of I/O read, written, or extended.
+ extend_timedouble precision
- Relation data reads, writes, and extends are done in
- block_size units, derived from the build-time
- parameter BLCKSZ, which is 8192 by
- default.
+ Time spent waiting for extend operations in milliseconds. (if
+ is enabled and
+ object is not wal,
+ or if is enabled
+ and object is wal,
+ otherwise zero)
@@ -2784,8 +2939,12 @@ description | Waiting for a newly initialized WAL file to reach durable storage
fsync_timedouble precision
- Time spent in fsync operations in milliseconds (if
- is enabled, otherwise zero)
+ Time spent waiting for fsync operations in milliseconds (if
+ is enabled and
+ object is not wal,
+ or if is enabled
+ and object is wal,
+ otherwise zero)
@@ -2823,6 +2982,16 @@ description | Waiting for a newly initialized WAL file to reach durable storage
writer.
+
+ For the objectwal,
+ fsyncs and fsync_time track the
+ fsync activity of WAL files done in issue_xlog_fsync.
+ writes and write_time
+ track the write activity of WAL files done in
+ XLogWrite.
+ See for more information.
+
+
pg_stat_io can be used to inform database tuning.
For example:
@@ -2857,7 +3026,7 @@ description | Waiting for a newly initialized WAL file to reach durable storage
- Columns tracking I/O time will only be non-zero when
+ Columns tracking I/O wait time will only be non-zero when
is enabled. The user should be
careful when referencing these columns in combination with their
corresponding I/O operations in case track_io_timing
@@ -2970,7 +3139,7 @@ description | Waiting for a newly initialized WAL file to reach durable storage
num_timedbigint
- Number of scheduled checkpoints that have been performed
+ Number of scheduled checkpoints due to timeout
@@ -2979,7 +3148,16 @@ description | Waiting for a newly initialized WAL file to reach durable storage
num_requestedbigint
- Number of requested checkpoints that have been performed
+ Number of requested checkpoints
+
+
+
+
+
+ num_donebigint
+
+
+ Number of checkpoints that have been performed
@@ -3037,7 +3215,16 @@ description | Waiting for a newly initialized WAL file to reach durable storage
buffers_writtenbigint
- Number of buffers written during checkpoints and restartpoints
+ Number of shared buffers written during checkpoints and restartpoints
+
+
+
+
+
+ slru_writtenbigint
+
+
+ Number of SLRU buffers written during checkpoints and restartpoints
@@ -3053,6 +3240,18 @@ description | Waiting for a newly initialized WAL file to reach durable storage
+
+ Checkpoints may be skipped if the server has been idle since the last one.
+ num_timed and
+ num_requested count both completed and skipped
+ checkpoints, while num_done tracks only
+ the completed ones. Similarly, restartpoints may be skipped
+ if the last replayed checkpoint record is already the last restartpoint.
+ restartpoints_timed and
+ restartpoints_req count both completed and
+ skipped restartpoints, while restartpoints_done
+ tracks only the completed ones.
+
@@ -3118,63 +3317,6 @@ description | Waiting for a newly initialized WAL file to reach durable storage
-
-
- wal_writebigint
-
-
- Number of times WAL buffers were written out to disk via
- XLogWrite request.
- See for more information about
- the internal WAL function XLogWrite.
-
-
-
-
-
- wal_syncbigint
-
-
- Number of times WAL files were synced to disk via
- issue_xlog_fsync request
- (if is on and
- is either
- fdatasync, fsync or
- fsync_writethrough, otherwise zero).
- See for more information about
- the internal WAL function issue_xlog_fsync.
-
-
-
-
-
- wal_write_timedouble precision
-
-
- Total amount of time spent writing WAL buffers to disk via
- XLogWrite request, in milliseconds
- (if is enabled,
- otherwise zero). This includes the sync time when
- wal_sync_method is either
- open_datasync or open_sync.
-
-
-
-
-
- wal_sync_timedouble precision
-
-
- Total amount of time spent syncing WAL files to disk via
- issue_xlog_fsync request, in milliseconds
- (if track_wal_io_timing is enabled,
- fsync is on, and
- wal_sync_method is either
- fdatasync, fsync or
- fsync_writethrough, otherwise zero).
-
-
-
stats_resettimestamp with time zone
@@ -3385,8 +3527,8 @@ description | Waiting for a newly initialized WAL file to reach durable storage
Number of data page checksum failures detected in this
- database (or on a shared object), or NULL if data checksums are not
- enabled.
+ database (or on a shared object), or NULL if data checksums are
+ disabled.
@@ -3396,8 +3538,8 @@ description | Waiting for a newly initialized WAL file to reach durable storage
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.
+ this database (or on a shared object), or NULL if data checksums are
+ disabled.
@@ -3500,6 +3642,24 @@ description | Waiting for a newly initialized WAL file to reach durable storage
+
+
+ parallel_workers_to_launchbigint
+
+
+ Number of parallel workers planned to be launched by queries on this database
+
+
+
+
+
+ parallel_workers_launchedbigint
+
+
+ Number of parallel workers launched by queries on this database
+
+
+
stats_resettimestamp with time zone
@@ -3831,6 +3991,7 @@ description | Waiting for a newly initialized WAL file to reach durable storage
Estimated number of rows inserted since this table was last vacuumed
+ (not counting VACUUM FULL)
@@ -3911,6 +4072,49 @@ description | Waiting for a newly initialized WAL file to reach durable storage
daemon
+
+
+
+ total_vacuum_timedouble precision
+
+
+ Total time this table has been manually vacuumed, in milliseconds
+ (not counting VACUUM FULL).
+ (This includes the time spent sleeping due to cost-based delays.)
+
+
+
+
+
+ total_autovacuum_timedouble precision
+
+
+ Total time this table has been vacuumed by the autovacuum daemon,
+ in milliseconds. (This includes the time spent sleeping due to
+ cost-based delays.)
+
+
+
+
+
+ total_analyze_timedouble precision
+
+
+ Total time this table has been manually analyzed, in milliseconds.
+ (This includes the time spent sleeping due to cost-based delays.)
+
+
+
+
+
+ total_autoanalyze_timedouble precision
+
+
+ Total time this table has been analyzed by the autovacuum daemon,
+ in milliseconds. (This includes the time spent sleeping due to
+ cost-based delays.)
+
+
@@ -4066,16 +4270,35 @@ description | Waiting for a newly initialized WAL file to reach durable storage
- Queries that use certain SQL constructs to search for
- rows matching any value out of a list or array of multiple scalar values
- (see ) perform multiple
- primitive index scans (up to one primitive scan per scalar
- value) during query execution. Each internal primitive index scan
- increments pg_stat_all_indexes.idx_scan,
+ Index scans may sometimes perform multiple index searches per execution.
+ Each index search increments pg_stat_all_indexes.idx_scan,
so it's possible for the count of index scans to significantly exceed the
total number of index scan executor node executions.
+
+ This can happen with queries that use certain SQL
+ constructs to search for rows matching any value out of a list or array of
+ multiple scalar values (see ). It
+ can also happen to queries with a
+ column_name =
+ value1 OR
+ column_name =
+ value2 ... construct, though only
+ when the optimizer transforms the construct into an equivalent
+ multi-valued array representation. Similarly, when B-tree index scans use
+ the skip scan optimization, an index search is performed each time the
+ scan is repositioned to the next index leaf page that might have matching
+ tuples (see ).
+
+
+
+ EXPLAIN ANALYZE outputs the total number of index
+ searches performed by each index scan node. See
+ for an example demonstrating how
+ this works.
+
+
@@ -4661,6 +4884,27 @@ description | Waiting for a newly initialized WAL file to reach durable storage
+
+
+
+ pg_stat_get_backend_io
+
+ pg_stat_get_backend_io ( integer )
+ setof record
+
+
+ Returns I/O statistics about the backend with the specified
+ process ID. The output fields are exactly the same as the ones in the
+ pg_stat_io view.
+
+
+ The function does not return I/O statistics for the checkpointer,
+ the background writer, the startup process and the autovacuum launcher
+ as they are already visible in the pg_stat_io
+ view and there is only one of each.
+
+
+
@@ -4677,6 +4921,25 @@ description | Waiting for a newly initialized WAL file to reach durable storage
+
+
+
+ pg_stat_get_backend_wal
+
+ pg_stat_get_backend_wal ( integer )
+ record
+
+
+ Returns WAL statistics about the backend with the specified
+ process ID. The output fields are exactly the same as the ones in the
+ pg_stat_wal view.
+
+
+ The function does not return WAL statistics for the checkpointer,
+ the background writer, the startup process and the autovacuum launcher.
+
+
+
@@ -4842,6 +5105,24 @@ description | Waiting for a newly initialized WAL file to reach durable storage
+
+
+
+ pg_stat_reset_backend_stats
+
+ pg_stat_reset_backend_stats ( integer )
+ void
+
+
+ Resets statistics for a single backend with the specified process ID
+ to zero.
+
+
+ This function is restricted to superusers by default, but other users
+ can be granted EXECUTE to run the function.
+
+
+
@@ -5374,6 +5655,18 @@ FROM pg_stat_get_backend_idset() AS backendid;
acquiring inherited sample rows.
+
+
+
+ delay_timedouble precision
+
+
+ Total time spent sleeping due to cost-based delay (see
+ , in milliseconds
+ (if is enabled, otherwise
+ zero).
+
+
@@ -5441,9 +5734,9 @@ FROM pg_stat_get_backend_idset() AS backendid;
- Note that when ANALYZE is run on a partitioned table,
- all of its partitions are also recursively analyzed.
- In that case, ANALYZE
+ Note that when ANALYZE is run on a partitioned table
+ without the ONLY keyword, all of its partitions are
+ also recursively analyzed. In that case, ANALYZE
progress is reported first for the parent table, whereby its inheritance
statistics are collected, followed by that for each partition.
@@ -6268,6 +6561,15 @@ FROM pg_stat_get_backend_idset() AS backendid;
+
+
+ num_dead_item_idsbigint
+
+
+ Number of dead item identifiers collected since the last index vacuum cycle.
+
+
+
indexes_totalbigint
@@ -6290,6 +6592,21 @@ FROM pg_stat_get_backend_idset() AS backendid;
cleaning up indexes.
+
+
+
+ delay_timedouble precision
+
+
+ Total time spent sleeping due to cost-based delay (see
+ ), in milliseconds
+ (if is enabled, otherwise
+ zero). This includes the time that any associated parallel workers have
+ slept. However, parallel workers report their sleep time no more
+ frequently than once per second, so the reported value may be slightly
+ stale.
+
+
@@ -6474,6 +6791,16 @@ FROM pg_stat_get_backend_idset() AS backendid;
advances when the phase is streaming database files.
+
+
+
+ backup_typetext
+
+
+ Backup type. Either full or
+ incremental.
+
+
diff --git a/doc/src/sgml/mvcc.sgml b/doc/src/sgml/mvcc.sgml
index 380d0c9e8051e..049ee75a4ba3b 100644
--- a/doc/src/sgml/mvcc.sgml
+++ b/doc/src/sgml/mvcc.sgml
@@ -417,8 +417,8 @@
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:
+ cases. For example, consider transferring $100 from one account
+ to another:
BEGIN;
@@ -427,8 +427,8 @@ UPDATE accounts SET balance = balance - 100.00 WHERE acctnum = 7534;
COMMIT;
- If two such transactions concurrently try to change the balance of account
- 12345, we clearly want the second transaction to start with the updated
+ If another transaction concurrently tries to change the balance of account
+ 7534, we clearly want the second statement 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.
diff --git a/doc/src/sgml/oauth-validators.sgml b/doc/src/sgml/oauth-validators.sgml
new file mode 100644
index 0000000000000..704089dd7b3cb
--- /dev/null
+++ b/doc/src/sgml/oauth-validators.sgml
@@ -0,0 +1,416 @@
+
+
+
+ OAuth Validator Modules
+
+ OAuth Validators
+
+
+ PostgreSQL provides infrastructure for creating
+ custom modules to perform server-side validation of OAuth bearer tokens.
+ Because OAuth implementations vary so wildly, and bearer token validation is
+ heavily dependent on the issuing party, the server cannot check the token
+ itself; validator modules provide the integration layer between the server
+ and the OAuth provider in use.
+
+
+ OAuth validator modules must at least consist of an initialization function
+ (see ) and the required callback for
+ performing validation (see ).
+
+
+
+ Since a misbehaving validator might let unauthorized users into the database,
+ correct implementation is crucial for server safety. See
+ for design considerations.
+
+
+
+
+ Safely Designing a Validator Module
+
+
+ Read and understand the entirety of this section before implementing a
+ validator module. A malfunctioning validator is potentially worse than no
+ authentication at all, both because of the false sense of security it
+ provides, and because it may contribute to attacks against other pieces of
+ an OAuth ecosystem.
+
+
+
+
+ Validator Responsibilities
+
+ Although different modules may take very different approaches to token
+ validation, implementations generally need to perform three separate
+ actions:
+
+
+
+ Validate the Token
+
+
+ The validator must first ensure that the presented token is in fact a
+ valid Bearer token for use in client authentication. The correct way to
+ do this depends on the provider, but it generally involves either
+ cryptographic operations to prove that the token was created by a trusted
+ party (offline validation), or the presentation of the token to that
+ trusted party so that it can perform validation for you (online
+ validation).
+
+
+ Online validation, usually implemented via
+ OAuth Token
+ Introspection, requires fewer steps of a validator module and
+ allows central revocation of a token in the event that it is stolen
+ or misissued. However, it does require the module to make at least one
+ network call per authentication attempt (all of which must complete
+ within the configured ).
+ Additionally, your provider may not provide introspection endpoints for
+ use by external resource servers.
+
+
+ Offline validation is much more involved, typically requiring a validator
+ to maintain a list of trusted signing keys for a provider and then
+ check the token's cryptographic signature along with its contents.
+ Implementations must follow the provider's instructions to the letter,
+ including any verification of issuer ("where is this token from?"),
+ audience ("who is this token for?"), and validity period ("when can this
+ token be used?"). Since there is no communication between the module and
+ the provider, tokens cannot be centrally revoked using this method;
+ offline validator implementations may wish to place restrictions on the
+ maximum length of a token's validity period.
+
+
+ If the token cannot be validated, the module should immediately fail.
+ Further authentication/authorization is pointless if the bearer token
+ wasn't issued by a trusted party.
+
+
+
+
+ Authorize the Client
+
+
+ Next the validator must ensure that the end user has given the client
+ permission to access the server on their behalf. This generally involves
+ checking the scopes that have been assigned to the token, to make sure
+ that they cover database access for the current HBA parameters.
+
+
+ The purpose of this step is to prevent an OAuth client from obtaining a
+ token under false pretenses. If the validator requires all tokens to
+ carry scopes that cover database access, the provider should then loudly
+ prompt the user to grant that access during the flow. This gives them the
+ opportunity to reject the request if the client isn't supposed to be
+ using their credentials to connect to databases.
+
+
+ While it is possible to establish client authorization without explicit
+ scopes by using out-of-band knowledge of the deployed architecture, doing
+ so removes the user from the loop, which prevents them from catching
+ deployment mistakes and allows any such mistakes to be exploited
+ silently. Access to the database must be tightly restricted to only
+ trusted clients
+
+
+ That is, "trusted" in the sense that the OAuth client and the
+ PostgreSQL server are controlled by the same
+ entity. Notably, the Device Authorization client flow supported by
+ libpq does not usually meet this bar, since it's designed for use by
+ public/untrusted clients.
+
+
+ if users are not prompted for additional scopes.
+
+
+ Even if authorization fails, a module may choose to continue to pull
+ authentication information from the token for use in auditing and
+ debugging.
+
+
+
+
+ Authenticate the End User
+
+
+ Finally, the validator should determine a user identifier for the token,
+ either by asking the provider for this information or by extracting it
+ from the token itself, and return that identifier to the server (which
+ will then make a final authorization decision using the HBA
+ configuration). This identifier will be available within the session via
+ system_user
+ and recorded in the server logs if
+ is enabled.
+
+
+ Different providers may record a variety of different authentication
+ information for an end user, typically referred to as
+ claims. Providers usually document which of these
+ claims are trustworthy enough to use for authorization decisions and
+ which are not. (For instance, it would probably not be wise to use an
+ end user's full name as the identifier for authentication, since many
+ providers allow users to change their display names arbitrarily.)
+ Ultimately, the choice of which claim (or combination of claims) to use
+ comes down to the provider implementation and application requirements.
+
+
+ Note that anonymous/pseudonymous login is possible as well, by enabling
+ usermap delegation; see
+ .
+
+
+
+
+
+
+
+ General Coding Guidelines
+
+ Developers should keep the following in mind when implementing token
+ validation:
+
+
+
+ Token Confidentiality
+
+
+ Modules should not write tokens, or pieces of tokens, into the server
+ log. This is true even if the module considers the token invalid; an
+ attacker who confuses a client into communicating with the wrong provider
+ should not be able to retrieve that (otherwise valid) token from the
+ disk.
+
+
+ Implementations that send tokens over the network (for example, to
+ perform online token validation with a provider) must authenticate the
+ peer and ensure that strong transport security is in use.
+
+
+
+
+ Logging
+
+
+ Modules may use the same logging
+ facilities as standard extensions; however, the rules for emitting
+ log entries to the client are subtly different during the authentication
+ phase of the connection. Generally speaking, modules should log
+ verification problems at the COMMERROR level and return
+ normally, instead of using ERROR/FATAL
+ to unwind the stack, to avoid leaking information to unauthenticated
+ clients.
+
+
+
+
+ Interruptibility
+
+
+ Modules must remain interruptible by signals so that the server can
+ correctly handle authentication timeouts and shutdown signals from
+ pg_ctl. For example, blocking calls on sockets
+ should generally be replaced with code that handles both socket events
+ and interrupts without races (see WaitLatchOrSocket(),
+ WaitEventSetWait(), et al), and long-running loops
+ should periodically call CHECK_FOR_INTERRUPTS().
+ Failure to follow this guidance may result in unresponsive backend
+ sessions.
+
+
+
+
+ Testing
+
+
+ The breadth of testing an OAuth system is well beyond the scope of this
+ documentation, but at minimum, negative testing should be considered
+ mandatory. It's trivial to design a module that lets authorized users in;
+ the whole point of the system is to keep unauthorized users out.
+
+
+
+
+ Documentation
+
+
+ Validator implementations should document the contents and format of the
+ authenticated ID that is reported to the server for each end user, since
+ DBAs may need to use this information to construct pg_ident maps. (For
+ instance, is it an email address? an organizational ID number? a UUID?)
+ They should also document whether or not it is safe to use the module in
+ delegate_ident_mapping=1 mode, and what additional
+ configuration is required in order to do so.
+
+
+
+
+
+
+
+ Authorizing Users (Usermap Delegation)
+
+ The standard deliverable of a validation module is the user identifier,
+ which the server will then compare to any configured
+ pg_ident.conf
+ mappings and determine whether the end user is authorized to connect.
+ However, OAuth is itself an authorization framework, and tokens may carry
+ information about user privileges. For example, a token may be associated
+ with the organizational groups that a user belongs to, or list the roles
+ that a user may assume, and duplicating that knowledge into local usermaps
+ for every server may not be desirable.
+
+
+ To bypass username mapping entirely, and have the validator module assume
+ the additional responsibility of authorizing user connections, the HBA may
+ be configured with .
+ The module may then use token scopes or an equivalent method to decide
+ whether the user is allowed to connect under their desired role. The user
+ identifier will still be recorded by the server, but it plays no part in
+ determining whether to continue the connection.
+
+
+ Using this scheme, authentication itself is optional. As long as the module
+ reports that the connection is authorized, login will continue even if there
+ is no recorded user identifier at all. This makes it possible to implement
+ anonymous or pseudonymous access to the database, where the third-party
+ provider performs all necessary authentication but does not provide any
+ user-identifying information to the server. (Some providers may create an
+ anonymized ID number that can be recorded instead, for later auditing.)
+
+
+ Usermap delegation provides the most architectural flexibility, but it turns
+ the validator module into a single point of failure for connection
+ authorization. Use with caution.
+
+
+
+
+
+ Initialization Functions
+
+ _PG_oauth_validator_module_init
+
+
+ OAuth validator modules are dynamically loaded from the shared
+ libraries listed in .
+ Modules are loaded on demand when requested from a login in progress.
+ The normal library search path is used to locate the library. To
+ provide the validator callbacks and to indicate that the library is an OAuth
+ validator module a function named
+ _PG_oauth_validator_module_init must be provided. The
+ return value of the function must be a pointer to a struct of type
+ OAuthValidatorCallbacks, which contains a magic
+ number and pointers to the module's token validation functions. The returned
+ pointer must be of server lifetime, which is typically achieved by defining
+ it as a static const variable in global scope.
+
+typedef struct OAuthValidatorCallbacks
+{
+ uint32 magic; /* must be set to PG_OAUTH_VALIDATOR_MAGIC */
+
+ ValidatorStartupCB startup_cb;
+ ValidatorShutdownCB shutdown_cb;
+ ValidatorValidateCB validate_cb;
+} OAuthValidatorCallbacks;
+
+typedef const OAuthValidatorCallbacks *(*OAuthValidatorModuleInit) (void);
+
+
+ Only the validate_cb callback is required, the others
+ are optional.
+
+
+
+
+ OAuth Validator Callbacks
+
+ OAuth validator modules implement their functionality by defining a set of
+ callbacks. The server will call them as required to process the
+ authentication request from the user.
+
+
+
+ Startup Callback
+
+ The startup_cb callback is executed directly after
+ loading the module. This callback can be used to set up local state and
+ perform additional initialization if required. If the validator module
+ has state it can use state->private_data to
+ store it.
+
+
+typedef void (*ValidatorStartupCB) (ValidatorModuleState *state);
+
+
+
+
+
+ Validate Callback
+
+ The validate_cb callback is executed during the OAuth
+ exchange when a user attempts to authenticate using OAuth. Any state set in
+ previous calls will be available in state->private_data.
+
+
+typedef bool (*ValidatorValidateCB) (const ValidatorModuleState *state,
+ const char *token, const char *role,
+ ValidatorModuleResult *result);
+
+
+ token will contain the bearer token to validate.
+ PostgreSQL has ensured that the token is well-formed syntactically, but no
+ other validation has been performed. role will
+ contain the role the user has requested to log in as. The callback must
+ set output parameters in the result struct, which is
+ defined as below:
+
+
+typedef struct ValidatorModuleResult
+{
+ bool authorized;
+ char *authn_id;
+} ValidatorModuleResult;
+
+
+ The connection will only proceed if the module sets
+ result->authorized to true. To
+ authenticate the user, the authenticated user name (as determined using the
+ token) shall be palloc'd and returned in the result->authn_id
+ field. Alternatively, result->authn_id may be set to
+ NULL if the token is valid but the associated user identity cannot be
+ determined.
+
+
+ A validator may return false to signal an internal error,
+ in which case any result parameters are ignored and the connection fails.
+ Otherwise the validator should return true to indicate
+ that it has processed the token and made an authorization decision.
+
+
+ The behavior after validate_cb returns depends on the
+ specific HBA setup. Normally, the result->authn_id user
+ name must exactly match the role that the user is logging in as. (This
+ behavior may be modified with a usermap.) But when authenticating against
+ an HBA rule with delegate_ident_mapping turned on,
+ PostgreSQL will not perform any checks on the value of
+ result->authn_id at all; in this case it is up to the
+ validator to ensure that the token carries enough privileges for the user to
+ log in under the indicated role.
+
+
+
+
+ Shutdown Callback
+
+ The shutdown_cb callback is executed when the backend
+ process associated with the connection exits. If the validator module has
+ any allocated state, this callback should free it to avoid resource leaks.
+
+typedef void (*ValidatorShutdownCB) (ValidatorModuleState *state);
+
+
+
+
+
+
diff --git a/doc/src/sgml/pageinspect.sgml b/doc/src/sgml/pageinspect.sgml
index 27e0598f74c01..f5014787c783b 100644
--- a/doc/src/sgml/pageinspect.sgml
+++ b/doc/src/sgml/pageinspect.sgml
@@ -73,9 +73,9 @@
passed as argument. For example:
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
+ lsn | checksum | flags | lower | upper | special | pagesize | version | prune_xid
+------------+----------+--------+-------+-------+---------+----------+---------+-----------
+ 0/024A1B50 | 0 | 1 | 232 | 368 | 8192 | 8192 | 4 | 0
The returned columns correspond to the fields in the
PageHeaderData struct.
@@ -85,7 +85,7 @@ test=# SELECT * FROM page_header(get_raw_page('pg_class', 0));
The checksum 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
+ data checksums are disabled for this instance, then the value stored
is meaningless.
@@ -741,9 +741,9 @@ test=# SELECT first_tid, nbytes, tids[0:5] AS some_tids
For example:
test=# SELECT * FROM gist_page_opaque_info(get_raw_page('test_gist_idx', 2));
- lsn | nsn | rightlink | flags
------+-----+-----------+--------
- 0/1 | 0/0 | 1 | {leaf}
+ lsn | nsn | rightlink | flags
+------------+------------+-----------+--------
+ 0/0B5FE088 | 0/00000000 | 1 | {leaf}
(1 row)
diff --git a/doc/src/sgml/parallel.sgml b/doc/src/sgml/parallel.sgml
index dae9dd7f2f9bc..1ce9abf86f525 100644
--- a/doc/src/sgml/parallel.sgml
+++ b/doc/src/sgml/parallel.sgml
@@ -202,7 +202,7 @@ EXPLAIN SELECT * FROM pgbench_accounts WHERE filler LIKE '%x%';
- Even when parallel query plan is generated for a particular query, there
+ Even when a 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 Gather
@@ -423,7 +423,7 @@ EXPLAIN SELECT * FROM pgbench_accounts WHERE filler LIKE '%x%';
Append 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
+ involve appending multiple result 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
@@ -510,12 +510,6 @@ EXPLAIN SELECT * FROM pgbench_accounts WHERE filler LIKE '%x%';
-
-
- Plan nodes to which an InitPlan is attached.
-
-
-
Plan nodes that reference a correlated SubPlan.
diff --git a/doc/src/sgml/passwordcheck.sgml b/doc/src/sgml/passwordcheck.sgml
index 601f489227223..7ea32410463b6 100644
--- a/doc/src/sgml/passwordcheck.sgml
+++ b/doc/src/sgml/passwordcheck.sgml
@@ -59,4 +59,41 @@
+
+ Configuration Parameters
+
+
+
+
+ passwordcheck.min_password_length (integer)
+
+ passwordcheck.min_password_length configuration parameter
+
+
+
+
+ The minimum acceptable password length in bytes. The default is 8. Only
+ superusers can change this setting.
+
+
+
+ This parameter has no effect if a user supplies a pre-encrypted
+ password.
+
+
+
+
+
+
+
+ In ordinary usage, this parameter is set in
+ postgresql.conf, but superusers can alter it on-the-fly
+ within their own sessions. Typical usage might be:
+
+
+
+# postgresql.conf
+passwordcheck.min_password_length = 12
+
+
diff --git a/doc/src/sgml/perform.sgml b/doc/src/sgml/perform.sgml
index ff689b65245fc..106583fb2965d 100644
--- a/doc/src/sgml/perform.sgml
+++ b/doc/src/sgml/perform.sgml
@@ -39,7 +39,7 @@
Examples in this section are drawn from the regression test database
- after doing a VACUUM ANALYZE, using v17 development sources.
+ after doing a VACUUM ANALYZE, using v18 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 ANALYZE's statistics are random samples rather
@@ -578,6 +578,31 @@ WHERE t1.unique1 < 100 AND t1.unique2 = t2.unique2;
discussed below.
+
+ When using the enable/disable flags to disable plan node types, many of
+ the flags only discourage the use of the corresponding plan node and don't
+ outright disallow the planner's ability to use the plan node type. This
+ is by design so that the planner still maintains the ability to form a
+ plan for a given query. When the resulting plan contains a disabled node,
+ the EXPLAIN output will indicate this fact.
+
+
+SET enable_seqscan = off;
+EXPLAIN SELECT * FROM unit;
+
+ QUERY PLAN
+---------------------------------------------------------
+ Seq Scan on unit (cost=0.00..21.30 rows=1130 width=44)
+ Disabled: true
+
+
+
+
+ Because the unit table has no indexes, there is no
+ other means to read the table data, so the sequential scan is the only
+ option available to the query planner.
+
+
subplan
@@ -696,14 +721,22 @@ WHERE t1.unique1 < 10 AND t1.unique2 = t2.unique2;
QUERY PLAN
-------------------------------------------------------------------&zwsp;--------------------------------------------------------------
- Nested Loop (cost=4.65..118.50 rows=10 width=488) (actual time=0.017..0.051 rows=10 loops=1)
- -> Bitmap Heap Scan on tenk1 t1 (cost=4.36..39.38 rows=10 width=244) (actual time=0.009..0.017 rows=10 loops=1)
+ Nested Loop (cost=4.65..118.50 rows=10 width=488) (actual time=0.017..0.051 rows=10.00 loops=1)
+ Buffers: shared hit=36 read=6
+ -> Bitmap Heap Scan on tenk1 t1 (cost=4.36..39.38 rows=10 width=244) (actual time=0.009..0.017 rows=10.00 loops=1)
Recheck Cond: (unique1 < 10)
Heap Blocks: exact=10
- -> Bitmap Index Scan on tenk1_unique1 (cost=0.00..4.36 rows=10 width=0) (actual time=0.004..0.004 rows=10 loops=1)
+ Buffers: shared hit=3 read=5 written=4
+ -> Bitmap Index Scan on tenk1_unique1 (cost=0.00..4.36 rows=10 width=0) (actual time=0.004..0.004 rows=10.00 loops=1)
Index Cond: (unique1 < 10)
- -> Index Scan using tenk2_unique2 on tenk2 t2 (cost=0.29..7.90 rows=1 width=244) (actual time=0.003..0.003 rows=1 loops=10)
+ Index Searches: 1
+ Buffers: shared hit=2
+ -> Index Scan using tenk2_unique2 on tenk2 t2 (cost=0.29..7.90 rows=1 width=244) (actual time=0.003..0.003 rows=1.00 loops=10)
Index Cond: (unique2 = t1.unique2)
+ Index Searches: 10
+ Buffers: shared hit=24 read=6
+ Planning:
+ Buffers: shared hit=15 dirtied=9
Planning Time: 0.485 ms
Execution Time: 0.073 ms
@@ -741,19 +774,28 @@ WHERE t1.unique1 < 100 AND t1.unique2 = t2.unique2 ORDER BY t1.fivethous;
QUERY PLAN
-------------------------------------------------------------------&zwsp;-------------------------------------------------------------------&zwsp;------
- Sort (cost=713.05..713.30 rows=100 width=488) (actual time=2.995..3.002 rows=100 loops=1)
+ Sort (cost=713.05..713.30 rows=100 width=488) (actual time=2.995..3.002 rows=100.00 loops=1)
Sort Key: t1.fivethous
Sort Method: quicksort Memory: 74kB
- -> Hash Join (cost=226.23..709.73 rows=100 width=488) (actual time=0.515..2.920 rows=100 loops=1)
+ Buffers: shared hit=440
+ -> Hash Join (cost=226.23..709.73 rows=100 width=488) (actual time=0.515..2.920 rows=100.00 loops=1)
Hash Cond: (t2.unique2 = t1.unique2)
- -> Seq Scan on tenk2 t2 (cost=0.00..445.00 rows=10000 width=244) (actual time=0.026..1.790 rows=10000 loops=1)
- -> Hash (cost=224.98..224.98 rows=100 width=244) (actual time=0.476..0.477 rows=100 loops=1)
+ Buffers: shared hit=437
+ -> Seq Scan on tenk2 t2 (cost=0.00..445.00 rows=10000 width=244) (actual time=0.026..1.790 rows=10000.00 loops=1)
+ Buffers: shared hit=345
+ -> Hash (cost=224.98..224.98 rows=100 width=244) (actual time=0.476..0.477 rows=100.00 loops=1)
Buckets: 1024 Batches: 1 Memory Usage: 35kB
- -> Bitmap Heap Scan on tenk1 t1 (cost=5.06..224.98 rows=100 width=244) (actual time=0.030..0.450 rows=100 loops=1)
+ Buffers: shared hit=92
+ -> Bitmap Heap Scan on tenk1 t1 (cost=5.06..224.98 rows=100 width=244) (actual time=0.030..0.450 rows=100.00 loops=1)
Recheck Cond: (unique1 < 100)
Heap Blocks: exact=90
- -> Bitmap Index Scan on tenk1_unique1 (cost=0.00..5.04 rows=100 width=0) (actual time=0.013..0.013 rows=100 loops=1)
+ Buffers: shared hit=92
+ -> Bitmap Index Scan on tenk1_unique1 (cost=0.00..5.04 rows=100 width=0) (actual time=0.013..0.013 rows=100.00 loops=1)
Index Cond: (unique1 < 100)
+ Index Searches: 1
+ Buffers: shared hit=2
+ Planning:
+ Buffers: shared hit=12
Planning Time: 0.187 ms
Execution Time: 3.036 ms
@@ -766,6 +808,90 @@ WHERE t1.unique1 < 100 AND t1.unique2 = t2.unique2 ORDER BY t1.fivethous;
shown.)
+
+ Index Scan nodes (as well as Bitmap Index Scan and Index-Only Scan nodes)
+ show an Index Searches line that reports the total number
+ of searches across all node
+ executions/loops:
+
+
+EXPLAIN ANALYZE SELECT * FROM tenk1 WHERE thousand IN (1, 500, 700, 999);
+ QUERY PLAN
+-------------------------------------------------------------------&zwsp;---------------------------------------------------------------
+ Bitmap Heap Scan on tenk1 (cost=9.45..73.44 rows=40 width=244) (actual time=0.012..0.028 rows=40.00 loops=1)
+ Recheck Cond: (thousand = ANY ('{1,500,700,999}'::integer[]))
+ Heap Blocks: exact=39
+ Buffers: shared hit=47
+ -> Bitmap Index Scan on tenk1_thous_tenthous (cost=0.00..9.44 rows=40 width=0) (actual time=0.009..0.009 rows=40.00 loops=1)
+ Index Cond: (thousand = ANY ('{1,500,700,999}'::integer[]))
+ Index Searches: 4
+ Buffers: shared hit=8
+ Planning Time: 0.029 ms
+ Execution Time: 0.034 ms
+
+
+ Here we see a Bitmap Index Scan node that needed 4 separate index
+ searches. The scan had to search the index from the
+ tenk1_thous_tenthous index root page once per
+ integer value from the predicate's IN
+ construct. However, the number of index searches often won't have such a
+ simple correspondence to the query predicate:
+
+
+EXPLAIN ANALYZE SELECT * FROM tenk1 WHERE thousand IN (1, 2, 3, 4);
+ QUERY PLAN
+-------------------------------------------------------------------&zwsp;---------------------------------------------------------------
+ Bitmap Heap Scan on tenk1 (cost=9.45..73.44 rows=40 width=244) (actual time=0.009..0.019 rows=40.00 loops=1)
+ Recheck Cond: (thousand = ANY ('{1,2,3,4}'::integer[]))
+ Heap Blocks: exact=38
+ Buffers: shared hit=40
+ -> Bitmap Index Scan on tenk1_thous_tenthous (cost=0.00..9.44 rows=40 width=0) (actual time=0.005..0.005 rows=40.00 loops=1)
+ Index Cond: (thousand = ANY ('{1,2,3,4}'::integer[]))
+ Index Searches: 1
+ Buffers: shared hit=2
+ Planning Time: 0.029 ms
+ Execution Time: 0.026 ms
+
+
+ This variant of our IN query performed only 1 index
+ search. It spent less time traversing the index (compared to the original
+ query) because its IN construct uses values matching
+ index tuples stored next to each other, on the same
+ tenk1_thous_tenthous index leaf page.
+
+
+
+ The Index Searches line is also useful with B-tree index
+ scans that apply the skip scan optimization to
+ more efficiently traverse through an index:
+
+EXPLAIN ANALYZE SELECT four, unique1 FROM tenk1 WHERE four BETWEEN 1 AND 3 AND unique1 = 42;
+ QUERY PLAN
+-------------------------------------------------------------------&zwsp;---------------------------------------------------------------
+ Index Only Scan using tenk1_four_unique1_idx on tenk1 (cost=0.29..6.90 rows=1 width=8) (actual time=0.006..0.007 rows=1.00 loops=1)
+ Index Cond: ((four >= 1) AND (four <= 3) AND (unique1 = 42))
+ Heap Fetches: 0
+ Index Searches: 3
+ Buffers: shared hit=7
+ Planning Time: 0.029 ms
+ Execution Time: 0.012 ms
+
+
+ Here we see an Index-Only Scan node using
+ tenk1_four_unique1_idx, a multi-column index on the
+ tenk1 table's four and
+ unique1 columns. The scan performs 3 searches
+ that each read a single index leaf page:
+ four = 1 AND unique1 = 42,
+ four = 2 AND unique1 = 42, and
+ four = 3 AND unique1 = 42. This index
+ is generally a good target for skip scan, since, as discussed in
+ , its leading column (the
+ four column) contains only 4 distinct values,
+ while its second/final column (the unique1
+ column) contains many distinct values.
+
+
Another type of extra information is the number of rows removed by a
filter condition:
@@ -775,9 +901,10 @@ EXPLAIN ANALYZE SELECT * FROM tenk1 WHERE ten < 7;
QUERY PLAN
-------------------------------------------------------------------&zwsp;--------------------------------------
- Seq Scan on tenk1 (cost=0.00..470.00 rows=7000 width=244) (actual time=0.030..1.995 rows=7000 loops=1)
+ Seq Scan on tenk1 (cost=0.00..470.00 rows=7000 width=244) (actual time=0.030..1.995 rows=7000.00 loops=1)
Filter: (ten < 7)
Rows Removed by Filter: 3000
+ Buffers: shared hit=345
Planning Time: 0.102 ms
Execution Time: 2.145 ms
@@ -798,9 +925,10 @@ EXPLAIN ANALYZE SELECT * FROM polygon_tbl WHERE f1 @> polygon '(0.5,2.0)';
QUERY PLAN
-------------------------------------------------------------------&zwsp;-----------------------------------
- Seq Scan on polygon_tbl (cost=0.00..1.09 rows=1 width=85) (actual time=0.023..0.023 rows=0 loops=1)
+ Seq Scan on polygon_tbl (cost=0.00..1.09 rows=1 width=85) (actual time=0.023..0.023 rows=0.00 loops=1)
Filter: (f1 @> '((0.5,2))'::polygon)
Rows Removed by Filter: 7
+ Buffers: shared hit=1
Planning Time: 0.039 ms
Execution Time: 0.033 ms
@@ -817,9 +945,11 @@ EXPLAIN ANALYZE SELECT * FROM polygon_tbl WHERE f1 @> polygon '(0.5,2.0)';
QUERY PLAN
-------------------------------------------------------------------&zwsp;-------------------------------------------------------
- Index Scan using gpolygonind on polygon_tbl (cost=0.13..8.15 rows=1 width=85) (actual time=0.074..0.074 rows=0 loops=1)
+ Index Scan using gpolygonind on polygon_tbl (cost=0.13..8.15 rows=1 width=85) (actual time=0.074..0.074 rows=0.00 loops=1)
Index Cond: (f1 @> '((0.5,2))'::polygon)
Rows Removed by Index Recheck: 1
+ Index Searches: 1
+ Buffers: shared hit=1
Planning Time: 0.039 ms
Execution Time: 0.098 ms
@@ -832,34 +962,33 @@ EXPLAIN ANALYZE SELECT * FROM polygon_tbl WHERE f1 @> polygon '(0.5,2.0)';
- EXPLAIN has a BUFFERS option that can be used with
- ANALYZE to get even more run time statistics:
+ EXPLAIN has a BUFFERS option which
+ provides additional detail about I/O operations performed during the
+ planning and execution of the given query. The buffer numbers displayed
+ show the count of the non-distinct buffers hit, read, dirtied, and written
+ for the given node and all of its child nodes. The
+ ANALYZE option implicitly enables the
+ BUFFERS option. If this
+ is undesired, BUFFERS may be explicitly disabled:
-EXPLAIN (ANALYZE, BUFFERS) SELECT * FROM tenk1 WHERE unique1 < 100 AND unique2 > 9000;
+EXPLAIN (ANALYZE, BUFFERS OFF) SELECT * FROM tenk1 WHERE unique1 < 100 AND unique2 > 9000;
QUERY PLAN
-------------------------------------------------------------------&zwsp;--------------------------------------------------------------
- Bitmap Heap Scan on tenk1 (cost=25.07..60.11 rows=10 width=244) (actual time=0.105..0.114 rows=10 loops=1)
+ Bitmap Heap Scan on tenk1 (cost=25.07..60.11 rows=10 width=244) (actual time=0.105..0.114 rows=10.00 loops=1)
Recheck Cond: ((unique1 < 100) AND (unique2 > 9000))
Heap Blocks: exact=10
- Buffers: shared hit=14 read=3
- -> BitmapAnd (cost=25.07..25.07 rows=10 width=0) (actual time=0.100..0.101 rows=0 loops=1)
- Buffers: shared hit=4 read=3
- -> Bitmap Index Scan on tenk1_unique1 (cost=0.00..5.04 rows=100 width=0) (actual time=0.027..0.027 rows=100 loops=1)
+ -> BitmapAnd (cost=25.07..25.07 rows=10 width=0) (actual time=0.100..0.101 rows=0.00 loops=1)
+ -> Bitmap Index Scan on tenk1_unique1 (cost=0.00..5.04 rows=100 width=0) (actual time=0.027..0.027 rows=100.00 loops=1)
Index Cond: (unique1 < 100)
- Buffers: shared hit=2
- -> Bitmap Index Scan on tenk1_unique2 (cost=0.00..19.78 rows=999 width=0) (actual time=0.070..0.070 rows=999 loops=1)
+ Index Searches: 1
+ -> Bitmap Index Scan on tenk1_unique2 (cost=0.00..19.78 rows=999 width=0) (actual time=0.070..0.070 rows=999.00 loops=1)
Index Cond: (unique2 > 9000)
- Buffers: shared hit=2 read=3
- Planning:
- Buffers: shared hit=3
+ Index Searches: 1
Planning Time: 0.162 ms
Execution Time: 0.143 ms
-
- The numbers provided by BUFFERS help to identify which parts
- of the query are the most I/O-intensive.
@@ -877,12 +1006,15 @@ EXPLAIN ANALYZE UPDATE tenk1 SET hundred = hundred + 1 WHERE unique1 < 100;
QUERY PLAN
-------------------------------------------------------------------&zwsp;-------------------------------------------------------------
- Update on tenk1 (cost=5.06..225.23 rows=0 width=0) (actual time=1.634..1.635 rows=0 loops=1)
- -> Bitmap Heap Scan on tenk1 (cost=5.06..225.23 rows=100 width=10) (actual time=0.065..0.141 rows=100 loops=1)
+ Update on tenk1 (cost=5.06..225.23 rows=0 width=0) (actual time=1.634..1.635 rows=0.00 loops=1)
+ -> Bitmap Heap Scan on tenk1 (cost=5.06..225.23 rows=100 width=10) (actual time=0.065..0.141 rows=100.00 loops=1)
Recheck Cond: (unique1 < 100)
Heap Blocks: exact=90
- -> Bitmap Index Scan on tenk1_unique1 (cost=0.00..5.04 rows=100 width=0) (actual time=0.031..0.031 rows=100 loops=1)
+ Buffers: shared hit=4 read=2
+ -> Bitmap Index Scan on tenk1_unique1 (cost=0.00..5.04 rows=100 width=0) (actual time=0.031..0.031 rows=100.00 loops=1)
Index Cond: (unique1 < 100)
+ Index Searches: 1
+ Buffers: shared read=2
Planning Time: 0.151 ms
Execution Time: 1.856 ms
@@ -1014,11 +1146,14 @@ EXPLAIN ANALYZE SELECT * FROM tenk1 WHERE unique1 < 100 AND unique2 > 9000
QUERY PLAN
-------------------------------------------------------------------&zwsp;------------------------------------------------------------
- Limit (cost=0.29..14.33 rows=2 width=244) (actual time=0.051..0.071 rows=2 loops=1)
- -> Index Scan using tenk1_unique2 on tenk1 (cost=0.29..70.50 rows=10 width=244) (actual time=0.051..0.070 rows=2 loops=1)
+ Limit (cost=0.29..14.33 rows=2 width=244) (actual time=0.051..0.071 rows=2.00 loops=1)
+ Buffers: shared hit=16
+ -> Index Scan using tenk1_unique2 on tenk1 (cost=0.29..70.50 rows=10 width=244) (actual time=0.051..0.070 rows=2.00 loops=1)
Index Cond: (unique2 > 9000)
Filter: (unique1 < 100)
Rows Removed by Filter: 287
+ Index Searches: 1
+ Buffers: shared hit=16
Planning Time: 0.077 ms
Execution Time: 0.086 ms
diff --git a/doc/src/sgml/pgbuffercache.sgml b/doc/src/sgml/pgbuffercache.sgml
index 4b90eefc0b078..eeb85a0e04908 100644
--- a/doc/src/sgml/pgbuffercache.sgml
+++ b/doc/src/sgml/pgbuffercache.sgml
@@ -19,20 +19,40 @@
pg_buffercache_pages
+
+ pg_buffercache_numa
+
+
pg_buffercache_summary
+
+ pg_buffercache_usage_counts
+
+
pg_buffercache_evict
+
+ pg_buffercache_evict_relation
+
+
+
+ pg_buffercache_evict_all
+
+
This module provides the pg_buffercache_pages()
- function (wrapped in the pg_buffercache view),
- the pg_buffercache_summary() function, the
- pg_buffercache_usage_counts() function and
- the pg_buffercache_evict() function.
+ function (wrapped in the pg_buffercache view), the
+ pg_buffercache_numa_pages() function (wrapped in the
+ pg_buffercache_numa view), the
+ pg_buffercache_summary() function, the
+ pg_buffercache_usage_counts() function, the
+ pg_buffercache_evict() function, the
+ pg_buffercache_evict_relation() function and the
+ pg_buffercache_evict_all() function.
@@ -42,6 +62,15 @@
convenient use.
+
+ The pg_buffercache_numa_pages() function provides
+ NUMA node mappings for shared buffer entries. This
+ information is not part of pg_buffercache_pages()
+ itself, as it is much slower to retrieve.
+ The pg_buffercache_numa view wraps the function for
+ convenient use.
+
+
The pg_buffercache_summary() function returns a single
row summarizing the state of the shared buffer cache.
@@ -65,6 +94,19 @@
function is restricted to superusers only.
+
+ The pg_buffercache_evict_relation() function allows all
+ unpinned shared buffers in the relation to be evicted from the buffer pool
+ given a relation identifier. Use of this function is restricted to
+ superusers only.
+
+
+
+ The pg_buffercache_evict_all() function allows all
+ unpinned shared buffers to be evicted in the buffer pool. Use of this
+ function is restricted to superusers only.
+
+
The <structname>pg_buffercache</structname> View
@@ -200,6 +242,78 @@
+
+ The <structname>pg_buffercache_numa</structname> View
+
+
+ The definitions of the columns exposed by the view are shown in .
+
+
+
+ <structname>pg_buffercache_numa</structname> Columns
+
+
+
+
+ Column Type
+
+
+ Description
+
+
+
+
+
+
+
+ bufferidinteger
+
+
+ ID, in the range 1..shared_buffers
+
+
+
+
+
+ os_page_numbigint
+
+
+ number of OS memory page for this buffer
+
+
+
+
+
+ numa_nodeint
+
+
+ ID of NUMA node
+
+
+
+
+
+
+
+
+ As NUMA node ID inquiry for each page requires memory pages
+ to be paged-in, the first execution of this function can take a noticeable
+ amount of time. In all the cases (first execution or not), retrieving this
+ information is costly and querying the view at a high frequency is not recommended.
+
+
+
+
+ When determining the NUMA node, the view touches
+ all memory pages for the shared memory segment. This will force
+ allocation of the shared memory, if it wasn't allocated already,
+ and the memory may get allocated in a single NUMA
+ node (depending on system configuration).
+
+
+
+
+
The <function>pg_buffercache_summary()</function> Function
@@ -365,15 +479,53 @@
- The <structname>pg_buffercache_evict</structname> Function
+ The <function>pg_buffercache_evict()</function> Function
The pg_buffercache_evict() function takes a buffer
identifier, as shown in the bufferid column of
- the pg_buffercache view. It returns true on success,
- and false if the buffer wasn't valid, if it couldn't be evicted because it
- was pinned, or if it became dirty again after an attempt to write it out.
- The result is immediately out of date upon return, as the buffer might
- become valid again at any time due to concurrent activity. The function is
+ the pg_buffercache view. It returns information
+ about whether the buffer was evicted and flushed. The buffer_evicted
+ column is true on success, and false if the buffer wasn't valid, if it
+ couldn't be evicted because it was pinned, or if it became dirty again
+ after an attempt to write it out. The buffer_flushed column is true if the
+ buffer was flushed. This does not necessarily mean that buffer was flushed
+ by us, it might be flushed by someone else. The result is immediately out
+ of date upon return, as the buffer might become valid again at any time due
+ to concurrent activity. The function is intended for developer testing
+ only.
+
+
+
+
+ The <structname>pg_buffercache_evict_relation()</structname> Function
+
+ The pg_buffercache_evict_relation() function is very
+ similar to the pg_buffercache_evict() function. The
+ difference is that the pg_buffercache_evict_relation()
+ takes a relation identifier instead of buffer identifier. It tries to
+ evict all buffers for all forks in that relation.
+
+ It returns the number of evicted buffers, flushed buffers and the number of
+ buffers that could not be evicted. Flushed buffers haven't necessarily
+ been flushed by us, they might have been flushed by someone else. The
+ result is immediately out of date upon return, as buffers might immediately
+ be read back in due to concurrent activity. The function is intended for
+ developer testing only.
+
+
+
+
+ The <structname>pg_buffercache_evict_all()</structname> Function
+
+ The pg_buffercache_evict_all() function is very
+ similar to the pg_buffercache_evict() function. The
+ difference is, the pg_buffercache_evict_all() function
+ does not take an argument; instead it tries to evict all buffers in the
+ buffer pool. It returns the number of evicted buffers, flushed buffers and
+ the number of buffers that could not be evicted. Flushed buffers haven't
+ necessarily been flushed by us, they might have been flushed by someone
+ else. The result is immediately out of date upon return, as buffers might
+ immediately be read back in due to concurrent activity. The function is
intended for developer testing only.
diff --git a/doc/src/sgml/pgcrypto.sgml b/doc/src/sgml/pgcrypto.sgml
index b8b89696e7f68..bc5c74ad017fa 100644
--- a/doc/src/sgml/pgcrypto.sgml
+++ b/doc/src/sgml/pgcrypto.sgml
@@ -106,7 +106,7 @@ hmac(data bytea, key bytea, type text) returns bytea
The algorithms in crypt() differ from the usual
- MD5 or SHA1 hashing algorithms in the following respects:
+ MD5 or SHA-1 hashing algorithms in the following respects:
@@ -146,6 +146,12 @@ hmac(data bytea, key bytea, type text) returns bytea
Supported Algorithms for <function>crypt()</function>
+
+
+
+
+
+ Algorithm
@@ -189,6 +195,29 @@ hmac(data bytea, key bytea, type text) returns bytea
13Original UNIX crypt
+
+ sha256crypt
+ unlimited
+ yes
+ up to 32
+ 80
+ Adapted from publicly available reference implementation
+ Unix crypt using SHA-256 and SHA-512
+
+
+
+
+ sha512crypt
+ unlimited
+ yes
+ up to 32
+ 123
+ Adapted from publicly available reference implementation
+ Unix crypt using SHA-256 and SHA-512
+
+
+
+
@@ -245,7 +274,9 @@ gen_salt(type text [, iter_count integer ]) returns text
The type parameter specifies the hashing algorithm.
The accepted types are: des, xdes,
- md5 and bf.
+ md5, bf, sha256crypt and
+ sha512crypt. The last two, sha256crypt and
+ sha512crypt are modern SHA-2 based password hashes.
@@ -284,6 +315,12 @@ gen_salt(type text [, iter_count integer ]) returns text
431
+
+ sha256crypt, sha512crypt
+ 5000
+ 1000
+ 999999999
+
@@ -313,6 +350,14 @@ gen_salt(type text [, iter_count integer ]) returns text
gen_salt.
+
+ The default iter_count for sha256crypt and
+ sha512crypt of 5000 is considered too low for modern
+ hardware, but can be adjusted to generate stronger password hashes.
+ Otherwise both hashes, sha256crypt and sha512crypt are
+ considered safe.
+
+
Hash Algorithm Speeds
@@ -525,7 +570,7 @@ gen_salt(type text [, iter_count integer ]) returns text
- A SHA1 hash of the random prefix and data is appended.
+ A SHA-1 hash of the random prefix and data is appended.
@@ -1082,6 +1127,11 @@ decrypt_iv(data bytea, key bytea, iv bytea, type text) returns bytea
cbc — next block depends on previous (default)
+
+
+ cfb — next block depends on previous encrypted block
+
+ ecb — each block is encrypted separately (for
@@ -1112,7 +1162,8 @@ encrypt(data, 'fooz', 'bf-cbc/pad:pkcs')
In encrypt_iv and decrypt_iv, the
- iv parameter is the initial value for the CBC mode;
+ iv parameter is the initial value for the CBC and
+ CFB 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.
@@ -1149,6 +1200,60 @@ gen_random_uuid() returns uuid
+
+ OpenSSL Support Functions
+
+
+ fips_mode
+
+
+
+fips_mode() returns boolean
+
+
+ Returns true if OpenSSL is
+ running with FIPS mode enabled, otherwise false.
+
+
+
+
+ Configuration Parameters
+
+
+ There is one configuration parameter that controls the behavior of
+ pgcrypto.
+
+
+
+
+
+ pgcrypto.builtin_crypto_enabled (enum)
+
+ pgcrypto.builtin_crypto_enabled configuration
+ parameter
+
+
+
+
+ pgcrypto.builtin_crypto_enabled determines if the
+ built in crypto functions gen_salt(), and
+ crypt() are available for use. Setting this to
+ off disables these functions. on
+ (the default) enables these functions to work normally.
+ fips disables these functions if
+ OpenSSL is detected to operate in FIPS mode.
+
+
+
+
+
+
+ In ordinary usage, this parameter is set
+ in postgresql.conf, although superusers can alter it
+ on-the-fly within their own sessions.
+
+
+
Notes
diff --git a/doc/src/sgml/pgfreespacemap.sgml b/doc/src/sgml/pgfreespacemap.sgml
index 829ad60f32fdc..3774a9f8c6b29 100644
--- a/doc/src/sgml/pgfreespacemap.sgml
+++ b/doc/src/sgml/pgfreespacemap.sgml
@@ -67,7 +67,7 @@
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.
+ whether a page is in-use or empty.
diff --git a/doc/src/sgml/pglogicalinspect.sgml b/doc/src/sgml/pglogicalinspect.sgml
new file mode 100644
index 0000000000000..1c1a9d14e510a
--- /dev/null
+++ b/doc/src/sgml/pglogicalinspect.sgml
@@ -0,0 +1,143 @@
+
+
+
+ pg_logicalinspect — logical decoding components inspection
+
+
+ pg_logicalinspect
+
+
+
+ The pg_logicalinspect module provides SQL functions
+ that allow you to inspect the contents of logical decoding components. It
+ allows the inspection of serialized logical snapshots of a running
+ PostgreSQL database cluster, which is useful
+ for debugging or educational purposes.
+
+
+
+ By default, use of these functions is restricted to superusers and members of
+ the pg_read_server_files role. Access may be granted by
+ superusers to others using GRANT.
+
+
+
+ Functions
+
+
+
+
+ pg_get_logical_snapshot_meta(filename text) returns record
+
+
+
+
+ Gets logical snapshot metadata about a snapshot file that is located in
+ the server's pg_logical/snapshots directory.
+ The filename argument represents the snapshot
+ file name.
+ For example:
+
+postgres=# SELECT * FROM pg_ls_logicalsnapdir();
+-[ RECORD 1 ]+-----------------------
+name | 0-40796E18.snap
+size | 152
+modification | 2024-08-14 16:36:32+00
+
+postgres=# SELECT * FROM pg_get_logical_snapshot_meta('0-40796E18.snap');
+-[ RECORD 1 ]--------
+magic | 1369563137
+checksum | 1028045905
+version | 6
+
+postgres=# SELECT ss.name, meta.* FROM pg_ls_logicalsnapdir() AS ss,
+pg_get_logical_snapshot_meta(ss.name) AS meta;
+-[ RECORD 1 ]-------------
+name | 0-40796E18.snap
+magic | 1369563137
+checksum | 1028045905
+version | 6
+
+
+
+ If filename does not match a snapshot file, the
+ function raises an error.
+
+
+
+
+
+
+ pg_get_logical_snapshot_info(filename text) returns record
+
+
+
+
+ Gets logical snapshot information about a snapshot file that is located in
+ the server's pg_logical/snapshots directory.
+ The filename argument represents the snapshot
+ file name.
+ For example:
+
+postgres=# SELECT * FROM pg_ls_logicalsnapdir();
+-[ RECORD 1 ]+-----------------------
+name | 0-40796E18.snap
+size | 152
+modification | 2024-08-14 16:36:32+00
+
+postgres=# SELECT * FROM pg_get_logical_snapshot_info('0-40796E18.snap');
+-[ RECORD 1 ]------------+-----------
+state | consistent
+xmin | 751
+xmax | 751
+start_decoding_at | 0/40796AF8
+two_phase_at | 0/40796AF8
+initial_xmin_horizon | 0
+building_full_snapshot | f
+in_slot_creation | f
+last_serialized_snapshot | 0/00000000
+next_phase_at | 0
+committed_count | 0
+committed_xip |
+catchange_count | 2
+catchange_xip | {751,752}
+
+postgres=# SELECT ss.name, info.* FROM pg_ls_logicalsnapdir() AS ss,
+pg_get_logical_snapshot_info(ss.name) AS info;
+-[ RECORD 1 ]------------+----------------
+name | 0-40796E18.snap
+state | consistent
+xmin | 751
+xmax | 751
+start_decoding_at | 0/40796AF8
+two_phase_at | 0/40796AF8
+initial_xmin_horizon | 0
+building_full_snapshot | f
+in_slot_creation | f
+last_serialized_snapshot | 0/00000000
+next_phase_at | 0
+committed_count | 0
+committed_xip |
+catchange_count | 2
+catchange_xip | {751,752}
+
+
+
+ If filename does not match a snapshot file, the
+ function raises an error.
+
+
+
+
+
+
+
+
+ Author
+
+
+ Bertrand Drouvot bertranddrouvot.pg@gmail.com
+
+
+
+
diff --git a/doc/src/sgml/pgoverexplain.sgml b/doc/src/sgml/pgoverexplain.sgml
new file mode 100644
index 0000000000000..377ddc8139ecf
--- /dev/null
+++ b/doc/src/sgml/pgoverexplain.sgml
@@ -0,0 +1,201 @@
+
+
+
+ pg_overexplain — allow EXPLAIN to dump even more details
+
+
+ pg_overexplain
+
+
+
+ The pg_overexplain module extends EXPLAIN
+ with new options that provide additional output. It is mostly intended to
+ assist with debugging of and development of the planner, rather than for
+ general use. Since this module displays internal details of planner data
+ structures, it may be necessary to refer to the source code to make sense
+ of the output. Furthermore, the output is likely to change whenever (and as
+ often as) those data structures change.
+
+
+
+ To use it, simply load it into the server. You can load it into an
+ individual session:
+
+
+LOAD 'pg_overexplain';
+
+
+ You can also preload it into some or all sessions by including
+ pg_overexplain in
+ or
+ in
+ postgresql.conf.
+
+
+
+ EXPLAIN (DEBUG)
+
+
+ The DEBUG option displays miscellaneous information from
+ the plan tree that is not normally shown because it is not expected to be
+ of general interest. For each individual plan node, it will display the
+ following fields. See Plan in
+ nodes/plannodes.h for additional documentation of these
+ fields.
+
+
+
+
+
+ Disabled Nodes. Normal EXPLAIN
+ determines whether a node is disabled by checking whether the node's
+ count of disabled nodes is larger than the sum of the counts for the
+ underlying nodes. This option shows the raw counter value.
+
+
+
+
+
+ Parallel Safe. Indicates whether it would be safe for
+ a plan tree node to appear beneath a Gather or
+ Gather Merge node, regardless of whether it is
+ actually below such a node.
+
+
+
+
+
+ Plan Node ID. An internal ID number that should be
+ unique for every node in the plan tree. It is used to coordinate parallel
+ query activity.
+
+
+
+
+
+ extParam and allParam. Information
+ about which numbered parameters affect this plan node or its children. In
+ text mode, these fields are only displayed if they are non-empty sets.
+
+
+
+
+
+ Once per query, the DEBUG option will display the
+ following fields. See PlannedStmt in
+ nodes/plannodes.h for additional detail.
+
+
+
+
+
+ Command Type. For example, select
+ or update.
+
+
+
+
+
+ Flags. A comma-separated list of Boolean structure
+ member names from the PlannedStmt that are set to
+ true. It covers the following structure members:
+ hasReturning, hasModifyingCTE,
+ canSetTag, transientPlan,
+ dependsOnRole, parallelModeNeeded.
+
+
+
+
+
+ Subplans Needing Rewind. Integer IDs of subplans that
+ may need to be rewound by the executor.
+
+
+
+
+
+ Relation OIDs. OIDs of relations upon which this plan
+ depends.
+
+
+
+
+
+ Executor Parameter Types. Type OID for each executor parameter
+ (e.g. when a nested loop is chosen and a parameter is used to pass a value down
+ to an inner index scan). Does not include parameters supplied to a prepared
+ statement by the user.
+
+
+
+
+
+ Parse Location. Location within the query string
+ supplied to the planner where this query's text can be found. May be
+ Unknown in some contexts. Otherwise, may be
+ NNN to end for some integer NNN or
+ NNN for MMM bytes for some integers
+ NNN and MMM.
+
+
+
+
+
+
+ EXPLAIN (RANGE_TABLE)
+
+
+ The RANGE_TABLE option displays information from the
+ plan tree specifically concerning the query's range table. Range table
+ entries correspond roughly to items appearing in the query's
+ FROM clause, but with numerous exceptions. For example,
+ subqueries that are proved unnecessary may be deleted from the range table
+ entirely, while inheritance expansion adds range table entries for child
+ tables that are not named directly in the query.
+
+
+
+ Range table entries are generally referenced within the query plan by a
+ range table index, or RTI. Plan nodes that reference one or more RTIs will
+ be labelled accordingly, using one of the following fields: Scan
+ RTI, Nominal RTI, Exclude Relation
+ RTI, Append RTIs.
+
+
+
+ In addition, the query as a whole may maintain lists of range table indexes
+ that are needed for various purposes. These lists will be displayed once
+ per query, labelled as appropriate as Unprunable RTIs or
+ Result RTIs. In text mode, these fields are only
+ displayed if they are non-empty sets.
+
+
+
+ Finally, but most importantly, the RANGE_TABLE option
+ will display a dump of the query's entire range table. Each range table
+ entry is labelled with the appropriate range table index, the kind of range
+ table entry (e.g. relation,
+ subquery, or join), followed by the
+ contents of various range table entry fields that are not normally part of
+ EXPLAIN output. Some of these fields are only displayed
+ for certain kinds of range table entries. For example,
+ Eref is displayed for all types of range table entries,
+ but CTE Name is displayed only for range table entries
+ of type cte.
+
+
+
+ For more information about range table entries, see the definition of
+ RangeTblEntry in nodes/plannodes.h.
+
+
+
+
+ Author
+
+
+ Robert Haas rhaas@postgresql.org
+
+
+
+
diff --git a/doc/src/sgml/pgstatstatements.sgml b/doc/src/sgml/pgstatstatements.sgml
index 9b0aff73b1efe..d753de5836efb 100644
--- a/doc/src/sgml/pgstatstatements.sgml
+++ b/doc/src/sgml/pgstatstatements.sgml
@@ -436,6 +436,15 @@
+
+
+ wal_buffers_fullbigint
+
+
+ Number of times the WAL buffers became full
+
+
+
jit_functionsbigint
@@ -527,6 +536,42 @@
+
+
+ parallel_workers_to_launchbigint
+
+
+ Number of parallel workers planned to be launched
+
+
+
+
+
+ parallel_workers_launchedbigint
+
+
+ Number of parallel workers actually launched
+
+
+
+
+
+ generic_plan_callsbigint
+
+
+ Number of times the statement has been executed using a generic plan
+
+
+
+
+
+ custom_plan_callsbigint
+
+
+ Number of times the statement has been executed using a custom plan
+
+
+
stats_sincetimestamp with time zone
@@ -603,9 +648,25 @@
In some cases, queries with visibly different texts might get merged into a
- single pg_stat_statements 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.
+ single pg_stat_statements entry; as explained above,
+ this is expected to happen for semantically equivalent queries.
+ In addition, if the only difference between queries is the number of elements
+ in a list of constants, the list will get squashed down to a single element but shown
+ with a commented-out list indicator:
+
+
+=# SELECT pg_stat_statements_reset();
+=# SELECT * FROM test WHERE a IN (1, 2, 3, 4, 5, 6, 7);
+=# SELECT * FROM test WHERE a IN (1, 2, 3, 4, 5, 6, 7, 8);
+=# SELECT query, calls FROM pg_stat_statements
+ WHERE query LIKE 'SELECT%';
+-[ RECORD 1 ]------------------------------
+query | SELECT * FROM test WHERE a IN ($1 /*, ... */)
+calls | 2
+
+
+ In addition to these cases, 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.)
@@ -630,8 +691,13 @@
things, the internal object identifiers appearing in this representation.
This has some counterintuitive implications. For example,
pg_stat_statements 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.
+ queries to be distinct, if they reference for example a function that was
+ dropped and recreated between the executions of the two queries.
+ Conversely, if a table is dropped and recreated between the
+ executions of queries, two apparently-identical queries may be
+ considered the same. However, if the alias for a table is different
+ for otherwise-similar queries, these queries will be considered
+ distinct.
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 queryid
diff --git a/doc/src/sgml/pgstattuple.sgml b/doc/src/sgml/pgstattuple.sgml
index 4071da4ed941a..c747a5818ab7d 100644
--- a/doc/src/sgml/pgstattuple.sgml
+++ b/doc/src/sgml/pgstattuple.sgml
@@ -270,6 +270,15 @@ leaf_fragmentation | 0
page than is accounted for by internal_pages + leaf_pages +
empty_pages + deleted_pages, because it also includes the
index's metapage.
+ avg_leaf_density is the fraction of the index size that
+ is taken up by user data. Since indexes have a default fillfactor of 90,
+ this should be around 90 for newly built indexes of non-negligible size,
+ but usually deteriorates over time.
+ leaf_fragmentation represents a measure of disorder.
+ A higher leaf_fragmentation indicates that the
+ physical order of the index leaf pages increasingly deviates from their
+ logical order. This can have a significant impact if a large part
+ of the index is read from disk.
diff --git a/doc/src/sgml/pgwalinspect.sgml b/doc/src/sgml/pgwalinspect.sgml
index 3a8121c70f1f1..79c3ead40bc71 100644
--- a/doc/src/sgml/pgwalinspect.sgml
+++ b/doc/src/sgml/pgwalinspect.sgml
@@ -73,9 +73,9 @@
postgres=# SELECT * FROM pg_get_wal_record_info('0/E419E28');
-[ RECORD 1 ]----+-------------------------------------------------
-start_lsn | 0/E419E28
-end_lsn | 0/E419E68
-prev_lsn | 0/E419D78
+start_lsn | 0/0E419E28
+end_lsn | 0/0E419E68
+prev_lsn | 0/0E419D78
xid | 0
resource_manager | Heap2
record_type | VACUUM
@@ -146,9 +146,9 @@ block_ref |
postgres=# SELECT * FROM pg_get_wal_block_info('0/1230278', '0/12302B8');
-[ RECORD 1 ]-----+-----------------------------------
-start_lsn | 0/1230278
-end_lsn | 0/12302B8
-prev_lsn | 0/122FD40
+start_lsn | 0/01230278
+end_lsn | 0/012302B8
+prev_lsn | 0/0122FD40
block_id | 0
reltablespace | 1663
reldatabase | 1
diff --git a/doc/src/sgml/planstats.sgml b/doc/src/sgml/planstats.sgml
index c7ec749d0a601..068b804a18d70 100644
--- a/doc/src/sgml/planstats.sgml
+++ b/doc/src/sgml/planstats.sgml
@@ -489,10 +489,10 @@ SELECT relpages, reltuples FROM pg_class WHERE relname = 't';
condition on the a column:
-EXPLAIN (ANALYZE, TIMING OFF) SELECT * FROM t WHERE a = 1;
+EXPLAIN (ANALYZE, TIMING OFF, BUFFERS OFF) SELECT * FROM t WHERE a = 1;
QUERY PLAN
-------------------------------------------------------------------&zwsp;------------
- Seq Scan on t (cost=0.00..170.00 rows=100 width=8) (actual rows=100 loops=1)
+ Seq Scan on t (cost=0.00..170.00 rows=100 width=8) (actual rows=100.00 loops=1)
Filter: (a = 1)
Rows Removed by Filter: 9900
@@ -506,10 +506,10 @@ EXPLAIN (ANALYZE, TIMING OFF) SELECT * FROM t WHERE a = 1;
condition on both columns, combining them with AND:
-EXPLAIN (ANALYZE, TIMING OFF) SELECT * FROM t WHERE a = 1 AND b = 1;
+EXPLAIN (ANALYZE, TIMING OFF, BUFFERS OFF) SELECT * FROM t WHERE a = 1 AND b = 1;
QUERY PLAN
-------------------------------------------------------------------&zwsp;----------
- Seq Scan on t (cost=0.00..195.00 rows=1 width=8) (actual rows=100 loops=1)
+ Seq Scan on t (cost=0.00..195.00 rows=1 width=8) (actual rows=100.00 loops=1)
Filter: ((a = 1) AND (b = 1))
Rows Removed by Filter: 9900
@@ -530,10 +530,10 @@ EXPLAIN (ANALYZE, TIMING OFF) SELECT * FROM t WHERE a = 1 AND b = 1;
CREATE STATISTICS stts (dependencies) ON a, b FROM t;
ANALYZE t;
-EXPLAIN (ANALYZE, TIMING OFF) SELECT * FROM t WHERE a = 1 AND b = 1;
+EXPLAIN (ANALYZE, TIMING OFF, BUFFERS OFF) SELECT * FROM t WHERE a = 1 AND b = 1;
QUERY PLAN
-------------------------------------------------------------------&zwsp;------------
- Seq Scan on t (cost=0.00..195.00 rows=100 width=8) (actual rows=100 loops=1)
+ Seq Scan on t (cost=0.00..195.00 rows=100 width=8) (actual rows=100.00 loops=1)
Filter: ((a = 1) AND (b = 1))
Rows Removed by Filter: 9900
@@ -551,23 +551,23 @@ EXPLAIN (ANALYZE, TIMING OFF) SELECT * FROM t WHERE a = 1 AND b = 1;
estimated number of rows returned by the HashAggregate node) is very
accurate:
-EXPLAIN (ANALYZE, TIMING OFF) SELECT COUNT(*) FROM t GROUP BY a;
+EXPLAIN (ANALYZE, TIMING OFF, BUFFERS OFF) SELECT COUNT(*) FROM t GROUP BY a;
QUERY PLAN
-------------------------------------------------------------------&zwsp;----------------------
- HashAggregate (cost=195.00..196.00 rows=100 width=12) (actual rows=100 loops=1)
+ HashAggregate (cost=195.00..196.00 rows=100 width=12) (actual rows=100.00 loops=1)
Group Key: a
- -> Seq Scan on t (cost=0.00..145.00 rows=10000 width=4) (actual rows=10000 loops=1)
+ -> Seq Scan on t (cost=0.00..145.00 rows=10000 width=4) (actual rows=10000.00 loops=1)
But without multivariate statistics, the estimate for the number of
groups in a query with two columns in GROUP BY, as
in the following example, is off by an order of magnitude:
-EXPLAIN (ANALYZE, TIMING OFF) SELECT COUNT(*) FROM t GROUP BY a, b;
+EXPLAIN (ANALYZE, TIMING OFF, BUFFERS OFF) SELECT COUNT(*) FROM t GROUP BY a, b;
QUERY PLAN
-------------------------------------------------------------------&zwsp;-------------------------
- HashAggregate (cost=220.00..230.00 rows=1000 width=16) (actual rows=100 loops=1)
+ HashAggregate (cost=220.00..230.00 rows=1000 width=16) (actual rows=100.00 loops=1)
Group Key: a, b
- -> Seq Scan on t (cost=0.00..145.00 rows=10000 width=8) (actual rows=10000 loops=1)
+ -> Seq Scan on t (cost=0.00..145.00 rows=10000 width=8) (actual rows=10000.00 loops=1)
By redefining the statistics object to include n-distinct counts for the
two columns, the estimate is much improved:
@@ -575,12 +575,12 @@ EXPLAIN (ANALYZE, TIMING OFF) SELECT COUNT(*) FROM t GROUP BY a, b;
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;
+EXPLAIN (ANALYZE, TIMING OFF, BUFFERS OFF) SELECT COUNT(*) FROM t GROUP BY a, b;
QUERY PLAN
-------------------------------------------------------------------&zwsp;-------------------------
- HashAggregate (cost=220.00..221.00 rows=100 width=16) (actual rows=100 loops=1)
+ HashAggregate (cost=220.00..221.00 rows=100 width=16) (actual rows=100.00 loops=1)
Group Key: a, b
- -> Seq Scan on t (cost=0.00..145.00 rows=10000 width=8) (actual rows=10000 loops=1)
+ -> Seq Scan on t (cost=0.00..145.00 rows=10000 width=8) (actual rows=10000.00 loops=1)
@@ -615,10 +615,10 @@ EXPLAIN (ANALYZE, TIMING OFF) SELECT COUNT(*) FROM t GROUP BY a, b;
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;
+EXPLAIN (ANALYZE, TIMING OFF, BUFFERS OFF) SELECT * FROM t WHERE a = 1 AND b = 1;
QUERY PLAN
-------------------------------------------------------------------&zwsp;------------
- Seq Scan on t (cost=0.00..195.00 rows=100 width=8) (actual rows=100 loops=1)
+ Seq Scan on t (cost=0.00..195.00 rows=100 width=8) (actual rows=100.00 loops=1)
Filter: ((a = 1) AND (b = 1))
Rows Removed by Filter: 9900
@@ -672,10 +672,10 @@ SELECT m.* FROM pg_statistic_ext join pg_statistic_ext_data on (oid = stxoid),
to decide which combinations are compatible.
-EXPLAIN (ANALYZE, TIMING OFF) SELECT * FROM t WHERE a = 1 AND b = 10;
+EXPLAIN (ANALYZE, TIMING OFF, BUFFERS OFF) SELECT * FROM t WHERE a = 1 AND b = 10;
QUERY PLAN
-------------------------------------------------------------------&zwsp;--------
- Seq Scan on t (cost=0.00..195.00 rows=1 width=8) (actual rows=0 loops=1)
+ Seq Scan on t (cost=0.00..195.00 rows=1 width=8) (actual rows=0.00 loops=1)
Filter: ((a = 1) AND (b = 10))
Rows Removed by Filter: 10000
@@ -685,10 +685,10 @@ EXPLAIN (ANALYZE, TIMING OFF) SELECT * FROM t WHERE a = 1 AND b = 10;
consider the following range query for the same table:
-EXPLAIN (ANALYZE, TIMING OFF) SELECT * FROM t WHERE a <= 49 AND b > 49;
+EXPLAIN (ANALYZE, TIMING OFF, BUFFERS OFF) SELECT * FROM t WHERE a <= 49 AND b > 49;
QUERY PLAN
-------------------------------------------------------------------&zwsp;--------
- Seq Scan on t (cost=0.00..195.00 rows=1 width=8) (actual rows=0 loops=1)
+ Seq Scan on t (cost=0.00..195.00 rows=1 width=8) (actual rows=0.00 loops=1)
Filter: ((a <= 49) AND (b > 49))
Rows Removed by Filter: 10000
@@ -729,6 +729,9 @@ EXPLAIN (ANALYZE, TIMING OFF) SELECT * FROM t WHERE a <= 49 AND b > 49;
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.
+ The program's
+ \do+
+ meta-command is useful to determine which operators are marked as leakproof.
@@ -737,7 +740,7 @@ EXPLAIN (ANALYZE, TIMING OFF) SELECT * FROM t WHERE a <= 49 AND b > 49;
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
+ inaccessible to the user. In that case, the operator should be leakproof
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,
diff --git a/doc/src/sgml/plperl.sgml b/doc/src/sgml/plperl.sgml
index 25b1077ad7382..8007261d0224c 100644
--- a/doc/src/sgml/plperl.sgml
+++ b/doc/src/sgml/plperl.sgml
@@ -1093,6 +1093,19 @@ $$ LANGUAGE plperl;
be permitted to use this language.
+
+
+ Trusted PL/Perl relies on the Perl Opcode module to
+ preserve security.
+ Perl
+ documents
+ that the module is not effective for the trusted PL/Perl use case. If
+ your security needs are incompatible with the uncertainty in that warning,
+ consider executing REVOKE USAGE ON LANGUAGE plperl FROM
+ PUBLIC.
+
+
+
Here is an example of a function that will not work because file
system operations are not allowed for security reasons:
diff --git a/doc/src/sgml/plpgsql.sgml b/doc/src/sgml/plpgsql.sgml
index 6f880b705f88d..e937491e6b89e 100644
--- a/doc/src/sgml/plpgsql.sgml
+++ b/doc/src/sgml/plpgsql.sgml
@@ -1295,7 +1295,7 @@ $$ LANGUAGE plpgsql;
On failure, this function might produce an error message such as
ERROR: query returned no rows
-DETAIL: parameters: $1 = 'nosuchuser'
+DETAIL: parameters: username = 'nosuchuser'
CONTEXT: PL/pgSQL function get_userid(text) line 6 at SQL statement
@@ -3317,7 +3317,7 @@ OPEN curs1 FOR EXECUTE format('SELECT * FROM %I WHERE col1 = $1',tabname) USING
Opening a Bound Cursor
-OPEN bound_cursorvar ( argument_name := argument_value, ... ) ;
+OPEN bound_cursorvar ( argument_name { := | => } argument_value, ... ) ;
@@ -3340,7 +3340,8 @@ OPEN bound_cursorvar ( positional
or named notation. In positional
notation, all arguments are specified in order. In named notation,
- each argument's name is specified using := to
+ each argument's name is specified using :=
+ or => to
separate it from the argument expression. Similar to calling
functions, described in , it
is also allowed to mix positional and named notation.
@@ -3352,6 +3353,7 @@ OPEN bound_cursorvar (
@@ -3409,13 +3411,16 @@ FETCH direction { FROM | IN }
- FETCH retrieves the next row from the
+ FETCH retrieves the next row (in the indicated
+ direction) 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
- SELECT INTO. If there is no next row, the
+ SELECT INTO. If there is no suitable row, the
target is set to NULL(s). As with SELECT
INTO, the special variable FOUND can
- be checked to see whether a row was obtained or not.
+ be checked to see whether a row was obtained or not. If no row is
+ obtained, the cursor is positioned after the last row or before the
+ first row, depending on the movement direction.
@@ -3467,11 +3472,25 @@ MOVE direction { FROM | IN } <
MOVE repositions a cursor without retrieving
- any data. MOVE works exactly like the
+ any data. MOVE works like the
FETCH command, except it only repositions the
- cursor and does not return the row moved to. As with SELECT
+ cursor and does not return the row moved to.
+ The direction clause can be any of the
+ variants allowed in the SQL
+ command, including those that can fetch more than one row;
+ the cursor is positioned to the last such row.
+ (However, the case in which the direction
+ clause is simply a count expression with
+ no key word is deprecated in PL/pgSQL.
+ That syntax is ambiguous with the case where
+ the direction clause is omitted
+ altogether, and hence it may fail if
+ the count is not a constant.)
+ As with SELECT
INTO, the special variable FOUND can
- be checked to see whether there was a next row to move to.
+ be checked to see whether there was a row to move to. If there is no
+ such row, the cursor is positioned after the last row or before the
+ first row, depending on the movement direction.
@@ -3655,7 +3674,7 @@ COMMIT;
<<label>>
-FOR recordvar IN bound_cursorvar ( argument_name := argument_value, ... ) LOOP
+FOR recordvar IN bound_cursorvar ( argument_name { := | => } argument_value, ... ) LOOP
statements
END LOOP label;
@@ -3745,6 +3764,17 @@ CALL transaction_test1();
SELECT in between.
+
+ PL/pgSQL does not support savepoints
+ (SAVEPOINT/ROLLBACK TO
+ SAVEPOINT/RELEASE SAVEPOINT commands).
+ Typical usage patterns for savepoints can be replaced by blocks with
+ exception handlers (see ).
+ Under the hood, a block with exception handlers forms a
+ subtransaction, which means that transactions cannot be ended inside
+ such a block.
+
+
Special considerations apply to cursor loops. Consider this example:
@@ -3770,7 +3800,10 @@ CALL transaction_test2();
evaluated at the first COMMIT or
ROLLBACK rather than row by row. The cursor is still
removed automatically after the loop, so this is mostly invisible to the
- user.
+ user. But one must keep in mind that any table or row locks taken by
+ the cursor's query will no longer be held after the
+ first COMMIT or
+ ROLLBACK.
@@ -3778,10 +3811,6 @@ CALL transaction_test2();
that are not read-only (for example UPDATE
... RETURNING).
-
-
- A transaction cannot be ended inside a block with exception handlers.
-
@@ -3805,10 +3834,10 @@ CALL transaction_test2();
raise errors.
-RAISE level 'format' , expression, ... USING option = expression, ... ;
-RAISE levelcondition_name USING option = expression, ... ;
-RAISE level SQLSTATE 'sqlstate' USING option = expression, ... ;
-RAISE level USING option = expression, ... ;
+RAISE level 'format' , expression, ... USING option { = | := } expression, ... ;
+RAISE levelcondition_name USING option { = | := } expression, ... ;
+RAISE level SQLSTATE 'sqlstate' USING option { = | := } expression, ... ;
+RAISE level USING option { = | := } expression, ... ;
RAISE ;
@@ -3830,8 +3859,9 @@ RAISE ;
- After level if any,
- you can specify a format string
+ In the first syntax variant,
+ after the level if any,
+ write a format 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
@@ -3853,7 +3883,27 @@ RAISE NOTICE 'Calling cs_create_job(%)', v_job_id;
- You can attach additional information to the error report by writing
+ In the second and third syntax variants,
+ condition_name and
+ sqlstate specify an
+ error condition name or a five-character SQLSTATE code, respectively.
+ See for the valid error condition
+ names and the predefined SQLSTATE codes.
+
+
+
+ Here are examples
+ of condition_name
+ and sqlstate usage:
+
+RAISE division_by_zero;
+RAISE WARNING SQLSTATE '22012';
+
+
+
+
+ In any of these syntax variants,
+ you can attach additional information to the error report by writing
USING followed by option = expression items. Each
@@ -3866,8 +3916,7 @@ RAISE NOTICE 'Calling cs_create_job(%)', v_job_id;
MESSAGESets the error message text. This option can't be used in the
- form of RAISE that includes a format string
- before USING.
+ first syntax variant, since the message is already supplied.
@@ -3890,7 +3939,9 @@ RAISE NOTICE 'Calling cs_create_job(%)', v_job_id;
Specifies the error code (SQLSTATE) to report, either by condition
name, as shown in , or directly as a
- five-character SQLSTATE code.
+ five-character SQLSTATE code. This option can't be used in the
+ second or third syntax variant, since the error code is already
+ supplied.
@@ -3922,25 +3973,15 @@ RAISE EXCEPTION 'Nonexistent ID --> %', user_id
RAISE 'Duplicate user ID: %', user_id USING ERRCODE = 'unique_violation';
RAISE 'Duplicate user ID: %', user_id USING ERRCODE = '23505';
-
-
-
- There is a second RAISE syntax in which the main argument
- is the condition name or SQLSTATE to be reported, for example:
-
-RAISE division_by_zero;
-RAISE SQLSTATE '22012';
-
- In this syntax, USING can be used to supply a custom
- error message, detail, or hint. Another way to do the earlier
- example is
+ Another way to produce the same result is:
RAISE unique_violation USING MESSAGE = 'Duplicate user ID: ' || user_id;
- Still another variant is to write RAISE USING or RAISE
+ As shown in the fourth syntax variant, it is also possible to
+ write RAISE USING or RAISE
level USING and put
everything else into the USING list.
diff --git a/doc/src/sgml/plpython.sgml b/doc/src/sgml/plpython.sgml
index e5d51d6e9f5a4..27c4467ba7da3 100644
--- a/doc/src/sgml/plpython.sgml
+++ b/doc/src/sgml/plpython.sgml
@@ -1,6 +1,6 @@
-
+PL/Python — Python Procedural LanguagePL/Python
@@ -553,7 +553,7 @@ $$ LANGUAGE plpython3u;
Iterator (any object providing __iter__ and
- next methods)
+ __next__ methods)
@@ -569,7 +569,7 @@ AS $$
def __iter__ (self):
return self
- def next (self):
+ def __next__(self):
self.ndx += 1
if self.ndx == len(self.who):
raise StopIteration
@@ -662,6 +662,14 @@ $$ LANGUAGE plpython3u;
in PL/Python
+
+ PL/Python can be used to define trigger
+ functions.
+ PostgreSQL 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 trigger.
+
+
When a function is used as a trigger, the dictionary
TD contains trigger-related values:
@@ -769,6 +777,74 @@ $$ LANGUAGE plpython3u;
+
+ Event Trigger Functions
+
+
+ event trigger
+ in PL/Python
+
+
+
+ PL/Python can be used to define event triggers
+ (see also ).
+ PostgreSQL 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 event_trigger.
+
+
+
+ When a function is used as an event trigger, the dictionary
+ TD contains trigger-related values:
+
+
+
+ TD["event"]
+
+
+ The event the trigger was fired for, as a string, for example
+ ddl_command_start.
+
+
+
+
+
+ TD["tag"]
+
+
+ The command tag for which the trigger was fired, as a string, for
+ example DROP TABLE.
+
+
+
+
+
+
+
+ shows an example of an
+ event trigger function in PL/Python.
+
+
+
+ A <application>PL/Python</application> Event Trigger Function
+
+
+ This example trigger simply raises a NOTICE message
+ each time a supported command is executed.
+
+
+
+CREATE OR REPLACE FUNCTION pysnitch() RETURNS event_trigger
+LANGUAGE plpython3u
+AS $$
+ plpy.notice("TD[event] => " + TD["event"] + " ; TD[tag] => " + TD["tag"]);
+$$;
+
+CREATE EVENT TRIGGER pysnitch ON ddl_command_start EXECUTE FUNCTION pysnitch();
+
+
+
+
Database Access
diff --git a/doc/src/sgml/pltcl.sgml b/doc/src/sgml/pltcl.sgml
index b31f2c1330f5e..5a8e4c9d37e99 100644
--- a/doc/src/sgml/pltcl.sgml
+++ b/doc/src/sgml/pltcl.sgml
@@ -1120,16 +1120,25 @@ CALL transaction_test1();
In PostgreSQL, the same function name can be used for
- different function definitions as long as the number of arguments or their types
+ different function definitions if the functions are placed in different
+ schemas, or if 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 pg_proc as part of their name. Thus,
+ PL/Tcl deals with this by including the argument type names in the
+ internal Tcl procedure name, and then appending the function's object
+ ID (OID) to the internal Tcl procedure name if necessary to make it
+ different from the names of all previously-loaded functions in the
+ same Tcl interpreter. Thus,
PostgreSQL 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.
+
+ For this reason among others, a PL/Tcl function cannot call another one
+ directly (that is, within Tcl). If you need to do that, you must go
+ through SQL, using spi_exec or a related command.
+
+
diff --git a/doc/src/sgml/postgres-fdw.sgml b/doc/src/sgml/postgres-fdw.sgml
index 1a600382e2e77..781a01067f7d6 100644
--- a/doc/src/sgml/postgres-fdw.sgml
+++ b/doc/src/sgml/postgres-fdw.sgml
@@ -194,7 +194,9 @@ OPTIONS (ADD password_required 'false');
user can potentially use any client certificates,
.pgpass,
.pg_service.conf etc. in the unix home directory of the
- system user the postgres server runs as. They can also use any trust
+ system user the postgres server runs as. (For details on how home
+ directories are found, see .) They can
+ also use any trust
relationship granted by authentication modes like peer
or ident authentication.
@@ -754,7 +756,7 @@ OPTIONS (ADD password_required 'false');
-
+ keep_connections (boolean)
@@ -768,6 +770,73 @@ OPTIONS (ADD password_required 'false');
+
+ use_scram_passthrough (boolean)
+
+
+ This option controls whether postgres_fdw will
+ use the SCRAM pass-through authentication to connect to the foreign
+ server. With SCRAM pass-through authentication,
+ postgres_fdw uses SCRAM-hashed secrets instead of
+ plain-text user passwords to connect to the remote server. This
+ avoids storing plain-text user passwords in PostgreSQL system
+ catalogs.
+
+
+
+ To use SCRAM pass-through authentication:
+
+
+
+ The remote server must request the scram-sha-256
+ authentication method; otherwise, the connection will fail.
+
+
+
+
+
+ The remote server can be of any PostgreSQL version that supports
+ SCRAM. Support for use_scram_passthrough is
+ only required on the client side (FDW side).
+
+
+
+
+
+ The user mapping password is not used.
+
+
+
+
+
+ The server running postgres_fdw and the remote
+ server must have identical SCRAM secrets (encrypted passwords) for
+ the user being used on postgres_fdw to
+ authenticate on the foreign server (same salt and iterations, not
+ merely the same password).
+
+
+
+ As a corollary, if FDW connections to multiple hosts are to be
+ made, for example for partitioned foreign tables/sharding, then all
+ hosts must have identical SCRAM secrets for the users involved.
+
+
+
+
+
+ The current session on the PostgreSQL instance that makes the
+ outgoing FDW connections also must also use SCRAM authentication
+ for its incoming client connection. (Hence
+ pass-through: SCRAM must be used going in and out.)
+ This is a technical requirement of the SCRAM protocol.
+
+
+
+
+
+
+
@@ -777,29 +846,121 @@ OPTIONS (ADD password_required 'false');
- postgres_fdw_get_connections(OUT server_name text, OUT valid boolean) returns setof record
+ postgres_fdw_get_connections(
+ IN check_conn boolean DEFAULT false, OUT server_name text,
+ OUT user_name text, OUT valid boolean, OUT used_in_xact boolean,
+ OUT closed boolean, OUT remote_backend_pid int4)
+ returns setof record
- This function returns the foreign server names of all the open
- connections that postgres_fdw established from
- the local session to the foreign servers. It also returns whether
- each connection is valid or not. false 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
- NULL if the server is dropped),
- and then such invalid connection will be closed at
- the end of that transaction. true is returned
- otherwise. If there are no open connections, no record is returned.
+ This function returns information about all open connections postgres_fdw
+ has established from the local session to foreign servers. If there are
+ no open connections, no records are returned.
+
+
+ If check_conn is set to true,
+ the function checks the status of each connection and shows
+ the result in the closed column.
+ This feature is currently available only on systems that support
+ the non-standard POLLRDHUP extension to
+ the poll system call, including Linux.
+ This is useful to check if all connections used within
+ a transaction are still open. If any connections are closed,
+ the transaction cannot be committed successfully,
+ so it is better to roll back as soon as a closed connection is detected,
+ rather than continuing to the end. Users can roll back the transaction
+ immediately if the function reports connections where both
+ used_in_xact and closed are
+ true.
+
+
Example usage of the function:
-postgres=# SELECT * FROM postgres_fdw_get_connections() ORDER BY 1;
- server_name | valid
--------------+-------
- loopback1 | t
- loopback2 | f
+postgres=# SELECT * FROM postgres_fdw_get_connections(true);
+ server_name | user_name | valid | used_in_xact | closed | remote_backend_pid
+-------------+-----------+-------+--------------+-----------------------------
+ loopback1 | postgres | t | t | f | 1353340
+ loopback2 | public | t | t | f | 1353120
+ loopback3 | | f | t | f | 1353156
+ The output columns are described in
+ .
+
+
+ <function>postgres_fdw_get_connections</function> Output Columns
+
+
+
+ Column
+ Type
+ Description
+
+
+
+
+
+ server_name
+ text
+
+ The foreign server name of this connection. If the server is
+ dropped but the connection remains open (i.e., marked as
+ invalid), this will be NULL.
+
+
+
+ user_name
+ text
+
+ Name of the local user mapped to the foreign server of this
+ connection, or public if a public mapping is used.
+ If the user mapping is dropped but the connection remains open
+ (i.e., marked as invalid), this will be NULL.
+
+
+
+ valid
+ boolean
+
+ False if this connection is invalid, meaning it is used in
+ the current transaction, but its foreign server or
+ user mapping has been changed or dropped.
+ The invalid connection will be closed at the end of
+ the transaction. True is returned otherwise.
+
+
+
+ used_in_xact
+ boolean
+
+ True if this connection is used in the current transaction.
+
+
+
+ closed
+ boolean
+
+ True if this connection is closed, false otherwise.
+ NULL is returned if check_conn
+ is set to false or if the connection status check
+ is not available on this platform.
+
+
+
+ remote_backend_pid
+ int4
+
+ Process ID of the remote backend, on the foreign server,
+ handling the connection. If the remote backend is terminated and
+ the connection is closed (with closed set to
+ true), this still shows the process ID of
+ the terminated backend.
+
+
+
+
+
+
@@ -1028,7 +1189,10 @@ postgres=# SELECT postgres_fdw_disconnect_all();
postgres_fdw can be used with remote servers dating back
to PostgreSQL 8.3. Read-only capability is available
- back to 8.1. A limitation however is that postgres_fdw
+ back to 8.1.
+
+
+ A limitation however is that postgres_fdw
generally assumes that immutable built-in functions and operators are
safe to send to the remote server for execution, if they appear in a
WHERE clause for a foreign table. Thus, a built-in
@@ -1040,6 +1204,13 @@ postgres=# SELECT postgres_fdw_disconnect_all();
optimization fence, and placing the problematic function or operator
outside the sub-SELECT.
+
+ Another limitation is that when executing INSERT
+ statements with an ON CONFLICT DO NOTHING clause on
+ a foreign table, the remote server must be running
+ PostgreSQL 9.5 or later,
+ as earlier versions do not support this feature.
+
diff --git a/doc/src/sgml/postgres.sgml b/doc/src/sgml/postgres.sgml
index ec9f90e283e5f..af476c82fcc1e 100644
--- a/doc/src/sgml/postgres.sgml
+++ b/doc/src/sgml/postgres.sgml
@@ -9,6 +9,7 @@
%filelist;
+
Errors detected at semantic analysis or later, such as a misspelled
table or column name, do not have this effect.
+
+
+ Lastly, note that all the statements within the Query message will
+ observe the same value of statement_timestamp(),
+ since that timestamp is updated only upon receipt of the Query
+ message. This will result in them all observing the same
+ value of transaction_timestamp() as well,
+ except in cases where the query string ends a previously-started
+ transaction and begins a new one.
+
@@ -1070,16 +1171,17 @@ SELCT 1/0;
If the client has not issued an explicit BEGIN,
- then each Sync ordinarily causes an implicit COMMIT
- if the preceding step(s) succeeded, or an
- implicit ROLLBACK if they failed. However, there
- are a few DDL commands (such as CREATE DATABASE)
- 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.
+ then an implicit transaction block is started and each Sync ordinarily
+ causes an implicit COMMIT if the preceding step(s)
+ succeeded, or an implicit ROLLBACK if they failed.
+ This implicit transaction block will only be detected by the server
+ when the first command ends without a sync. There are a few DDL
+ commands (such as CREATE DATABASE) 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 after a Sync.
+ 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.
@@ -1325,6 +1427,7 @@ SELCT 1/0;
IntervalStyleis_superuserscram_iterations
+ search_pathserver_encodingserver_versionsession_authorization
@@ -1334,7 +1437,8 @@ SELCT 1/0;
(default_transaction_read_only and
in_hot_standby were not reported by releases before
14; scram_iterations was not reported by releases
- before 16.)
+ before 16; search_path was not reported by releases
+ before 18.)
Note that
server_version,
server_encoding and
@@ -1506,10 +1610,10 @@ SELCT 1/0;
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 SSL support
- to PostgreSQL. (Such servers are now very ancient,
- and likely do not exist in the wild anymore.)
+ response to SSLRequest from the server. The frontend should not display
+ this error message to the user/application, since the server has not been
+ authenticated
+ (CVE-2024-10977).
In this case the connection must
be closed, but the frontend might choose to open a fresh connection
and proceed without requesting SSL.
@@ -1619,12 +1723,13 @@ SELCT 1/0;
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 GSSAPI encryption
- support to PostgreSQL. In this case the
- connection must be closed, but the frontend might choose to open a fresh
- connection and proceed without requesting GSSAPI
- encryption.
+ response to GSSENCRequest from the server. The frontend should not display
+ this error message to the user/application, since the server has not been
+ authenticated
+ (CVE-2024-10977).
+ In this case the connection must be closed, but the frontend might choose
+ to open a fresh connection and proceed without requesting
+ GSSAPI encryption.
@@ -1676,11 +1781,11 @@ SELCT 1/0;
SASL is a framework for authentication in connection-oriented
- protocols. At the moment, PostgreSQL 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.
+ protocols. At the moment, PostgreSQL implements three
+ SASL authentication mechanisms: SCRAM-SHA-256, SCRAM-SHA-256-PLUS, and
+ OAUTHBEARER. More might be added in the future. The below steps illustrate how SASL
+ authentication is performed in general, while the next subsections give
+ more details on particular mechanisms.
@@ -1715,7 +1820,7 @@ SELCT 1/0;
Finally, when the authentication exchange is completed successfully, the
- server sends an AuthenticationSASLFinal message, followed
+ server sends an optional 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
@@ -1734,9 +1839,9 @@ SELCT 1/0;
SCRAM-SHA-256 Authentication
- The implemented SASL mechanisms at the moment
- are SCRAM-SHA-256 and its variant with channel
- binding SCRAM-SHA-256-PLUS. They are described in
+ SCRAM-SHA-256, and its variant with channel
+ binding SCRAM-SHA-256-PLUS, are password-based
+ authentication mechanisms. They are described in
detail in RFC 7677
and RFC 5802.
@@ -1838,6 +1943,121 @@ SELCT 1/0;
+
+
+ OAUTHBEARER Authentication
+
+
+ OAUTHBEARER is a token-based mechanism for federated
+ authentication. It is described in detail in
+ RFC 7628.
+
+
+
+ A typical exchange differs depending on whether or not the client already
+ has a bearer token cached for the current user. If it does not, the exchange
+ will take place over two connections: the first "discovery" connection to
+ obtain OAuth metadata from the server, and the second connection to send
+ the token after the client has obtained it. (libpq does not currently
+ implement a caching method as part of its builtin flow, so it uses the
+ two-connection exchange.)
+
+
+
+ This mechanism is client-initiated, like SCRAM. The client initial response
+ consists of the standard "GS2" header used by SCRAM, followed by a list of
+ key=value pairs. The only key currently supported by
+ the server is auth, which contains the bearer token.
+ OAUTHBEARER additionally specifies three optional
+ components of the client initial response (the authzid of
+ the GS2 header, and the host and
+ port keys) which are currently ignored by the
+ server.
+
+
+
+ OAUTHBEARER does not support channel binding, and there
+ is no "OAUTHBEARER-PLUS" mechanism. This mechanism does not make use of
+ server data during a successful authentication, so the
+ AuthenticationSASLFinal message is not used in the exchange.
+
+
+
+ Example
+
+
+ During the first exchange, the server sends an AuthenticationSASL message
+ with the OAUTHBEARER mechanism advertised.
+
+
+
+
+
+ The client responds by sending a SASLInitialResponse message which
+ indicates the OAUTHBEARER mechanism. Assuming the
+ client does not already have a valid bearer token for the current user,
+ the auth field is empty, indicating a discovery
+ connection.
+
+
+
+
+
+ Server sends an AuthenticationSASLContinue message containing an error
+ status alongside a well-known URI and scopes that the
+ client should use to conduct an OAuth flow.
+
+
+
+
+
+ Client sends a SASLResponse message containing the empty set (a single
+ 0x01 byte) to finish its half of the discovery
+ exchange.
+
+
+
+
+
+ Server sends an ErrorMessage to fail the first exchange.
+
+
+ At this point, the client conducts one of many possible OAuth flows to
+ obtain a bearer token, using any metadata that it has been configured with
+ in addition to that provided by the server. (This description is left
+ deliberately vague; OAUTHBEARER does not specify or
+ mandate any particular method for obtaining a token.)
+
+
+ Once it has a token, the client reconnects to the server for the final
+ exchange:
+
+
+
+
+
+ The server once again sends an AuthenticationSASL message with the
+ OAUTHBEARER mechanism advertised.
+
+
+
+
+
+ The client responds by sending a SASLInitialResponse message, but this
+ time the auth field in the message contains the
+ bearer token that was obtained during the client flow.
+
+
+
+
+
+ The server validates the token according to the instructions of the
+ token provider. If the client is authorized to connect, it sends an
+ AuthenticationOk message to end the SASL exchange.
+
+
+
+
@@ -2020,6 +2240,8 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;"
The name of the slot to create. Must be a valid replication slot
name (see ).
+ The name cannot be pg_conflict_detection as it
+ is reserved for the conflict detection.
@@ -2192,7 +2414,23 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;"
- The following option is supported:
+ The following options are supported:
+
+
+
+ TWO_PHASE [ boolean ]
+
+
+ If true, this logical replication slot supports decoding of two-phase
+ commit. With this option, commands related to two-phase commit such as
+ PREPARE TRANSACTION, COMMIT PREPARED
+ and ROLLBACK PREPARED are decoded and transmitted.
+ The transaction will be decoded and transmitted at
+ PREPARE TRANSACTION time.
+
+
+
+
@@ -2317,8 +2555,8 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;"
-
- XLogData (B)
+
+ WALData (B)
@@ -2366,11 +2604,11 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;"
- A single WAL record is never split across two XLogData messages.
+ A single WAL record is never split across two WALData 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.
+ continuation records can be sent in different WALData messages.
@@ -2422,6 +2660,65 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;"
+
+
+ Primary status update (B)
+
+
+
+ Byte1('s')
+
+
+ Identifies the message as a primary status update.
+
+
+
+
+
+ Int64
+
+
+ The latest WAL write position on the server.
+
+
+
+
+
+ Int64
+
+
+ The oldest transaction ID that is currently in the commit phase on
+ the server, along with its epoch. The most significant 32 bits are
+ the epoch. The least significant 32 bits are the transaction ID.
+ If no transactions are active on the server, this number will be
+ the next transaction ID to be assigned.
+
+
+
+
+
+ Int64
+
+
+ The next transaction ID to be assigned on the server, along with
+ its epoch. The most significant 32 bits are the epoch. The least
+ significant 32 bits are the transaction ID.
+
+
+
+
+
+ Int64
+
+
+ The server's system clock at the time of transmission, as
+ microseconds since midnight on 2000-01-01.
+
+
+
+
+
+
@@ -2566,6 +2863,33 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;"
+
+
+ Request primary status update (F)
+
+
+
+ Byte1('p')
+
+
+ Identifies the message as a request for a primary status update.
+
+
+
+
+
+ Int64
+
+
+ The client's system clock at the time of transmission, as
+ microseconds since midnight on 2000-01-01.
+
+
+
+
+
+
+
@@ -2631,7 +2955,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;"
The name of an option passed to the slot's logical decoding output
- plugin. See for
+ plugin. See for
options that are accepted by the standard (pgoutput)
plugin.
@@ -2659,8 +2983,6 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;"
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.
@@ -3201,127 +3523,15 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;"
the physical streaming replication protocol.
-
- PostgreSQL logical decoding supports output
- plugins. pgoutput is the standard one used for
- the built-in logical replication.
-
-
Logical Streaming Replication Parameters
- Using the START_REPLICATION command,
- pgoutput accepts the following options:
-
-
-
-
- proto_version
-
-
-
- Protocol version. Currently versions 1, 2,
- 3, and 4 are supported. A valid
- version is required.
-
-
- Version 2 is supported only for server version 14
- and above, and it allows streaming of large in-progress transactions.
-
-
- Version 3 is supported only for server version 15
- and above, and it allows streaming of two-phase commits.
-
-
- Version 4 is supported only for server version 16
- and above, and it allows streams of large in-progress transactions to
- be applied in parallel.
-
-
-
-
-
-
- publication_names
-
-
-
- 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.
- At least one publication name is required.
-
-
-
-
-
-
- binary
-
-
-
- Boolean option to use binary transfer mode. Binary mode is faster
- than the text mode but slightly less robust.
-
-
-
-
-
-
- messages
-
-
-
- Boolean option to enable sending the messages that are written
- by pg_logical_emit_message.
-
-
-
-
-
-
- streaming
-
-
-
- Boolean option to enable streaming of in-progress transactions.
- It accepts an additional value "parallel" to enable sending extra
- information with some messages to be used for parallelisation.
- Minimum protocol version 2 is required to turn it on. Minimum protocol
- version 4 is required for the "parallel" option.
-
-
-
-
-
-
- two_phase
-
-
-
- Boolean option to enable two-phase transactions. Minimum protocol
- version 3 is required to turn it on.
-
-
-
-
-
-
- origin
-
-
-
- Option to send changes by their origin. Possible values are "none"
- to only send the changes that have no origin associated, or "any"
- to send the changes regardless of their origin. This can be used
- to avoid loops (infinite replication of the same data) among
- replication nodes.
-
-
-
-
-
+ The START_REPLICATION command can pass
+ options to the logical decoding output plugin associated
+ with the specified replication slot.
+ See for options
+ that are accepted by the standard (pgoutput) plugin.
@@ -3482,10 +3692,10 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;"
indicate that it can be sent by a frontend (F), a backend (B), or both
(F & 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.)
+ most messages are defined so that the message end can be found without
+ reference to the byte count. This is for historical reasons, as the
+ original, now-obsolete protocol version 2 did not have an explicit length
+ field. It also aids validity checking though.
@@ -3901,7 +4111,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;"
- Int32(12)
+ Int32
Length of message contents in bytes, including self.
@@ -3919,14 +4129,29 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;"
- Int32
+ Byten
- The secret key of this backend.
+ The secret key of this backend. This field extends to the end of the
+ message, indicated by the length field.
+
+
+ The minimum and maximum key length are 4 and 256 bytes, respectively. The
+ PostgreSQL server only sends keys up to
+ 32 bytes, but the larger maximum size allows for future server
+ versions, as well as connection poolers and other middleware, to use
+ longer keys. One possible use case is augmenting the server's key
+ with extra information. Middleware is therefore also encouraged to
+ not use up all of the bytes, in case multiple middleware
+ applications are layered on top of each other, each of which may
+ wrap the key with extra data.
+
+ Before protocol version 3.2, the secret key was always 4 bytes long.
+
@@ -4132,14 +4357,18 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;"
- Int32
+ Byten
- The secret key for the target backend.
+ The secret key for the target backend. This field extends to the end of the
+ message, indicated by the length field. The maximum key length is 256 bytes.
+
+ Before protocol version 3.2, the secret key was always 4 bytes long.
+
@@ -5842,13 +6071,14 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;"
- Int32(196608)
+ Int32
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).
+ the major version number. The least significant 16 bits are the minor
+ version number. As an example protocol version 3.2 is represented as
+ 196610 in decimal or more clearly as
+ 0x00030002 in hexadecimal.
@@ -6525,7 +6755,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;"
Next, the following message part appears for each column included in
- the publication (except generated columns):
+ the publication:
@@ -7053,8 +7283,8 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;"
Int64 (XLogRecPtr)
- The LSN of the abort. This field is available since protocol version
- 4.
+ The LSN of the abort operation, present only when streaming is set to parallel.
+ This field is available since protocol version 4.
@@ -7063,9 +7293,9 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;"
Int64 (TimestampTz)
- Abort timestamp of the transaction. The value is in number
- of microseconds since PostgreSQL epoch (2000-01-01). This field is
- available since protocol version 4.
+ Abort timestamp of the transaction, present only when streaming is set to
+ parallel. The value is in number of microseconds since PostgreSQL epoch (2000-01-01).
+ This field is available since protocol version 4.
@@ -7458,7 +7688,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;"
- Next, one of the following submessages appears for each column (except generated columns):
+ Next, one of the following submessages appears for each published column:
@@ -7588,8 +7818,9 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;"
is a well-defined way to recover from errors during COPY. The special
\. last line is not needed anymore, and is not sent
during COPY OUT.
- (It is still recognized as a terminator during COPY IN, but its use is
- deprecated and will eventually be removed.) Binary COPY is supported.
+ (It is still recognized as a terminator during text-mode COPY
+ IN, but not in CSV mode. The text-mode behavior is
+ deprecated and may eventually be removed.) Binary COPY is supported.
The CopyInResponse and CopyOutResponse messages include fields indicating
the number of columns and the format of each column.
diff --git a/doc/src/sgml/queries.sgml b/doc/src/sgml/queries.sgml
index 372cce1a487e3..a326960ff4dfb 100644
--- a/doc/src/sgml/queries.sgml
+++ b/doc/src/sgml/queries.sgml
@@ -1461,10 +1461,10 @@ GROUP BY GROUPING SETS (
When multiple window functions are used, all the window functions having
- syntactically equivalent PARTITION BY and ORDER BY
- 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 ORDER BY does not uniquely determine an ordering.
+ equivalent PARTITION BY and ORDER BY
+ clauses in their window definitions are guaranteed to see the same
+ ordering of the input rows, even if the ORDER BY does
+ not uniquely determine the ordering.
However, no guarantees are made about the evaluation of functions having
different PARTITION BY or ORDER BY specifications.
(In such cases a sort step is typically required between the passes of
diff --git a/doc/src/sgml/query.sgml b/doc/src/sgml/query.sgml
index 59962d6e85633..b190f28d41ea6 100644
--- a/doc/src/sgml/query.sgml
+++ b/doc/src/sgml/query.sgml
@@ -264,8 +264,18 @@ COPY weather FROM '/home/user/weather.txt';
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
- COPY command in .
+ reads the file directly. The data inserted above into the weather table
+ could also be inserted from a file containing (values are separated by a
+ tab character):
+
+
+San Francisco 46 50 0.25 1994-11-27
+San Francisco 43 57 0.0 1994-11-29
+Hayward 37 54 \N 1994-11-29
+
+
+ You can read more about the COPY command in
+ .
@@ -671,7 +681,7 @@ SELECT max(temp_lo) FROM weather;
we might try:
-SELECT city FROM weather WHERE temp_lo = max(temp_lo); WRONG
+SELECT city FROM weather WHERE temp_lo = max(temp_lo); -- WRONG
but this will not work since the aggregate
diff --git a/doc/src/sgml/ref/alter_database.sgml b/doc/src/sgml/ref/alter_database.sgml
index 2479c41e8d635..1fc051e11a311 100644
--- a/doc/src/sgml/ref/alter_database.sgml
+++ b/doc/src/sgml/ref/alter_database.sgml
@@ -82,7 +82,8 @@ ALTER DATABASE name RESET ALL
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.
+ unaffected. The method used to copy files to the new tablespace
+ is affected by the setting.
diff --git a/doc/src/sgml/ref/alter_default_privileges.sgml b/doc/src/sgml/ref/alter_default_privileges.sgml
index 89aacec4fab84..6acd0f1df914c 100644
--- a/doc/src/sgml/ref/alter_default_privileges.sgml
+++ b/doc/src/sgml/ref/alter_default_privileges.sgml
@@ -51,6 +51,11 @@ GRANT { { USAGE | CREATE }
ON SCHEMAS
TO { [ GROUP ] role_name | PUBLIC } [, ...] [ WITH GRANT OPTION ]
+GRANT { { SELECT | UPDATE }
+ [, ...] | ALL [ PRIVILEGES ] }
+ ON LARGE OBJECTS
+ TO { [ GROUP ] role_name | PUBLIC } [, ...] [ WITH GRANT OPTION ]
+
REVOKE [ GRANT OPTION FOR ]
{ { SELECT | INSERT | UPDATE | DELETE | TRUNCATE | REFERENCES | TRIGGER | MAINTAIN }
[, ...] | ALL [ PRIVILEGES ] }
@@ -83,6 +88,13 @@ REVOKE [ GRANT OPTION FOR ]
ON SCHEMAS
FROM { [ GROUP ] role_name | PUBLIC } [, ...]
[ CASCADE | RESTRICT ]
+
+REVOKE [ GRANT OPTION FOR ]
+ { { SELECT | UPDATE }
+ [, ...] | ALL [ PRIVILEGES ] }
+ ON LARGE OBJECTS
+ FROM { [ GROUP ] role_name | PUBLIC } [, ...]
+ [ CASCADE | RESTRICT ]
@@ -117,8 +129,8 @@ REVOKE [ GRANT OPTION FOR ]
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.
+ tables), sequences, functions, types (including domains), and large objects
+ can be altered. For this command, functions include aggregates and procedures.
The words FUNCTIONS and ROUTINES are
equivalent in this command. (ROUTINES is preferred
going forward as the standard term for functions and procedures taken
@@ -161,7 +173,8 @@ REVOKE [ GRANT OPTION FOR ]
If IN SCHEMA is omitted, the global default privileges
are altered.
IN SCHEMA is not allowed when setting privileges
- for schemas, since schemas can't be nested.
+ for schemas and large objects, since schemas can't be nested and
+ large objects don't belong to a schema.
diff --git a/doc/src/sgml/ref/alter_domain.sgml b/doc/src/sgml/ref/alter_domain.sgml
index f6704d7557a81..74855172222ec 100644
--- a/doc/src/sgml/ref/alter_domain.sgml
+++ b/doc/src/sgml/ref/alter_domain.sgml
@@ -41,6 +41,11 @@ ALTER DOMAIN name
RENAME TO new_name
ALTER DOMAIN name
SET SCHEMA new_schema
+
+where domain_constraint is:
+
+[ CONSTRAINT constraint_name ]
+{ NOT NULL | CHECK (expression) }
@@ -79,8 +84,7 @@ ALTER DOMAIN nameADD domain_constraint [ NOT VALID ]
- This form adds a new constraint to a domain using the same syntax as
- CREATE DOMAIN.
+ This form adds a new constraint to a domain.
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
diff --git a/doc/src/sgml/ref/alter_foreign_table.sgml b/doc/src/sgml/ref/alter_foreign_table.sgml
index 3cb6f08fcf2a9..e2da3cc719f90 100644
--- a/doc/src/sgml/ref/alter_foreign_table.sgml
+++ b/doc/src/sgml/ref/alter_foreign_table.sgml
@@ -173,7 +173,8 @@ ALTER FOREIGN TABLE [ IF EXISTS ] name
This form adds a new constraint to a foreign table, using the same
syntax as CREATE FOREIGN TABLE.
- Currently only CHECK constraints are supported.
+ Currently only CHECK and NOT NULL
+ constraints are supported.
@@ -182,7 +183,8 @@ ALTER FOREIGN TABLE [ IF EXISTS ] nameCREATE FOREIGN TABLE.)
- If the constraint is marked NOT VALID, then it isn't
+ If the constraint is marked NOT VALID (allowed only for
+ the CHECK case), then it isn't
assumed to hold, but is only recorded for possible future use.
diff --git a/doc/src/sgml/ref/alter_index.sgml b/doc/src/sgml/ref/alter_index.sgml
index e26efec064bee..1d42d05d85816 100644
--- a/doc/src/sgml/ref/alter_index.sgml
+++ b/doc/src/sgml/ref/alter_index.sgml
@@ -87,10 +87,11 @@ ALTER INDEX ALL IN TABLESPACE name
- ATTACH PARTITION
+ ATTACH PARTITION index_name
- Causes the named index to become attached to the altered index.
+ Causes the named index (possibly schema-qualified) 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
diff --git a/doc/src/sgml/ref/alter_materialized_view.sgml b/doc/src/sgml/ref/alter_materialized_view.sgml
index da7ed045974f4..f81a7393f5d2f 100644
--- a/doc/src/sgml/ref/alter_materialized_view.sgml
+++ b/doc/src/sgml/ref/alter_materialized_view.sgml
@@ -100,7 +100,7 @@ ALTER MATERIALIZED VIEW ALL IN TABLESPACE namecolumn_name
- Name of a new or existing column.
+ Name of an existing column.
diff --git a/doc/src/sgml/ref/alter_opfamily.sgml b/doc/src/sgml/ref/alter_opfamily.sgml
index b2e5b9b72ec8b..5c4c2e579f570 100644
--- a/doc/src/sgml/ref/alter_opfamily.sgml
+++ b/doc/src/sgml/ref/alter_opfamily.sgml
@@ -273,14 +273,6 @@ ALTER OPERATOR FAMILY name USING name RENAME TO . See there for more information.
+
+
+ Altering the publish_via_partition_root parameter can
+ lead to data loss or duplication at the subscriber because it changes
+ the identity and schema of the published tables. Note this happens only
+ when a partition root table is specified as the replication target.
+
+
+ This problem can be avoided by refraining from modifying partition leaf
+ tables after the ALTER PUBLICATION ... SET until the
+ ALTER SUBSCRIPTION ... REFRESH PUBLICATION
+ is executed and by only refreshing using the copy_data = off
+ option.
+
+
diff --git a/doc/src/sgml/ref/alter_sequence.sgml b/doc/src/sgml/ref/alter_sequence.sgml
index 7be36cf466d2c..a998ccc7ead2f 100644
--- a/doc/src/sgml/ref/alter_sequence.sgml
+++ b/doc/src/sgml/ref/alter_sequence.sgml
@@ -27,9 +27,10 @@ ALTER SEQUENCE [ IF EXISTS ] name
[ AS data_type ]
[ INCREMENT [ BY ] increment ]
[ MINVALUE minvalue | NO MINVALUE ] [ MAXVALUE maxvalue | NO MAXVALUE ]
+ [ [ NO ] CYCLE ]
[ START [ WITH ] start ]
[ RESTART [ [ WITH ] restart ] ]
- [ CACHE cache ] [ [ NO ] CYCLE ]
+ [ CACHE cache ]
[ OWNED BY { table_name.column_name | NONE } ]
ALTER SEQUENCE [ IF EXISTS ] name SET { LOGGED | UNLOGGED }
ALTER SEQUENCE [ IF EXISTS ] name OWNER TO { new_owner | CURRENT_ROLE | CURRENT_USER | SESSION_USER }
@@ -154,6 +155,38 @@ ALTER SEQUENCE [ IF EXISTS ] name S
+
+ CYCLE
+
+
+ The optional CYCLE key word can be used to enable
+ the sequence to wrap around when the
+ maxvalue or
+ minvalue has been
+ reached by
+ an ascending or descending sequence respectively. If the limit is
+ reached, the next number generated will be the
+ minvalue or
+ maxvalue,
+ respectively.
+
+
+
+
+
+ NO CYCLE
+
+
+ If the optional NO CYCLE key word is
+ specified, any calls to nextval after the
+ sequence has reached its maximum value will return an error.
+ If neither CYCLE or NO
+ CYCLE are specified, the old cycle behavior will be
+ maintained.
+
+
+
+
start
@@ -207,38 +240,6 @@ ALTER SEQUENCE [ IF EXISTS ] name S
-
- CYCLE
-
-
- The optional CYCLE key word can be used to enable
- the sequence to wrap around when the
- maxvalue or
- minvalue has been
- reached by
- an ascending or descending sequence respectively. If the limit is
- reached, the next number generated will be the
- minvalue or
- maxvalue,
- respectively.
-
-
-
-
-
- NO CYCLE
-
-
- If the optional NO CYCLE key word is
- specified, any calls to nextval after the
- sequence has reached its maximum value will return an error.
- If neither CYCLE or NO
- CYCLE are specified, the old cycle behavior will be
- maintained.
-
-
-
-
SET { LOGGED | UNLOGGED }
diff --git a/doc/src/sgml/ref/alter_subscription.sgml b/doc/src/sgml/ref/alter_subscription.sgml
index 476f195622380..12f72ba31675c 100644
--- a/doc/src/sgml/ref/alter_subscription.sgml
+++ b/doc/src/sgml/ref/alter_subscription.sgml
@@ -68,11 +68,17 @@ ALTER SUBSCRIPTION name RENAME TO <
Commands ALTER SUBSCRIPTION ... REFRESH PUBLICATION,
ALTER SUBSCRIPTION ... {SET|ADD|DROP} PUBLICATION ...
- with refresh option as true and
- ALTER SUBSCRIPTION ... SET (failover = true|false)
+ with refresh option as true,
+ ALTER SUBSCRIPTION ... SET (failover = true|false) and
+ ALTER SUBSCRIPTION ... SET (two_phase = false)
cannot be executed inside a transaction block.
+
- These commands also cannot be executed when the subscription has
+
+ Commands ALTER SUBSCRIPTION ... REFRESH PUBLICATION and
+ ALTER SUBSCRIPTION ... {SET|ADD|DROP} PUBLICATION ...
+ with refresh option as true also cannot
+ be executed when the subscription has
two_phase
commit enabled, unless
copy_data
@@ -228,8 +234,11 @@ ALTER SUBSCRIPTION name RENAME TO <
disable_on_error,
password_required,
run_as_owner,
- origin, and
- failover.
+ origin,
+ failover,
+ two_phase,
+ retain_dead_tuples, and
+ max_retention_duration.
Only a superuser can set password_required = false.
@@ -252,6 +261,41 @@ ALTER SUBSCRIPTION name RENAME TO <
failover
option is enabled.
+
+
+ The failover,
+ two_phase, and
+ retain_dead_tuples
+ parameters can only be altered when the subscription is disabled.
+
+
+
+ When altering two_phase
+ from true to false, the backend
+ process reports an error if any prepared transactions done by the
+ logical replication worker (from when two_phase
+ parameter was still true) are found. You can resolve
+ prepared transactions on the publisher node, or manually roll back them
+ on the subscriber, and then try again. The transactions prepared by
+ logical replication worker corresponding to a particular subscription have
+ the following pattern: pg_gid_%u_%u
+ (parameters: subscription oid, remote transaction id xid).
+ To resolve such transactions manually, you need to roll back all
+ the prepared transactions with corresponding subscription IDs in their
+ names. Applications can check
+ pg_prepared_xacts
+ to find the required prepared transactions. After the two_phase
+ option is changed from true to false,
+ the publisher will replicate the transactions again when they are committed.
+
+
+
+ If the retain_dead_tuples
+ option is altered to false and no other subscription
+ has this option enabled, the replication slot named
+ pg_conflict_detection, created to retain
+ dead tuples for conflict detection, will be dropped.
+
diff --git a/doc/src/sgml/ref/alter_table.sgml b/doc/src/sgml/ref/alter_table.sgml
index 5d352abf991b5..8867da6c69307 100644
--- a/doc/src/sgml/ref/alter_table.sgml
+++ b/doc/src/sgml/ref/alter_table.sgml
@@ -37,13 +37,6 @@ ALTER TABLE [ IF EXISTS ] name
ATTACH PARTITION partition_name { FOR VALUES partition_bound_spec | DEFAULT }
ALTER TABLE [ IF EXISTS ] name
DETACH PARTITION partition_name [ CONCURRENTLY | FINALIZE ]
-ALTER TABLE [ IF EXISTS ] name
- SPLIT PARTITION partition_name INTO
- (PARTITION partition_name1 { FOR VALUES partition_bound_spec | DEFAULT },
- PARTITION partition_name2 { FOR VALUES partition_bound_spec | DEFAULT } [, ...])
-ALTER TABLE [ IF EXISTS ] name
- MERGE PARTITIONS (partition_name1, partition_name2 [, ...])
- INTO partition_namewhere action is one of:
@@ -65,7 +58,8 @@ ALTER TABLE [ IF EXISTS ] name
ALTER [ COLUMN ] column_name SET COMPRESSION compression_method
ADD table_constraint [ NOT VALID ]
ADD table_constraint_using_index
- ALTER CONSTRAINT constraint_name [ DEFERRABLE | NOT DEFERRABLE ] [ INITIALLY DEFERRED | INITIALLY IMMEDIATE ]
+ ALTER CONSTRAINT constraint_name [ DEFERRABLE | NOT DEFERRABLE ] [ INITIALLY DEFERRED | INITIALLY IMMEDIATE ] [ ENFORCED | NOT ENFORCED ]
+ ALTER CONSTRAINT constraint_name [ INHERIT | NO INHERIT ]
VALIDATE CONSTRAINT constraint_name
DROP CONSTRAINT [ IF EXISTS ] constraint_name [ RESTRICT | CASCADE ]
DISABLE TRIGGER [ trigger_name | ALL | USER ]
@@ -105,28 +99,29 @@ WITH ( MODULUS numeric_literal, REM
and column_constraint is:
[ CONSTRAINT constraint_name ]
-{ NOT NULL |
+{ NOT NULL [ NO INHERIT ] |
NULL |
CHECK ( expression ) [ NO INHERIT ] |
DEFAULT default_expr |
- GENERATED ALWAYS AS ( generation_expr ) STORED |
+ GENERATED ALWAYS AS ( generation_expr ) [ STORED | VIRTUAL ] |
GENERATED { ALWAYS | BY DEFAULT } AS IDENTITY [ ( sequence_options ) ] |
UNIQUE [ NULLS [ NOT ] DISTINCT ] index_parameters |
PRIMARY KEY index_parameters |
REFERENCES reftable [ ( refcolumn ) ] [ MATCH FULL | MATCH PARTIAL | MATCH SIMPLE ]
[ ON DELETE referential_action ] [ ON UPDATE referential_action ] }
-[ DEFERRABLE | NOT DEFERRABLE ] [ INITIALLY DEFERRED | INITIALLY IMMEDIATE ]
+[ DEFERRABLE | NOT DEFERRABLE ] [ INITIALLY DEFERRED | INITIALLY IMMEDIATE ] [ ENFORCED | NOT ENFORCED ]
and table_constraint is:
[ CONSTRAINT constraint_name ]
{ CHECK ( expression ) [ NO INHERIT ] |
- UNIQUE [ NULLS [ NOT ] DISTINCT ] ( column_name [, ... ] ) index_parameters |
- PRIMARY KEY ( column_name [, ... ] ) index_parameters |
+ NOT NULL column_name [ NO INHERIT ] |
+ UNIQUE [ NULLS [ NOT ] DISTINCT ] ( column_name [, ... ] [, column_name WITHOUT OVERLAPS ] ) index_parameters |
+ PRIMARY KEY ( column_name [, ... ] [, column_name WITHOUT OVERLAPS ] ) index_parameters |
EXCLUDE [ USING index_method ] ( exclude_element WITH operator [, ... ] ) index_parameters [ WHERE ( predicate ) ] |
- FOREIGN KEY ( column_name [, ... ] ) REFERENCES reftable [ ( refcolumn [, ... ] ) ]
+ FOREIGN KEY ( column_name [, ... ] [, PERIOD column_name ] ) REFERENCES reftable [ ( refcolumn [, ... ] [, PERIOD refcolumn ] ) ]
[ MATCH FULL | MATCH PARTIAL | MATCH SIMPLE ] [ ON DELETE referential_action ] [ ON UPDATE referential_action ] }
-[ DEFERRABLE | NOT DEFERRABLE ] [ INITIALLY DEFERRED | INITIALLY IMMEDIATE ]
+[ DEFERRABLE | NOT DEFERRABLE ] [ INITIALLY DEFERRED | INITIALLY IMMEDIATE ] [ ENFORCED | NOT ENFORCED ]
and table_constraint_using_index is:
@@ -215,6 +210,8 @@ WITH ( MODULUS numeric_literal, REM
When this form is used, the column's statistics are removed,
so running ANALYZE
on the table afterwards is recommended.
+ For a virtual generated column, ANALYZE
+ is not necessary because such columns never have statistics.
@@ -245,9 +242,12 @@ WITH ( MODULUS numeric_literal, REM
provided none of the records in the table contain a
NULL value for the column. Ordinarily this is
checked during the ALTER TABLE by scanning the
- entire table; however, if a valid CHECK constraint is
- found which proves no NULL can exist, then the
- table scan is skipped.
+ entire table, unless NOT VALID is specified;
+ however, if a valid CHECK constraint exists
+ (and is not dropped in the same command) which proves no
+ NULL can exist, then the table scan is skipped.
+ If a column has an invalid not-null constraint,
+ SET NOT NULL validates it.
@@ -258,7 +258,9 @@ WITH ( MODULUS numeric_literal, REM
table. Even if there is no NOT NULL constraint on the
parent, such a constraint can still be added to individual partitions,
if desired; that is, the children can disallow nulls even if the parent
- allows them, but not the other way around.
+ allows them, but not the other way around. It is also possible to drop
+ the NOT NULL constraint from ONLY
+ the parent table, which does not remove it from the children.
@@ -268,8 +270,17 @@ WITH ( MODULUS numeric_literal, REM
This form replaces the expression of a generated column. Existing data
- in the column is rewritten and all the future changes will apply the new
- generation expression.
+ in a stored generated column is rewritten and all the future changes
+ will apply the new generation expression.
+
+
+
+ When this form is used on a stored generated column, its statistics
+ are removed, so running
+ ANALYZE
+ on the table afterwards is recommended.
+ For a virtual generated column, ANALYZE
+ is not necessary because such columns never have statistics.
@@ -283,10 +294,15 @@ WITH ( MODULUS numeric_literal, REM
longer apply the generation expression.
+
+ This form is currently only supported for stored generated columns (not
+ virtual ones).
+
+
If DROP EXPRESSION IF EXISTS is specified and the
- column is not a stored generated column, no error is thrown. In this
- case a notice is issued instead.
+ column is not a generated column, no error is thrown. In this case a
+ notice is issued instead.
@@ -456,8 +472,8 @@ WITH ( MODULUS numeric_literal, REM
This form adds a new constraint to a table using the same constraint
syntax as CREATE TABLE, plus the option NOT
- VALID, which is currently only allowed for foreign key
- and CHECK constraints.
+ VALID, which is currently only allowed for foreign-key,
+ CHECK, and not-null constraints.
@@ -465,7 +481,7 @@ WITH ( MODULUS numeric_literal, REM
existing rows in the table satisfy the new constraint. But if
the NOT VALID 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
+ applied 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
@@ -490,8 +506,6 @@ WITH ( MODULUS numeric_literal, REM
Additional restrictions apply when unique or primary key constraints
are added to partitioned tables; see CREATE TABLE.
- Also, foreign key constraints on partitioned
- tables may not be declared NOT VALID at present.
@@ -557,19 +571,40 @@ WITH ( MODULUS numeric_literal, REM
This form alters the attributes of a constraint that was previously
- created. Currently only foreign key constraints may be altered.
+ created. Currently only foreign key constraints may be altered in
+ this fashion, but see below.
+
+ ALTER CONSTRAINT ... INHERIT
+ ALTER CONSTRAINT ... NO INHERIT
+
+
+ These forms modify a inheritable constraint so that it becomes not
+ inheritable, or vice-versa. Only not-null constraints may be altered
+ in this fashion at present.
+ In addition to changing the inheritability status of the constraint,
+ in the case where a non-inheritable constraint is being marked
+ inheritable, if the table has children, an equivalent constraint
+ will be added to them. If marking an inheritable constraint as
+ non-inheritable on a table with children, then the corresponding
+ constraint on children will be marked as no longer inherited,
+ but not removed.
+
+
+
+
VALIDATE CONSTRAINT
- This form validates a foreign key or check constraint that was
+ This form validates a foreign key, check, or not-null constraint that was
previously created as NOT VALID, 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.
+ satisfied. If the constraint was set to NOT ENFORCED, an error is thrown.
+ Nothing happens if the constraint is already marked valid.
(See below for an explanation
of the usefulness of this command.)
@@ -802,6 +837,10 @@ WITH ( MODULUS numeric_literal, REM
(for identity or serial columns). However, it is also possible to
change the persistence of such sequences separately.
+
+
+ This form is not supported for partitioned tables.
+
@@ -825,7 +864,7 @@ WITH ( MODULUS numeric_literal, REM
SHARE UPDATE EXCLUSIVE lock will be taken for
- fillfactor, toast and autovacuum storage parameters, as well as the
+ fillfactor, TOAST and autovacuum storage parameters, as well as the
planner parameter parallel_workers.
@@ -850,19 +889,16 @@ WITH ( MODULUS numeric_literal, REM
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 NOT NULL constraints in the parent
- then they must also have NOT NULL constraints in the
- child.
+ additional columns, too). The columns must have matching data types.
- There must also be matching child-table constraints for all
- CHECK constraints of the parent, except those
- marked non-inheritable (that is, created with ALTER TABLE ... ADD CONSTRAINT ... NO INHERIT)
- in the parent, which are ignored; all child-table constraints matched
- must not be marked non-inheritable.
- Currently
+ In addition, all CHECK and NOT NULL
+ constraints on the parent must also exist on the child, except those
+ marked non-inheritable (that is, created with
+ ALTER TABLE ... ADD CONSTRAINT ... NO INHERIT), which
+ are ignored. All child-table constraints matched must not be marked
+ non-inheritable. Currently
UNIQUE, PRIMARY KEY, and
FOREIGN KEY constraints are not considered, but
this might change in the future.
@@ -930,8 +966,9 @@ WITH ( MODULUS numeric_literal, REM
DEFAULT
- Records the old values of the columns of the primary key, if any.
+ Records the old values of the columns of the primary key.
This is the default for non-system tables.
+ When there is no primary key, the behavior is the same as NOTHING.
@@ -1017,20 +1054,18 @@ WITH ( MODULUS numeric_literal, REM
A partition using FOR VALUES uses same syntax for
partition_bound_spec as
- CREATE TABLE. The partition bound specification
+ CREATE TABLE.
+ 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 NOT NULL and
- CHECK constraints of the target table. Currently
+ CHECK constraints of the target table, not marked
+ NO INHERIT. Currently
FOREIGN KEY constraints are not considered.
UNIQUE and PRIMARY KEY constraints
from the parent table will be created in the partition, if they don't
already exist.
- If any of the CHECK constraints of the table being
- attached are marked NO INHERIT, the command will fail;
- such constraints must be recreated without the
- NO INHERIT clause.
@@ -1124,133 +1159,14 @@ WITH ( MODULUS numeric_literal, REM
-
- SPLIT PARTITION partition_name INTO (PARTITION partition_name1 { FOR VALUES partition_bound_spec | DEFAULT }, PARTITION partition_name2 { FOR VALUES partition_bound_spec | DEFAULT } [, ...])
-
-
-
- This form splits a single partition of the target table. Hash-partitioning
- is not supported. Bounds of new partitions should not overlap with new and
- existing partitions (except partition_name).
- If the split partition is a DEFAULT partition, one of the new partitions must be DEFAULT.
- In case one of the new partitions or one of existing partitions is DEFAULT,
- new partitions partition_name1,
- partition_name2, ... can have spaces
- between partitions bounds. If the partitioned table does not have a DEFAULT
- partition, the DEFAULT partition can be defined as one of the new partitions.
-
-
- In case new partitions do not contain a DEFAULT partition and the partitioned table
- does not have a DEFAULT partition, the following must be true: sum bounds of
- new partitions partition_name1,
- partition_name2, ... should be
- equal to bound of split partition partition_name.
- One of the new partitions partition_name1,
- partition_name2, ... can have
- the same name as split partition partition_name
- (this is suitable in case of splitting a DEFAULT partition: we split it, but after
- splitting we have a partition with the same name).
- Only simple, non-partitioned partition can be split.
-
-
- The new partitions will be created the same as tables created with the
- SQL command CREATE TABLE partition_nameN (LIKE name INCLUDING ALL EXCLUDING INDEXES EXCLUDING IDENTITY).
- The indexes and identity are created later, after moving the data
- into the new partitions.
- New partitions will have the same table access method as the parent.
- If the parent table is persistent then new partitions are created
- persistent. If the parent table is temporary then new partitions
- are also created temporary.
-
-
-
- This command acquires an ACCESS EXCLUSIVE lock.
- This is a significant limitation, which limits the usage of this
- command with large partitioned tables under a high load.
-
-
-
-
-
-
- MERGE PARTITIONS (partition_name1, partition_name2 [, ...]) INTO partition_name
-
-
-
- This form merges several partitions into the one partition of the target table.
- Hash-partitioning is not supported. If DEFAULT partition is not in the
- list of partitions partition_name1,
- partition_name2 [, ...]:
-
-
-
- For range-partitioned tables it is necessary that the ranges
- of the partitions partition_name1,
- partition_name2 [, ...] can
- be merged into one range without spaces and overlaps (otherwise an error
- will be generated). The combined range will be the range for the partition
- partition_name.
-
-
-
-
- For list-partitioned tables the value lists of all partitions
- partition_name1,
- partition_name2 [, ...] are
- combined and form the list of values of partition
- partition_name.
-
-
-
- If DEFAULT partition is in the list of partitions partition_name1,
- partition_name2 [, ...]:
-
-
-
- The partition partition_name
- will be the DEFAULT partition.
-
-
-
-
- For range- and list-partitioned tables the ranges and lists of values
- of the merged partitions can be any.
-
-
-
- The new partition partition_name
- can have the same name as one of the merged partitions. Only simple,
- non-partitioned partitions can be merged.
-
-
- The new partition will be created the same as a table created with the
- SQL command CREATE TABLE partition_name (LIKE name INCLUDING ALL EXCLUDING INDEXES EXCLUDING IDENTITY).
- The indexes and identity are created later, after moving the data
- into the new partition.
- The new partition will have the same table access method as the parent.
- If the parent table is persistent then the new partition is created
- persistent. If the parent table is temporary then the new partition
- is also created temporary.
-
-
-
- This command acquires an ACCESS EXCLUSIVE lock.
- This is a significant limitation, which limits the usage of this
- command with large partitioned tables under a high load.
-
-
-
-
-
- All the forms of ALTER TABLE that act on a single table, except
- RENAME, SET SCHEMA,
- ATTACH PARTITION, DETACH PARTITION,
- SPLIT PARTITION, and MERGE PARTITIONS
- can be combined into
+ All the forms of ALTER TABLE that act on a single table,
+ except RENAME, SET SCHEMA,
+ ATTACH PARTITION, and
+ DETACH PARTITION 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
@@ -1493,8 +1409,7 @@ WITH ( MODULUS numeric_literal, REM
partition_name
- The name of the table to attach as a new partition or to detach from this table,
- or the name of split partition, or the name of the new merged partition.
+ The name of the table to attach as a new partition or to detach from this table.
@@ -1521,36 +1436,53 @@ WITH ( MODULUS numeric_literal, REM
When a column is added with ADD COLUMN and a
- non-volatile DEFAULT is specified, the default is
+ non-volatile DEFAULT is specified, the default value 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 DEFAULT is specified, NULL is used. In
- neither case is a rewrite of the table required.
+ table's metadata, where it will be returned when any existing rows are
+ accessed. The value will be only applied when the table is rewritten,
+ making the ALTER TABLE very fast even on large tables.
+ If no column constraints are specified, NULL is used as the
+ DEFAULT. In neither case is a rewrite of the table
+ required.
+
+
+
+ Adding a column with a volatile DEFAULT
+ (e.g., clock_timestamp()), a stored generated column,
+ an identity column, or a column with a domain data type that has
+ constraints will cause the entire table and its indexes to be rewritten.
+ Adding a virtual generated column never requires a rewrite.
+
+
+
+ Changing the type of an existing column will normally cause the entire table
+ and its indexes to be rewritten.
+ As an exception, when changing the type of an existing column,
+ if the USING 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 will still 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 required because the new sort
+ order might be different. However, in the absence of a collation
+ change, a column can be changed from text to
+ varchar (or vice versa) without rebuilding the indexes
+ because these data types sort identically.
- Adding a column with a volatile DEFAULT 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 USING 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 text to varchar (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.
+ 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.
- Adding a CHECK or NOT NULL constraint requires
- scanning the table to verify that existing rows meet the constraint,
- but does not require a table rewrite.
+ Adding a CHECK or NOT NULL
+ constraint requires scanning the table to verify that existing rows meet the
+ constraint, but does not require a table rewrite. If a CHECK
+ constraint is added as NOT ENFORCED, no verification will
+ be performed.
@@ -1565,7 +1497,7 @@ WITH ( MODULUS numeric_literal, REM
- Scanning a large table to verify a new foreign key or check constraint
+ Scanning a large table to verify new foreign-key, check, or not-null constraints
can take a long time, and other updates to the table are locked out
until the ALTER TABLE ADD CONSTRAINT command is
committed. The main purpose of the NOT VALID
@@ -1910,42 +1842,23 @@ ALTER TABLE measurement
DETACH PARTITION measurement_y2015m12;
-
- To split a single partition of the range-partitioned table:
-
-ALTER TABLE sales_range SPLIT PARTITION sales_feb_mar_apr2023 INTO
- (PARTITION sales_feb2023 FOR VALUES FROM ('2023-02-01') TO ('2023-03-01'),
- PARTITION sales_mar2023 FOR VALUES FROM ('2023-03-01') TO ('2023-04-01'),
- PARTITION sales_apr2023 FOR VALUES FROM ('2023-04-01') TO ('2023-05-01'));
-
-
-
- To split a single partition of the list-partitioned table:
-
-ALTER TABLE sales_list SPLIT PARTITION sales_all INTO
- (PARTITION sales_west FOR VALUES IN ('Lisbon', 'New York', 'Madrid'),
- PARTITION sales_east FOR VALUES IN ('Bejing', 'Delhi', 'Vladivostok'),
- PARTITION sales_central FOR VALUES IN ('Warsaw', 'Berlin', 'Kyiv'));
-
-
-
- To merge several partitions into one partition of the target table:
-
-ALTER TABLE sales_list MERGE PARTITIONS (sales_west, sales_east, sales_central)
- INTO sales_all;
-
-
Compatibility
- The forms ADD (without USING INDEX),
+ The forms ADD [COLUMN],
DROP [COLUMN], DROP IDENTITY, RESTART,
SET DEFAULT, SET DATA TYPE (without USING),
SET GENERATED, and SET sequence_option
- conform with the SQL standard. The other forms are
+ conform with the SQL standard.
+ The form ADD table_constraint
+ conforms with the SQL standard when the USING INDEX and
+ NOT VALID clauses are omitted and the constraint type is
+ one of CHECK, UNIQUE, PRIMARY KEY,
+ or REFERENCES.
+ The other forms are
PostgreSQL extensions of the SQL standard.
Also, the ability to specify more than one manipulation in a single
ALTER TABLE command is an extension.
diff --git a/doc/src/sgml/ref/alter_tablespace.sgml b/doc/src/sgml/ref/alter_tablespace.sgml
index 6ec863400d17b..d0e08089ddb96 100644
--- a/doc/src/sgml/ref/alter_tablespace.sgml
+++ b/doc/src/sgml/ref/alter_tablespace.sgml
@@ -88,7 +88,7 @@ ALTER TABLESPACE name RESET ( ,
,
diff --git a/doc/src/sgml/ref/analyze.sgml b/doc/src/sgml/ref/analyze.sgml
index 2b94b378e9f31..ec81f00fecf87 100644
--- a/doc/src/sgml/ref/analyze.sgml
+++ b/doc/src/sgml/ref/analyze.sgml
@@ -31,7 +31,7 @@ ANALYZE [ ( option [, ...] ) ] [ and table_and_columns is:
- table_name [ ( column_name [, ...] ) ]
+ [ ONLY ] table_name [ * ] [ ( column_name [, ...] ) ]
@@ -65,7 +65,7 @@ ANALYZE [ ( option [, ...] ) ] [ VERBOSE
- Enables display of progress messages.
+ Enables display of progress messages at INFO level.
@@ -142,9 +142,12 @@ ANALYZE [ ( option [, ...] ) ] [ ONLY is specified before
+ the table name, only that table is analyzed. If ONLY
+ is not specified, the table and all its inheritance child tables or
+ partitions (if any) are analyzed. Optionally, *
+ can be specified after the table name to explicitly indicate that
+ inheritance child tables (or partitions) are to be analyzed.
@@ -284,22 +287,23 @@ ANALYZE [ ( option [, ...] ) ] [ ANALYZE 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 ANALYZE manually.
+ planning queries that process the inheritance tree as a whole. 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
+ ANALYZE manually. By default,
+ ANALYZE will also recursively collect and update the
+ statistics for each inheritance child table. The ONLY
+ keyword may be used to disable this.
For partitioned tables, ANALYZE 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.
+ sampling rows from all partitions. By default,
+ ANALYZE will also recursively collect and update the
+ statistics for each partition. The ONLY keyword may be
+ used to disable this.
diff --git a/doc/src/sgml/ref/checkpoint.sgml b/doc/src/sgml/ref/checkpoint.sgml
index 28a1d717b87eb..cd981cf2cab9f 100644
--- a/doc/src/sgml/ref/checkpoint.sgml
+++ b/doc/src/sgml/ref/checkpoint.sgml
@@ -21,7 +21,12 @@ PostgreSQL documentation
-CHECKPOINT
+CHECKPOINT [ ( option [, ...] ) ]
+
+where option can be one of:
+
+ FLUSH_UNLOGGED [ boolean ]
+ MODE { FAST | SPREAD }
@@ -37,14 +42,24 @@ CHECKPOINT
- The CHECKPOINT command forces an immediate
+ By default, the CHECKPOINT command forces a fast
checkpoint when the command is issued, without waiting for a
regular checkpoint scheduled by the system (controlled by the settings in
).
+ To request the checkpoint be spread over a longer interval, set the
+ MODE option to SPREAD.
CHECKPOINT is not intended for use during normal
operation.
+
+ The server may consolidate concurrently requested checkpoints. Such
+ consolidated requests will contain a combined set of options. For example,
+ if one session requests a fast checkpoint and another requests a spread
+ checkpoint, the server may combine those requests and perform one fast
+ checkpoint.
+
+
If executed during recovery, the CHECKPOINT command
will force a restartpoint (see )
@@ -53,11 +68,60 @@ CHECKPOINT
Only superusers or users with the privileges of
- the pg_checkpoint
+ the
role can call CHECKPOINT.
+
+ Parameters
+
+
+
+ FLUSH_UNLOGGED
+
+
+ Normally, CHECKPOINT does not flush dirty buffers of
+ unlogged relations. This option, which is disabled by default, enables
+ flushing unlogged relations to disk.
+
+
+
+
+
+ MODE
+
+
+ When set to FAST, which is the default, the requested
+ checkpoint will be completed as fast as possible, which may result in a
+ significantly higher rate of I/O during the checkpoint.
+
+
+ MODE can also be set to SPREAD to
+ request the checkpoint be spread over a longer interval (controlled via
+ the settings in ), like a
+ regular checkpoint scheduled by the system. This can reduce the rate of
+ I/O during the checkpoint.
+
+
+
+
+
+ boolean
+
+
+ Specifies whether the selected option should be turned on or off.
+ You can write TRUE, ON, or
+ 1 to enable the option, and FALSE,
+ OFF, or 0 to disable it. The
+ boolean value can also
+ be omitted, in which case TRUE is assumed.
+
+
+
+
+
+
Compatibility
diff --git a/doc/src/sgml/ref/cluster.sgml b/doc/src/sgml/ref/cluster.sgml
index c5760244e67e2..8811f169ea0b1 100644
--- a/doc/src/sgml/ref/cluster.sgml
+++ b/doc/src/sgml/ref/cluster.sgml
@@ -106,7 +106,8 @@ CLUSTER [ ( option [, ...] ) ] [ VERBOSE
- Prints a progress report as each table is clustered.
+ Prints a progress report as each table is clustered
+ at INFO level.
diff --git a/doc/src/sgml/ref/clusterdb.sgml b/doc/src/sgml/ref/clusterdb.sgml
index d3145318b361f..0d2051bf6f188 100644
--- a/doc/src/sgml/ref/clusterdb.sgml
+++ b/doc/src/sgml/ref/clusterdb.sgml
@@ -248,9 +248,8 @@ PostgreSQL documentation
- Specifies the name of the database to connect to to discover which
- databases should be clustered,
- when / is used.
+ When the / is used, connect
+ to this database to gather the list of databases to cluster.
If not specified, the postgres database will be used,
or if that does not exist, template1 will be used.
This can be a connection
diff --git a/doc/src/sgml/ref/copy.sgml b/doc/src/sgml/ref/copy.sgml
index 1518af8a0450c..c2d1fbc1fbe94 100644
--- a/doc/src/sgml/ref/copy.sgml
+++ b/doc/src/sgml/ref/copy.sgml
@@ -37,13 +37,14 @@ COPY { table_name [ ( delimiter_character'
NULL 'null_string'
DEFAULT 'default_string'
- HEADER [ boolean | MATCH ]
+ HEADER [ boolean | integer | MATCH ]
QUOTE 'quote_character'
ESCAPE 'escape_character'
FORCE_QUOTE { ( column_name [, ...] ) | * }
FORCE_NOT_NULL { ( column_name [, ...] ) | * }
FORCE_NULL { ( column_name [, ...] ) | * }
ON_ERROR error_action
+ REJECT_LIMIT maxerror
ENCODING 'encoding_name'
LOG_VERBOSITY verbosity
@@ -211,6 +212,15 @@ COPY { table_name [ (
+
+ integer
+
+
+ Specifies a non-negative integer value passed to the selected option.
+
+
+
+
FORMAT
@@ -220,6 +230,7 @@ COPY { table_name [ ( csv (Comma Separated Values),
or binary.
The default is text.
+ See below for details.
@@ -235,7 +246,7 @@ COPY { table_name [ ( COPY FREEZE on
- a partitioned table.
+ a partitioned table or foreign table.
This option is only allowed in COPY FROM.
@@ -301,16 +312,25 @@ COPY { table_name [ ( HEADER
- 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 true (or equivalent Boolean value).
- If this option is set to MATCH, 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.
+ On output, if this option is set to true
+ (or an equivalent Boolean value), the first line of the output will
+ contain the column names from the table.
+ Integer values 0 and 1 are
+ accepted as Boolean values, but other integers are not allowed for
+ COPY TO commands.
+
+
+ On input, if this option is set to true
+ (or an equivalent Boolean value), the first line of the input is
+ discarded. If set to a non-negative integer, that number of
+ lines are discarded. If set to MATCH, the first line
+ is discarded, and it must contain column names that exactly match the
+ table's columns, in both number and order; otherwise, an error is raised.
+ The MATCH value is only valid for
+ COPY FROM commands.
+
+
This option is not allowed when using binary format.
- The MATCH option is only valid for COPY
- FROM commands.
@@ -407,6 +427,26 @@ COPY { table_name [ ( verbose, a NOTICE message
containing the line of the input file and the column name whose input
conversion has failed is emitted for each discarded row.
+ When it is set to silent, no message is emitted
+ regarding ignored rows.
+
+
+
+
+
+ REJECT_LIMIT
+
+
+ Specifies the maximum number of errors tolerated while converting a
+ column's input value to its data type, when ON_ERROR is
+ set to ignore.
+ If the input causes more errors than the specified value, the COPY
+ command fails, even with ON_ERROR set to ignore.
+ This clause must be used with ON_ERROR=ignore
+ and maxerror must be positive bigint.
+ If not specified, ON_ERROR=ignore
+ allows an unlimited number of errors, meaning COPY will
+ skip all erroneous data.
@@ -427,10 +467,12 @@ COPY { table_name [ ( LOG_VERBOSITY
- Specify the amount of messages emitted by a COPY
- command: default or verbose. If
- verbose is specified, additional messages are emitted
- during processing.
+ Specifies the amount of messages emitted by a COPY
+ command: default, verbose, or
+ silent.
+ If verbose is specified, additional messages are
+ emitted during processing.
+ silent suppresses both verbose and default messages.
This is currently used in COPY FROM command when
@@ -496,16 +538,16 @@ COPY countNotes
- COPY TO can be used only with plain
- tables, not views, and does not copy rows from child tables
- or child partitions. For example, COPY table TO copies
- the same rows as SELECT * FROM ONLY table.
- The syntax COPY (SELECT * FROM table) TO ... can be used to
- dump all of the rows in an inheritance hierarchy, partitioned table,
- or view.
+ COPY TO can be used with plain
+ tables and populated materialized views.
+ For example,
+ COPY table
+ TO copies the same rows as
+ SELECT * FROM ONLY table.
+ However it doesn't directly support other relation types,
+ such as partitioned tables, inheritance child tables, or views.
+ To copy all rows from such relations, use COPY (SELECT * FROM
+ table) TO.
@@ -627,10 +669,10 @@ COPY count
-
+ File Formats
-
+ Text Format
@@ -646,11 +688,16 @@ COPY count
- End of data can be represented by a single line containing just
+ End of data can be represented by a line containing just
backslash-period (\.). 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.
+ serves perfectly well; in that context this provision exists only for
+ backward compatibility. However, psql
+ uses \. to terminate a COPY FROM
+ STDIN operation (that is, reading
+ in-line COPY data in an SQL script). In that
+ context the rule is needed to be able to end the operation before the
+ end of the script.
@@ -770,11 +817,11 @@ COPY count
-
+ CSV Format
- This format option is used for importing and exporting the Comma
+ This format option is used for importing and exporting the Comma-
Separated Value (CSV) file format used by many other
programs, such as spreadsheets. Instead of the escaping rules used by
PostgreSQL's standard text format, it
@@ -811,16 +858,25 @@ COPY count
Because backslash is not a special character in the CSV
- format, \., the end-of-data marker, could also appear
- as a data value. To avoid any misinterpretation, a \.
- 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 \., you might need to quote that value in the
- input file.
+ format, the end-of-data marker used in text mode (\.)
+ is not normally treated as special when reading CSV
+ data. An exception is that psql will terminate
+ a COPY FROM STDIN operation (that is, reading
+ in-line COPY data in an SQL script) at a line containing
+ only \., whether it is text or CSV
+ mode.
+
+
+ PostgreSQL versions before v18 always
+ recognized unquoted \. as an end-of-data marker,
+ even when reading from a separate file. For compatibility with older
+ versions, COPY TO will quote \.
+ when it's alone on a line, even though this is no longer necessary.
+
+
+
In CSV format, all characters are significant. A quoted value
@@ -855,7 +911,7 @@ COPY count
-
+ Binary Format
diff --git a/doc/src/sgml/ref/create_collation.sgml b/doc/src/sgml/ref/create_collation.sgml
index e34bfc97c3da2..4af1836ae30e4 100644
--- a/doc/src/sgml/ref/create_collation.sgml
+++ b/doc/src/sgml/ref/create_collation.sgml
@@ -99,7 +99,8 @@ CREATE COLLATION [ IF NOT EXISTS ] name FROM
If provider is builtin,
then locale must be specified and set to
- either C or C.UTF-8.
+ either C, C.UTF-8 or
+ PG_UNICODE_FAST.
diff --git a/doc/src/sgml/ref/create_database.sgml b/doc/src/sgml/ref/create_database.sgml
index 7653cb902eebe..3544b15efdafa 100644
--- a/doc/src/sgml/ref/create_database.sgml
+++ b/doc/src/sgml/ref/create_database.sgml
@@ -138,7 +138,9 @@ CREATE DATABASE name
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.
+ have a noticeable negative impact on overall system performance. The
+ FILE_COPY strategy is affected by the setting.
@@ -148,12 +150,12 @@ CREATE DATABASE name
Sets the default collation order and character classification in the
new database. Collation 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. Character classification affects the categorization
- of characters, e.g., lower, upper, and digit. Also sets the
- associated aspects of the operating system environment,
- LC_COLLATE and LC_CTYPE. The
- default is the same setting as the template database. See ORDER BY, as well as the
+ order used in indexes on text columns. Character classification
+ affects the categorization of characters, e.g., lower, upper, and
+ digit. Also sets the LC_CTYPE aspect of the
+ operating system environment. The default is the same setting as the
+ template database. See and for details.
@@ -168,7 +170,8 @@ CREATE DATABASE name
If is
builtin, then locale or
builtin_locale must be specified and set to
- either C or C.UTF-8.
+ either C, C.UTF-8, or
+ PG_UNICODE_FAST.
@@ -186,17 +189,16 @@ CREATE DATABASE namelc_collate
- Sets LC_COLLATE in the database server's operating
- system environment. The default is the setting of if specified, otherwise the same
- setting as the template database. See below for additional
- restrictions.
+ If is
+ libc, sets the default collation order to use in
+ the new database, overriding the setting . Otherwise, this setting is
+ ignored.
- If is
- libc, also sets the default collation order to use
- in the new database, overriding the setting .
+ The default is the setting of
+ if specified, otherwise the same setting as the template database.
+ See below for additional restrictions.
@@ -205,16 +207,18 @@ CREATE DATABASE name
Sets LC_CTYPE in the database server's operating
- system environment. The default is the setting of if specified, otherwise the same
- setting as the template database. See below for additional
- restrictions.
+ system environment.
If is
- libc, also sets the default character
- classification to use in the new database, overriding the setting
- .
+ libc, sets the default character classification to
+ use in the new database, overriding the setting .
+
+
+ The default is the setting of
+ if specified, otherwise the same setting as the template database.
+ See below for additional restrictions.
@@ -233,7 +237,8 @@ CREATE DATABASE name
The locales available for the builtin provider are
- C and C.UTF-8.
+ C, C.UTF-8 and
+ PG_UNICODE_FAST.
diff --git a/doc/src/sgml/ref/create_domain.sgml b/doc/src/sgml/ref/create_domain.sgml
index ce55520348620..c111285a69c6d 100644
--- a/doc/src/sgml/ref/create_domain.sgml
+++ b/doc/src/sgml/ref/create_domain.sgml
@@ -283,7 +283,8 @@ CREATE TABLE us_snail_addy (
The syntax NOT NULL in this command is a
PostgreSQL extension. (A standard-conforming
- way to write the same would be CHECK (VALUE IS NOT
+ way to write the same for non-composite data types would be
+ CHECK (VALUE IS NOT
NULL). However, per ,
such constraints are best avoided in practice anyway.) The
NULLconstraint is a
diff --git a/doc/src/sgml/ref/create_extension.sgml b/doc/src/sgml/ref/create_extension.sgml
index ca2b80d669c5e..713abd9c49447 100644
--- a/doc/src/sgml/ref/create_extension.sgml
+++ b/doc/src/sgml/ref/create_extension.sgml
@@ -90,8 +90,10 @@ CREATE EXTENSION [ IF NOT EXISTS ] extension_name
The name of the extension to be
installed. PostgreSQL will create the
- extension using details from the file
- SHAREDIR/extension/extension_name.control.
+ extension using details from the file extension_name.control,
+ found via the server's extension control path (set by .)
diff --git a/doc/src/sgml/ref/create_foreign_table.sgml b/doc/src/sgml/ref/create_foreign_table.sgml
index dc4b90759901b..009fa46532bbe 100644
--- a/doc/src/sgml/ref/create_foreign_table.sgml
+++ b/doc/src/sgml/ref/create_foreign_table.sgml
@@ -23,7 +23,8 @@ PostgreSQL documentation
CREATE FOREIGN TABLE [ IF NOT EXISTS ] table_name ( [
{ column_namedata_type [ OPTIONS ( option 'value' [, ... ] ) ] [ COLLATE collation ] [ column_constraint [ ... ] ]
- | table_constraint }
+ | table_constraint
+ | LIKE source_table [ like_option ... ] }
[, ... ]
] )
[ INHERITS ( parent_table [, ... ] ) ]
@@ -43,16 +44,23 @@ CREATE FOREIGN TABLE [ IF NOT EXISTS ] table_name
where column_constraint is:
[ CONSTRAINT constraint_name ]
-{ NOT NULL |
+{ NOT NULL [ NO INHERIT ] |
NULL |
CHECK ( expression ) [ NO INHERIT ] |
DEFAULT default_expr |
- GENERATED ALWAYS AS ( generation_expr ) STORED }
+ GENERATED ALWAYS AS ( generation_expr ) [ STORED | VIRTUAL ] }
+[ ENFORCED | NOT ENFORCED ]
and table_constraint is:
[ CONSTRAINT constraint_name ]
-CHECK ( expression ) [ NO INHERIT ]
+{ NOT NULL column_name [ NO INHERIT ] |
+ CHECK ( expression ) [ NO INHERIT ] }
+[ ENFORCED | NOT ENFORCED ]
+
+and like_option is:
+
+{ INCLUDING | EXCLUDING } { COMMENTS | CONSTRAINTS | DEFAULTS | GENERATED | STATISTICS | ALL }
and partition_bound_spec is:
@@ -188,6 +196,111 @@ WITH ( MODULUS numeric_literal, REM
+
+ LIKE source_table [ like_option ... ]
+
+
+ The LIKE clause specifies a table from which
+ the new table automatically copies all column names, their data types,
+ and their not-null constraints.
+
+
+ Unlike INHERITS, 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.
+
+
+ Also unlike INHERITS, columns and
+ constraints copied by LIKE are not merged with similarly
+ named columns and constraints.
+ If the same name is specified explicitly or in another
+ LIKE clause, an error is signaled.
+
+
+ The optional like_option clauses specify
+ which additional properties of the original table to copy. Specifying
+ INCLUDING copies the property, specifying
+ EXCLUDING omits the property.
+ EXCLUDING is the default. If multiple specifications
+ are made for the same kind of object, the last one is used. The
+ available options are:
+
+
+
+ INCLUDING COMMENTS
+
+
+ Comments for the copied columns and constraints will be
+ copied. The default behavior is to exclude comments, resulting in
+ the copied columns and constraints in the new table having no
+ comments.
+
+
+
+
+
+ INCLUDING CONSTRAINTS
+
+
+ CHECK constraints will be copied. No distinction
+ is made between column constraints and table constraints. Not-null
+ constraints are always copied to the new table.
+
+
+
+
+
+ INCLUDING DEFAULTS
+
+
+ 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
+ nextval, may create a functional linkage
+ between the original and new tables.
+
+
+
+
+
+ INCLUDING GENERATED
+
+
+ Any generation expressions of copied column definitions will be
+ copied. By default, new columns will be regular base columns.
+
+
+
+
+
+ INCLUDING STATISTICS
+
+
+ Extended statistics are copied to the new table.
+
+
+
+
+
+ INCLUDING ALL
+
+
+ INCLUDING ALL is an abbreviated form selecting
+ all the available individual options. (It could be useful to write
+ individual EXCLUDING clauses after
+ INCLUDING ALL to select all but some specific
+ options.)
+
+
+
+
+
+
+
+
CONSTRAINT constraint_name
@@ -203,11 +316,16 @@ WITH ( MODULUS numeric_literal, REM
- NOT NULL
+ NOT NULL [ NO INHERIT ]
The column is not allowed to contain null values.
+
+
+ A constraint marked with NO INHERIT will not propagate to
+ child tables.
+
@@ -275,7 +393,7 @@ WITH ( MODULUS numeric_literal, REM
- GENERATED ALWAYS AS ( generation_expr ) STOREDgenerated column
+ GENERATED ALWAYS AS ( generation_expr ) [ STORED | VIRTUAL ]generated column
This clause creates the column as a generated
@@ -284,10 +402,13 @@ WITH ( MODULUS numeric_literal, REM
- The keyword STORED is required to signify that the
+ When VIRTUAL is specified, the column will be
+ computed when it is read. (The foreign-data wrapper will see it as a
+ null value in new rows and may choose to store it as a null value or
+ ignore it altogether.) When STORED is specified, 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.)
+ reading.) VIRTUAL is the default.
@@ -437,6 +558,8 @@ CREATE FOREIGN TABLE measurement_y2016m07
The ability to specify column default values is also
a PostgreSQL extension. Table inheritance, in the form
defined by PostgreSQL, is nonstandard.
+ The LIKE clause, as supported in this command, is
+ nonstandard.
diff --git a/doc/src/sgml/ref/create_index.sgml b/doc/src/sgml/ref/create_index.sgml
index 621bc0e253ceb..b9c679c41e8db 100644
--- a/doc/src/sgml/ref/create_index.sgml
+++ b/doc/src/sgml/ref/create_index.sgml
@@ -387,9 +387,13 @@ CREATE [ UNIQUE ] INDEX [ CONCURRENTLY ] [ [ IF NOT EXISTS ]
The optional WITH clause specifies storage
- parameters 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:
+ parameters 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:
@@ -401,7 +405,7 @@ CREATE [ UNIQUE ] INDEX [ CONCURRENTLY ] [ [ IF NOT EXISTS ]
- The fillfactor for an index is a percentage that determines how full
+ Controls 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).
@@ -488,7 +492,7 @@ CREATE [ UNIQUE ] INDEX [ CONCURRENTLY ] [ [ IF NOT EXISTS ]
- Determines whether the buffered build technique described in
+ Controls whether the buffered build technique described in
is used to build the index. With
OFF buffering is disabled, with ON
it is enabled, and with AUTO it is initially disabled,
@@ -503,7 +507,7 @@ CREATE [ UNIQUE ] INDEX [ CONCURRENTLY ] [ [ IF NOT EXISTS ]
- GIN indexes accept different parameters:
+ GIN indexes accept these parameters:
@@ -515,8 +519,8 @@ CREATE [ UNIQUE ] INDEX [ CONCURRENTLY ] [ [ IF NOT EXISTS ]
- This setting controls usage of the fast update technique described in
- . It is a Boolean parameter:
+ Controls usage of the fast update technique described in
+ .
ON enables fast update, OFF disables it.
The default is ON.
@@ -525,8 +529,9 @@ CREATE [ UNIQUE ] INDEX [ CONCURRENTLY ] [ [ IF NOT EXISTS ]
Turning fastupdate off via ALTER INDEX prevents
future insertions from going into the list of pending index entries,
- but does not in itself flush previous entries. You might want to
- VACUUM the table or call gin_clean_pending_list
+ but does not in itself flush existing entries. You might want to
+ VACUUM the table or call
+ the gin_clean_pending_list
function afterward to ensure the pending list is emptied.
@@ -544,7 +549,8 @@ CREATE [ UNIQUE ] INDEX [ CONCURRENTLY ] [ [ IF NOT EXISTS ]
- Custom parameter.
+ Overrides the global setting of
+ for this index.
This value is specified in kilobytes.
@@ -552,7 +558,7 @@ CREATE [ UNIQUE ] INDEX [ CONCURRENTLY ] [ [ IF NOT EXISTS ]
- BRIN indexes accept different parameters:
+ BRIN indexes accept these parameters:
@@ -580,8 +586,8 @@ CREATE [ UNIQUE ] INDEX [ CONCURRENTLY ] [ [ IF NOT EXISTS ]
Defines whether a summarization run is queued for the previous page
- range whenever an insertion is detected on the next one.
- See for more details.
+ range whenever an insertion is detected on the next one
+ (see for more details).
The default is off.
@@ -808,7 +814,7 @@ Indexes:
leveraging multiple CPUs in order to process the table rows faster.
This feature is known as parallel index
build. For index methods that support building indexes
- in parallel (currently, only B-tree),
+ in parallel (currently, B-tree, GIN, and BRIN),
maintenance_work_mem 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.
diff --git a/doc/src/sgml/ref/create_materialized_view.sgml b/doc/src/sgml/ref/create_materialized_view.sgml
index 0d2fea2b97f0d..62d897931c314 100644
--- a/doc/src/sgml/ref/create_materialized_view.sgml
+++ b/doc/src/sgml/ref/create_materialized_view.sgml
@@ -143,7 +143,9 @@ CREATE MATERIALIZED VIEW [ IF NOT EXISTS ] table_name
A SELECT, TABLE,
or VALUES command. This query will run within a
security-restricted operation; in particular, calls to functions that
- themselves create temporary tables will fail.
+ themselves create temporary tables will fail. Also, while the query is
+ running, the is temporarily changed to
+ pg_catalog, pg_temp.
diff --git a/doc/src/sgml/ref/create_opclass.sgml b/doc/src/sgml/ref/create_opclass.sgml
index f1d6a4cbbe286..2d560b68658cf 100644
--- a/doc/src/sgml/ref/create_opclass.sgml
+++ b/doc/src/sgml/ref/create_opclass.sgml
@@ -269,14 +269,6 @@ CREATE OPERATOR CLASS name [ DEFAUL
is likely to be inlined into the calling query, which will prevent
the optimizer from recognizing that the query matches an index.
-
-
- Before PostgreSQL 8.4, the OPERATOR
- clause could include a RECHECK option. This is no longer
- supported because whether an index operator is lossy is now
- determined on-the-fly at run time. This allows efficient handling of
- cases where an operator might or might not be lossy.
-
diff --git a/doc/src/sgml/ref/create_operator.sgml b/doc/src/sgml/ref/create_operator.sgml
index 3553d36454185..d2ffb1b2a500f 100644
--- a/doc/src/sgml/ref/create_operator.sgml
+++ b/doc/src/sgml/ref/create_operator.sgml
@@ -23,7 +23,7 @@ PostgreSQL documentation
CREATE OPERATOR name (
{FUNCTION|PROCEDURE} = function_name
- [, LEFTARG = left_type ] [, RIGHTARG = right_type ]
+ [, LEFTARG = left_type ] , RIGHTARG = right_type
[, COMMUTATOR = com_op ] [, NEGATOR = neg_op ]
[, RESTRICT = res_proc ] [, JOIN = join_proc ]
[, HASHES ] [, MERGES ]
@@ -88,8 +88,8 @@ CREATE OPERATOR name (
For binary operators, both LEFTARG and
- RIGHTARG must be defined. For prefix operators only
- RIGHTARG should be defined.
+ RIGHTARG must be defined. For prefix operators, only
+ RIGHTARG must be defined.
The function_name
function must have been previously defined using CREATE
FUNCTION and must be defined to accept the correct number
diff --git a/doc/src/sgml/ref/create_publication.sgml b/doc/src/sgml/ref/create_publication.sgml
index fd9c5deac95dc..802630f2df116 100644
--- a/doc/src/sgml/ref/create_publication.sgml
+++ b/doc/src/sgml/ref/create_publication.sgml
@@ -89,8 +89,11 @@ CREATE PUBLICATION name
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
+ The column list can contain stored generated columns as well. If the
+ column list is omitted, the publication will replicate all non-generated
+ columns (including any added in the future) by default. Stored generated
+ columns can also be replicated if publish_generated_columns
+ is set to stored. Specifying a column list has no
effect on TRUNCATE commands. See
for details about column
lists.
@@ -188,6 +191,42 @@ CREATE PUBLICATION name
+
+ publish_generated_columns (enum)
+
+
+ Specifies whether the generated columns present in the tables
+ associated with the publication should be replicated. Possible values
+ are none and stored.
+
+
+
+ The default is none meaning the generated
+ columns present in the tables associated with publication will not be
+ replicated.
+
+
+
+ If set to stored, the stored generated columns
+ present in the tables associated with publication will be replicated.
+
+
+
+
+ If the subscriber is from a release prior to 18, then initial table
+ synchronization won't copy generated columns even if parameter
+ publish_generated_columns is stored
+ in the publisher.
+
+
+
+
+ See for more details about
+ logical replication of generated columns.
+
+
+
+
publish_via_partition_root (boolean)
@@ -290,6 +329,14 @@ CREATE PUBLICATION name
system columns.
+
+ The generated columns that are part of REPLICA IDENTITY
+ must be published explicitly either by listing them in the column list or
+ by enabling the publish_generated_columns option, in
+ order for UPDATE and DELETE operations
+ to be published.
+
+
The row filter on a table becomes redundant if
FOR TABLES IN SCHEMA is specified and the table
diff --git a/doc/src/sgml/ref/create_role.sgml b/doc/src/sgml/ref/create_role.sgml
index 27e48da12a20f..cee23b1ea6b4d 100644
--- a/doc/src/sgml/ref/create_role.sgml
+++ b/doc/src/sgml/ref/create_role.sgml
@@ -71,7 +71,7 @@ in sync when changing the above synopsis!
During role creation it is possible to immediately assign the newly created
role to be a member of an existing role, and also assign existing roles
to be members of the newly created role. The rules for which initial
- role membership options are enabled described below in the
+ role membership options are enabled are described below in the
IN ROLE, ROLE, and
ADMIN clauses. The
command has fine-grained option control during membership creation,
@@ -273,6 +273,14 @@ in sync when changing the above synopsis!
different format). This allows reloading of encrypted passwords
during dump/restore.
+
+
+ Support for MD5-encrypted passwords is deprecated and will be removed
+ in a future release of PostgreSQL. Refer
+ to for details about migrating to
+ another password type.
+
+
diff --git a/doc/src/sgml/ref/create_sequence.sgml b/doc/src/sgml/ref/create_sequence.sgml
index 34e9084b5ccbf..1e283f13d15c6 100644
--- a/doc/src/sgml/ref/create_sequence.sgml
+++ b/doc/src/sgml/ref/create_sequence.sgml
@@ -25,7 +25,9 @@ CREATE [ { TEMPORARY | TEMP } | UNLOGGED ] SEQUENCE [ IF NOT EXISTS ] data_type ]
[ INCREMENT [ BY ] increment ]
[ MINVALUE minvalue | NO MINVALUE ] [ MAXVALUE maxvalue | NO MAXVALUE ]
- [ START [ WITH ] start ] [ CACHE cache ] [ [ NO ] CYCLE ]
+ [ [ NO ] CYCLE ]
+ [ START [ WITH ] start ]
+ [ CACHE cache ]
[ OWNED BY { table_name.column_name | NONE } ]
@@ -193,6 +195,31 @@ SELECT * FROM name;
+
+ CYCLE
+ NO CYCLE
+
+
+ The CYCLE option allows the sequence to wrap
+ around when the maxvalue or minvalue has been reached by an
+ ascending or descending sequence respectively. If the limit is
+ reached, the next number generated will be the minvalue or maxvalue, respectively.
+
+
+
+ If NO CYCLE is specified, any calls to
+ nextval after the sequence has reached its
+ maximum value will return an error. If neither
+ CYCLE or NO CYCLE are
+ specified, NO CYCLE is the default.
+
+
+
+
start
@@ -221,31 +248,6 @@ SELECT * FROM name;
-
- CYCLE
- NO CYCLE
-
-
- The CYCLE option allows the sequence to wrap
- around when the maxvalue or minvalue has been reached by an
- ascending or descending sequence respectively. If the limit is
- reached, the next number generated will be the minvalue or maxvalue, respectively.
-
-
-
- If NO CYCLE is specified, any calls to
- nextval after the sequence has reached its
- maximum value will return an error. If neither
- CYCLE or NO CYCLE are
- specified, NO CYCLE is the default.
-
-
-
-
OWNED BYtable_name.column_nameOWNED BY NONE
diff --git a/doc/src/sgml/ref/create_subscription.sgml b/doc/src/sgml/ref/create_subscription.sgml
index 740b7d9421041..fc3144373110f 100644
--- a/doc/src/sgml/ref/create_subscription.sgml
+++ b/doc/src/sgml/ref/create_subscription.sgml
@@ -169,7 +169,9 @@ CREATE SUBSCRIPTION subscription_name
Name of the publisher's replication slot to use. The default is
- to use the name of the subscription for the slot name.
+ to use the name of the subscription for the slot name. The name cannot
+ be pg_conflict_detection as it is reserved for the
+ conflict detection.
@@ -185,7 +187,7 @@ CREATE SUBSCRIPTION subscription_name
When setting slot_name to a valid name and
- create_slot to false, the
+ create_slot to false, the
failover property value of the named slot may
differ from the counterpart failover parameter
specified in the subscription. Always ensure the slot property
@@ -271,11 +273,23 @@ CREATE SUBSCRIPTION subscription_name
Specifies whether to enable streaming of in-progress transactions
- for this subscription. The default value is off,
- meaning all transactions are fully decoded on the publisher and only
- then sent to the subscriber as a whole.
+ for this subscription. The default value is parallel,
+ meaning incoming changes are directly applied via one of the parallel
+ apply workers, if available. If no parallel apply worker is free to
+ handle streaming transactions then the changes are written to
+ temporary files and applied after the transaction is committed. Note
+ that if an error happens in a parallel apply worker, the finish LSN
+ of the remote transaction might not be reported in the server log.
+
+
+ There is a risk of deadlock when the schemas of the publisher and
+ subscriber differ, although such cases are rare. The apply worker
+ is equipped to retry these transactions automatically.
+
+
+
If set to on, the incoming changes are written to
temporary files and then applied only after the transaction is
@@ -283,13 +297,8 @@ CREATE SUBSCRIPTION subscription_name
- If set to parallel, incoming changes are directly
- applied via one of the parallel apply workers, if available. If no
- parallel apply worker is free to handle streaming transactions then
- the changes are written to temporary files and applied after the
- transaction is committed. Note that if an error happens in a
- parallel apply worker, the finish LSN of the remote transaction
- might not be reported in the server log.
+ If set to off, all transactions are fully decoded
+ on the publisher and only then sent to the subscriber as a whole.
@@ -428,6 +437,131 @@ CREATE SUBSCRIPTION subscription_name
+
+
+ retain_dead_tuples (boolean)
+
+
+ Specifies whether the information (e.g., dead tuples, commit
+ timestamps, and origins) required for conflict detection on the
+ subscriber is retained. The default is false.
+ If set to true, the detection of
+ is enabled, and a physical
+ replication slot named pg_conflict_detection
+ is created on the subscriber to prevent the information for detecting
+ conflicts from being removed.
+
+
+
+ Note that the information useful for conflict detection is retained
+ only after the creation of the slot. You can verify the existence of
+ this slot by querying pg_replication_slots.
+ And even if multiple subscriptions on one node enable this option,
+ only one replication slot will be created. Also,
+ wal_level must be set to replica
+ or higher to allow the replication slot to be used.
+
+
+
+
+ Note that the information for conflict detection cannot be purged if
+ the subscription is disabled; thus, the information will accumulate
+ until the subscription is enabled. To prevent excessive accumulation,
+ it is recommended to disable retain_dead_tuples
+ if the subscription will be inactive for an extended period.
+
+
+
+ Additionally when enabling retain_dead_tuples for
+ conflict detection in logical replication, it is important to design the
+ replication topology to balance data retention requirements with
+ overall system performance. This option provides minimal performance
+ overhead when applied appropriately. The following scenarios illustrate
+ effective usage patterns when enabling this option.
+
+
+
+ a. Large Tables with Bidirectional Writes:
+ For large tables subject to concurrent writes on both publisher and
+ subscriber nodes, publishers can define row filters when creating
+ publications to segment data. This allows multiple subscriptions
+ to replicate exclusive subsets of the table in parallel, optimizing
+ the throughput.
+
+
+
+ b. Write-Enabled Subscribers:
+ If a subscriber node is expected to perform write operations, replication
+ can be structured using multiple publications and subscriptions. By
+ distributing tables across these publications, the workload is spread among
+ several apply workers, improving concurrency and reducing contention.
+
+
+
+ c. Read-Only Subscribers:
+ In configurations involving single or multiple publisher nodes
+ performing concurrent write operations, read-only subscriber nodes may
+ replicate changes without seeing a performance impact if it does index
+ scan. However, if the subscriber is impacted due to replication lag or
+ scan performance (say due to sequential scans), it needs to follow one
+ of the two previous strategies to distribute the workload on the
+ subscriber.
+
+
+
+
+ This option cannot be enabled if the publisher is a physical standby.
+
+
+
+ Enabling this option ensures retention of information useful for
+ conflict detection solely for changes occurring locally on the
+ publisher. For the changes originating from different origins,
+ reliable conflict detection cannot be guaranteed.
+
+
+
+
+
+ max_retention_duration (integer)
+
+
+ Maximum duration in milliseconds for which this subscription's apply worker
+ is allowed to retain the information useful for conflict detection when
+ retain_dead_tuples is enabled. The default value
+ is 0, indicating that the information is retained
+ until it is no longer needed for detection purposes.
+
+
+ The information useful for conflict detection is no longer retained if
+ all apply workers associated with the subscriptions, where
+ retain_dead_tuples is enabled, confirm that the
+ retention duration has exceeded the
+ max_retention_duration set within the corresponding
+ subscription. The retention will not be automatically resumed unless a
+ new subscription is created with retain_dead_tuples =
+ true, or the user manually re-enables
+ retain_dead_tuples.
+
+
+ Note that overall retention will not stop if other subscriptions that
+ have a value greater than 0 for this parameter have not exceeded it,
+ or if they set this option to 0.
+
+
+ This option is effective only when
+ retain_conflict_info is enabled and the apply
+ worker associated with the subscription is active.
+
+
+
+ Note that setting a non-zero value for this option could lead to
+ information for conflict detection being removed prematurely,
+ potentially resulting in incorrect conflict detection.
+
+
+
+
@@ -474,7 +608,8 @@ CREATE SUBSCRIPTION subscription_name
If any table in the publication has a WHERE clause, rows
for which the expression
- evaluates to false or null will not be published. If the subscription has
+ 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 WHERE clauses, a row will be published if any
of the expressions (referring to that publish operation) are satisfied. In
@@ -526,12 +661,14 @@ CREATE SUBSCRIPTION subscription_name
# substitute <pub-names> below with your publication name(s) to be queried
SELECT DISTINCT PT.schemaname, PT.tablename
-FROM pg_publication_tables PT,
+FROM pg_publication_tables PT
+ JOIN pg_class C ON (C.relname = PT.tablename)
+ JOIN pg_namespace N ON (N.nspname = PT.schemaname),
pg_subscription_rel PS
- JOIN pg_class C ON (C.oid = PS.srrelid)
- JOIN pg_namespace N ON (N.oid = C.relnamespace)
-WHERE N.nspname = PT.schemaname AND
- C.relname = PT.tablename AND
+WHERE C.relnamespace = N.oid AND
+ (PS.srrelid = C.oid OR
+ C.oid IN (SELECT relid FROM pg_partition_ancestors(PS.srrelid) UNION
+ SELECT relid FROM pg_partition_tree(PS.srrelid))) AND
PT.pubname IN (<pub-names>);
diff --git a/doc/src/sgml/ref/create_table.sgml b/doc/src/sgml/ref/create_table.sgml
index f19306e7760cd..dc000e913c143 100644
--- a/doc/src/sgml/ref/create_table.sgml
+++ b/doc/src/sgml/ref/create_table.sgml
@@ -61,29 +61,30 @@ CREATE [ [ GLOBAL | LOCAL ] { TEMPORARY | TEMP } | UNLOGGED ] TABLE [ IF NOT EXI
where column_constraint is:
[ CONSTRAINT constraint_name ]
-{ NOT NULL |
+{ NOT NULL [ NO INHERIT ] |
NULL |
CHECK ( expression ) [ NO INHERIT ] |
DEFAULT default_expr |
- GENERATED ALWAYS AS ( generation_expr ) STORED |
+ GENERATED ALWAYS AS ( generation_expr ) [ STORED | VIRTUAL ] |
GENERATED { ALWAYS | BY DEFAULT } AS IDENTITY [ ( sequence_options ) ] |
UNIQUE [ NULLS [ NOT ] DISTINCT ] index_parameters |
PRIMARY KEY index_parameters |
REFERENCES reftable [ ( refcolumn ) ] [ MATCH FULL | MATCH PARTIAL | MATCH SIMPLE ]
[ ON DELETE referential_action ] [ ON UPDATE referential_action ] }
-[ DEFERRABLE | NOT DEFERRABLE ] [ INITIALLY DEFERRED | INITIALLY IMMEDIATE ]
+[ DEFERRABLE | NOT DEFERRABLE ] [ INITIALLY DEFERRED | INITIALLY IMMEDIATE ] [ ENFORCED | NOT ENFORCED ]
and table_constraint is:
[ CONSTRAINT constraint_name ]
{ CHECK ( expression ) [ NO INHERIT ] |
- UNIQUE [ NULLS [ NOT ] DISTINCT ] ( column_name [, ... ] ) index_parameters |
- PRIMARY KEY ( column_name [, ... ] ) index_parameters |
+ NOT NULL column_name [ NO INHERIT ] |
+ UNIQUE [ NULLS [ NOT ] DISTINCT ] ( column_name [, ... ] [, column_name WITHOUT OVERLAPS ] ) index_parameters |
+ PRIMARY KEY ( column_name [, ... ] [, column_name WITHOUT OVERLAPS ] ) index_parameters |
EXCLUDE [ USING index_method ] ( exclude_element WITH operator [, ... ] ) index_parameters [ WHERE ( predicate ) ] |
- FOREIGN KEY ( column_name [, ... ] ) REFERENCES reftable [ ( refcolumn [, ... ] ) ]
+ FOREIGN KEY ( column_name [, ... ] [, PERIOD column_name ] ) REFERENCES reftable [ ( refcolumn [, ... ] [, PERIOD refcolumn ] ) ]
[ MATCH FULL | MATCH PARTIAL | MATCH SIMPLE ] [ ON DELETE referential_action ] [ ON UPDATE referential_action ] }
-[ DEFERRABLE | NOT DEFERRABLE ] [ INITIALLY DEFERRED | INITIALLY IMMEDIATE ]
+[ DEFERRABLE | NOT DEFERRABLE ] [ INITIALLY DEFERRED | INITIALLY IMMEDIATE ] [ ENFORCED | NOT ENFORCED ]
and like_option is:
@@ -220,6 +221,10 @@ WITH ( MODULUS numeric_literal, REM
If this is specified, any sequences created together with the unlogged
table (for identity or serial columns) are also created as unlogged.
+
+
+ This form is not supported for partitioned tables.
+
@@ -249,18 +254,18 @@ WITH ( MODULUS numeric_literal, REM
Creates a typed table, 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 DROP TYPE ... CASCADE).
+ structure from the specified stand-alone composite type (that is,
+ one created using ) though it still
+ produces a new composite type as well. The table will have a
+ dependency on the referenced type, meaning that cascaded alter and
+ drop actions on that type will propagate to the table.
- 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 CREATE TABLE command.
+ A typed table always has the same column names and data types as the
+ type it is derived from, so you cannot specify additional columns.
But the CREATE TABLE command can add defaults
- and constraints to the table and can specify storage parameters.
+ and constraints to the table, as well as specify storage parameters.
@@ -442,11 +447,6 @@ WITH ( MODULUS numeric_literal, REM
the values in the new row, an error will be reported.
-
- Partitioned tables do not support EXCLUDE constraints;
- however, you can define these constraints on individual partitions.
-
-
See for more discussion on table
partitioning.
@@ -720,8 +720,9 @@ WITH ( MODULUS numeric_literal, REM
INCLUDING GENERATED
- Any generation expressions of copied column definitions will be
- copied. By default, new columns will be regular base columns.
+ Any generation expressions as well as the stored/virtual choice of
+ copied column definitions will be copied. By default, new columns
+ will be regular base columns.
@@ -814,11 +815,16 @@ WITH ( MODULUS numeric_literal, REM
- NOT NULL
+ NOT NULL [ NO INHERIT ]
The column is not allowed to contain null values.
+
+
+ A constraint marked with NO INHERIT will not propagate to
+ child tables.
+
@@ -897,7 +903,7 @@ WITH ( MODULUS numeric_literal, REM
- GENERATED ALWAYS AS ( generation_expr ) STOREDgenerated column
+ GENERATED ALWAYS AS ( generation_expr ) [ STORED | VIRTUAL ]generated column
This clause creates the column as a generated
@@ -906,8 +912,11 @@ WITH ( MODULUS numeric_literal, REM
- The keyword STORED is required to signify that the
- column will be computed on write and will be stored on disk.
+ When VIRTUAL is specified, the column will be
+ computed when it is read, and it will not occupy any storage. When
+ STORED is specified, the column will be computed on
+ write and will be stored on disk. VIRTUAL is the
+ default.
@@ -915,6 +924,15 @@ WITH ( MODULUS numeric_literal, REM
not other generated columns. Any functions and operators used must be
immutable. References to other tables are not allowed.
+
+
+ A virtual generated column cannot have a user-defined type, and the
+ generation expression of a virtual generated column must not reference
+ user-defined functions or types, that is, it can only use built-in
+ functions or types. This applies also indirectly, such as for functions
+ or types that underlie operators or casts. (This restriction does not
+ exist for stored generated columns.)
+
@@ -924,8 +942,8 @@ WITH ( MODULUS numeric_literal, REM
This clause creates the column as an identity
column. 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.
+ and in newly-inserted rows the column will automatically have values
+ from the sequence assigned to it.
Such a column is implicitly NOT NULL.
@@ -955,16 +973,23 @@ WITH ( MODULUS numeric_literal, REM
- The optional sequence_options clause can be
- used to override the options of the sequence.
- See for details.
+ The optional sequence_options clause can
+ be used to override the parameters of the sequence. The available
+ options include those shown for ,
+ plus SEQUENCE NAME name,
+ LOGGED, and UNLOGGED, which
+ allow selection of the name and persistence level of the
+ sequence. Without SEQUENCE NAME, the system
+ chooses an unused name for the sequence.
+ Without LOGGED or UNLOGGED,
+ the sequence will have the same persistence level as the table.
UNIQUE [ NULLS [ NOT ] DISTINCT ] (column constraint)
- UNIQUE [ NULLS [ NOT ] DISTINCT ] ( column_name [, ... ] )
+ UNIQUE [ NULLS [ NOT ] DISTINCT ] ( column_name [, ... ] [, column_name WITHOUT OVERLAPS ] )INCLUDE ( column_name [, ...]) (table constraint)
@@ -978,6 +1003,27 @@ WITH ( MODULUS numeric_literal, REM
of these columns.
+
+ If the WITHOUT OVERLAPS option is specified for the
+ last column, then that column is checked for overlaps instead of
+ equality. In that case, the other columns of the constraint will allow
+ duplicates so long as the duplicates don't overlap in the
+ WITHOUT OVERLAPS column. (This is sometimes called a
+ temporal key, if the column is a range of dates or timestamps, but
+ PostgreSQL allows ranges over any base type.)
+ In effect, such a constraint is enforced with an EXCLUDE
+ constraint rather than a UNIQUE constraint. So for
+ example UNIQUE (id, valid_at WITHOUT OVERLAPS) behaves
+ like EXCLUDE USING GIST (id WITH =, valid_at WITH
+ &&). The WITHOUT OVERLAPS column
+ must have a range or multirange type. Empty ranges/multiranges are
+ not permitted. The non-WITHOUT OVERLAPS columns of
+ the constraint can be any type that can be compared for equality in a
+ GiST index. By default, only range types are supported, but you can use
+ other types by adding the extension (which
+ is the expected way to use this feature).
+
+
For the purpose of a unique constraint, null values are not
considered equal, unless NULLS NOT DISTINCT is
@@ -1000,8 +1046,10 @@ WITH ( MODULUS numeric_literal, REM
Adding a unique constraint will automatically create a unique btree
- index on the column or group of columns used in the constraint. The
- created index has the same name as the unique constraint.
+ index on the column or group of columns used in the constraint. But if
+ the constraint includes a WITHOUT OVERLAPS clause, it
+ will use a GiST index. The created index has the same name as the
+ unique constraint.
@@ -1019,7 +1067,7 @@ WITH ( MODULUS numeric_literal, REM
PRIMARY KEY (column constraint)
- PRIMARY KEY ( column_name [, ... ] )
+ PRIMARY KEY ( column_name [, ... ] [, column_name WITHOUT OVERLAPS ] )INCLUDE ( column_name [, ...]) (table constraint)
@@ -1054,8 +1102,8 @@ WITH ( MODULUS numeric_literal, REM
Adding a PRIMARY KEY constraint will automatically
create a unique btree index on the column or group of columns used in
- the constraint. That index has the same name as the primary key
- constraint.
+ the constraint, or GiST if WITHOUT OVERLAPS was
+ specified.
@@ -1118,14 +1166,26 @@ WITH ( MODULUS numeric_literal, REM
exclusion constraint on a subset of the table; internally this creates a
partial index. Note that parentheses are required around the predicate.
+
+
+ When establishing an exclusion 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. Additionally,
+ those columns must be compared using the equality operator. These
+ restrictions ensure that potentially-conflicting rows will exist in the
+ same partition. The constraint may also refer to other columns which
+ are not a part of any partition key, which can be compared using any
+ appropriate operator.
+ REFERENCES reftable [ ( refcolumn ) ] [ MATCH matchtype ] [ ON DELETE referential_action ] [ ON UPDATE referential_action ] (column constraint)
- FOREIGN KEY ( column_name [, ... ] )
- REFERENCES reftable [ ( refcolumn [, ... ] ) ]
+ FOREIGN KEY ( column_name [, ... ] [, PERIOD column_name ] )
+ REFERENCES reftable [ ( refcolumn [, ... ] [, PERIOD refcolumn ] ) ]
[ MATCH matchtype ]
[ ON DELETE referential_action ]
[ ON UPDATE referential_action ]
@@ -1141,7 +1201,39 @@ WITH ( MODULUS numeric_literal, REM
primary key of the reftable
is used. Otherwise, the refcolumn
list must refer to the columns of a non-deferrable unique or primary key
- constraint or be the columns of a non-partial unique index. The user
+ constraint or be the columns of a non-partial unique index.
+
+
+
+ If the last column is marked with PERIOD, it is
+ treated in a special way. While the non-PERIOD
+ columns are compared for equality (and there must be at least one of
+ them), the PERIOD column is not. Instead, the
+ constraint is considered satisfied if the referenced table has matching
+ records (based on the non-PERIOD parts of the key)
+ whose combined PERIOD values completely cover the
+ referencing record's. In other words, the reference must have a
+ referent for its entire duration. This column must be a range or
+ multirange type. In addition, the referenced table must have a primary
+ key or unique constraint declared with WITHOUT
+ OVERLAPS. Finally, if the foreign key has a PERIOD
+ column_name specification
+ the corresponding refcolumn,
+ if present, must also be marked PERIOD. If the
+ refcolumn clause is omitted,
+ and thus the reftable's primary key constraint chosen, the primary key
+ must have its final column marked WITHOUT OVERLAPS.
+
+
+
+ For each pair of referencing and referenced column, if they are of a
+ collatable data type, then the collations must either be both
+ deterministic or else both the same. This ensures that both columns
+ have a consistent notion of equality.
+
+
+
+ The user
must have REFERENCES permission on the referenced
table (either the whole table, or the specific referenced columns). The
addition of a foreign key constraint requires a
@@ -1176,17 +1268,16 @@ WITH ( MODULUS numeric_literal, REM
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
- NO ACTION check cannot be deferred, even if
- the constraint is declared deferrable. There are the following possible
- actions for each clause:
+ changed, no action is done. Referential actions are executed as part of
+ the data changing command, even if the constraint is deferred. There
+ are the following possible actions for each clause:
NO ACTION
- Produce an error indicating that the deletion or update
+ Produce an error if 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
@@ -1199,10 +1290,17 @@ WITH ( MODULUS numeric_literal, REM
RESTRICT
- Produce an error indicating that the deletion or update
- would create a foreign key constraint violation.
- This is the same as NO ACTION except that
- the check is not deferrable.
+ Produce an error if a row to be deleted or updated matches a row in
+ the referencing table. This prevents the action even if the state
+ after the action would not violate the foreign key constraint. In
+ particular, it prevents updates of referenced rows to values that
+ are distinct but compare as equal. (But it does not prevent
+ no-op updates that update a column to the same
+ value.)
+
+
+
+ In a temporal foreign key, this option is not supported.
@@ -1215,6 +1313,10 @@ WITH ( MODULUS numeric_literal, REM
values of the referencing column(s) to the new values of the
referenced columns, respectively.
+
+
+ In a temporal foreign key, this option is not supported.
+
@@ -1226,6 +1328,10 @@ WITH ( MODULUS numeric_literal, REM
referencing columns, to null. A subset of columns can only be
specified for ON DELETE actions.
+
+
+ In a temporal foreign key, this option is not supported.
+
@@ -1239,6 +1345,10 @@ WITH ( MODULUS numeric_literal, REM
(There must be a row in the referenced table matching the default
values, if they are not null, or the operation will fail.)
+
+
+ In a temporal foreign key, this option is not supported.
+
@@ -1291,6 +1401,36 @@ WITH ( MODULUS numeric_literal, REM
+
+ ENFORCED
+ NOT ENFORCED
+
+
+ When the constraint is ENFORCED, then the database
+ system will ensure that the constraint is satisfied, by checking the
+ constraint at appropriate times (after each statement or at the end of
+ the transaction, as appropriate). That is the default. If the
+ constraint is NOT ENFORCED, the database system will
+ not check the constraint. It is then up to the application code to
+ ensure that the constraints are satisfied. The database system might
+ still assume that the data actually satisfies the constraint for
+ optimization decisions where this does not affect the correctness of the
+ result.
+
+
+
+ NOT ENFORCED constraints can be useful as
+ documentation if the actual checking of the constraint at run time is
+ too expensive.
+
+
+
+ This is currently only supported for foreign key and CHECK
+ constraints.
+
+
+
+
USING method
@@ -1563,20 +1703,16 @@ WITH ( MODULUS numeric_literal, REM
vacuum_truncate, toast.vacuum_truncate (boolean)
- vacuum_truncate storage parameter
+ vacuum_truncate
+ storage parameter
- Enables or disables vacuum to try to truncate off any empty pages
- at the end of this table. The default value is true.
- If true, VACUUM and
- autovacuum do the truncation and the disk space for
- the truncated pages is returned to the operating system.
- Note that the truncation requires ACCESS EXCLUSIVE
- lock on the table. The TRUNCATE parameter
- of VACUUM, if specified, overrides the value
- of this option.
+ Per-table value for parameter. The
+ TRUNCATE parameter of
+ VACUUM, if
+ specified, overrides the value of this option.
@@ -1596,6 +1732,21 @@ WITH ( MODULUS numeric_literal, REM
+
+ autovacuum_vacuum_max_threshold, toast.autovacuum_vacuum_max_threshold (integer)
+
+ autovacuum_vacuum_max_threshold
+ storage parameter
+
+
+
+
+ Per-table value for
+ parameter.
+
+
+
+
autovacuum_vacuum_scale_factor, toast.autovacuum_vacuum_scale_factor (floating point)
@@ -1815,6 +1966,21 @@ WITH ( MODULUS numeric_literal, REM
+
+ vacuum_max_eager_freeze_failure_rate, toast.vacuum_max_eager_freeze_failure_rate (floating point)
+
+ vacuum_max_eager_freeze_failure_rate
+ storage parameter
+
+
+
+
+ Per-table value for
+ parameter.
+
+
+
+
user_catalog_table (boolean)
@@ -2327,13 +2493,6 @@ CREATE TABLE cities_partdef
constraint, and index names must be unique across all relations within
the same schema.
-
-
- Currently, PostgreSQL does not record names
- for not-null constraints at all, so they are not
- subject to the uniqueness restriction. This might change in a future
- release.
-
@@ -2380,9 +2539,9 @@ CREATE TABLE cities_partdef
Generated Columns
- The option STORED is not standard but is also used by
- other SQL implementations. The SQL standard does not specify the storage
- of generated columns.
+ The options STORED and VIRTUAL are
+ not standard but are also used by other SQL implementations. The SQL
+ standard does not specify the storage of generated columns.
diff --git a/doc/src/sgml/ref/create_tablespace.sgml b/doc/src/sgml/ref/create_tablespace.sgml
index 9d5ab025261da..b77e774c53f92 100644
--- a/doc/src/sgml/ref/create_tablespace.sgml
+++ b/doc/src/sgml/ref/create_tablespace.sgml
@@ -110,7 +110,7 @@ CREATE TABLESPACE tablespace_name
and maintenance_io_concurrency.
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
+ that tablespace, and how many concurrent I/Os are issued, as established
by the configuration parameters of the
same name (see ,
,
diff --git a/doc/src/sgml/ref/create_trigger.sgml b/doc/src/sgml/ref/create_trigger.sgml
index 982ab6f3ee450..0d8d463479bc1 100644
--- a/doc/src/sgml/ref/create_trigger.sgml
+++ b/doc/src/sgml/ref/create_trigger.sgml
@@ -29,7 +29,7 @@ PostgreSQL documentation
CREATE [ OR REPLACE ] [ CONSTRAINT ] TRIGGER name { BEFORE | AFTER | INSTEAD OF } { event [ OR ... ] }
ON table_name
[ FROM referenced_table_name ]
- [ NOT DEFERRABLE | [ DEFERRABLE ] [ INITIALLY IMMEDIATE | INITIALLY DEFERRED ] ]
+ [ NOT DEFERRABLE | [ DEFERRABLE ] [ INITIALLY IMMEDIATE | INITIALLY DEFERRED ] ] [ ENFORCED ]
[ REFERENCING { { OLD | NEW } TABLE [ AS ] transition_relation_name } [ ... ] ]
[ FOR [ EACH ] { ROW | STATEMENT } ]
[ WHEN ( condition ) ]
@@ -197,9 +197,11 @@ CREATE [ OR REPLACE ] [ CONSTRAINT ] TRIGGER name
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 AFTER trigger that is not a constraint trigger; also, if
- the trigger is an UPDATE trigger, it must not specify
- a column_name list.
+ an AFTER trigger on a plain table (not a foreign table).
+ The trigger should not be a constraint trigger. Also, if the trigger is
+ an UPDATE trigger, it must not specify
+ a column_name list when using
+ this option.
OLD TABLE may only be specified once, and only for a trigger
that can fire on UPDATE or DELETE; it creates a
transition relation containing the before-images of all rows
@@ -321,6 +323,15 @@ UPDATE OF column_name1 [, column_name2
+
+ ENFORCED
+
+
+ This is a noise word. Constraint triggers are always enforced.
+
+
+
+
REFERENCING
diff --git a/doc/src/sgml/ref/createdb.sgml b/doc/src/sgml/ref/createdb.sgml
index 5c4e0465ed9da..2ccbe13f39008 100644
--- a/doc/src/sgml/ref/createdb.sgml
+++ b/doc/src/sgml/ref/createdb.sgml
@@ -136,7 +136,8 @@ PostgreSQL documentation
- Specifies the LC_COLLATE setting to be used in this database.
+ Specifies the LC_COLLATE setting to be used in this database (ignored
+ unless the locale provider is libc).
diff --git a/doc/src/sgml/ref/delete.sgml b/doc/src/sgml/ref/delete.sgml
index 0b6fa0051235a..29649f6afd65c 100644
--- a/doc/src/sgml/ref/delete.sgml
+++ b/doc/src/sgml/ref/delete.sgml
@@ -25,7 +25,8 @@ PostgreSQL documentation
DELETE FROM [ ONLY ] table_name [ * ] [ [ AS ] alias ]
[ USING from_item [, ...] ]
[ WHERE condition | WHERE CURRENT OF cursor_name ]
- [ RETURNING * | output_expression [ [ AS ] output_name ] [, ...] ]
+ [ RETURNING [ WITH ( { OLD | NEW } AS output_alias [, ...] ) ]
+ { * | output_expression [ [ AS ] output_name ] } [, ...] ]
@@ -160,6 +161,26 @@ DELETE FROM [ ONLY ] table_name [ *
+
+ output_alias
+
+
+ An optional substitute name for OLD or
+ NEW rows in the RETURNING list.
+
+
+
+ By default, old values from the target table can be returned by writing
+ OLD.column_name
+ or OLD.*, and new values can be returned by writing
+ NEW.column_name
+ or NEW.*. When an alias is provided, these names are
+ hidden and the old or new rows must be referred to using the alias.
+ For example RETURNING WITH (OLD AS o, NEW AS n) o.*, n.*.
+
+
+
+
output_expression
@@ -170,6 +191,23 @@ DELETE FROM [ ONLY ] table_name [ *
or table(s) listed in USING.
Write * to return all columns.
+
+
+ A column name or * may be qualified using
+ OLD or NEW, or the corresponding
+ output_alias for
+ OLD or NEW, to cause old or new
+ values to be returned. An unqualified column name, or
+ *, or a column name or * qualified
+ using the target table name or alias will return old values.
+
+
+
+ For a simple DELETE, all new values will be
+ NULL. However, if an ON DELETE
+ rule causes an INSERT or UPDATE
+ to be executed instead, the new values may be non-NULL.
+
diff --git a/doc/src/sgml/ref/drop_extension.sgml b/doc/src/sgml/ref/drop_extension.sgml
index 484e5d9b11a15..4266c6d1ceb31 100644
--- a/doc/src/sgml/ref/drop_extension.sgml
+++ b/doc/src/sgml/ref/drop_extension.sgml
@@ -82,7 +82,7 @@ DROP EXTENSION [ IF EXISTS ] name [
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.
+ explicitly dependent routines, depend on them. This is the default.
diff --git a/doc/src/sgml/ref/drop_owned.sgml b/doc/src/sgml/ref/drop_owned.sgml
index efda01a39e88b..46e1c229ec0fb 100644
--- a/doc/src/sgml/ref/drop_owned.sgml
+++ b/doc/src/sgml/ref/drop_owned.sgml
@@ -33,7 +33,7 @@ DROP OWNED BY { name | CURRENT_ROLE
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.
+ parameters, or other roles) will also be revoked.
diff --git a/doc/src/sgml/ref/explain.sgml b/doc/src/sgml/ref/explain.sgml
index db9d3a8549add..6dda680aa0de8 100644
--- a/doc/src/sgml/ref/explain.sgml
+++ b/doc/src/sgml/ref/explain.sgml
@@ -201,8 +201,8 @@ ROLLBACK;
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. This parameter defaults to
- FALSE.
+ format, only non-zero values are printed. Buffers information is
+ automatically included when ANALYZE is used.
@@ -240,8 +240,9 @@ ROLLBACK;
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.
+ number of records, number of full page images (fpi), the amount of WAL
+ generated in bytes and the number of times the WAL buffers became full.
+ In text format, only non-zero values are printed.
This parameter may only be used when ANALYZE is also
enabled. It defaults to FALSE.
@@ -497,14 +498,17 @@ EXPLAIN ANALYZE EXECUTE query(100, 200);
QUERY PLAN
-------------------------------------------------------------------&zwsp;------------------------------------------------------
- HashAggregate (cost=10.77..10.87 rows=10 width=12) (actual time=0.043..0.044 rows=10 loops=1)
+ HashAggregate (cost=10.77..10.87 rows=10 width=12) (actual time=0.043..0.044 rows=10.00 loops=1)
Group Key: foo
Batches: 1 Memory Usage: 24kB
- -> Index Scan using test_pkey on test (cost=0.29..10.27 rows=99 width=8) (actual time=0.009..0.025 rows=99 loops=1)
+ Buffers: shared hit=4
+ -> Index Scan using test_pkey on test (cost=0.29..10.27 rows=99 width=8) (actual time=0.009..0.025 rows=99.00 loops=1)
Index Cond: ((id > 100) AND (id < 200))
+ Index Searches: 1
+ Buffers: shared hit=4
Planning Time: 0.244 ms
Execution Time: 0.073 ms
-(7 rows)
+(10 rows)
diff --git a/doc/src/sgml/ref/initdb.sgml b/doc/src/sgml/ref/initdb.sgml
index 74008a9a82f87..7613174c18b56 100644
--- a/doc/src/sgml/ref/initdb.sgml
+++ b/doc/src/sgml/ref/initdb.sgml
@@ -227,7 +227,7 @@ PostgreSQL documentation
-
+
@@ -260,14 +260,20 @@ PostgreSQL documentation
-
+
- 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
+ Use checksums on data pages to help detect corruption by the I/O
+ system that would otherwise be silent. This is enabled by default;
+ use to disable
+ checksums.
+
+
+
+ Enabling checksums
+ might incur a small performance penalty. If set, checksums
are calculated for all objects, in all databases. All checksum
failures will be reported in the
@@ -289,8 +295,8 @@ PostgreSQL documentation
If is builtin,
or must be
- specified and set to C or
- C.UTF-8.
+ specified and set to C, C.UTF-8
+ or PG_UNICODE_FAST.
@@ -343,6 +349,15 @@ PostgreSQL documentation
+
+
+
+
+ Do not enable data checksums.
+
+
+
+
@@ -512,6 +527,33 @@ PostgreSQL documentation
+
+
+
+
+ By default, initdb safely writes all database files
+ to disk. This option instructs initdb to skip
+ synchronizing all files in the individual database directories, the
+ database directories themselves, and the tablespace directories, i.e.,
+ everything in the base subdirectory and any other
+ tablespace directories. Other files, such as those in
+ pg_wal and pg_xact, will still be
+ synchronized unless the option is also
+ specified.
+
+
+ Note that if is used in
+ conjunction with , some or all of
+ the aforementioned files and directories will be synchronized because
+ syncfs processes entire file systems.
+
+
+ This option is primarily intended for internal use by tools that
+ separately ensure the skipped files are synchronized to disk.
+
+
+
+
@@ -525,6 +567,18 @@ PostgreSQL documentation
+
+
+
+
+
+ Show internal settings and exit, without doing anything else. This
+ can be used to debug the initdb
+ installation.
+
+
+
+
diff --git a/doc/src/sgml/ref/insert.sgml b/doc/src/sgml/ref/insert.sgml
index 7cea70329e107..3f13991779050 100644
--- a/doc/src/sgml/ref/insert.sgml
+++ b/doc/src/sgml/ref/insert.sgml
@@ -26,7 +26,8 @@ INSERT INTO table_name [ AS expression | DEFAULT } [, ...] ) [, ...] | query }
[ ON CONFLICT [ conflict_target ] conflict_action ]
- [ RETURNING * | output_expression [ [ AS ] output_name ] [, ...] ]
+ [ RETURNING [ WITH ( { OLD | NEW } AS output_alias [, ...] ) ]
+ { * | output_expression [ [ AS ] output_name ] } [, ...] ]
where conflict_target can be one of:
@@ -293,6 +294,26 @@ INSERT INTO table_name [ AS
+
+ output_alias
+
+
+ An optional substitute name for OLD or
+ NEW rows in the RETURNING list.
+
+
+
+ By default, old values from the target table can be returned by writing
+ OLD.column_name
+ or OLD.*, and new values can be returned by writing
+ NEW.column_name
+ or NEW.*. When an alias is provided, these names are
+ hidden and the old or new rows must be referred to using the alias.
+ For example RETURNING WITH (OLD AS o, NEW AS n) o.*, n.*.
+
+
+
+
output_expression
@@ -305,6 +326,23 @@ INSERT INTO table_name [ AS * to return all columns of the inserted or updated
row(s).
+
+
+ A column name or * may be qualified using
+ OLD or NEW, or the corresponding
+ output_alias for
+ OLD or NEW, to cause old or new
+ values to be returned. An unqualified column name, or
+ *, or a column name or *
+ qualified using the target table name or alias will return new values.
+
+
+
+ For a simple INSERT, all old values will be
+ NULL. However, for an INSERT
+ with an ON CONFLICT DO UPDATE clause, the old
+ values may be non-NULL.
+
@@ -711,6 +749,20 @@ INSERT INTO employees_log SELECT *, current_timestamp FROM upd;
INSERT INTO distributors (did, dname)
VALUES (5, 'Gizmo Transglobal'), (6, 'Associated Computing, Inc')
ON CONFLICT (did) DO UPDATE SET dname = EXCLUDED.dname;
+
+
+
+ Insert or update new distributors as above, returning information
+ about any existing values that were updated, together with the new data
+ inserted. Note that the returned values for old_did
+ and old_dname will be NULL for
+ non-conflicting rows:
+
+INSERT INTO distributors (did, dname)
+ VALUES (5, 'Gizmo Transglobal'), (6, 'Associated Computing, Inc')
+ ON CONFLICT (did) DO UPDATE SET dname = EXCLUDED.dname
+ RETURNING old.did AS old_did, old.dname AS old_dname,
+ new.did AS new_did, new.dname AS new_dname;
diff --git a/doc/src/sgml/ref/merge.sgml b/doc/src/sgml/ref/merge.sgml
index f63df90c162ba..c2e181066a4e1 100644
--- a/doc/src/sgml/ref/merge.sgml
+++ b/doc/src/sgml/ref/merge.sgml
@@ -23,36 +23,37 @@ PostgreSQL documentation
[ WITH with_query [, ...] ]
MERGE INTO [ ONLY ] target_table_name [ * ] [ [ AS ] target_alias ]
-USING data_source ON join_condition
-when_clause [...]
-[ RETURNING * | output_expression [ [ AS ] output_name ] [, ...] ]
+ USING data_source ON join_condition
+ when_clause [...]
+ [ RETURNING [ WITH ( { OLD | NEW } AS output_alias [, ...] ) ]
+ { * | output_expression [ [ AS ] output_name ] } [, ...] ]
where data_source is:
-{ [ ONLY ] source_table_name [ * ] | ( source_query ) } [ [ AS ] source_alias ]
+ { [ ONLY ] source_table_name [ * ] | ( source_query ) } [ [ AS ] source_alias ]
and when_clause is:
-{ WHEN MATCHED [ AND condition ] THEN { merge_update | merge_delete | DO NOTHING } |
- WHEN NOT MATCHED BY SOURCE [ AND condition ] THEN { merge_update | merge_delete | DO NOTHING } |
- WHEN NOT MATCHED [ BY TARGET ] [ AND condition ] THEN { merge_insert | DO NOTHING } }
+ { WHEN MATCHED [ AND condition ] THEN { merge_update | merge_delete | DO NOTHING } |
+ WHEN NOT MATCHED BY SOURCE [ AND condition ] THEN { merge_update | merge_delete | DO NOTHING } |
+ WHEN NOT MATCHED [ BY TARGET ] [ AND condition ] THEN { merge_insert | DO NOTHING } }
and merge_insert is:
-INSERT [( column_name [, ...] )]
-[ OVERRIDING { SYSTEM | USER } VALUE ]
-{ VALUES ( { expression | DEFAULT } [, ...] ) | DEFAULT VALUES }
+ INSERT [( column_name [, ...] )]
+ [ OVERRIDING { SYSTEM | USER } VALUE ]
+ { VALUES ( { expression | DEFAULT } [, ...] ) | DEFAULT VALUES }
and merge_update is:
-UPDATE SET { column_name = { expression | DEFAULT } |
- ( column_name [, ...] ) = [ ROW ] ( { expression | DEFAULT } [, ...] ) |
- ( column_name [, ...] ) = ( sub-SELECT )
- } [, ...]
+ UPDATE SET { column_name = { expression | DEFAULT } |
+ ( column_name [, ...] ) = [ ROW ] ( { expression | DEFAULT } [, ...] ) |
+ ( column_name [, ...] ) = ( sub-SELECT )
+ } [, ...]
and merge_delete is:
-DELETE
+ DELETE
@@ -105,10 +106,11 @@ DELETE
to compute and return value(s) based on each row inserted, updated, or
deleted. Any expression using the source or target table's columns, or
the merge_action()
- function can be computed. When an INSERT or
+ function can be computed. By default, when an INSERT or
UPDATE action is performed, the new values of the target
- table's columns are used. When a DELETE is performed,
- the old values of the target table's columns are used. The syntax of the
+ table's columns are used, and when a DELETE is performed,
+ the old values of the target table's columns are used, but it is also
+ possible to explicitly request old and new values. The syntax of the
RETURNING list is identical to that of the output list
of SELECT.
@@ -499,6 +501,25 @@ DELETE
+
+ output_alias
+
+
+ An optional substitute name for OLD or
+ NEW rows in the RETURNING list.
+
+
+ By default, old values from the target table can be returned by writing
+ OLD.column_name
+ or OLD.*, and new values can be returned by writing
+ NEW.column_name
+ or NEW.*. When an alias is provided, these names are
+ hidden and the old or new rows must be referred to using the alias.
+ For example RETURNING WITH (OLD AS o, NEW AS n) o.*, n.*.
+
+
+
+
output_expression
@@ -517,6 +538,17 @@ DELETE
qualifying the * with the name or alias of the source
or target table.
+
+ A column name or * may also be qualified using
+ OLD or NEW, or the corresponding
+ output_alias for
+ OLD or NEW, to cause old or new
+ values from the target table to be returned. An unqualified column
+ name from the target table, or a column name or *
+ qualified using the target table name or alias will return new values
+ for INSERT and UPDATE actions, and
+ old values for DELETE actions.
+
@@ -707,23 +739,6 @@ WHEN NOT MATCHED THEN
-
- Notice that this would be exactly equivalent to the following
- statement because the MATCHED result does not change
- during execution.
-
-
-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);
-
-
-
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
@@ -739,7 +754,7 @@ WHEN MATCHED AND w.stock + s.stock_delta > 0 THEN
UPDATE SET stock = w.stock + s.stock_delta
WHEN MATCHED THEN
DELETE
-RETURNING merge_action(), w.*;
+RETURNING merge_action(), w.winename, old.stock AS old_stock, new.stock AS new_stock;
The wine_stock_changes table might be, for example, a
diff --git a/doc/src/sgml/ref/pg_amcheck.sgml b/doc/src/sgml/ref/pg_amcheck.sgml
index 6bfe28799c4e6..ef2bdfd19ae5d 100644
--- a/doc/src/sgml/ref/pg_amcheck.sgml
+++ b/doc/src/sgml/ref/pg_amcheck.sgml
@@ -41,7 +41,7 @@ PostgreSQL documentation
- Only ordinary and toast table relations, materialized views, sequences, and
+ Only ordinary and TOAST table relations, materialized views, sequences, and
btree indexes are currently supported. Other relation types are silently
skipped.
@@ -276,7 +276,7 @@ PostgreSQL documentation
- By default, if a table is checked, its toast table, if any, will also
+ 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 --table or --relation.
This option suppresses that behavior.
@@ -306,9 +306,9 @@ PostgreSQL documentation
- By default, whenever a toast pointer is encountered in a table,
+ 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
+ entries in the TOAST table. These checks can be quite slow, and this
option can be used to skip them.
@@ -368,9 +368,9 @@ PostgreSQL documentation
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
+ 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,
+ TOAST blocks may still be accessed while validating TOAST pointers,
unless that is suppressed using
.
diff --git a/doc/src/sgml/ref/pg_basebackup.sgml b/doc/src/sgml/ref/pg_basebackup.sgml
index 82d0c8e0088d2..fecee08b0a536 100644
--- a/doc/src/sgml/ref/pg_basebackup.sgml
+++ b/doc/src/sgml/ref/pg_basebackup.sgml
@@ -500,8 +500,9 @@ PostgreSQL documentation
- Sets checkpoint mode to fast (immediate) or spread (the default)
+ Sets checkpoint mode to fast or spread
(see ).
+ The default is spread.
@@ -687,7 +688,7 @@ PostgreSQL documentation
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
+ tampered with, while the CRC-32C 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
@@ -807,14 +808,18 @@ PostgreSQL documentation
will override any conflicting command line options.
- The option is called --dbname for consistency with other
+ This option is called --dbname for consistency with other
client applications, but because pg_basebackup
doesn't connect to any particular database in the cluster, any database
- name in the connection string will be ignored
- by PostgreSQL. Middleware, or proxies, used in
- connecting to PostgreSQL might however
- utilize the value. The database name specified in connection string can
- also be used by
+ name included in the connection string will be ignored by the server.
+ However, a database name supplied that way overrides the default
+ database name (replication) for purposes of
+ looking up the replication connection's password
+ in ~/.pgpass. Similarly, middleware or proxies
+ used in connecting to PostgreSQL might
+ utilize the name for purposes such as connection routing. The
+ database name can also be used
+ by
logical replication slot synchronization.
@@ -1001,10 +1006,11 @@ PostgreSQL documentation
pg_basebackup works with servers of the same
- or an older major version, down to 9.1. However, WAL streaming mode (-X
- stream) only works with server version 9.3 and later, and tar format
+ or older major version, down to 9.1. However, WAL streaming mode (-X
+ stream) only works with server version 9.3 and later, the tar format
(--format=tar) only works with server version 9.5
- and later.
+ and later, and incremental backup (--incremental) only works
+ with server version 17 and later.
diff --git a/doc/src/sgml/ref/pg_combinebackup.sgml b/doc/src/sgml/ref/pg_combinebackup.sgml
index 375307d57bd42..330a598f7013e 100644
--- a/doc/src/sgml/ref/pg_combinebackup.sgml
+++ b/doc/src/sgml/ref/pg_combinebackup.sgml
@@ -81,6 +81,35 @@ PostgreSQL documentation
+
+
+
+
+
+ Use hard links instead of copying files to the synthetic backup.
+ Reconstruction of the synthetic backup might be faster (no file copying)
+ and use less disk space, but care must be taken when using the output
+ directory, because any modifications to that directory (for example,
+ starting the server) can also affect the input directories. Likewise,
+ changes to the input directories (for example, starting the server on
+ the full backup) could affect the output directory. Thus, this option
+ is best used when the input directories are only copies that will be
+ removed after pg_combinebackup has completed.
+
+
+
+ Requires that the input backups and the output directory are in the
+ same file system.
+
+
+
+ If a backup manifest is not available or does not contain checksum of
+ the right type, hard links will still be created, but the file will be
+ also read block-by-block for the checksum calculation.
+
+
+
+
@@ -162,6 +191,17 @@ PostgreSQL documentation
+
+
+
+
+ Perform regular file copy. This is the default. (See also
+ , , and
+ /.)
+
+
+
+
diff --git a/doc/src/sgml/ref/pg_createsubscriber.sgml b/doc/src/sgml/ref/pg_createsubscriber.sgml
index 142bffff0234c..bb9cc72576c4a 100644
--- a/doc/src/sgml/ref/pg_createsubscriber.sgml
+++ b/doc/src/sgml/ref/pg_createsubscriber.sgml
@@ -49,7 +49,8 @@ PostgreSQL documentation
pg_createsubscriber creates a new logical
replica from a physical standby server. All tables in the specified
- database are included in the logical replication setup. A pair of
+ database are included in the logical
+ replication setup. A pair of
publication and subscription objects are created for each database. It
must be run at the target server.
@@ -57,20 +58,24 @@ PostgreSQL documentation
After a successful run, the state of the target server is analogous to a
fresh logical replication setup. The main difference between the logical
- replication setup and pg_createsubscriber is the
- initial data copy. It does only the synchronization phase, which ensures
- each table is brought up to a synchronized state.
+ replication setup and pg_createsubscriber is how
+ the data synchronization is done. pg_createsubscriber
+ does not copy the initial table data. It does only the synchronization phase,
+ which ensures each table is brought up to a synchronized state.
- The pg_createsubscriber targets large database
+ pg_createsubscriber targets large database
systems because in logical replication setup, most of the time is spent
doing the initial data copy. Furthermore, a side effect of this long time
spent synchronizing data is usually a large amount of changes to be applied
(that were produced during the initial data copy), which increases even
more the time when the logical replica will be available. For smaller
- databases,
- initial data synchronization is recommended.
+ databases, it is recommended to set up logical replication with initial data
+ synchronization. For details, see the CREATE SUBSCRIPTION
+
+ copy_data option.
+
@@ -82,13 +87,40 @@ PostgreSQL documentation
command-line arguments:
+
+
+
+
+
+ Create one subscription per database on the target server. Exceptions
+ are template databases and databases that don't allow connections.
+ To discover the list of all databases, connect to the source server
+ using the database name specified in the
+ connection string, or if not specified, the postgres
+ database will be used, or if that does not exist, template1
+ will be used.
+ Automatically generated names for subscriptions, publications, and
+ replication slots are used when this option is specified.
+ This option cannot be used along with ,
+ , , or
+ .
+
+
+
+
- The database name to create the subscription. Multiple databases can
- be selected by writing multiple switches.
+ The name of the database in which to create a subscription. Multiple
+ databases can be selected by writing multiple
+ switches. This option cannot be used together with .
+ If option is not provided, the database name will be
+ obtained from option. If the database name is not
+ specified in either the option, or the
+ option, and option is not
+ specified, an error will be reported.
@@ -139,7 +171,7 @@ PostgreSQL documentation
-
+
The directory to use for postmaster sockets on target server. The
@@ -159,6 +191,19 @@ PostgreSQL documentation
+
+
+
+
+
+ Enables two_phase
+ commit for the subscription. When multiple databases are specified, this
+ option applies uniformly to all subscriptions created on those databases.
+ The default is false.
+
+
+
+
@@ -184,13 +229,42 @@ PostgreSQL documentation
+
+
+
+
+ Drop all objects of the specified type from specified databases on the
+ target server.
+
+
+
+
+
+ publications:
+ The FOR ALL TABLES publications established for this
+ subscriber are always dropped; specifying this object type causes all
+ other publications replicated from the source server to be dropped as
+ well.
+
+
+
+
+
+ The objects selected to be dropped are individually logged, including during
+ a . There is no opportunity to affect or stop the
+ dropping of the selected objects, so consider taking a backup of them
+ using pg_dump.
+
+
+
+
Use the specified main server configuration file for the target data
- directory. The pg_createsubscriber uses
- internally the pg_ctl command to start and
+ directory. pg_createsubscriber internally uses
+ the pg_ctl command to start and
stop the target server. It allows you to specify the actual
postgresql.conf configuration file if it is stored
outside the data directory.
@@ -208,7 +282,8 @@ PostgreSQL documentation
names must match the number of specified databases, otherwise an error
is reported. The order of the multiple publication name switches must
match the order of database switches. If this option is not specified,
- a generated name is assigned to the publication name.
+ a generated name is assigned to the publication name. This option cannot
+ be used together with .
@@ -224,7 +299,8 @@ PostgreSQL documentation
otherwise an error is reported. The order of the multiple replication
slot name switches must match the order of database switches. If this
option is not specified, the subscription name is assigned to the
- replication slot name.
+ replication slot name. This option cannot be used together with
+ .
@@ -239,7 +315,8 @@ PostgreSQL documentation
names must match the number of specified databases, otherwise an error
is reported. The order of the multiple subscription name switches must
match the order of database switches. If this option is not specified,
- a generated name is assigned to the subscription name.
+ a generated name is assigned to the subscription name. This option cannot
+ be used together with .
@@ -289,12 +366,14 @@ PostgreSQL documentation
The target server must be used as a physical standby. The target server
- must have and and configured to a value
greater than or equal to the number of specified databases. The target
server must have configured to a
value greater than the number of specified databases. The target server
- must accept local connections.
+ must accept local connections. If you are planning to use the
+ switch then you will also need to set
+ the appropriately.
@@ -325,13 +404,6 @@ PostgreSQL documentation
connections to the target server should fail.
-
- During the recovery process, if the target server disconnects from the
- source server, pg_createsubscriber will check a
- few times if the connection has been reestablished to stream the required
- WAL. After a few attempts, it terminates with an error.
-
-
Since DDL commands are not replicated by logical replication, avoid
executing DDL commands that change the database schema while running
@@ -360,6 +432,18 @@ PostgreSQL documentation
pg_createsubscriber.
+
+ Unless the switch is specified,
+ pg_createsubscriber sets up logical
+ replication with two-phase commit disabled. This means that any
+ prepared transactions will be replicated at the time
+ of COMMIT PREPARED, without advance preparation.
+ Once setup is complete, you can manually drop and re-create the
+ subscription(s) with
+ the two_phase
+ option enabled.
+
+
pg_createsubscriber changes the system
identifier using pg_resetwal. It would avoid
@@ -367,6 +451,13 @@ PostgreSQL documentation
server. If the target server has a standby, replication will break and a
fresh standby should be created.
+
+
+ Replication failures can occur if required WAL files are missing. To prevent
+ this, the source server must set
+ to -1 to
+ ensure that required WAL files are not prematurely removed.
+
@@ -401,11 +492,11 @@ PostgreSQL documentation
Create a publication and replication slot for each specified database on
the source server. Each publication is created using FOR ALL
- TABLES. If option is
- not specified, it has the following name pattern:
+ TABLES. If the option
+ is not specified, the publication has the following name pattern:
pg_createsubscriber_%u_%x (parameter:
database oid, random int).
- If is not specified, the
+ If the option is not specified, the
replication slot has the following name pattern:
pg_createsubscriber_%u_%x (parameters:
database oid, random int).
@@ -440,8 +531,8 @@ PostgreSQL documentation
Create a subscription for each specified database on the target server.
- If is not specified, the subscription
- has the following name pattern:
+ If the option is not specified, the
+ subscription has the following name pattern:
pg_createsubscriber_%u_%x (parameters:
database oid, random int).
It does not copy existing data from the source server. It does not
@@ -489,6 +580,15 @@ PostgreSQL documentation
+
+
+ If the standby server contains failover
+ replication slots, they cannot be synchronized anymore, so drop
+ them.
+
+
+
Update the system identifier on the target server. The
diff --git a/doc/src/sgml/ref/pg_dump.sgml b/doc/src/sgml/ref/pg_dump.sgml
index 08d775379fd1b..fd4ecf01a0a00 100644
--- a/doc/src/sgml/ref/pg_dump.sgml
+++ b/doc/src/sgml/ref/pg_dump.sgml
@@ -18,7 +18,7 @@ PostgreSQL documentation
pg_dump
- extract a PostgreSQL database into a script file or other archive file
+ export a PostgreSQL database as an SQL script or to other formats
@@ -36,16 +36,20 @@ PostgreSQL documentation
Description
- pg_dump is a utility for backing up a
+ pg_dump is a utility for exporting a
PostgreSQL database. It makes consistent
- backups even if the database is being used concurrently.
+ exports even if the database is being used concurrently.
pg_dump does not block other users
accessing the database (readers or writers).
+ Note, however, that except in simple cases,
+ pg_dump is generally not the right choice for
+ taking regular backups of production databases. See for further discussion.
pg_dump only dumps a single database.
- To back up an entire cluster, or to back up global objects that are
+ To export an entire cluster, or to export global objects that are
common to all databases in a cluster (such as roles and tablespaces),
use .
@@ -76,7 +80,7 @@ PostgreSQL documentation
pg_restore,
pg_dump provides a flexible archival and
transfer mechanism. pg_dump can be used to
- backup an entire database, then pg_restore
+ export an entire database, then pg_restore
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 custom format () and the
@@ -92,6 +96,18 @@ PostgreSQL documentation
light of the limitations listed below.
+
+
+ Restoring a dump causes the destination to execute arbitrary code of the
+ source superusers' choice. Partial dumps and partial restores do not limit
+ that. If the source superusers are not trusted, the dumped SQL statements
+ must be inspected before restoring. Non-plain-text dumps can be inspected
+ by using pg_restore's
+ option. Note that the client running the dump and restore need not trust
+ the source or destination superusers.
+
+
+
@@ -119,7 +135,7 @@ PostgreSQL documentation
- Dump only the data, not the schema (data definitions).
+ Dump only the data, not the schema (data definitions) or statistics.
Table data, large objects, and sequence values are dumped.
@@ -137,13 +153,15 @@ PostgreSQL documentation
Include large objects in the dump. This is the default behavior
- except when , , or
- is specified. The
- switch is therefore only useful to add large objects to dumps
- where a specific schema or table has been requested. Note that
- large objects are considered data and therefore will be included when
- is used, but not
- when is.
+ except when , ,
+ , , or
+ is specified. The
+ switch is therefore only useful to add large objects to dumps where a
+ specific schema or table has been requested. Note that large objects
+ are considered data and therefore will be included when
+ is used, but not when
+ or
+ is.
@@ -512,10 +530,11 @@ PostgreSQL documentation
- Dump only the object definitions (schema), not data.
+ Dump only the object definitions (schema), not data or statistics.
- This option is the inverse of .
+ This option cannot be used with
+ or .
It is similar to, but for historical reasons not identical to,
specifying
.
@@ -737,7 +756,8 @@ PostgreSQL documentation
- This option is relevant only when creating a data-only dump.
+ This option is relevant only when creating a dump that includes data
+ but does not include schema.
It instructs pg_dump to include commands
to temporarily disable triggers on the target tables while
the data is restored. Use this if you have referential
@@ -829,7 +849,8 @@ PostgreSQL documentation
though you do not need the data in it.
- To exclude data for all tables in the database, see .
+ To exclude data for all tables in the database, see
+ or .
@@ -866,13 +887,14 @@ PostgreSQL documentation
same rules as the corresponding options:
/,
,
- or
- for tables,
- / for schemas,
+ /, and
+ for tables,
+ / and
+ / for schemas,
for data on foreign servers,
- ,
+ and
for table data, and
- / or
+ / and
for extensions.
To read from STDIN, use - as the
filename. The option can be specified in
@@ -895,34 +917,37 @@ PostgreSQL documentation
- extension: extensions, works like the
- / option.
+ extension: extensions. This works like the
+ / or
+ option.
- foreign_data: data on foreign servers, works like
+ foreign_data: data on foreign servers. This works like
the option. This keyword can
only be used with the include keyword.
- table: tables, works like the
- / option.
+ table: tables. This works like the
+ / or
+ / option.
table_and_children: tables including any partitions
- or inheritance child tables, works like the
- option.
+ or inheritance child tables. This works like the
+ or
+ option.
table_data: table data of any tables matching
- pattern, works like the
+ pattern. This works like the
option. This keyword can only
be used with the exclude keyword.
@@ -931,15 +956,16 @@ PostgreSQL documentation
table_data_and_children: table data of any tables
matching pattern as well as any partitions
- or inheritance children of the table(s), works like the
+ or inheritance children of the table(s). This works like the
option. This
keyword can only be used with the exclude keyword.
- schema: schemas, works like the
- / option.
+ schema: schemas. This works like the
+ / or
+ / option.
@@ -992,6 +1018,14 @@ PostgreSQL documentation
The only exception is that an empty pattern is disallowed.
+
+
+ Using wildcards in may result
+ in access to unexpected foreign servers. Also, to use this option securely,
+ make sure that the named server must have a trusted owner.
+
+
+
When is specified,
@@ -1058,7 +1092,25 @@ PostgreSQL documentation
- Do not dump comments.
+ Do not dump COMMENT commands.
+
+
+
+
+
+
+
+
+ Do not dump data.
+
+
+
+
+
+
+
+
+ Do not dump row security policies.
@@ -1072,6 +1124,15 @@ PostgreSQL documentation
+
+
+
+
+ Do not dump schema (data definitions).
+
+
+
+
@@ -1081,6 +1142,15 @@ PostgreSQL documentation
+
+
+
+
+ Do not dump statistics. This is the default.
+
+
+
+
@@ -1194,6 +1264,29 @@ PostgreSQL documentation
+
+
+
+
+ Use the provided string as the psql
+ \restrict key in the dump output. This can only be
+ specified for plain-text dumps, i.e., when is
+ set to plain or the option
+ is omitted. If no restrict key is specified,
+ pg_dump will generate a random one as
+ needed. Keys may contain only alphanumeric characters.
+
+
+ This option is primarily intended for testing purposes and other
+ scenarios that require repeatable output (e.g., comparing dump files).
+ It is not recommended for general use, as a malicious server with
+ advance knowledge of the key may be able to inject arbitrary code that
+ will be executed on the machine that runs
+ psql with the dump output.
+
+
+
+
@@ -1219,14 +1312,27 @@ PostgreSQL documentation
The data section contains actual table data, large-object
- contents, and sequence values.
+ contents, sequence values, and statistics for tables,
+ materialized views, and foreign tables.
Post-data items include definitions of indexes, triggers, rules,
- and constraints other than validated check constraints.
+ statistics for indexes, and constraints other than validated check
+ and not-null constraints.
Pre-data items include all other data definition items.
+
+
+
+
+ Include sequence data in the dump. This is the default behavior except
+ when , , or
+ is specified.
+
+
+
+
@@ -1283,6 +1389,26 @@ PostgreSQL documentation
+
+
+
+
+ Dump statistics.
+
+
+
+
+
+
+
+
+ Dump only the statistics, not the schema (data definitions) or data.
+ Statistics for tables, materialized views, foreign tables,
+ and indexes are dumped.
+
+
+
+
@@ -1564,7 +1690,7 @@ CREATE DATABASE foo WITH TEMPLATE template0;
- When a data-only dump is chosen and the option
+ When a dump without schema is chosen and the option
is used, pg_dump emits commands
to disable triggers on user tables before inserting the data,
and then commands to re-enable them after the data has been
@@ -1573,12 +1699,14 @@ CREATE DATABASE foo WITH TEMPLATE template0;
- The dump file produced by pg_dump
- does not contain the statistics used by the optimizer to make
- query planning decisions. Therefore, it is wise to run
- ANALYZE after restoring from a dump file
- to ensure optimal performance; see
- and for more information.
+ If is specified,
+ pg_dump will include most optimizer statistics in the
+ resulting dump file. However, some statistics may not be included, such as
+ those created explicitly with or
+ custom statistics added by an extension. Therefore, it may be useful to
+ run ANALYZE after restoring from a dump file to ensure
+ optimal performance; see and for more information.
@@ -1619,6 +1747,14 @@ CREATE DATABASE foo WITH TEMPLATE template0;
option will be automatically enabled by the subscriber if the subscription
had been originally created with two_phase = true option.
+
+
+ It is generally recommended to use the
+ () option when restoring a database from a
+ plain-text pg_dump script to ensure a clean
+ restore process and prevent potential conflicts with
+ non-default psql configurations.
+
@@ -1636,7 +1772,7 @@ CREATE DATABASE foo WITH TEMPLATE template0;
newdb:
-$psql -d newdb -f db.sql
+$psql -X -d newdb -f db.sql
diff --git a/doc/src/sgml/ref/pg_dumpall.sgml b/doc/src/sgml/ref/pg_dumpall.sgml
index 4d7c0464687ef..9f639f61db021 100644
--- a/doc/src/sgml/ref/pg_dumpall.sgml
+++ b/doc/src/sgml/ref/pg_dumpall.sgml
@@ -66,6 +66,16 @@ PostgreSQL documentation
linkend="libpq-pgpass"/> for more information.
+
+
+ Restoring a dump causes the destination to execute arbitrary code of the
+ source superusers' choice. Partial dumps and partial restores do not limit
+ that. If the source superusers are not trusted, the dumped SQL statements
+ must be inspected before restoring. Note that the client running the dump
+ and restore need not trust the source or destination superusers.
+
+
+
@@ -81,7 +91,7 @@ PostgreSQL documentation
- Dump only the data, not the schema (data definitions).
+ Dump only the data, not the schema (data definitions) or statistics.
@@ -125,37 +135,6 @@ PostgreSQL documentation
-
-
-
-
- Specify a filename from which to read patterns for databases excluded
- from the dump. The patterns are interpreted according to the same rules
- as .
- To read from STDIN, use - as the
- filename. The option can be specified in
- conjunction with for excluding
- databases, and can also be specified more than once for multiple filter
- files.
-
-
-
- The file lists one database pattern per row, with the following format:
-
-exclude database PATTERN
-
-
-
-
- Lines starting with # are considered comments and
- ignored. Comments can be placed after an object pattern row as well.
- Blank lines are also ignored. See
- for how to perform quoting in patterns.
-
-
-
-
-
@@ -307,7 +286,7 @@ exclude database PATTERN
- This option is relevant only when creating a data-only dump.
+ This option is relevant only when creating a dump with data and without schema.
It instructs pg_dumpall to include commands
to temporarily disable triggers on the target tables while
the data is restored. Use this if you have referential
@@ -354,6 +333,37 @@ exclude database PATTERN
+
+
+
+
+ Specify a filename from which to read patterns for databases excluded
+ from the dump. The patterns are interpreted according to the same rules
+ as .
+ To read from STDIN, use - as the
+ filename. The option can be specified in
+ conjunction with for excluding
+ databases, and can also be specified more than once for multiple filter
+ files.
+
+
+
+ The file lists one database pattern per row, with the following format:
+
+exclude database PATTERN
+
+
+
+
+ Lines starting with # are considered comments and
+ ignored. Comments can be placed after an object pattern row as well.
+ Blank lines are also ignored. See
+ for how to perform quoting in patterns.
+
+
+
+
+
@@ -417,7 +427,25 @@ exclude database PATTERN
- Do not dump comments.
+ Do not dump COMMENT commands.
+
+
+
+
+
+
+
+
+ Do not dump data.
+
+
+
+
+
+
+
+
+ Do not dump row security policies.
@@ -447,6 +475,15 @@ exclude database PATTERN
+
+
+
+
+ Do not dump schema (data definitions).
+
+
+
+
@@ -456,6 +493,15 @@ exclude database PATTERN
+
+
+
+
+ Do not dump statistics. This is the default.
+
+
+
+
@@ -555,6 +601,26 @@ exclude database PATTERN
+
+
+
+
+ Use the provided string as the psql
+ \restrict key in the dump output. If no restrict
+ key is specified, pg_dumpall will generate a
+ random one as needed. Keys may contain only alphanumeric characters.
+
+
+ This option is primarily intended for testing purposes and other
+ scenarios that require repeatable output (e.g., comparing dump files).
+ It is not recommended for general use, as a malicious server with
+ advance knowledge of the key may be able to inject arbitrary code that
+ will be executed on the machine that runs
+ psql with the dump output.
+
+
+
+
@@ -569,6 +635,37 @@ exclude database PATTERN
+
+
+
+
+ Dump statistics.
+
+
+
+
+
+
+
+
+ Dump only the statistics, not the schema (data definitions) or data.
+ Statistics for tables, materialized views, foreign tables,
+ and indexes are dumped.
+
+
+
+
+
+
+
+
+ Include sequence data in the dump. This is the default behavior except
+ when , , or
+ is specified.
+
+
+
+
@@ -793,10 +890,14 @@ exclude database PATTERN
- Once restored, it is wise to run ANALYZE on each
- database so the optimizer has useful statistics. You
- can also run vacuumdb -a -z to analyze all
- databases.
+ If is specified,
+ pg_dumpall will include most optimizer statistics in the
+ resulting dump file. However, some statistics may not be included, such as
+ those created explicitly with or
+ custom statistics added by an extension. Therefore, it may be useful to
+ run ANALYZE on each database after restoring from a dump
+ file to ensure optimal performance. You can also run vacuumdb -a
+ -z to analyze all databases.
@@ -817,6 +918,17 @@ exclude database PATTERN
database creation will fail for databases in non-default
locations.
+
+
+ It is generally recommended to use the
+ () option when restoring a database from a
+ pg_dumpall script to ensure a clean restore
+ process and prevent potential conflicts with non-default
+ psql configurations. Additionally, because
+ the pg_dumpall script may
+ include psql meta-commands, it may be
+ incompatible with clients other than psql.
+
@@ -833,9 +945,9 @@ exclude database PATTERN
To restore database(s) from this file, you can use:
-$psql -f db.out postgres
+$psql -X -f db.out -d postgres
- It is not important to which database you connect here since the
+ It is not important which database you connect to here since the
script file created by pg_dumpall will
contain the appropriate commands to create and connect to the saved
databases. An exception is that if you specified ,
diff --git a/doc/src/sgml/ref/pg_receivewal.sgml b/doc/src/sgml/ref/pg_receivewal.sgml
index 8944eee2a3649..9e353a068e5a3 100644
--- a/doc/src/sgml/ref/pg_receivewal.sgml
+++ b/doc/src/sgml/ref/pg_receivewal.sgml
@@ -315,13 +315,16 @@ PostgreSQL documentation
will override any conflicting command line options.
- The option is called --dbname for consistency with other
+ This option is called --dbname for consistency with other
client applications, but because pg_receivewal
doesn't connect to any particular database in the cluster, any database
- name in the connection string will be ignored by
- PostgreSQL. Middleware, or proxies, used in
- connecting to PostgreSQL might however
- utilize the value.
+ name included in the connection string will be ignored by the server.
+ However, a database name supplied that way overrides the default
+ database name (replication) for purposes of
+ looking up the replication connection's password
+ in ~/.pgpass. Similarly, middleware or proxies
+ used in connecting to PostgreSQL might
+ utilize the name for purposes such as connection routing.
diff --git a/doc/src/sgml/ref/pg_recvlogical.sgml b/doc/src/sgml/ref/pg_recvlogical.sgml
index 95eb14b6352e2..263ebdeeab4a8 100644
--- a/doc/src/sgml/ref/pg_recvlogical.sgml
+++ b/doc/src/sgml/ref/pg_recvlogical.sgml
@@ -53,6 +53,16 @@ PostgreSQL documentation
(ControlC)
or SIGTERM signal.
+
+
+ When pg_recvlogical receives
+ a SIGHUP signal, it closes the current output file
+ and opens a new one using the filename specified by
+ the option. This allows us to rotate
+ the output file by first renaming the current file and then sending
+ a SIGHUP signal to
+ pg_recvlogical.
+
@@ -74,8 +84,13 @@ PostgreSQL documentation
- The can be specified with
- to enable decoding of prepared transactions.
+ The and are required
+ for this action.
+
+
+
+ The and
+ options can be specified with .
@@ -87,6 +102,10 @@ PostgreSQL documentation
Drop the replication slot with the name specified
by , then exit.
+
+
+ The is required for this action.
+
@@ -101,6 +120,11 @@ PostgreSQL documentation
is specified.
+
+ The and ,
+ are required for this action.
+
+
The stream format is determined by the output plugin specified when
the slot was created.
@@ -151,6 +175,16 @@ PostgreSQL documentation
+
+
+
+
+ Enables the slot to be synchronized to the standbys. This option may
+ only be specified with .
+
+
+
+
@@ -159,6 +193,9 @@ PostgreSQL documentation
Write received and decoded transaction data into this
file. Use - for stdout.
+
+ This parameter is required for .
+
@@ -265,12 +302,16 @@ PostgreSQL documentation
mode, create the slot with this name. In
mode, delete the slot with this name.
+
+ This parameter is required for any of actions.
+
-
+
+ (deprecated)
Enables decoding of prepared transactions. This option may only be specified with
@@ -305,7 +346,11 @@ PostgreSQL documentation
The dbname can be a connection string. If so,
connection string parameters will override any conflicting
- command line options. Defaults to the user name.
+ command line options.
+
+
+ This parameter is required for
+ and .
diff --git a/doc/src/sgml/ref/pg_resetwal.sgml b/doc/src/sgml/ref/pg_resetwal.sgml
index cf9c7e70f2712..2c019c2aac6eb 100644
--- a/doc/src/sgml/ref/pg_resetwal.sgml
+++ b/doc/src/sgml/ref/pg_resetwal.sgml
@@ -313,34 +313,6 @@ PostgreSQL documentation
-
-
-
-
- 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 for more information.
-
-
-
- This option can also be used to change the WAL segment size of an
- existing database cluster, avoiding the need to
- re-initdb.
-
-
-
-
- While pg_resetwal 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 together with this option to manually set the
- WAL starting address if WAL file name overlap will cause problems with
- your archiving strategy.
-
-
-
-
-
@@ -383,6 +355,53 @@ PostgreSQL documentation
+
+
+
+
+
+ Manually set the default char signedness. Possible values are
+ signed and unsigned.
+
+
+ For a database cluster that pg_upgrade upgraded from
+ a PostgreSQL version before 18, the safe
+ value would be the default char signedness of the platform
+ that ran the cluster before that upgrade. For all other
+ clusters, signed would be the safe value. However,
+ this option is exclusively for use with pg_upgrade
+ and should not normally be used manually.
+
+
+
+
+
+
+
+
+ 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 for more information.
+
+
+
+ This option can also be used to change the WAL segment size of an
+ existing database cluster, avoiding the need to
+ re-initdb.
+
+
+
+
+ While pg_resetwal 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 together with this option to manually set the
+ WAL starting address if WAL file name overlap will cause problems with
+ your archiving strategy.
+
+
+
+
diff --git a/doc/src/sgml/ref/pg_restore.sgml b/doc/src/sgml/ref/pg_restore.sgml
index 2e3ba80258177..a468a38361a13 100644
--- a/doc/src/sgml/ref/pg_restore.sgml
+++ b/doc/src/sgml/ref/pg_restore.sgml
@@ -68,6 +68,18 @@ PostgreSQL documentation
pg_restore will not be able to load the data
using COPY statements.
+
+
+
+ Restoring a dump causes the destination to execute arbitrary code of the
+ source superusers' choice. Partial dumps and partial restores do not limit
+ that. If the source superusers are not trusted, the dumped SQL statements
+ must be inspected before restoring. Non-plain-text dumps can be inspected
+ by using pg_restore's
+ option. Note that the client running the dump and restore need not trust
+ the source or destination superusers.
+
+
@@ -94,7 +106,7 @@ PostgreSQL documentation
- Restore only the data, not the schema (data definitions).
+ Restore only the data, not the schema (data definitions) or statistics.
Table data, large objects, and sequence values are restored,
if present in the archive.
@@ -190,86 +202,6 @@ PostgreSQL documentation
-
-
-
-
- Specify a filename from which to read patterns for objects excluded
- or included from restore. The patterns are interpreted according to the
- same rules as
- / for including objects in schemas,
- /for excluding objects in schemas,
- / for restoring named functions,
- / for restoring named indexes,
- / for restoring named tables
- or / for restoring triggers.
- To read from STDIN, use - as the
- filename. The option can be specified in
- conjunction with the above listed options for including or excluding
- objects, and can also be specified more than once for multiple filter
- files.
-
-
-
- The file lists one database pattern per row, with the following format:
-
-{ include | exclude } { function | index | schema | table | trigger } PATTERN
-
-
-
-
- The first keyword specifies whether the objects matched by the pattern
- are to be included or excluded. The second keyword specifies the type
- of object to be filtered using the pattern:
-
-
-
- function: functions, works like the
- / option. This keyword
- can only be used with the include keyword.
-
-
-
-
- index: indexes, works like the
- / option. This keyword
- can only be used with the include keyword.
-
-
-
-
- schema: schemas, works like the
- / and
- / options.
-
-
-
-
- table: tables, works like the
- / option. This keyword
- can only be used with the include keyword.
-
-
-
-
- trigger: triggers, works like the
- / option. This keyword
- can only be used with the include keyword.
-
-
-
-
-
-
- Lines starting with # are considered comments and
- ignored. Comments can be placed after an object pattern row as well.
- Blank lines are also ignored. See
- for how to perform quoting in patterns.
-
-
-
-
-
@@ -483,10 +415,11 @@ PostgreSQL documentation
to the extent that schema entries are present in the archive.
- This option is the inverse of .
+ This option cannot be used with
+ or .
It is similar to, but for historical reasons not identical to,
specifying
- .
+ .
(Do not confuse this with the option, which
@@ -617,7 +550,7 @@ PostgreSQL documentation
- This option is relevant only when performing a data-only restore.
+ This option is relevant only when performing a restore without schema.
It instructs pg_restore to execute commands
to temporarily disable triggers on the target tables while
the data is restored. Use this if you have referential
@@ -658,6 +591,86 @@ PostgreSQL documentation
+
+
+
+
+ Specify a filename from which to read patterns for objects excluded
+ or included from restore. The patterns are interpreted according to the
+ same rules as
+ / for including objects in schemas,
+ / for excluding objects in schemas,
+ / for restoring named functions,
+ / for restoring named indexes,
+ / for restoring named tables
+ or / for restoring triggers.
+ To read from STDIN, use - as the
+ filename. The option can be specified in
+ conjunction with the above listed options for including or excluding
+ objects, and can also be specified more than once for multiple filter
+ files.
+
+
+
+ The file lists one database pattern per row, with the following format:
+
+{ include | exclude } { function | index | schema | table | trigger } PATTERN
+
+
+
+
+ The first keyword specifies whether the objects matched by the pattern
+ are to be included or excluded. The second keyword specifies the type
+ of object to be filtered using the pattern:
+
+
+
+ function: functions, works like the
+ / option. This keyword
+ can only be used with the include keyword.
+
+
+
+
+ index: indexes, works like the
+ / option. This keyword
+ can only be used with the include keyword.
+
+
+
+
+ schema: schemas, works like the
+ / and
+ / options.
+
+
+
+
+ table: tables, works like the
+ / option. This keyword
+ can only be used with the include keyword.
+
+
+
+
+ trigger: triggers, works like the
+ / option. This keyword
+ can only be used with the include keyword.
+
+
+
+
+
+
+ Lines starting with # are considered comments and
+ ignored. Comments can be placed after an object pattern row as well.
+ Blank lines are also ignored. See
+ for how to perform quoting in patterns.
+
+
+
+
+
@@ -681,6 +694,16 @@ PostgreSQL documentation
+
+
+
+
+ Do not output commands to restore data, even if the archive
+ contains them.
+
+
+
+
@@ -703,6 +726,16 @@ PostgreSQL documentation
+
+
+
+
+ Do not output commands to restore row security policies, even if
+ the archive contains them.
+
+
+
+
@@ -713,6 +746,16 @@ PostgreSQL documentation
+
+
+
+
+ Do not output commands to restore schema (data definitions), even if
+ the archive contains them.
+
+
+
+
@@ -723,6 +766,16 @@ PostgreSQL documentation
+
+
+
+
+ Do not output commands to restore statistics, even if the archive
+ contains them.
+
+
+
+
@@ -755,6 +808,28 @@ PostgreSQL documentation
+
+
+
+
+ Use the provided string as the psql
+ \restrict key in the dump output. This can only be
+ specified for SQL script output, i.e., when the
+ option is used. If no restrict key is specified,
+ pg_restore will generate a random one as
+ needed. Keys may contain only alphanumeric characters.
+
+
+ This option is primarily intended for testing purposes and other
+ scenarios that require repeatable output (e.g., comparing dump files).
+ It is not recommended for general use, as a malicious server with
+ advance knowledge of the key may be able to inject arbitrary code that
+ will be executed on the machine that runs
+ psql with the dump output.
+
+
+
+
@@ -774,6 +849,25 @@ PostgreSQL documentation
+
+
+
+
+ Output commands to restore statistics, if the archive contains them.
+ This is the default.
+
+
+
+
+
+
+
+
+ Restore only the statistics, not schema (data definitions) or data.
+
+
+
+
@@ -781,7 +875,7 @@ PostgreSQL documentation
Require that each schema
(/) and table
(/) qualifier match at
- least one schema/table in the backup file.
+ least one schema/table in the file to be restored.
@@ -1040,10 +1134,12 @@ CREATE DATABASE foo WITH TEMPLATE template0;
- Once restored, it is wise to run ANALYZE on each
- restored table so the optimizer has useful statistics; see
- and
- for more information.
+ By default, pg_restore will restore optimizer statistics
+ if included in the dump file. If not all statistics were restored, it may
+ be useful to run ANALYZE on each restored table so the
+ optimizer has useful statistics; see and for more
+ information.
diff --git a/doc/src/sgml/ref/pg_rewind.sgml b/doc/src/sgml/ref/pg_rewind.sgml
index dc039d875665a..5485033ed8c7c 100644
--- a/doc/src/sgml/ref/pg_rewind.sgml
+++ b/doc/src/sgml/ref/pg_rewind.sgml
@@ -186,8 +186,10 @@ PostgreSQL documentation
Create standby.signal and append connection
settings to postgresql.auto.conf in the output
- directory. --source-server is mandatory with
- this option.
+ directory. The dbname will be recorded only if the dbname was
+ specified explicitly in the connection string or
+ environment variable. --source-server is
+ mandatory with this option.
diff --git a/doc/src/sgml/ref/pg_verifybackup.sgml b/doc/src/sgml/ref/pg_verifybackup.sgml
index a3f167f9f6e01..61c12975e4ad5 100644
--- a/doc/src/sgml/ref/pg_verifybackup.sgml
+++ b/doc/src/sgml/ref/pg_verifybackup.sgml
@@ -34,8 +34,12 @@ PostgreSQL documentation
integrity of a database cluster backup taken using
pg_basebackup against a
backup_manifest 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.
+ of the backup. The backup may be stored either in the "plain" or the "tar"
+ format; this includes tar-format backups compressed with any algorithm
+ supported by pg_basebackup. However, at present,
+ WAL verification is supported only for plain-format
+ backups. Therefore, if the backup is stored in tar-format, the
+ -n, --no-parse-wal option should be used.
@@ -139,6 +143,45 @@ PostgreSQL documentation
+
+
+
+
+
+ Specifies the format of the backup. format
+ can be one of the following:
+
+
+
+ p
+ plain
+
+
+ Backup consists of plain files with the same layout as the
+ source server's data directory and tablespaces.
+
+
+
+
+
+ t
+ tar
+
+
+ Backup consists of tar files, which may be compressed. A valid
+ backup includes the main data directory in a file named
+ base.tar, the WAL files in
+ pg_wal.tar, and separate tar files for
+ each tablespace, named after the tablespace's OID. If the backup
+ is compressed, the relevant compression extension is added to the
+ end of each file name.
+
+
+
+
+
+
+
diff --git a/doc/src/sgml/ref/pg_waldump.sgml b/doc/src/sgml/ref/pg_waldump.sgml
index a9371e037bde5..ce23add5577ed 100644
--- a/doc/src/sgml/ref/pg_waldump.sgml
+++ b/doc/src/sgml/ref/pg_waldump.sgml
@@ -284,7 +284,7 @@ PostgreSQL documentation
The full page images are saved with the following file name format:
- TIMELINE-LSN.RELTABLESPACE.DATOID.RELNODE.BLKNOFORK
+ TIMELINE-LSN.RELTABLESPACE.DATOID.RELNODE.BLKNO_FORK
The file names are composed of the following parts:
@@ -335,8 +335,8 @@ PostgreSQL documentation
FORK
The name of the fork the full page image came from, such as
- _main, _fsm,
- _vm, or _init.
+ main, fsm,
+ vm, or init.
diff --git a/doc/src/sgml/ref/pgbench.sgml b/doc/src/sgml/ref/pgbench.sgml
index 46240e3f72599..ab252d9fc74f9 100644
--- a/doc/src/sgml/ref/pgbench.sgml
+++ b/doc/src/sgml/ref/pgbench.sgml
@@ -231,11 +231,10 @@ pgbench optionsd
sent to the server. This uses the client/server bandwidth
extensively through a COPY.
pgbench uses the option
- with version 14 or later
- of PostgreSQL to speed up
- subsequent VACUUM, except on the
- pgbench_accounts table if partitions are
- enabled. Using g causes logging to
+ to load data into ordinary (non-partition) tables with version 14
+ or later of PostgreSQL to speed up
+ subsequent VACUUM.
+ Using g causes logging to
print one message every 100,000 rows while generating data for all
tables.
@@ -909,7 +908,7 @@ pgbench optionsd
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.).
+ case the output can be significantly increased.)
See for more information.
diff --git a/doc/src/sgml/ref/pgtesttiming.sgml b/doc/src/sgml/ref/pgtesttiming.sgml
index a5eb3aa25e02f..afe6a12be4b30 100644
--- a/doc/src/sgml/ref/pgtesttiming.sgml
+++ b/doc/src/sgml/ref/pgtesttiming.sgml
@@ -30,11 +30,23 @@ PostgreSQL documentation
Description
- pg_test_timing is a tool to measure the timing overhead
- on your system and confirm that the system time never moves backwards.
+ pg_test_timing is a tool to measure the
+ timing overhead on your system and confirm that the system time never
+ moves backwards. It simply reads the system clock over and over again
+ as fast as it can for a specified length of time, and then prints
+ statistics about the observed differences in successive clock readings.
+
+
+ Smaller (but not zero) differences are better, since they imply both
+ more-precise clock hardware and less overhead to collect a clock reading.
Systems that are slow to collect timing data can give less accurate
EXPLAIN ANALYZE results.
+
+ This tool is also helpful to determine if
+ the track_io_timing configuration parameter is likely
+ to produce useful results.
+
@@ -59,6 +71,21 @@ PostgreSQL documentation
+
+
+
+
+
+ Specifies the cutoff percentage for the list of exact observed
+ timing durations (that is, the changes in the system clock value
+ from one reading to the next). The list will end once the running
+ percentage total reaches or exceeds this value, except that the
+ largest observed duration will always be printed. The default
+ cutoff is 99.99.
+
+
+
+
@@ -92,205 +119,83 @@ PostgreSQL documentation
Interpreting Results
- Good results will show most (>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:
-
-
+ The first block of output has four columns, with rows showing a
+ shifted-by-one log2(ns) histogram of timing durations (that is, the
+ differences between successive clock readings). This is not the
+ classic log2(n+1) histogram as it counts zeros separately and then
+ switches to log2(ns) starting from value 1.
-
- 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).
+ The columns are:
+
+
+ nanosecond value that is >= the durations in this
+ bucket
+
+
+ percentage of durations in this bucket
+
+
+ running-sum percentage of durations in this and previous
+ buckets
+
+
+ count of durations in this bucket
+
+
-
-
-
- Measuring Executor Timing Overhead
-
- When the query executor is running a statement using
- EXPLAIN ANALYZE, individual operations are timed as well
- as showing a summary. The overhead of your system can be checked by
- counting rows with the psql program:
-
-
-CREATE TABLE t AS SELECT * FROM generate_series(1,100000);
-\timing
-SELECT COUNT(*) FROM t;
-EXPLAIN ANALYZE SELECT COUNT(*) FROM t;
-
+ The second block of output goes into more detail, showing the exact
+ timing differences observed. For brevity this list is cut off when the
+ running-sum percentage exceeds the user-selectable cutoff value.
+ However, the largest observed difference is always shown.
-
- The i7-860 system measured runs the count query in 9.8 ms while
- the EXPLAIN ANALYZE 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.
+ The example results below show that 99.99% of timing loops took between
+ 8 and 31 nanoseconds, with the worst case somewhere between 32768 and
+ 65535 nanoseconds. In the second block, we can see that typical loop
+ time is 16 nanoseconds, and the readings appear to have full nanosecond
+ precision.
-
-
-
- Changing Time Sources
- 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:
-
/sys/devices/system/clocksource/clocksource0/current_clocksource
-# pg_test_timing
-Per loop time including overhead: 722.92 ns
+Testing timing overhead for 3 seconds.
+Average loop time including overhead: 16.40 ns
Histogram of timing durations:
- < us % of total count
- 1 27.84870 1155682
- 2 72.05956 2990371
- 4 0.07810 3241
- 8 0.01357 563
- 16 0.00007 3
+ <= ns % of total running % count
+ 0 0.0000 0.0000 0
+ 1 0.0000 0.0000 0
+ 3 0.0000 0.0000 0
+ 7 0.0000 0.0000 0
+ 15 4.5452 4.5452 8313178
+ 31 95.4527 99.9979 174581501
+ 63 0.0001 99.9981 253
+ 127 0.0001 99.9982 165
+ 255 0.0000 99.9982 35
+ 511 0.0000 99.9982 1
+ 1023 0.0013 99.9994 2300
+ 2047 0.0004 99.9998 690
+ 4095 0.0000 99.9998 9
+ 8191 0.0000 99.9998 8
+ 16383 0.0002 100.0000 337
+ 32767 0.0000 100.0000 2
+ 65535 0.0000 100.0000 1
+
+Observed timing durations up to 99.9900%:
+ ns % of total running % count
+ 15 4.5452 4.5452 8313178
+ 16 58.3785 62.9237 106773354
+ 17 33.6840 96.6078 61607584
+ 18 3.1151 99.7229 5697480
+ 19 0.2638 99.9867 482570
+ 20 0.0093 99.9960 17054
+...
+ 38051 0.0000 100.0000 1
]]>
-
- In this configuration, the sample EXPLAIN ANALYZE 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 EXPLAIN ANALYZE totals involving
- many timed operations would be inflated significantly by timing overhead.
-
-
-
- FreeBSD also allows changing the time source on the fly, and it logs
- information about the timer selected during boot:
-
-
-# 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 -> TSC
-
-
-
-
- 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:
-
-
-
-
-
- Clock Hardware and Timing Accuracy
-
-
- 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.
-
-
-
- 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.
-
-
-
- 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.
-
-
-
- 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.
-
-
-
- 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.
-
-
-
- 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.
-
-
-
- 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.
-
-
@@ -298,6 +203,8 @@ Histogram of timing durations:
+ Wiki
+ discussion about timing
diff --git a/doc/src/sgml/ref/pgupgrade.sgml b/doc/src/sgml/ref/pgupgrade.sgml
index 9877f2f01c691..356baa912991d 100644
--- a/doc/src/sgml/ref/pgupgrade.sgml
+++ b/doc/src/sgml/ref/pgupgrade.sgml
@@ -67,9 +67,17 @@ PostgreSQL documentation
- pg_upgrade supports upgrades from 9.2.X and later to the current
+ pg_upgrade supports upgrades from 9.2.X and later to the current
major release of PostgreSQL, including snapshot and beta releases.
+
+
+
+ Upgrading a cluster causes the destination to execute arbitrary code of the
+ source superusers' choice. Ensure that the source superusers are trusted
+ before upgrading.
+
+
@@ -118,7 +126,7 @@ PostgreSQL documentation
- number of simultaneous processes or threads to use
+ number of simultaneous connections and processes/threads to use
@@ -235,7 +243,8 @@ PostgreSQL documentation
Copy files to the new cluster. This is the default. (See also
- and .)
+ , ,
+ , and .)
@@ -253,6 +262,94 @@ PostgreSQL documentation
+
+
+
+
+ Do not restore statistics from the old cluster into the new cluster.
+
+
+
+
+
+ option
+
+
+ Manually set the default char signedness of new clusters. Possible values
+ are signed and unsigned.
+
+
+ In the C language, the default signedness of the char type
+ (when not explicitly specified) varies across platforms. For example,
+ char defaults to signed char on x86 CPUs but
+ to unsigned char on ARM CPUs.
+
+
+ Starting from PostgreSQL 18, database clusters
+ maintain their own default char signedness setting, which can be used to
+ ensure consistent behavior across platforms with different default char
+ signedness. By default, pg_upgrade preserves
+ the char signedness setting when upgrading from an existing cluster.
+ However, when upgrading from PostgreSQL 17 or
+ earlier, pg_upgrade adopts the char signedness
+ of the platform on which it was built.
+
+
+ This option allows you to explicitly set the default char signedness for
+ the new cluster, overriding any inherited values. There are two specific
+ scenarios where this option is relevant:
+
+
+
+ If you are planning to migrate to a different platform after the upgrade,
+ you should not use this option. The default behavior is right in this case.
+ Instead, perform the upgrade on the original platform without this flag,
+ and then migrate the cluster afterward. This is the recommended and safest
+ approach.
+
+
+
+
+ If you have already migrated the cluster to a platform with different
+ char signedness (for example, from an x86-based system to an ARM-based
+ system), you should use this option to specify the signedness matching
+ the original platform's default char signedness. Additionally, it's
+ essential not to modify any data files between migrating data files and
+ running pg_upgrade. pg_upgrade
+ should be the first operation that starts the cluster on the new platform.
+
+
+
+
+
+
+
+
+
+
+
+ Move the data directories from the old cluster to the new cluster.
+ Then, replace the catalog files with those generated for the new
+ cluster. This mode can outperform ,
+ , , and
+ , especially on clusters with many
+ relations.
+
+
+ However, this mode creates many garbage files in the old cluster, which
+ can prolong the file synchronization step if
+ is used. Therefore, it is
+ recommended to use with
+ .
+
+
+ Additionally, once the file transfer step begins, the old cluster will
+ be destructively modified and therefore will no longer be safe to
+ start. See for details.
+
+
+
+
method
@@ -295,6 +392,14 @@ PostgreSQL documentation
with pg_upgrade:
+
+
+ The steps to upgrade logical replication clusters
+ are not covered here;
+ refer to for details.
+
+
+
Optionally move the old cluster
@@ -396,129 +501,6 @@ make prefix=/usr/local/pgsql.new install
-
- Prepare for publisher upgrades
-
-
- pg_upgrade attempts to migrate logical
- slots. This helps avoid the need for manually defining the same
- logical slots on the new publisher. Migration of logical slots is
- only supported when the old cluster is version 17.0 or later.
- Logical slots on clusters before version 17.0 will silently be
- ignored.
-
-
-
- Before you start upgrading the publisher cluster, ensure that the
- subscription is temporarily disabled, by executing
- ALTER SUBSCRIPTION ... DISABLE.
- Re-enable the subscription after the upgrade.
-
-
-
- There are some prerequisites for pg_upgrade to
- be able to upgrade the logical slots. If these are not met an error
- will be reported.
-
-
-
-
-
- The new cluster must have
- wal_level as
- logical.
-
-
-
-
- The new cluster must have
- max_replication_slots
- configured to a value greater than or equal to the number of slots
- present in the old cluster.
-
-
-
-
- The output plugins referenced by the slots on the old cluster must be
- installed in the new PostgreSQL executable directory.
-
-
-
-
- The old cluster has replicated all the transactions and logical decoding
- messages to subscribers.
-
-
-
-
- All slots on the old cluster must be usable, i.e., there are no slots
- whose
- pg_replication_slots.conflicting
- is not true.
-
-
-
-
- The new cluster must not have permanent logical slots, i.e.,
- there must be no slots where
- pg_replication_slots.temporary
- is false.
-
-
-
-
-
-
-
- Prepare for subscriber upgrades
-
-
- Setup the
- subscriber configurations in the new subscriber.
- pg_upgrade attempts to migrate subscription
- dependencies which includes the subscription's table information present in
- pg_subscription_rel
- system catalog and also the subscription's replication origin. This allows
- logical replication on the new subscriber to continue from where the
- old subscriber was up to. Migration of subscription dependencies is only
- supported when the old cluster is version 17.0 or later. Subscription
- dependencies on clusters before version 17.0 will silently be ignored.
-
-
-
- There are some prerequisites for pg_upgrade to
- be able to upgrade the subscriptions. If these are not met an error
- will be reported.
-
-
-
-
-
- All the subscription tables in the old subscriber should be in state
- i (initialize) or r (ready). This
- can be verified by checking pg_subscription_rel.srsubstate.
-
-
-
-
- The replication origin entry corresponding to each of the subscriptions
- should exist in the old cluster. This can be found by checking
- pg_subscription and
- pg_replication_origin
- system tables.
-
-
-
-
- The new cluster must have
- max_replication_slots
- configured to a value greater than or equal to the number of
- subscriptions present in the old cluster.
-
-
-
-
-
Stop both servers
@@ -566,7 +548,7 @@ NET STOP postgresql-&majorversion;
Always run the pg_upgrade binary of the new server, not the old one.
pg_upgrade requires the specification of the old and new cluster's
data and executable (bin) directories. You can also specify
- user and port values, and whether you want the data files linked or cloned
+ user and port values, and whether you want the data files linked, cloned, or swapped
instead of the default copy behavior.
@@ -583,15 +565,18 @@ NET STOP postgresql-&majorversion;
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.
+ Swap mode may be the fastest if there are many relations, but you will not
+ be able to access your old cluster once the file transfer step begins.
+ Swap mode also requires that the old and new cluster data directories be
+ in the same file system.
- The 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.
+ Setting to 2 or higher allows pg_upgrade to
+ process multiple databases and tablespaces in parallel. A good starting
+ point is the number of CPU cores on the machine. This option can
+ substantially reduce the upgrade time for multi-database and
+ multi-tablespace servers.
@@ -612,8 +597,9 @@ pg_upgrade.exe
to perform only the checks, even if the old server is still
running. pg_upgrade --check 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
- or with
+ are going to be using link, clone, copy-file-range, or swap mode, you
+ should use the option , ,
+ , or with
to enable mode-specific checks.
pg_upgrade requires write permission in the current directory.
@@ -845,17 +831,29 @@ psql --username=postgres --file=script.sql postgres
Statistics
- Because optimizer statistics are not transferred by pg_upgrade, 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.
+ Unless the option is specified,
+ pg_upgrade will transfer most optimizer statistics
+ from the old cluster to the new cluster. However, some statistics may
+ not be transferred, such as those created explicitly with or custom statistics added by an
+ extension.
- Using vacuumdb --all --analyze-only can efficiently
- generate such statistics, and the use of
- can speed it up. Option
- can be used to generate minimal statistics quickly.
+ Because not all statistics are transferred by
+ pg_upgrade, you will be instructed to run commands to
+ regenerate that information at the end of the upgrade. You might need to
+ set connection parameters to match your new cluster.
+
+
+
+ First, use
+ vacuumdb --all --analyze-in-stages --missing-stats-only
+ to quickly generate minimal optimizer statistics for relations without
+ any. Then, use vacuumdb --all --analyze-only to ensure
+ all relations have updated cumulative statistics for triggering vacuum and
+ analyze. For both commands, the use of can speed
+ it up.
If vacuum_cost_delay is set to a non-zero
value, this can be overridden to speed up statistics generation
using PGOPTIONS, e.g., PGOPTIONS='-c
@@ -893,7 +891,7 @@ psql --username=postgres --file=script.sql postgres
- If the option was not
+ If neither nor was
used, the old cluster was unmodified; it can be restarted.
@@ -933,6 +931,32 @@ psql --username=postgres --file=script.sql postgres
+
+
+
+ If the option was used, the old cluster might
+ be destructively modified:
+
+
+
+
+ If pg_upgrade aborts before reporting that the
+ old cluster is no longer safe to start, the old cluster was
+ unmodified; it can be restarted.
+
+
+
+
+
+ If pg_upgrade has reported that the old cluster
+ is no longer safe to start, the old cluster was destructively
+ modified. The old cluster will need to be restored from backup in
+ this case.
+
+
+
+
+
@@ -1094,7 +1118,8 @@ psql --username=postgres --file=script.sql postgres
regprocregprocedure
- (regclass, regrole, and regtype can be upgraded.)
+ (regclass, regdatabase, regrole, and
+ regtype can be upgraded.)
diff --git a/doc/src/sgml/ref/psql-ref.sgml b/doc/src/sgml/ref/psql-ref.sgml
index 830306ea1e202..1a339600bc48f 100644
--- a/doc/src/sgml/ref/psql-ref.sgml
+++ b/doc/src/sgml/ref/psql-ref.sgml
@@ -864,6 +864,13 @@ testdb=>
same line.
+
+ Many of the meta-commands also allow x to be appended
+ as an option. This will cause the results to be displayed in expanded
+ mode, as if \x or \pset expanded
+ had been used.
+
+
The following meta-commands are defined:
@@ -908,11 +915,42 @@ INSERT INTO tbl1 VALUES ($1, $2) \bind 'first value' 'second value' \g
linkend="protocol-query-concepts"/>) to be used, unlike normal
psql operation, which uses the simple
query protocol. So this command can be useful to test the extended
- query protocol from psql. (The extended query protocol is used even
- if the query has no parameters and this command specifies zero
- parameters.) This command affects only the next query executed; all
- subsequent queries will use the simple query protocol by default.
+ query protocol from psql. (The extended
+ query protocol is used even if the query has no parameters and this
+ command specifies zero parameters.) This command affects only the
+ next query executed; all subsequent queries will use the simple query
+ protocol by default.
+
+
+
+
+
+ \bind_namedstatement_name [ parameter ] ...
+
+
+
+ \bind_named is equivalent to \bind,
+ except that it takes the name of an existing prepared statement as
+ first parameter. An empty string denotes the unnamed prepared
+ statement.
+
+
+
+ Example:
+
+INSERT INTO tbls1 VALUES ($1, $2) \parse stmt1
+\bind_named stmt1 'first value' 'second value' \g
+
+
+
+ This command causes the extended query protocol (see
+ ) to be used, unlike normal
+ psql operation, which uses the simple
+ query protocol. So this command can be useful to test the extended
+ query protocol from psql.
+
+
@@ -1017,7 +1055,8 @@ INSERT INTO tbl1 VALUES ($1, $2) \bind 'first value' 'second value' \g
Changes the current working directory to
directory. Without argument, changes
- to the current user's home directory.
+ to the current user's home directory. For details on how home
+ directories are found, see .
@@ -1028,12 +1067,51 @@ INSERT INTO tbl1 VALUES ($1, $2) \bind 'first value' 'second value' \g
+
+ \close_preparedprepared_statement_name
+
+
+
+ Closes the specified prepared statement. An empty string denotes the
+ unnamed prepared statement. If no prepared statement exists with this
+ name, the operation is a no-op.
+
+
+
+ Example:
+
+SELECT $1 \parse stmt1
+\close_prepared stmt1
+
+
+
+
+ This command causes the extended query protocol to be used,
+ unlike normal psql operation, which
+ uses the simple query protocol. So this command can be useful
+ to test the extended query protocol from
+ psql.
+
+
+
+
+
\conninfo
-
- Outputs information about the current database connection.
-
+
+ Outputs information about the current database connection,
+ including SSL-related information if SSL is in use.
+
+
+ Note that the Client User field shows
+ the user at the time of connection, while the
+ Superuser field indicates whether
+ the current user (in the current execution context) has
+ superuser privileges. These users are usually the same, but they can
+ differ, for example, if the current user was changed with the
+ SET ROLE command.
+
@@ -1075,7 +1153,8 @@ INSERT INTO tbl1 VALUES ($1, $2) \bind 'first value' 'second value' \g
For \copy ... from stdin, data rows are read from the same
- source that issued the command, continuing until \.
+ source that issued the command, continuing until a line containing
+ only \.
is read or the stream reaches EOF. This option is useful
for populating tables in-line within an SQL script file.
For \copy ... to stdout, output is sent to the same place
@@ -1119,10 +1198,6 @@ INSERT INTO tbl1 VALUES ($1, $2) \bind 'first value' 'second value' \g
destination, because all data must pass through the client/server
connection. For large amounts of data the SQL
command might be preferable.
- Also, because of this pass-through method, \copy
- ... from in CSV mode will erroneously
- treat a \. data value alone on a line as an
- end-of-input marker.
@@ -1214,7 +1289,7 @@ INSERT INTO tbl1 VALUES ($1, $2) \bind 'first value' 'second value' \g
- \d[S+] [ pattern ]
+ \d[Sx+] [ pattern ]
@@ -1263,12 +1338,24 @@ INSERT INTO tbl1 VALUES ($1, $2) \bind 'first value' 'second value' \g
foreign tables.
This is purely a convenience measure.
+
+ As with many other commands, if x is appended to
+ the command name, the results are displayed in expanded mode, but note
+ that this only applies when \d is used without a
+ pattern argument, and
+ the x modifier cannot appear immediately after the
+ \d (because \dx is a different
+ command); the x modifier may only appear after an
+ S or + modifier. For example,
+ \d+x is equivalent to \dtvmsE+x
+ and will show a list of all relations in expanded mode.
+
- \da[S] [ pattern ]
+ \da[Sx] [ pattern ]
@@ -1279,19 +1366,23 @@ INSERT INTO tbl1 VALUES ($1, $2) \bind 'first value' 'second value' \g
By default, only user-created objects are shown; supply a
pattern or the S modifier to include system
objects.
+ If x is appended to the command name, the results
+ are displayed in expanded mode.
- \dA[+] [ pattern ]
+ \dA[x+] [ pattern ]
Lists access methods. If pattern is specified, only access
- methods whose names match the pattern are shown. If
- + is appended to the command name, each access
+ methods whose names match the pattern are shown.
+ If x is appended to the command name, the results
+ are displayed in expanded mode.
+ If + is appended to the command name, each access
method is listed with its associated handler function and description.
@@ -1299,7 +1390,7 @@ INSERT INTO tbl1 VALUES ($1, $2) \bind 'first value' 'second value' \g
- \dAc[+]
+ \dAc[x+]
[access-method-pattern
[input-type-pattern]]
@@ -1314,6 +1405,8 @@ INSERT INTO tbl1 VALUES ($1, $2) \bind 'first value' 'second value' \g
If input-type-pattern
is specified, only operator classes associated with input types whose
names match that pattern are listed.
+ If x is appended to the command name, the results
+ are displayed in expanded mode.
If + is appended to the command name, each operator
class is listed with its associated operator family and owner.
@@ -1322,7 +1415,7 @@ INSERT INTO tbl1 VALUES ($1, $2) \bind 'first value' 'second value' \g
- \dAf[+]
+ \dAf[x+]
[access-method-pattern
[input-type-pattern]]
@@ -1337,6 +1430,8 @@ INSERT INTO tbl1 VALUES ($1, $2) \bind 'first value' 'second value' \g
If input-type-pattern
is specified, only operator families associated with input types whose
names match that pattern are listed.
+ If x is appended to the command name, the results
+ are displayed in expanded mode.
If + is appended to the command name, each operator
family is listed with its owner.
@@ -1345,7 +1440,7 @@ INSERT INTO tbl1 VALUES ($1, $2) \bind 'first value' 'second value' \g
- \dAo[+]
+ \dAo[x+]
[access-method-pattern
[operator-family-pattern]]
@@ -1361,15 +1456,18 @@ INSERT INTO tbl1 VALUES ($1, $2) \bind 'first value' 'second value' \g
If operator-family-pattern
is specified, only members of operator families whose names match that
pattern are listed.
+ If x is appended to the command name, the results
+ are displayed in expanded mode.
If + is appended to the command name, each operator
- is listed with its sort operator family (if it is an ordering operator).
+ is listed with its sort operator family (if it is an ordering operator),
+ and whether its underlying function is leakproof.
- \dAp[+]
+ \dAp[x+]
[access-method-pattern
[operator-family-pattern]]
@@ -1384,6 +1482,8 @@ INSERT INTO tbl1 VALUES ($1, $2) \bind 'first value' 'second value' \g
If operator-family-pattern
is specified, only functions of operator families whose names match
that pattern are listed.
+ If x is appended to the command name, the results
+ are displayed in expanded mode.
If + is appended to the command name, functions are
displayed verbosely, with their actual parameter lists.
@@ -1391,13 +1491,15 @@ INSERT INTO tbl1 VALUES ($1, $2) \bind 'first value' 'second value' \g
- \db[+] [ pattern ]
+ \db[x+] [ pattern ]
Lists tablespaces. If pattern
is specified, only tablespaces whose names match the pattern are shown.
+ If x is appended to the command name, the results
+ are displayed in expanded mode.
If + is appended to the command name, each tablespace
is listed with its associated options, on-disk size, permissions and
description.
@@ -1407,7 +1509,7 @@ INSERT INTO tbl1 VALUES ($1, $2) \bind 'first value' 'second value' \g
- \dc[S+] [ pattern ]
+ \dc[Sx+] [ pattern ]
Lists conversions between character-set encodings.
@@ -1417,6 +1519,8 @@ INSERT INTO tbl1 VALUES ($1, $2) \bind 'first value' 'second value' \g
By default, only user-created objects are shown; supply a
pattern or the S modifier to include system
objects.
+ If x is appended to the command name, the results
+ are displayed in expanded mode.
If + is appended to the command name, each object
is listed with its associated description.
@@ -1425,7 +1529,7 @@ INSERT INTO tbl1 VALUES ($1, $2) \bind 'first value' 'second value' \g
- \dconfig[+] [ pattern ]
+ \dconfig[x+] [ pattern ]
Lists server configuration parameters and their values.
@@ -1434,6 +1538,8 @@ INSERT INTO tbl1 VALUES ($1, $2) \bind 'first value' 'second value' \g
a pattern, only
parameters that are set to non-default values are listed.
(Use \dconfig * to see all parameters.)
+ If x is appended to the command name, the results
+ are displayed in expanded mode.
If + 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
@@ -1444,22 +1550,25 @@ INSERT INTO tbl1 VALUES ($1, $2) \bind 'first value' 'second value' \g
- \dC[+] [ pattern ]
+ \dC[x+] [ pattern ]
Lists type casts.
If pattern
is specified, only casts whose source or target types match the
pattern are listed.
- If + is appended to the command name, each object
- is listed with its associated description.
+ If x is appended to the command name, the results
+ are displayed in expanded mode.
+ If + is appended to the command name, additional
+ information about each cast is shown, including whether its underlying
+ function is leakproof, and the cast's description.
- \dd[S] [ pattern ]
+ \dd[Sx] [ pattern ]
Shows the descriptions of objects of type constraint,
@@ -1476,6 +1585,8 @@ INSERT INTO tbl1 VALUES ($1, $2) \bind 'first value' 'second value' \g
By default, only user-created objects are shown; supply a
pattern or the S modifier to include system
objects.
+ If x is appended to the command name, the results
+ are displayed in expanded mode.
@@ -1488,7 +1599,7 @@ INSERT INTO tbl1 VALUES ($1, $2) \bind 'first value' 'second value' \g
- \dD[S+] [ pattern ]
+ \dD[Sx+] [ pattern ]
Lists domains. If S modifier to include system
objects.
+ If x is appended to the command name, the results
+ are displayed in expanded mode.
If + is appended to the command name, each object
is listed with its associated permissions and description.
@@ -1505,7 +1618,7 @@ INSERT INTO tbl1 VALUES ($1, $2) \bind 'first value' 'second value' \g
- \ddp [ pattern ]
+ \ddp[x] [ pattern ]
Lists default access privilege settings. An entry is shown for
@@ -1514,6 +1627,8 @@ INSERT INTO tbl1 VALUES ($1, $2) \bind 'first value' 'second value' \g
If pattern is
specified, only entries whose role name or schema name matches
the pattern are listed.
+ If x is appended to the command name, the results
+ are displayed in expanded mode.
@@ -1527,12 +1642,12 @@ INSERT INTO tbl1 VALUES ($1, $2) \bind 'first value' 'second value' \g
- \dE[S+] [ pattern ]
- \di[S+] [ pattern ]
- \dm[S+] [ pattern ]
- \ds[S+] [ pattern ]
- \dt[S+] [ pattern ]
- \dv[S+] [ pattern ]
+ \dE[Sx+] [ pattern ]
+ \di[Sx+] [ pattern ]
+ \dm[Sx+] [ pattern ]
+ \ds[Sx+] [ pattern ]
+ \dt[Sx+] [ pattern ]
+ \dv[Sx+] [ pattern ]
@@ -1545,7 +1660,10 @@ INSERT INTO tbl1 VALUES ($1, $2) \bind 'first value' 'second value' \g
You can specify any or all of
these letters, in any order, to obtain a listing of objects
of these types. For example, \dti lists
- tables and indexes. If + is
+ tables and indexes.
+ If x is appended to the command name, the results
+ are displayed in expanded mode.
+ If + 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.
@@ -1560,14 +1678,17 @@ INSERT INTO tbl1 VALUES ($1, $2) \bind 'first value' 'second value' \g
- \des[+] [ pattern ]
+ \des[x+] [ pattern ]
Lists foreign servers (mnemonic: external
servers).
If pattern is
specified, only those servers whose name matches the pattern
- are listed. If the form \des+ is used, a
+ are listed.
+ If x is appended to the command name, the results
+ are displayed in expanded mode.
+ If + is appended to the command name, a
full description of each server is shown, including the
server's access privileges, type, version, options, and description.
@@ -1576,14 +1697,17 @@ INSERT INTO tbl1 VALUES ($1, $2) \bind 'first value' 'second value' \g
- \det[+] [ pattern ]
+ \det[x+] [ pattern ]
Lists foreign tables (mnemonic: external tables).
If pattern is
specified, only entries whose table name or schema name matches
- the pattern are listed. If the form \det+
- is used, generic options and the foreign table description
+ the pattern are listed.
+ If x is appended to the command name, the results
+ are displayed in expanded mode.
+ If + is appended to the command name,
+ generic options and the foreign table description
are also displayed.
@@ -1591,15 +1715,18 @@ INSERT INTO tbl1 VALUES ($1, $2) \bind 'first value' 'second value' \g
- \deu[+] [ pattern ]
+ \deu[x+] [ pattern ]
Lists user mappings (mnemonic: external
users).
If pattern is
specified, only those mappings whose user names match the
- pattern are listed. If the form \deu+ is
- used, additional information about each mapping is shown.
+ pattern are listed.
+ If x is appended to the command name, the results
+ are displayed in expanded mode.
+ If + is appended to the command name,
+ additional information about each mapping is shown.
@@ -1614,15 +1741,18 @@ INSERT INTO tbl1 VALUES ($1, $2) \bind 'first value' 'second value' \g
- \dew[+] [ pattern ]
+ \dew[x+] [ pattern ]
Lists foreign-data wrappers (mnemonic: external
wrappers).
If pattern is
specified, only those foreign-data wrappers whose name matches
- the pattern are listed. If the form \dew+
- is used, the access privileges, options, and description of the
+ the pattern are listed.
+ If x is appended to the command name, the results
+ are displayed in expanded mode.
+ If + is appended to the command name,
+ the access privileges, options, and description of the
foreign-data wrapper are also shown.
@@ -1630,7 +1760,7 @@ INSERT INTO tbl1 VALUES ($1, $2) \bind 'first value' 'second value' \g
- \df[anptwS+] [ pattern [ arg_pattern ... ] ]
+ \df[anptwSx+] [ pattern [ arg_pattern ... ] ]
@@ -1651,11 +1781,13 @@ INSERT INTO tbl1 VALUES ($1, $2) \bind 'first value' 'second value' \g
By default, only user-created
objects are shown; supply a pattern or the S
modifier to include system objects.
- If the form \df+ is used, additional information
+ If x is appended to the command name, the results
+ are displayed in expanded mode.
+ If + is appended to the command name, additional information
about each function is shown, including volatility,
- parallel safety, owner, security classification, access privileges,
- language, internal name (for C and internal functions only),
- and description.
+ parallel safety, owner, security classification, whether it is
+ leakproof, access privileges, language, internal name (for C and
+ internal functions only), and description.
Source code for a specific function can be seen
using \sf.
@@ -1664,13 +1796,15 @@ INSERT INTO tbl1 VALUES ($1, $2) \bind 'first value' 'second value' \g
- \dF[+] [ pattern ]
+ \dF[x+] [ pattern ]
Lists text search configurations.
If pattern is specified,
only configurations whose names match the pattern are shown.
- If the form \dF+ is used, a full description of
+ If x is appended to the command name, the results
+ are displayed in expanded mode.
+ If + is appended to the command name, a full description of
each configuration is shown, including the underlying text search
parser and the dictionary list for each parser token type.
@@ -1678,13 +1812,15 @@ INSERT INTO tbl1 VALUES ($1, $2) \bind 'first value' 'second value' \g
- \dFd[+] [ pattern ]
+ \dFd[x+] [ pattern ]
Lists text search dictionaries.
If pattern is specified,
only dictionaries whose names match the pattern are shown.
- If the form \dFd+ is used, additional information
+ If x is appended to the command name, the results
+ are displayed in expanded mode.
+ If + is appended to the command name, additional information
is shown about each selected dictionary, including the underlying
text search template and the option values.
@@ -1692,13 +1828,15 @@ INSERT INTO tbl1 VALUES ($1, $2) \bind 'first value' 'second value' \g
- \dFp[+] [ pattern ]
+ \dFp[x+] [ pattern ]
Lists text search parsers.
If pattern is specified,
only parsers whose names match the pattern are shown.
- If the form \dFp+ is used, a full description of
+ If x is appended to the command name, the results
+ are displayed in expanded mode.
+ If + is appended to the command name, a full description of
each parser is shown, including the underlying functions and the
list of recognized token types.
@@ -1706,13 +1844,15 @@ INSERT INTO tbl1 VALUES ($1, $2) \bind 'first value' 'second value' \g
- \dFt[+] [ pattern ]
+ \dFt[x+] [ pattern ]
Lists text search templates.
If pattern is specified,
only templates whose names match the pattern are shown.
- If the form \dFt+ is used, additional information
+ If x is appended to the command name, the results
+ are displayed in expanded mode.
+ If + is appended to the command name, additional information
is shown about each template, including the underlying function names.
@@ -1720,7 +1860,7 @@ INSERT INTO tbl1 VALUES ($1, $2) \bind 'first value' 'second value' \g
- \dg[S+] [ pattern ]
+ \dg[Sx+] [ pattern ]
Lists database roles.
@@ -1731,7 +1871,9 @@ INSERT INTO tbl1 VALUES ($1, $2) \bind 'first value' 'second value' \g
S modifier to include system roles.
If pattern is specified,
only those roles whose names match the pattern are listed.
- If the form \dg+ is used, additional information
+ If x is appended to the command name, the results
+ are displayed in expanded mode.
+ If + is appended to the command name, additional information
is shown about each role; currently this adds the comment for each
role.
@@ -1740,11 +1882,13 @@ INSERT INTO tbl1 VALUES ($1, $2) \bind 'first value' 'second value' \g
- \dl[+]
+ \dl[x+]
This is an alias for \lo_list, which shows a
list of large objects.
+ If x is appended to the command name, the results
+ are displayed in expanded mode.
If + is appended to the command name,
each large object is listed with its associated permissions,
if any.
@@ -1753,7 +1897,7 @@ INSERT INTO tbl1 VALUES ($1, $2) \bind 'first value' 'second value' \g
- \dL[S+] [ pattern ]
+ \dL[Sx+] [ pattern ]
Lists procedural languages. If S modifier to include system
- objects. If + is appended to the command name, each
+ objects.
+ If x is appended to the command name, the results
+ are displayed in expanded mode.
+ If + is appended to the command name, each
language is listed with its call handler, validator, access privileges,
and whether it is a system object.
@@ -1770,7 +1917,7 @@ INSERT INTO tbl1 VALUES ($1, $2) \bind 'first value' 'second value' \g
- \dn[S+] [ pattern ]
+ \dn[Sx+] [ pattern ]
@@ -1779,6 +1926,8 @@ INSERT INTO tbl1 VALUES ($1, $2) \bind 'first value' 'second value' \g
is specified, only schemas whose names match the pattern are listed.
By default, only user-created objects are shown; supply a
pattern or the S modifier to include system objects.
+ If x is appended to the command name, the results
+ are displayed in expanded mode.
If + is appended to the command name, each object
is listed with its associated permissions and description, if any.
@@ -1787,7 +1936,7 @@ INSERT INTO tbl1 VALUES ($1, $2) \bind 'first value' 'second value' \g
- \do[S+] [ pattern [ arg_pattern [ arg_pattern ] ] ]
+ \do[Sx+] [ pattern [ arg_pattern [ arg_pattern ] ] ]
Lists operators with their operand and result types.
@@ -1803,16 +1952,18 @@ INSERT INTO tbl1 VALUES ($1, $2) \bind 'first value' 'second value' \g
By default, only user-created objects are shown; supply a
pattern or the S modifier to include system
objects.
+ If x is appended to the command name, the results
+ are displayed in expanded mode.
If + is appended to the command name,
- additional information about each operator is shown, currently just
- the name of the underlying function.
+ additional information about each operator is shown, including
+ the name of the underlying function, and whether it is leakproof.
- \dO[S+] [ pattern ]
+ \dO[Sx+] [ pattern ]
Lists collations.
@@ -1820,7 +1971,10 @@ INSERT INTO tbl1 VALUES ($1, $2) \bind 'first value' 'second value' \g
specified, only collations whose names match the pattern are
listed. By default, only user-created objects are shown;
supply a pattern or the S modifier to
- include system objects. If + is appended
+ include system objects.
+ If x is appended to the command name, the results
+ are displayed in expanded mode.
+ If + 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
@@ -1832,7 +1986,7 @@ INSERT INTO tbl1 VALUES ($1, $2) \bind 'first value' 'second value' \g
- \dp[S] [ pattern ]
+ \dp[Sx] [ pattern ]
Lists tables, views and sequences with their
@@ -1842,6 +1996,8 @@ INSERT INTO tbl1 VALUES ($1, $2) \bind 'first value' 'second value' \g
pattern are listed. By default only user-created objects are shown;
supply a pattern or the S modifier to include
system objects.
+ If x is appended to the command name, the results
+ are displayed in expanded mode.
@@ -1856,7 +2012,7 @@ INSERT INTO tbl1 VALUES ($1, $2) \bind 'first value' 'second value' \g
- \dP[itn+] [ pattern ]
+ \dP[itnx+] [ pattern ]
Lists partitioned relations.
@@ -1876,6 +2032,8 @@ INSERT INTO tbl1 VALUES ($1, $2) \bind 'first value' 'second value' \g
+ If x is appended to the command name, the results
+ are displayed in expanded mode.
If + 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.
@@ -1889,7 +2047,7 @@ INSERT INTO tbl1 VALUES ($1, $2) \bind 'first value' 'second value' \g
- \drds [ role-pattern [ database-pattern ] ]
+ \drds[x] [ role-pattern [ database-pattern ] ]
Lists defined configuration settings. These settings can be
@@ -1899,6 +2057,8 @@ INSERT INTO tbl1 VALUES ($1, $2) \bind 'first value' 'second value' \g
specific roles and databases to list, respectively. If omitted, or if
* is specified, all settings are listed, including those
not role-specific or database-specific, respectively.
+ If x is appended to the command name, the results
+ are displayed in expanded mode.
@@ -1912,7 +2072,7 @@ INSERT INTO tbl1 VALUES ($1, $2) \bind 'first value' 'second value' \g
- \drg[S] [ pattern ]
+ \drg[Sx] [ pattern ]
Lists information about each granted role membership, including
@@ -1926,19 +2086,23 @@ INSERT INTO tbl1 VALUES ($1, $2) \bind 'first value' 'second value' \g
S modifier to include system roles.
If pattern is specified,
only grants to those roles whose names match the pattern are listed.
+ If x is appended to the command name, the results
+ are displayed in expanded mode.
- \dRp[+] [ pattern ]
+ \dRp[x+] [ pattern ]
Lists replication publications.
If pattern is
specified, only those publications whose names match the pattern are
listed.
+ If x is appended to the command name, the results
+ are displayed in expanded mode.
If + is appended to the command name, the tables and
schemas associated with each publication are shown as well.
@@ -1946,13 +2110,15 @@ INSERT INTO tbl1 VALUES ($1, $2) \bind 'first value' 'second value' \g
- \dRs[+] [ pattern ]
+ \dRs[x+] [ pattern ]
Lists replication subscriptions.
If pattern is
specified, only those subscriptions whose names match the pattern are
listed.
+ If x is appended to the command name, the results
+ are displayed in expanded mode.
If + is appended to the command name, additional
properties of the subscriptions are shown.
@@ -1960,12 +2126,14 @@ INSERT INTO tbl1 VALUES ($1, $2) \bind 'first value' 'second value' \g
- \dT[S+] [ pattern ]
+ \dT[Sx+] [ pattern ]
Lists data types.
If pattern is
specified, only types whose names match the pattern are listed.
+ If x is appended to the command name, the results
+ are displayed in expanded mode.
If + is appended to the command name, each type is
listed with its internal name and size, its allowed values
if it is an enum type, and its associated permissions.
@@ -1977,7 +2145,7 @@ INSERT INTO tbl1 VALUES ($1, $2) \bind 'first value' 'second value' \g
- \du[S+] [ pattern ]
+ \du[Sx+] [ pattern ]
Lists database roles.
@@ -1988,7 +2156,9 @@ INSERT INTO tbl1 VALUES ($1, $2) \bind 'first value' 'second value' \g
S modifier to include system roles.
If pattern is specified,
only those roles whose names match the pattern are listed.
- If the form \du+ is used, additional information
+ If x is appended to the command name, the results
+ are displayed in expanded mode.
+ If + is appended to the command name, additional information
is shown about each role; currently this adds the comment for each
role.
@@ -1996,27 +2166,31 @@ INSERT INTO tbl1 VALUES ($1, $2) \bind 'first value' 'second value' \g
- \dx[+] [ pattern ]
+ \dx[x+] [ pattern ]
Lists installed extensions.
If pattern
is specified, only those extensions whose names match the pattern
are listed.
- If the form \dx+ is used, all the objects belonging
+ If x is appended to the command name, the results
+ are displayed in expanded mode.
+ If + is appended to the command name, all the objects belonging
to each matching extension are listed.
- \dX [ pattern ]
+ \dX[x] [ pattern ]
Lists extended statistics.
If pattern
is specified, only those extended statistics whose names match the
pattern are listed.
+ If x is appended to the command name, the results
+ are displayed in expanded mode.
@@ -2032,13 +2206,15 @@ INSERT INTO tbl1 VALUES ($1, $2) \bind 'first value' 'second value' \g
- \dy[+] [ pattern ]
+ \dy[x+] [ pattern ]
Lists event triggers.
If pattern
is specified, only those event triggers whose names match the pattern
are listed.
+ If x is appended to the command name, the results
+ are displayed in expanded mode.
If + is appended to the command name, each object
is listed with its associated description.
@@ -2626,13 +2802,15 @@ SELECT
- \l[+] or \list[+] [ pattern ]
+ \l[x+] or \list[x+] [ pattern ]
List the databases in the server and show their names, owners,
character set encodings, and access privileges.
If pattern is specified,
only databases whose names match the pattern are listed.
+ If x is appended to the command name, the results
+ are displayed in expanded mode.
If + 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
@@ -2696,12 +2874,14 @@ lo_import 152801
- \lo_list[+]
+ \lo_list[x+]
Shows a list of all PostgreSQL
large objects currently stored in the database,
along with any comments provided for them.
+ If x is appended to the command name, the results
+ are displayed in expanded mode.
If + is appended to the command name,
each large object is listed with its associated permissions,
if any.
@@ -2779,6 +2959,37 @@ lo_import 152801
+
+ \parse statement_name
+
+
+ Creates a prepared statement from the current query buffer, based on
+ the name of a destination prepared-statement object. An empty string
+ denotes the unnamed prepared statement.
+
+
+
+ Example:
+
+SELECT $1 \parse stmt1
+
+
+
+
+ This command causes the extended query protocol to be used, unlike
+ normal psql operation, which uses the
+ simple query protocol. A
+
+ message will be issued by this command so it can be useful to
+ test the extended query protocol from
+ psql. This command affects only the next
+ query executed; all subsequent queries will use the simple query
+ protocol by default.
+
+
+
+
+
\password [ username ]
@@ -3340,6 +3551,24 @@ lo_import 152801
+
+ \restrict restrict_key
+
+
+ Enter "restricted" mode with the provided key. In this mode, the only
+ allowed meta-command is \unrestrict, to exit
+ restricted mode. The key may contain only alphanumeric characters.
+
+
+ This command is primarily intended for use in plain-text dumps
+ generated by pg_dump,
+ pg_dumpall, and
+ pg_restore, but it may be useful elsewhere.
+
+
+
+
+
\s [ filename ]
@@ -3473,6 +3702,83 @@ testdb=> \setenv LESS -imx4F
+
+ \startpipeline
+ \sendpipeline
+ \syncpipeline
+ \endpipeline
+ \flushrequest
+ \flush
+ \getresults [ number_results ]
+
+
+
+ This group of commands implements pipelining of SQL statements.
+ A pipeline must begin with a \startpipeline
+ and end with an \endpipeline. In between there
+ may be any number of \syncpipeline commands,
+ which sends a sync message
+ without ending the ongoing pipeline and flushing the send buffer.
+ In pipeline mode, statements are sent to the server without waiting
+ for the results of previous statements.
+ See for more details.
+
+
+
+ All queries executed while a pipeline is ongoing use the extended
+ query protocol. Queries are appended to the pipeline when ending with
+ a semicolon. The meta-commands \bind,
+ \bind_named, \close_prepared or
+ \parse can be used in an ongoing pipeline. While
+ a pipeline is ongoing, \sendpipeline will append
+ the current query buffer to the pipeline. Other meta-commands like
+ \g, \gx or
+ \gdesc are not allowed in pipeline mode.
+
+
+
+ \flushrequest appends a flush command to the
+ pipeline, allowing to read results with
+ \getresults without issuing a sync or ending the
+ pipeline. \getresults will automatically push
+ unsent data to the server. \flush can be used to
+ manually push unsent data.
+
+
+
+ \getresults accepts an optional
+ number_results parameter.
+ If provided, only the first
+ number_results pending
+ results will be read. If not provided or 0, all
+ pending results are read.
+
+
+
+ When pipeline mode is active, a dedicated prompt variable is available
+ to report the pipeline status.
+ See for more details
+
+
+
+ COPY is not supported while in pipeline mode.
+
+
+
+ Example:
+
+\startpipeline
+SELECT * FROM pg_class;
+SELECT 1 \bind \sendpipeline
+\flushrequest
+\getresults
+\endpipeline
+
+
+
+
+
+
\t
@@ -3514,6 +3820,24 @@ testdb=> \setenv LESS -imx4F
+
+ \unrestrict restrict_key
+
+
+ Exit "restricted" mode (i.e., where all other meta-commands are
+ blocked), provided the specified key matches the one given to
+ \restrict when restricted mode was entered.
+
+
+ This command is primarily intended for use in plain-text dumps
+ generated by pg_dump,
+ pg_dumpall, and
+ pg_restore, but it may be useful elsewhere.
+
+
+
+
+
\unset name
@@ -3577,6 +3901,8 @@ testdb=> \setenv LESS -imx4F
until interrupted, or the query fails, or the execution count limit
(if given) is reached, or the query no longer returns the minimum number
of rows. Wait the specified number of seconds (default 2) between executions.
+ The default wait can be changed with the variable
+ .
For backwards compatibility,
seconds can be specified
with or without an interval= prefix.
@@ -3604,7 +3930,7 @@ testdb=> \setenv LESS -imx4F
- \z[S] [ pattern ]
+ \z[Sx] [ pattern ]
Lists tables, views and sequences with their
@@ -3614,6 +3940,8 @@ testdb=> \setenv LESS -imx4F
pattern are listed. By default only user-created objects are shown;
supply a pattern or the S modifier to include
system objects.
+ If x is appended to the command name, the results
+ are displayed in expanded mode.
@@ -4231,6 +4559,37 @@ bar
+
+ PIPELINE_COMMAND_COUNT
+
+
+ The number of commands queued in an ongoing pipeline.
+
+
+
+
+
+ PIPELINE_RESULT_COUNT
+
+
+ The number of commands of an ongoing pipeline that were followed
+ by either a \flushrequest or a
+ \syncpipeline, forcing the server to send the
+ results. These results can be retrieved with
+ \getresults.
+
+
+
+
+
+ PIPELINE_SYNC_COUNT
+
+
+ The number of sync messages queued in an ongoing pipeline.
+
+
+
+
PORT
@@ -4291,6 +4650,24 @@ bar
+
+ SERVICE
+
+
+ The service name, if applicable.
+
+
+
+
+
+ SERVICEFILE
+
+
+ The service file name, if applicable.
+
+
+
+
SHELL_ERROR
@@ -4334,7 +4711,8 @@ bar
When this variable is set to off, only the last
result of a combined query (\;) is shown instead of
all of them. The default is on. The off behavior
- is for compatibility with older versions of psql.
+ is for compatibility with older versions of
+ psql.
@@ -4428,6 +4806,18 @@ bar
+
+ WATCH_INTERVAL
+
+
+ This variable sets the default interval, in seconds, which
+ \watch waits between executing the query. The
+ default is 2 seconds. Specifying an interval in the command overrides
+ this variable.
+
+
+
+
@@ -4584,6 +4974,11 @@ testdb=> INSERT INTO my_table VALUES (:'content');
+
+ %s
+ The name of the service.
+
+
%/The name of the current database.
@@ -4615,6 +5010,17 @@ testdb=> INSERT INTO my_table VALUES (:'content');
+
+ %P
+
+
+ Pipeline status: off when not in a pipeline,
+ on when in an ongoing pipeline or
+ abort when in an aborted pipeline.
+
+
+
+
%R
@@ -5282,6 +5688,31 @@ testdb=> \df int*pl * bigint
+
+ Here, the + option is used to display additional
+ information about one of these functions, and x is used
+ to display the results in expanded mode:
+
+testdb=> \df+x int*pl integer bigint
+List of functions
+-[ RECORD 1 ]-------+-----------------------------
+Schema | pg_catalog
+Name | int48pl
+Result data type | bigint
+Argument data types | integer, bigint
+Type | func
+Volatility | immutable
+Parallel | safe
+Owner | postgres
+Security | invoker
+Leakproof? | no
+Access privileges |
+Language | internal
+Internal name | int48pl
+Description | implementation of + operator
+
+
+
When suitable, query results can be shown in a crosstab representation
with the \crosstabview command:
diff --git a/doc/src/sgml/ref/reindex.sgml b/doc/src/sgml/ref/reindex.sgml
index 2942dccf1e2e1..c405539714695 100644
--- a/doc/src/sgml/ref/reindex.sgml
+++ b/doc/src/sgml/ref/reindex.sgml
@@ -194,7 +194,8 @@ REINDEX [ ( option [, ...] ) ] { DA
VERBOSE
- Prints a progress report as each index is reindexed.
+ Prints a progress report as each index is reindexed
+ at INFO level.
@@ -305,7 +306,7 @@ REINDEX [ ( option [, ...] ) ] { DA
partitioned table, such commands skip the privilege checks when processing
the individual partitions. Reindexing a schema or database requires being the
owner of that schema or database or having privileges of the
- pg_maintain
+
role. Note specifically that it's thus
possible for non-superusers to rebuild indexes of tables owned by
other users. However, as a special exception,
@@ -464,14 +465,17 @@ Indexes:
If the index marked INVALID is suffixed
- ccnew, then it corresponds to the transient
+ _ccnew, then it corresponds to the transient
index created during the concurrent operation, and the recommended
recovery method is to drop it using DROP INDEX,
then attempt REINDEX CONCURRENTLY again.
- If the invalid index is instead suffixed ccold,
+ If the invalid index is instead suffixed _ccold,
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.
+ A nonzero number may be appended to the suffix of the invalid index
+ names to keep them unique, like _ccnew1,
+ _ccold2, etc.
diff --git a/doc/src/sgml/ref/reindexdb.sgml b/doc/src/sgml/ref/reindexdb.sgml
index 98c3333228fb9..abcb041179bb9 100644
--- a/doc/src/sgml/ref/reindexdb.sgml
+++ b/doc/src/sgml/ref/reindexdb.sgml
@@ -352,9 +352,8 @@ PostgreSQL documentation
- Specifies the name of the database to connect to to discover which
- databases should be reindexed,
- when / is used.
+ When the / is used, connect
+ to this database to gather the list of databases to reindex.
If not specified, the postgres database will be used,
or if that does not exist, template1 will be used.
This can be a connection
diff --git a/doc/src/sgml/ref/security_label.sgml b/doc/src/sgml/ref/security_label.sgml
index e5e5fb483e94e..aa45c0af2487b 100644
--- a/doc/src/sgml/ref/security_label.sgml
+++ b/doc/src/sgml/ref/security_label.sgml
@@ -84,6 +84,10 @@ SECURITY LABEL [ FOR provider ] ON
based on object labels, rather than traditional discretionary access control
(DAC) concepts such as users and groups.
+
+
+ You must own the database object to use SECURITY LABEL.
+
diff --git a/doc/src/sgml/ref/select.sgml b/doc/src/sgml/ref/select.sgml
index 066aed44e6e16..d7089eac0bee7 100644
--- a/doc/src/sgml/ref/select.sgml
+++ b/doc/src/sgml/ref/select.sgml
@@ -34,7 +34,7 @@ PostgreSQL documentation
[ WITH [ RECURSIVE ] with_query [, ...] ]
SELECT [ ALL | DISTINCT [ ON ( expression [, ...] ) ] ]
- [ * | expression [ [ AS ] output_name ] [, ...] ]
+ [ { * | expression [ [ AS ] output_name ] } [, ...] ]
[ FROM from_item [, ...] ]
[ WHERE condition ]
[ GROUP BY [ ALL | DISTINCT ] grouping_element [, ...] ]
diff --git a/doc/src/sgml/ref/select_into.sgml b/doc/src/sgml/ref/select_into.sgml
index 82a77784b9976..ae7e6bed24f25 100644
--- a/doc/src/sgml/ref/select_into.sgml
+++ b/doc/src/sgml/ref/select_into.sgml
@@ -23,7 +23,7 @@ PostgreSQL documentation
[ WITH [ RECURSIVE ] with_query [, ...] ]
SELECT [ ALL | DISTINCT [ ON ( expression [, ...] ) ] ]
- * | expression [ [ AS ] output_name ] [, ...]
+ [ { * | expression [ [ AS ] output_name ] } [, ...] ]
INTO [ TEMPORARY | TEMP | UNLOGGED ] [ TABLE ] new_table
[ FROM from_item [, ...] ]
[ WHERE condition ]
diff --git a/doc/src/sgml/ref/set.sgml b/doc/src/sgml/ref/set.sgml
index 5459b29525969..2218f54682ec3 100644
--- a/doc/src/sgml/ref/set.sgml
+++ b/doc/src/sgml/ref/set.sgml
@@ -165,7 +165,7 @@ SET [ SESSION | LOCAL ] TIME ZONE { valueNAMES
- SET NAMES value is an alias for
+ SET NAMES 'value' is an alias for
SET client_encoding TO value.
@@ -200,7 +200,7 @@ SELECT setseed(value);
- 'PST8PDT'
+ 'America/Los_Angeles'
The time zone for Berkeley, California.
@@ -298,7 +298,7 @@ SET datestyle TO postgres, dmy;
Set the time zone for Berkeley, California:
-SET TIME ZONE 'PST8PDT';
+SET TIME ZONE 'America/Los_Angeles';
diff --git a/doc/src/sgml/ref/show.sgml b/doc/src/sgml/ref/show.sgml
index b3747b119f9d2..5fbb5bbe013e3 100644
--- a/doc/src/sgml/ref/show.sgml
+++ b/doc/src/sgml/ref/show.sgml
@@ -77,30 +77,6 @@ SHOW ALL
-
- LC_COLLATE
-
-
- 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.
-
-
-
-
-
- LC_CTYPE
-
-
- 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.
-
-
-
-
IS_SUPERUSER
diff --git a/doc/src/sgml/ref/update.sgml b/doc/src/sgml/ref/update.sgml
index babb34fa511d6..40cca06394636 100644
--- a/doc/src/sgml/ref/update.sgml
+++ b/doc/src/sgml/ref/update.sgml
@@ -29,7 +29,8 @@ UPDATE [ ONLY ] table_name [ * ] [
} [, ...]
[ FROM from_item [, ...] ]
[ WHERE condition | WHERE CURRENT OF cursor_name ]
- [ RETURNING * | output_expression [ [ AS ] output_name ] [, ...] ]
+ [ RETURNING [ WITH ( { OLD | NEW } AS output_alias [, ...] ) ]
+ { * | output_expression [ [ AS ] output_name ] } [, ...] ]
@@ -56,7 +57,8 @@ UPDATE [ ONLY ] table_name [ * ] [
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 FROM, can be computed.
- The new (post-update) values of the table's columns are used.
+ By default, the new (post-update) values of the table's columns are used,
+ but it is also possible to request the old (pre-update) values.
The syntax of the RETURNING list is identical to that of the
output list of SELECT.
@@ -211,6 +213,26 @@ UPDATE [ ONLY ] table_name [ * ] [
+
+ output_alias
+
+
+ An optional substitute name for OLD or
+ NEW rows in the RETURNING list.
+
+
+
+ By default, old values from the target table can be returned by writing
+ OLD.column_name
+ or OLD.*, and new values can be returned by writing
+ NEW.column_name
+ or NEW.*. When an alias is provided, these names are
+ hidden and the old or new rows must be referred to using the alias.
+ For example RETURNING WITH (OLD AS o, NEW AS n) o.*, n.*.
+
+
+
+
output_expression
@@ -221,6 +243,16 @@ UPDATE [ ONLY ] table_name [ * ] [
or table(s) listed in FROM.
Write * to return all columns.
+
+
+ A column name or * may be qualified using
+ OLD or NEW, or the corresponding
+ output_alias for
+ OLD or NEW, to cause old or new
+ values to be returned. An unqualified column name, or
+ *, or a column name or * qualified
+ using the target table name or alias will return new values.
+
@@ -348,12 +380,13 @@ UPDATE weather SET temp_lo = temp_lo+1, temp_hi = temp_lo+15, prcp = DEFAULT
- Perform the same operation and return the updated entries:
+ Perform the same operation and return the updated entries, and the old
+ precipitation value:
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;
+ RETURNING temp_lo, temp_hi, prcp, old.prcp AS old_prcp;
diff --git a/doc/src/sgml/ref/vacuum.sgml b/doc/src/sgml/ref/vacuum.sgml
index 9857b35627b3e..bd5dcaf86a5cc 100644
--- a/doc/src/sgml/ref/vacuum.sgml
+++ b/doc/src/sgml/ref/vacuum.sgml
@@ -42,7 +42,7 @@ VACUUM [ ( option [, ...] ) ] [ and table_and_columns is:
- table_name [ ( column_name [, ...] ) ]
+ [ ONLY ] table_name [ * ] [ ( column_name [, ...] ) ]
@@ -129,7 +129,8 @@ VACUUM [ ( option [, ...] ) ] [ VERBOSE
- Prints a detailed vacuum activity report for each table.
+ Prints a detailed vacuum activity report for each table
+ at INFO level.
@@ -264,7 +265,8 @@ VACUUM [ ( option [, ...] ) ] [ vacuum_truncate
+ and is the default unless
+ is set to false or the vacuum_truncate
option has been set to false for the table to be vacuumed.
Setting this option to false may be useful to avoid
ACCESS EXCLUSIVE lock on the table that
@@ -401,8 +403,13 @@ VACUUM [ ( option [, ...] ) ] [
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.
+ materialized view to vacuum. If ONLY is specified
+ before the table name, only that table is vacuumed. If
+ ONLY is not specified, the table and all its
+ inheritance child tables or partitions (if any) are also vacuumed.
+ Optionally, * can be specified after the table name
+ to explicitly indicate that inheritance child tables (or partitions) are
+ to be vacuumed.
diff --git a/doc/src/sgml/ref/vacuumdb.sgml b/doc/src/sgml/ref/vacuumdb.sgml
index 66fccb30a2d26..84c76d7350c83 100644
--- a/doc/src/sgml/ref/vacuumdb.sgml
+++ b/doc/src/sgml/ref/vacuumdb.sgml
@@ -277,6 +277,32 @@ PostgreSQL documentation
+
+
+
+
+ Only analyze relations that are missing statistics for a column, index
+ expression, or extended statistics object. When used with
+ , this option prevents
+ vacuumdb from temporarily replacing existing
+ statistics with ones generated with lower statistics targets, thus
+ avoiding transiently worse query optimizer choices.
+
+
+ This option can only be used in conjunction with
+ or .
+
+
+ Note that requires
+ SELECT privileges on
+ pg_statistic
+ and
+ pg_statistic_ext_data,
+ which are restricted to superusers by default.
+
+
+
+
@@ -379,6 +405,15 @@ PostgreSQL documentation
Multiple tables can be vacuumed by writing multiple
switches.
+
+ If no tables are specified with the option,
+ vacuumdb will clean all regular tables
+ and materialized views in the connected database.
+ If or
+ is also specified,
+ it will analyze all regular tables, partitioned tables,
+ and materialized views (but not foreign tables).
+
If you specify columns, you probably have to escape the parentheses
@@ -544,9 +579,8 @@ PostgreSQL documentation
- Specifies the name of the database to connect to to discover which
- databases should be vacuumed,
- when / is used.
+ When the / is used, connect
+ to this database to gather the list of databases to vacuum.
If not specified, the postgres database will be used,
or if that does not exist, template1 will be used.
This can be a connection
diff --git a/doc/src/sgml/regress.sgml b/doc/src/sgml/regress.sgml
index d1042e022280d..8838fe7f0225f 100644
--- a/doc/src/sgml/regress.sgml
+++ b/doc/src/sgml/regress.sgml
@@ -285,10 +285,13 @@ make check-world PG_TEST_EXTRA='kerberos ldap ssl load_balance libpq_encryption'
- ssl
+ libpq_encryption
- Runs the test suite under src/test/ssl. This opens TCP/IP listen sockets.
+ Runs the test src/interfaces/libpq/t/005_negotiate_encryption.pl.
+ This opens TCP/IP listen sockets. If PG_TEST_EXTRA
+ also includes kerberos, additional tests that require
+ an MIT Kerberos installation are enabled.
@@ -305,13 +308,44 @@ make check-world PG_TEST_EXTRA='kerberos ldap ssl load_balance libpq_encryption'
- libpq_encryption
+ oauth
- Runs the test src/interfaces/libpq/t/005_negotiate_encryption.pl.
- This opens TCP/IP listen sockets. If PG_TEST_EXTRA
- also includes kerberos, additional tests that require
- an MIT Kerberos installation are enabled.
+ Runs the test suite under src/test/modules/oauth_validator.
+ This opens TCP/IP listen sockets for a test server running HTTPS.
+
+
+
+
+
+ regress_dump_restore
+
+
+ Runs an additional test suite in
+ src/bin/pg_upgrade/t/002_pg_upgrade.pl which
+ cycles the regression database through pg_dump/
+ pg_restore. Not enabled by default because it
+ is resource intensive.
+
+
+
+
+
+ sepgsql
+
+
+ Runs the test suite under contrib/sepgsql. This
+ requires an SELinux environment that is set up in a specific way; see
+ .
+
+
+
+
+
+ ssl
+
+
+ Runs the test suite under src/test/ssl. This opens TCP/IP listen sockets.
@@ -576,11 +610,11 @@ make check NO_LOCALE=1
Most of the date and time results are dependent on the time zone
environment. The reference files are generated for time zone
- PST8PDT (Berkeley, California), and there will be
+ America/Los_Angeles, and there will be
apparent failures if the tests are not run with that time zone setting.
The regression test driver sets environment variable
- PGTZ to PST8PDT, which normally
- ensures proper results.
+ PGTZ to America/Los_Angeles,
+ which normally ensures proper results.
diff --git a/doc/src/sgml/release-17.sgml b/doc/src/sgml/release-17.sgml
deleted file mode 100644
index 612eb100a7bea..0000000000000
--- a/doc/src/sgml/release-17.sgml
+++ /dev/null
@@ -1,2861 +0,0 @@
-
-
-
-
- Release 17
-
-
- Release date:
- 2024-??-??, AS OF 2024-05-18
-
-
-
- Overview
-
-
- PostgreSQL 17 contains many new features
- and enhancements, including:
-
-
-
- TO BE COMPLETED LATER
-
-
-
- The above items and other new features of
- PostgreSQL 17 are explained in more detail
- in the sections below.
-
-
-
-
-
-
- Migration to Version 17
-
-
- A dump/restore using or use of
- or logical replication is required for
- those wishing to migrate data from any previous release. See for general information on migrating to new
- major releases.
-
-
-
- Version 17 contains a number of changes that may affect compatibility
- with previous releases. Observe the following incompatibilities:
-
-
-
-
-
-
-
-
-Change functions to use a safe search_path during maintenance operations (Jeff Davis)
-
-
-
-This prevents maintenance operations (ANALYZE, CLUSTER, REFRESH MATERIALIZED VIEW, REINDEX, or VACUUM) from performing unsafe access. Functions used by expression indexes and
-materialized views that need to reference non-default schemas must specify a search path during function creation.
-
-
-
-
-
-
-
-Restrict "ago" to only appear at the end in interval values (Joseph Koshakow)
-
-
-
-Also, prevent empty interval units and interval units from appearing multiple times.
-
-
-
-
-
-
-
-Remove server variable old_snapshot_threshold (Thomas Munro)
-
-
-
-This variable allowed vacuum to remove rows that potentially could be still visible to running transactions, causing "snapshot too old" error later if accessed. This feature
-might be re-added to Postgres later if an improved implementation is found.
-
-
-
-
-
-
-
-Rename server variable session_auth_is_superuser to the more accurate current_role_is_superuser (Nathan Bossart)
-
-
-
-
-
-
-
-Change SET SESSION AUTHORIZATION handling of the initial session user's superuser status (Joseph Koshakow)
-
-
-
-The new behavior is based on the session user's superuser status at the time the SET SESSION AUTHORIZATION command is issued, rather than their superuser status at connection time.
-
-
-
-
-
-
-
-Remove feature which simulated per-database users (Nathan Bossart)
-
-
-
-The feature, db_user_namespace, was rarely used.
-
-
-
-
-
-
-
-Remove wal_sync_method value fsync_writethrough on Windows (Thomas Munro)
-
-
-
-This value was the same as "fsync" on Windows.
-
-
-
-
-
-
-
-Change file boundary handling of two WAL file name functions (Kyotaro Horiguchi, Andres Freund, Bruce Momjian)
-
-
-
-The functions pg_walfile_name() and pg_walfile_name_offset() used to report the previous LSN segment number when the LSN was on a file segment boundary; it now returns the LSN segment.
-
-
-
-
-
-
-
-Remove server variable trace_recovery_messages since it is no longer needed (Bharath Rupireddy)
-
-
-
-
-
-
-
-Remove information schema column element_types.domain_default (Peter Eisentraut)
-
-
-
-
-
-
-
-Change pgrowlocks lock mode output labels (Bruce Momjian)
-
-
-
-
-
-
-
-Rename I/O block read/write timing statistics columns of pg_stat_statements (Nazir Bilal Yavuz)
-
-
-
-This renames "blk_read_time" to "shared_blk_read_time", and "blk_write_time" to "shared_blk_write_time".
-
-
-
-
-
-
-
-Remove buffers_backend and buffers_backend_fsync from pg_stat_checkpointer (Bharath Rupireddy)
-
-
-
-These fields are considered redundant to similar columns in pg_stat_io.
-
-
-
-
-
-
-
-Change pg_attribute.attstattarget and pg_attribute.stxstattarget to represent the default statistics target as NULL (Peter Eisentraut)
-
-
-
-
-
-
-
-Change pg_stat_progress_vacuum columns max_dead_tuples to max_dead_tuple_bytes and num_dead_tuples to dead_tuple_bytes (Masahiko Sawada)
-
-
-
-These columns now report bytes instead of tuples.
-
-
-
-
-
-
-
-Rename SLRU columns in system view pg_stat_slru (Alvaro Herrera)
-
-
-
-The column names accepted by pg_stat_slru_rest() are also changed.
-
-
-
-
-
-
-
-
- Changes
-
-
- Below you will find a detailed account of the changes between
- PostgreSQL 17 and the previous major
- release.
-
-
-
- Server
-
-
- Optimizer
-
-
-
-
-
-
-
-Allow the optimizer to improve CTE plans by considering the statistics of columns referenced in earlier row output clauses (Jian Guo, Tom Lane)
-
-
-
-
-
-
-
-Allow the optimizer to improve CTE plans by considering the sort order of columns referenced in earlier row output clauses (Richard Guo)
-
-
-
-
-
-
-
-Improve optimization of IS NOT NULL and IS NULL query restrictions (David Rowley, Richard Guo, Andy Fan)
-
-
-
-Remove IS NOT NULL query restrictions on NOT NULL columns and eliminate scans on NOT NULL columns if IS NULL is specified.
-
-
-
-
-
-
-
-Allow partition pruning on boolean columns on IS [NOT] UNKNOWN conditionals (David Rowley)
-
-
-
-
-
-
-
-Improve optimization of range values when using containment operators <@ and @> (Kim Johan Andersson, Jian He)
-
-
-
-
-
-
-
-Allow correlated IN subqueries to be transformed into joins (Andy Fan, Tom Lane)
-
-
-
-
-
-
-
-Improve optimization of the LIMIT clause on partitioned tables, inheritance parents, and UNION ALL queries (Andy Fan, David Rowley)
-
-
-
-
-
-
-
-Allow query nodes to be run in parallel in more cases (Tom Lane)
-
-
-
-
-
-
-
-Allow GROUP BY columns to be internally ordered to match ORDER BY (Andrei Lepikhov, Teodor Sigaev)
-
-
-
-This can be disabled using server variable enable_group_by_reordering.
-
-
-
-
-
-
-
-Allow UNION (without ALL) to use MergeAppend (David Rowley)
-
-
-
-
-
-
-
-Fix MergeAppend plans to more accurately compute the number of rows that need to be sorted (Alexander Kuzmenkov)
-
-
-
-
-
-
-
-Allow GiST and SP-GiST indexes to be part of incremental sorts (Miroslav Bendik)
-
-
-
-This is particularly useful for ORDER BY clauses where the first column has a GiST and SP-GiST index, and other columns do not.
-
-
-
-
-
-
-
-Add columns to pg_stats to report range-type histogram information (Egor Rogov, Soumyadeep Chakraborty)
-
-
-
-
-
-
-
-
- Indexes
-
-
-
-
-
-
-Allow btree indexes to more efficiently find array matches (Peter Geoghegan, Matthias van de Meent)
-
-
-
-
-
-
-
-Allow BRIN indexes to be created using parallel workers (Tomas Vondra, Matthias van de Meent)
-
-
-
-
-
-
-
-
- General Performance
-
-
-
-
-
-
-
-Allow vacuum to more efficiently remove and freeze tuples (Melanie Plageman)
-
-
-
-WAL traffic caused by vacuum is also more compact.
-
-
-
-
-
-
-
-Allow vacuum to more efficiently store tuple references (Masahiko Sawada, John Naylor)
-
-
-
-Additionally, vacuum is no longer silently limited to one gigabyte of memory when maintenance_work_mem or autovacuum_work_mem are higher.
-
-
-
-
-
-
-
-Optimize vacuuming of relations with no indexes (Melanie Plageman)
-
-
-
-
-
-
-
-Increase default vacuum_buffer_usage_limit to 2MB (Thomas Munro)
-
-
-
-
-
-
-
-Improve performance when checking roles with many memberships (Nathan Bossart)
-
-
-
-
-
-
-
-Improve performance of heavily-contended WAL writes (Bharath Rupireddy)
-
-
-
-
-
-
-
-Improve performance when transferring large blocks of data to a client (Melih Mutlu)
-
-
-
-
-
-
-
-Allow the grouping of file system reads with the new system variable io_combine_limit (Thomas Munro, Andres Freund, Melanie Plageman, Nazir Bilal Yavuz)
-
-
-
-
-
-
-
-
- Monitoring
-
-
-
-
-
-
-
-Create system view pg_stat_checkpointer (Bharath Rupireddy, Anton A. Melnikov, Alexander Korotkov)
-
-
-
-Relevant columns have been removed from pg_stat_bgwriter and added to this new system view.
-
-
-
-
-
-
-
-Allow pg_stat_reset_shared() to reset all shared statistics (Atsushi Torikoshi)
-
-
-
-This is done by passing NULL.
-
-
-
-
-
-
-
-Allow pg_stat_reset_shared("slru") to clear SLRU statistics (Atsushi Torikoshi)
-
-
-
-Now pg_stat_reset_shared(NULL) also resets SLRU statistics.
-
-
-
-
-
-
-
-Allow pg_stat_reset_slru() to reset all SLRU statistics (Bharath Rupireddy)
-
-
-
-The command pg_stat_reset_slru(NULL) already did this.
-
-
-
-
-
-
-
-Add log messages related to WAL recovery from backup (Andres Freund)
-
-
-
-
-
-
-
-Add log_connections log line for "trust" connections (Jacob Champion)
-
-
-
-
-
-
-
-Add log message to report walsender acquisition and release of replication slots (Bharath Rupireddy)
-
-
-
-This is enabled by the server variable log_replication_commands.
-
-
-
-
-
-
-
-Fix emit_log_hook to use the same time value as other log records for the same query (Kambam Vinay, Michael Paquier)
-
-
-
-
-
-
-
-Add system view pg_wait_events that reports wait event types (Bertrand Drouvot)
-
-
-
-This is useful for adding descriptions to wait events reported in pg_stat_activity.
-
-
-
-
-
-
-
-Add wait events for checkpoint delays (Thomas Munro)
-
-
-
-
-
-
-
-Allow vacuum to report the progress of index processing (Sami Imseih)
-
-
-
-This appears in system view columns pg_stat_progress_vacuum.indexes_total and pg_stat_progress_vacuum.indexes_processed.
-
-
-
-
-
-
-
-Add server variable trace_connection_negotiation to allow debugging of connection encryption (Heikki Linnakangas, Kyotaro Horiguchi)
-
-
-
-
-
-
-
-
- Privileges
-
-
-
-
-
-
-
-Add per-table GRANT permission MAINTAIN to control maintenance operations (Nathan Bossart)
-
-
-
-The operations are VACUUM, ANALYZE, REINDEX, REFRESH MATERIALIZED VIEW, CLUSTER, and LOCK TABLE.
-
-
-
-
-
-
-
-Add user-grantable role pg_maintain to control maintenance operations (Nathan Bossart)
-
-
-
-The operations are VACUUM, ANALYZE, REINDEX, REFRESH MATERIALIZED VIEW, CLUSTER, and LOCK TABLE.
-
-
-
-
-
-
-
-Allow roles with pg_monitor membership to execute pg_current_logfile() (Pavlo Golub, Nathan Bossart)
-
-
-
-
-
-
-
-
- Server Configuration
-
-
-
-
-
-
-
-Add system variable allow_alter_system to disallow ALTER SYSTEM (Jelte Fennema-Nio, Gabriele Bartolini)
-
-
-
-
-
-
-
-Allow ALTER SYSTEM to set unrecognized custom server variables (Tom Lane)
-
-
-
-This is also possible with GRANT ON PARAMETER.
-
-
-
-
-
-
-
-Add server variable transaction_timeout to restrict the duration of transactions (Andrey Borodin, Japin Li, Junwang Zhao, Alexander Korotkov)
-
-
-
-
-
-
-
-Create "builtin" collation provider similar to libc's C locale (Jeff Davis)
-
-
-
-While its C locale is similar but independent of libc, its C.UTF-8 locale sorts by Unicode code points and has Unicode-based case folding.
-
-
-
-
-
-
-
-Add server variable huge_pages_status to report the use of huge pages by Postgres (Justin Pryzby)
-
-
-
-This is useful when huge_pages is set to "try".
-
-
-
-
-
-
-
-Add server variable to disable event triggers (Daniel Gustafsson)
-
-
-
-The setting, event_triggers, allows for the temporary disabling of event triggers for debugging.
-
-
-
-
-
-
-
-Allow the SLRU cache sizes to be configured (Andrey Borodin, Dilip Kumar)
-
-
-
-The new server variables are commit_timestamp_buffers, multixact_member_buffers, multixact_offset_buffers, notify_buffers, serializable_buffers, subtransaction_buffers, and
-transaction_buffers.
-
-
-
-
-
-
-
-
- Streaming Replication and Recovery
-
-
-
-
-
-
-
-Add support for incremental file system backup (Robert Haas, Jakub Wartak, Tomas Vondra)
-
-
-
-Incremental backups can be created using pg_basebackup's new --incremental option. The new application pg_combinebackup allows manipulation of base and incremental file system backups.
-
-
-
-
-
-
-
-Allow the creation of WAL summarization files (Robert Haas, Nathan Bossart, Hubert Depesz Lubaczewski)
-
-
-
-These files record the block numbers that have changed within an LSN range and are useful for incremental file system backups. This is controlled by the server variables
-summarize_wal and wal_summarize_keep_time, and introspected with pg_available_wal_summaries(), pg_wal_summary_contents(), and pg_get_wal_summarizer_state().
-
-
-
-
-
-
-
-Add the system identifier to file system backup manifest files (Amul Sul)
-
-
-
-This helps detect invalid WAL usage.
-
-
-
-
-
-
-
-Allow connection string value dbname to be written when pg_basebackup writes connection information to postgresql.auto.conf (Vignesh C, Hayato Kuroda)
-
-
-
-
-
-
-
-Add column pg_replication_slots.invalidation_reason to report the reason for invalid slots (Shveta Malik, Bharath Rupireddy)
-
-
-
-
-
-
-
-Add pg_replication_slots.inactive_since to report slot inactivity duration (Bharath Rupireddy)
-
-
-
-
-
-
-
-Add function pg_sync_replication_slots() to synchronize logical replication slots (Hou Zhijie, Shveta Malik, Ajin Cherian, Peter Eisentraut)
-
-
-
-
-
-
-
-Add the failover property to the replication protocol (Hou Zhijie, Shveta Malik)
-
-
-
-
-
-
-
-
- <link linkend="logical-replication">Logical Replication</link>
-
-
-
-
-
-
-
-Add application pg_createsubscriber to create a logical replica from a physical standby server (Euler Taveira)
-
-
-
-
-
-
-
-Have pg_upgrade migrate valid logical slots and subscriptions (Hayato Kuroda, Hou Zhijie, Vignesh C, Julien Rouhaud, Shlok Kyal)
-
-
-
-This allows logical replication to continue quickly after the upgrade. This only works for old clusters of PostgreSQL version 17.0 or later.
-
-
-
-
-
-
-
-Enable the failover of logical slots (Hou Zhijie, Shveta Malik, Ajin Cherian)
-
-
-
-This is controlled by an optional fifth argument to pg_create_logical_replication_slot().
-
-
-
-
-
-
-
-Add server variable sync_replication_slots to enable failover logical slot synchronization (Shveta Malik, Hou Zhijie, Peter Smith)
-
-
-
-
-
-
-
-Add logical replication failover control to CREATE/ALTER SUBSCRIPTION (Shveta Malik, Hou Zhijie, Ajin Cherian)
-
-
-
-
-
-
-
-Allow the application of logical replication changes to use hash indexes on the subscriber (Hayato Kuroda)
-
-
-
-Previously only btree indexes could be used for this purpose.
-
-
-
-
-
-
-
-Improve logical decoding performance in cases where there are many subtransactions (Masahiko Sawada)
-
-
-
-
-
-
-
-Restart apply workers if subscription owner's superuser privileges are revoked (Vignesh C)
-
-
-
-This forces reauthentication.
-
-
-
-
-
-
-
-Add "flush" option to pg_logical_emit_message() (Michael Paquier)
-
-
-
-This makes the message durable.
-
-
-
-
-
-
-
-Allow specification of physical standbys that must be synchronized before they are visible to subscribers (Hou Zhijie, Shveta Malik)
-
-
-
-The server variable is standby_slot_names.
-
-
-
-
-
-
-
-Add worker type column to pg_stat_subscription (Peter Smith)
-
-
-
-
-
-
-
-
-
-
- Utility Commands
-
-
-
-
-
-
-
-Add new COPY option "ON_ERROR ignore" to discard error rows (Damir Belyalov, Atsushi Torikoshi, Alex Shulgin, Jian He, Yugo Nagata)
-
-
-
-The default behavior is "ON_ERROR stop".
-
-
-
-
-
-
-
-Add new COPY option LOG_VERBOSITY which reports COPY FROM ignored error rows (Bharath Rupireddy)
-
-
-
-
-
-
-
-Allow COPY FROM to report the number of skipped rows during processing (Atsushi Torikoshi)
-
-
-
-This appears in system view column pg_stat_progress_copy.tuples_skipped.
-
-
-
-
-
-
-
-In COPY FROM, allow easy specification that all columns should be forced null or not null (Zhang Mingli)
-
-
-
-
-
-
-
-Allow EXPLAIN to report optimizer memory usage (Ashutosh Bapat)
-
-
-
-The option is called "MEMORY".
-
-
-
-
-
-
-
-Add EXPLAIN option SERIALIZE to report the cost of converting data for network transmission (Stepan Rutz, Matthias van de Meent)
-
-
-
-
-
-
-
-Add local I/O block read/write timing statistics to EXPLAIN (Nazir Bilal Yavuz)
-
-
-
-
-
-
-
-Improve EXPLAIN's display of SubPlan nodes and output parameters (Tom Lane, Dean Rasheed)
-
-
-
-
-
-
-
-Add JIT deform_counter details to EXPLAIN (Dmitry Dolgov)
-
-
-
-
-
-
-
-Allow partitions to be merged using ALTER TABLE ... MERGE PARTITIONS (Dmitry Koval)
-
-
-
-
-
-
-
-Allow partitions to be split using ALTER TABLE ... SPLIT PARTITION (Dmitry Koval)
-
-
-
-
-
-
-
-Allow partitioned tables to have identity columns (Ashutosh Bapat)
-
-
-
-
-
-
-
-Allow exclusion constraints on partitioned tables (Paul A. Jungwirth)
-
-
-
-As long as exclusion constraints compare partition key columns for equality, other columns can use exclusion constraint-specific comparisons.
-
-
-
-
-
-
-
-Allow specification of partitioned table access methods (Justin Pryzby, Soumyadeep Chakraborty, Michael Paquier)
-
-
-
-
-
-
-
-Add clearer ALTER TABLE method to set a column to the default statistics target (Peter Eisentraut)
-
-
-
-The command is ALTER TABLE ... SET STATISTICS DEFAULT; using "SET STATISTICS -1" is still supported.
-
-
-
-
-
-
-
-Allow ALTER TABLE to change a columns generation expression (Amul Sul)
-
-
-
-The syntax is "ALTER TABLE ... ALTER COLUMN ... SET EXPRESSION".
-
-
-
-
-
-
-
-Add DEFAULT setting for ALTER TABLE .. SET ACCESS METHOD (Michael Paquier)
-
-
-
-
-
-
-
-Add support for event triggers that fire at connection time (Konstantin Knizhnik, Mikhail Gribkov)
-
-
-
-
-
-
-
-Add event trigger support for REINDEX (Garrett Thornburg, Jian He)
-
-
-
-
-
-
-
-Allow parenthesized syntax for CLUSTER options if a table name is not specified (Nathan Bossart)
-
-
-
-
-
-
-
-
- Data Types
-
-
-
-
-
-
-
-Allow the interval data type to support +/-infinity values (Joseph Koshakow, Jian He, Ashutosh Bapat)
-
-
-
-
-
-
-
-Allow the use of an ENUM added via ALTER TYPE if the type was created in the same transaction (Tom Lane)
-
-
-
-This was previously disallowed.
-
-
-
-
-
-
-
-
- <link linkend="sql-merge">MERGE</link>
-
-
-
-
-
-
-
-
-Allow MERGE to modify updatable views (Dean Rasheed)
-
-
-
-
-
-
-
-Add WHEN NOT MATCHED BY SOURCE to MERGE (Dean Rasheed)
-
-
-
-"WHEN NOT MATCHED" on target rows was already supported.
-
-
-
-
-
-
-
-Allow MERGE to use the RETURNING clause (Dean Rasheed)
-
-
-
-The new RETURNING function merge_action() reports on the DML that generated the row.
-
-
-
-
-
-
-
-
- Functions
-
-
-
-
-
-
-
-Add function JSON_TABLE() to convert JSON data to a table representation (Nikita Glukhov, Teodor Sigaev, Oleg Bartunov, Alexander Korotkov, Andrew Dunstan, Amit Langote, Jian He)
-
-
-
-This function can be used in the FROM clause of SELECT queries as a tuple source.
-
-
-
-
-
-
-
-Add SQL/JSON constructor functions JSON(), JSON_SCALAR(), and JSON_SERIALIZE() (Amit Langote)
-
-
-
-
-
-
-
-Add SQL/JSON query functions JSON_EXISTS(), JSON_QUERY(), and JSON_VALUE() (Nikita Glukhov, Teodor Sigaev, Oleg Bartunov, Alexander Korotkov, Andrew Dunstan, Amit Langote,
-Peter Eisentraut, Jian He)
-
-
-
-
-
-
-
-Add jsonpath methods to convert JSON values to other JSON data types (Jeevan Chalke)
-
-
-
-The jsonpath methods are .bigint(), .boolean(), .date(), .decimal([precision [, scale]]), .integer(), .number(), .string(), .time(), .time_tz(), .timestamp(), and .timestamp_tz().
-
-
-
-
-
-
-
-Add to_timestamp() time zone format specifiers (Tom Lane)
-
-
-
-"TZ" accepts time zone abbreviations or numeric offsets, while "OF" accepts only numeric offsets.
-
-
-
-
-
-
-
-Allow the session time zone to be specified by AS LOCAL (Vik Fearing)
-
-
-
-This is useful when converting adding and removing time zones from time stamps values, rather than specifying the literal session time zone.
-
-
-
-
-
-
-
-Add functions uuid_extract_timestamp() and uuid_extract_version() to return UUID information (Andrey Borodin)
-
-
-
-
-
-
-
-Add functions to generate random numbers in a specified range (Dean Rasheed)
-
-
-
-The functions are random(min, max) and they take values of type integer, bigint, and numeric.
-
-
-
-
-
-
-
-Add functions to convert integers to hex and binary strings (Eric Radman, Nathan Bossart)
-
-
-
-The functions are to_bin() and to_oct().
-
-
-
-
-
-
-
-Add Unicode informational functions (Jeff Davis)
-
-
-
-Function unicode_version() returns the Unicode version, icu_unicode_version() returns the ICU version, and unicode_assigned() returns if the characters are assigned Unicode codepoints.
-
-
-
-
-
-
-
-Add function xmltext() to convert text to a single XML text node (Jim Jones)
-
-
-
-
-
-
-
-Add function to_regtypemod() to return the type modifier of a type specification (David Wheeler, Erik Wienhold)
-
-
-
-
-
-
-
-Add pg_basetype() function to return a domain's base type (Steve Chavez)
-
-
-
-
-
-
-
-Add function pg_column_toast_chunk_id() to return a value's TOAST identifier (Yugo Nagata)
-
-
-
-This returns NULL if the value is not stored in TOAST.
-
-
-
-
-
-
-
-
- <link linkend="plpgsql">PL/pgSQL</link>
-
-
-
-
-
-
-
-Allow plpgsql %TYPE and %ROWTYPE specifications to represent arrays of non-array types (Quan Zongliang, Pavel Stehule)
-
-
-
-
-
-
-
-Allow plpgsql %TYPE specification to reference composite column (Tom Lane)
-
-
-
-
-
-
-
-
- <link linkend="libpq">libpq</link>
-
-
-
-
-
-
-
-Add libpq function to change role passwords (Joe Conway)
-
-
-
-The new function, PQchangePassword(), hashes the new password before sending it to the server.
-
-
-
-
-
-
-
-Add libpq functions to close portals and prepared statements (Jelte Fennema-Nio)
-
-
-
-The functions are PQclosePrepared(), PQclosePortal(), PQsendClosePrepared(), and PQsendClosePortal().
-
-
-
-
-
-
-
-Add libpq API which allows for blocking and non-blocking cancel requests, with encryption if already in use (Jelte Fennema-Nio)
-
-
-
-Previously only blocking, unencrypted cancel requests were supported.
-
-
-
-
-
-
-
-Add libpq function PQsocketPoll to allow polling of network sockets (Tristan Partin)
-
-
-
-
-
-
-
-Add libpq function PQsendPipelineSync() to send a pipeline synchronization point (Anton Kirilov)
-
-
-
-This is similar to PQpipelineSync() but it does not flush to the server unless the size threshold of the output buffer is reached.
-
-
-
-
-
-
-
-Add libpq function PQsetChunkedRowsMode to allow retrieval of results in chunks (Daniel Vérité)
-
-
-
-
-
-
-
-Allow TLS connections without requiring a network round-trip negotiation (Greg Stark, Heikki Linnakangas, Peter Eisentraut, Michael Paquier, Daniel Gustafsson)
-
-
-
-This is enabled with the client-side option sslnegotation=direct, requires ALPN, and only works on PostgreSQL 17 and later servers.
-
-
-
-
-
-
-
-
- <xref linkend="app-psql"/>
-
-
-
-
-
-
-
-Improve psql display of default and empty privileges (Erik Wienhold, Laurenz Albe)
-
-
-
-Command \dp now displays "(none)" for empty privileges; default still display as empty.
-
-
-
-
-
-
-
-Have backslash commands honor "\pset null" (Erik Wienhold, Laurenz Albe)
-
-
-
-Previously "\pset null" was ignored.
-
-
-
-
-
-
-
-Allow psql's \watch to stop after a minimum number of rows returned (Greg Sabino Mullane)
-
-
-
-The parameter is "min_rows".
-
-
-
-
-
-
-
-Allow psql connections to be canceled with control-C (Tristan Partin)
-
-
-
-
-
-
-
-Allow psql to honor FETCH_COUNT for non-SELECT queries (Daniel Vérité)
-
-
-
-
-
-
-
-Improve psql tab completion (Dagfinn Ilmari Mannsåker, Gilles Darold, Christoph Heiss, Steve Chavez, Vignesh C, Pavel Borisov)
-
-
-
-
-
-
-
-
- Server Applications
-
-
-
-
-
-
-
-Add application pg_walsummary to dump WAL summary files (Robert Haas)
-
-
-
-
-
-
-
-Allow pg_dump's large objects to be restorable in batches (Tom Lane)
-
-
-
-This allows the restoration of many large objects to avoid transaction limits and to be restored in parallel.
-
-
-
-
-
-
-
-Add pg_dump option --exclude-extension (Ayush Vatsa)
-
-
-
-
-
-
-
-Allow pg_dump, pg_dumpall, and pg_restore to specify include/exclude objects in a file (Pavel Stehule, Daniel Gustafsson)
-
-
-
-The option is called "--filter".
-
-
-
-
-
-
-
-Add the --sync-method parameter to several client applications (Justin Pryzby, Nathan Bossart)
-
-
-
-The applications are initdb, pg_basebackup, pg_checksums, pg_dump, pg_rewind, and pg_upgrade.
-
-
-
-
-
-
-
-Add pg_restore option --transaction-size to allow object restore in transaction batches (Tom Lane)
-
-
-
-This allows the performance benefits of transaction batches without the problems of excessively large transaction blocks.
-
-
-
-
-
-
-
-Change pgbench debug mode option from -d to --debug (Greg Sabino Mullane)
-
-
-
-Option -d is now used for the database name, and the new --dbname option can be used as well.
-
-
-
-
-
-
-
-Add pgbench option "--exit-on-abort" to exit after any client aborts (Yugo Nagata)
-
-
-
-
-
-
-
-Add pgbench command \syncpipeline to allow sending of sync messages (Anthonin Bonnefoy)
-
-
-
-
-
-
-
-Allow pg_archivecleanup to remove backup history files (Atsushi Torikoshi)
-
-
-
-The option is --clean-backup-history.
-
-
-
-
-
-
-
-Add some long options to pg_archivecleanup (Atsushi Torikoshi)
-
-
-
-The long options are --debug, --dry-run, and --strip-extension.
-
-
-
-
-
-
-
-Allow pg_basebackup and pg_receivewal to use dbname in their connection specification (Jelte Fennema-Nio)
-
-
-
-This is useful for connection poolers that are sensitive to the database name.
-
-
-
-
-
-
-
-Add pg_upgrade option --copy-file-range (Thomas Munro)
-
-
-
-This is supported on Linux and FreeBSD.
-
-
-
-
-
-
-
-Allow reindexdb --index to process indexes from different tables in parallel (Maxim Orlov, Svetlana Derevyanko, Alexander Korotkov)
-
-
-
-
-
-
-
-Allow reindexdb to process objects in all databases matching a pattern (Nathan Bossart)
-
-
-
-Specifically, --all can now be used with --table, --schema, --index, and --system.
-
-
-
-
-
-
-
-Allow vacuumdb to process objects in all databases matching a pattern (Nathan Bossart)
-
-
-
-Specifically, --all can now be used with --table, --schema, and --exclude-schema.
-
-
-
-
-
-
-
-Allow clusterdb to process objects in all databases matching a pattern (Nathan Bossart)
-
-
-
-Specifically, --all can now be used with --table.
-
-
-
-
-
-
-
-
- Source Code
-
-
-
-
-
-
-
-Remove support for OpenSSL 1.0.1 (Michael Paquier)
-
-
-
-
-
-
-
-Allow tests to pass in OpenSSL FIPS mode (Peter Eisentraut)
-
-
-
-
-
-
-
-Use CPU AVX-512 instructions for bit counting (Paul Amonson, Nathan Bossart, Ants Aasma)
-
-
-
-
-
-
-
-Require LLVM version 10 or later (Thomas Munro)
-
-
-
-
-
-
-
-Use native CRC instructions on 64-bit LoongArch CPUs (YANG Xudong)
-
-
-
-
-
-
-
-Remove AIX support (Heikki Linnakangas)
-
-
-
-
-
-
-
-Remove the Microsoft Visual Studio-specific Postgres build option (Michael Paquier)
-
-
-
-Meson is now the only available method for Visual Studio builds.
-
-
-
-
-
-
-
-Remove configure option --disable-thread-safety (Thomas Munro, Heikki Linnakangas)
-
-
-
-We now assume all supported platforms have sufficient thread support.
-
-
-
-
-
-
-
-Remove configure option --with-CC (Heikki Linnakangas)
-
-
-
-Setting the CC environment variable is now the only supported method for specifying the compiler.
-
-
-
-
-
-
-
-User-defined data type receive functions will no longer receive their data null-terminated (David Rowley)
-
-
-
-
-
-
-
-Add incremental JSON parser for use with huge JSON documents (Andrew Dunstan)
-
-
-
-
-
-
-
-Convert source code README to Markdown (Nathan Bossart)
-
-
-
-
-
-
-
-Remove no longer needed top-level INSTALL file (Tom Lane)
-
-
-
-
-
-
-
-Remove make's distprep option (Peter Eisentraut)
-
-
-
-
-
-
-
-Add 'make' support for Android shared libraries (Peter Eisentraut)
-
-
-
-
-
-
-
-Add backend support for injection points (Michael Paquier)
-
-
-
-This is used for server debugging and they must be enabled at server compile time.
-
-
-
-
-
-
-
-Improve documentation for using jsonpath for predicate checks (David Wheeler)
-
-
-
-
-
-
-
-
- Additional Modules
-
-
-
-
-
-
-
-Allow joins with non-join qualifications to be pushed down to foreign servers and custom scans (Richard Guo, Etsuro Fujita)
-
-
-
-Foreign data wrappers and custom scans will need to be modified to handle these cases.
-
-
-
-
-
-
-
-Allow pushdown of EXISTS and IN subqueries to the postgres_fdw foreign server (Alexander Pyhalov)
-
-
-
-
-
-
-
-Increase the default foreign data wrapper tuple cost (David Rowley, Umair Shahid)
-
-
-
-This value is used by the optimizer.
-
-
-
-
-
-
-
-Create custom wait events for postgres_fdw (Masahiro Ikeda)
-
-
-
-
-
-
-
-Create custom wait events for dblink (Masahiro Ikeda)
-
-
-
-
-
-
-
-Allow dblink database operations to be interrupted (Noah Misch)
-
-
-
-
-
-
-
-Allow the creation of hash indexes on ltree columns (Tommy Pavlicek)
-
-
-
-This also enables hash join and hash aggregation on ltree columns.
-
-
-
-
-
-
-
-Allow unaccent character translation rules to contain whitespace and quotes (Michael Paquier)
-
-
-
-The syntax for unaccent.rules has changed.
-
-
-
-
-
-
-
-Allow amcheck to check for unique constraint violations (Anastasia Lubennikova, Pavel Borisov, Maxim Orlov)
-
-
-
-The pg_amcheck option --checkunique will check all the unique indexes.
-
-
-
-
-
-
-
-Allow citext tests to pass in OpenSSL FIPS mode (Peter Eisentraut)
-
-
-
-
-
-
-
-Allow pgcrypto tests to pass in OpenSSL FIPS mode (Peter Eisentraut)
-
-
-
-
-
-
-
-Remove some unused SPI macros (Bharath Rupireddy)
-
-
-
-
-
-
-
-Remove adminpack contrib extension (Daniel Gustafsson)
-
-
-
-This was used by now end-of-life pgAdmin III.
-
-
-
-
-
-
-
-Allow ALTER OPERATOR to set more optimization attributes (Tommy Pavlicek)
-
-
-
-This is useful for extensions.
-
-
-
-
-
-
-
-Allow extensions to define custom wait events (Masahiro Ikeda)
-
-
-
-
-
-
-
-Add pg_buffercache function pg_buffercache_evict() to allow shared buffer eviction (Palak Chaturvedi, Thomas Munro)
-
-
-
-This is useful for testing.
-
-
-
-
-
-
- <link linkend="pgstatstatements"><application>pg_statstatements</application></link>
-
-
-
-
-
-
-
-Replace CALL parameters in pg_stat_statements with placeholders (Sami Imseih)
-
-
-
-
-
-
-
-Replace savepoint names stored in pg_stat_statements with placeholders (Greg Sabino Mullane)
-
-
-
-This greatly reduces the number of entries needed to record SAVEPOINT, RELEASE SAVEPOINT, and ROLLBACK TO SAVEPOINT commands.
-
-
-
-
-
-
-
-Replace two-phase commit GIDs stored in pg_stat_statements with placeholders (Michael Paquier)
-
-
-
-This greatly reduces the number of entries needed to record PREPARE TRANSACTION, COMMIT PREPARED, and ROLLBACK PREPARED.
-
-
-
-
-
-
-
-Track DEALLOCATE in pg_stat_statements (Dagfinn Ilmari Mannsåker, Michael Paquier)
-
-
-
-DEALLOCATE names are stored in pg_stat_statements as placeholders.
-
-
-
-
-
-
-
-Add local I/O block read/write timing statistics columns of pg_stat_statements (Nazir Bilal Yavuz)
-
-
-
-The new columns are "local_blk_read_time" and "local_blk_write_time".
-
-
-
-
-
-
-
-Add JIT deform_counter details to pg_stat_statements (Dmitry Dolgov)
-
-
-
-
-
-
-
-Add optional fourth argument (minmax_only) to pg_stat_statements_reset() to allow for the resetting of only min/max statistics (Andrei Zubkov)
-
-
-
-This argument defaults to "false".
-
-
-
-
-
-
-
-Add pg_stat_statements columns "stats_since" and "minmax_stats_since" to track entry creation time and last min/max reset time (Andrei Zubkov)
-
-
-
-
-
-
-
-
-
-
-
-
- Acknowledgments
-
-
- The following individuals (in alphabetical order) have contributed
- to this release as patch authors, committers, reviewers, testers,
- or reporters of issues.
-
-
-
-
-
-
-
-
diff --git a/doc/src/sgml/release-19.sgml b/doc/src/sgml/release-19.sgml
new file mode 100644
index 0000000000000..8d242b5b28141
--- /dev/null
+++ b/doc/src/sgml/release-19.sgml
@@ -0,0 +1,16 @@
+
+
+
+
+ Release 19
+
+
+ Release date:
+ 2026-??-??
+
+
+
+ This is just a placeholder for now.
+
+
+
diff --git a/doc/src/sgml/release.sgml b/doc/src/sgml/release.sgml
index e1b953ed009d6..a659d382db95c 100644
--- a/doc/src/sgml/release.sgml
+++ b/doc/src/sgml/release.sgml
@@ -16,26 +16,6 @@ pg_[A-Za-z0-9_]+ ,
\<[a-z]+_[a-z_]+\> ,
-non-ASCII characters find using grep -P '[\x80-\xFF]'
- convert to HTML4 named entity (&) escapes
-
- official: http://www.w3.org/TR/html4/sgml/entities.html
- one page: http://www.zipcon.net/~swhite/docs/computers/browsers/entities_page.html
- other lists: http://www.zipcon.net/~swhite/docs/computers/browsers/entities.html
- http://www.zipcon.net/~swhite/docs/computers/browsers/entities_page.html
- https://en.wikipedia.org/wiki/List_of_XML_and_HTML_character_entity_references
-
- We cannot use UTF8 because back branches still use SGML Docbook,
- which does not support it. Also, rendering engines have to
- support the referenced characters.
-
- Do not use numeric _UTF_ numeric character escapes (&#nnn;),
- we can only use Latin1.
-
- Example: Alvaro Herrera is Álvaro Herrera
- Find non-ASCII characters (remove 'X'):
- grep -X-color='auto' -P -n "[\x80-\xFF]"
-
wrap long lines
For new features, add links to the documentation sections.
@@ -71,6 +51,15 @@ For new features, add links to the documentation sections.
review, so each item is truly a community effort.
+
+ Section markers (§) in the release notes link to gitweb
+ pages which show the primary git commit
+ messages and source tree changes responsible for the release note item.
+ There might be additional git commits which
+ are not shown.
+
+
-&release-17;
+&release-19;
Prior Releases
diff --git a/doc/src/sgml/rules.sgml b/doc/src/sgml/rules.sgml
index 7a928bd7b9040..282dcd722d495 100644
--- a/doc/src/sgml/rules.sgml
+++ b/doc/src/sgml/rules.sgml
@@ -60,6 +60,7 @@
SQL 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
+ debug_print_raw_parse,
debug_print_parse,
debug_print_rewritten, or
debug_print_plan. The rule actions are also
@@ -1029,8 +1030,8 @@ SELECT count(*) FROM words WHERE word = 'caterpiler';
With EXPLAIN ANALYZE, we see:
- Aggregate (cost=21763.99..21764.00 rows=1 width=0) (actual time=188.180..188.181 rows=1 loops=1)
- -> Foreign Scan on words (cost=0.00..21761.41 rows=1032 width=0) (actual time=188.177..188.177 rows=0 loops=1)
+ Aggregate (cost=21763.99..21764.00 rows=1 width=0) (actual time=188.180..188.181 rows=1.00 loops=1)
+ -> Foreign Scan on words (cost=0.00..21761.41 rows=1032 width=0) (actual time=188.177..188.177 rows=0.00 loops=1)
Filter: (word = 'caterpiler'::text)
Rows Removed by Filter: 479829
Foreign File: /usr/share/dict/words
@@ -1042,10 +1043,11 @@ SELECT count(*) FROM words WHERE word = 'caterpiler';
If the materialized view is used instead, the query is much faster:
- Aggregate (cost=4.44..4.45 rows=1 width=0) (actual time=0.042..0.042 rows=1 loops=1)
- -> 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)
+ Aggregate (cost=4.44..4.45 rows=1 width=0) (actual time=0.042..0.042 rows=1.00 loops=1)
+ -> 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.00 loops=1)
Index Cond: (word = 'caterpiler'::text)
Heap Fetches: 0
+ Index Searches: 1
Planning time: 0.164 ms
Execution time: 0.117 ms
@@ -1073,11 +1075,11 @@ SELECT word FROM words ORDER BY word <-> 'caterpiler' LIMIT 10;
- Limit (cost=11583.61..11583.64 rows=10 width=32) (actual time=1431.591..1431.594 rows=10 loops=1)
- -> Sort (cost=11583.61..11804.76 rows=88459 width=32) (actual time=1431.589..1431.591 rows=10 loops=1)
+ Limit (cost=11583.61..11583.64 rows=10 width=32) (actual time=1431.591..1431.594 rows=10.00 loops=1)
+ -> Sort (cost=11583.61..11804.76 rows=88459 width=32) (actual time=1431.589..1431.591 rows=10.00 loops=1)
Sort Key: ((word <-> 'caterpiler'::text))
Sort Method: top-N heapsort Memory: 25kB
- -> Foreign Scan on words (cost=0.00..9672.05 rows=88459 width=32) (actual time=0.057..1286.455 rows=479829 loops=1)
+ -> Foreign Scan on words (cost=0.00..9672.05 rows=88459 width=32) (actual time=0.057..1286.455 rows=479829.00 loops=1)
Foreign File: /usr/share/dict/words
Foreign File Size: 4953699
Planning time: 0.128 ms
@@ -1087,9 +1089,10 @@ SELECT word FROM words ORDER BY word <-> 'caterpiler' LIMIT 10;
Using the materialized view:
- Limit (cost=0.29..1.06 rows=10 width=10) (actual time=187.222..188.257 rows=10 loops=1)
- -> 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)
+ Limit (cost=0.29..1.06 rows=10 width=10) (actual time=187.222..188.257 rows=10.00 loops=1)
+ -> Index Scan using wrd_trgm on wrd (cost=0.29..37020.87 rows=479829 width=10) (actual time=187.219..188.252 rows=10.00 loops=1)
Order By: (word <-> 'caterpiler'::text)
+ Index Searches: 1
Planning time: 0.196 ms
Execution time: 198.640 ms
@@ -1645,6 +1648,23 @@ CREATE RULE shoelace_ins AS ON INSERT TO shoelace
RETURNING clause is simply ignored for INSERT.
+
+ Note that in the RETURNING clause of a rule,
+ OLD and NEW refer to the
+ pseudorelations added as extra range table entries to the rewritten
+ query, rather than old/new rows in the result relation. Thus, for
+ example, in a rule supporting UPDATE queries on this
+ view, if the RETURNING clause contained
+ old.sl_name, the old name would always be returned,
+ regardless of whether the RETURNING clause in the
+ query on the view specified OLD or NEW,
+ which might be confusing. To avoid this confusion, and support returning
+ old and new values in queries on the view, the RETURNING
+ clause in the rule definition should refer to entries from the result
+ relation such as shoelace_data.sl_name, without
+ specifying OLD or NEW.
+
+
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
@@ -2162,11 +2182,22 @@ CREATE VIEW phone_number WITH (security_barrier) AS
LEAKPROOF 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
+ event of overflow or division by zero) is not leakproof, and could provide
significant information about the unseen rows if applied before the security
view's row filters.
+
+ For example, an index scan cannot be selected for queries on security
+ barrier views (or tables with row-level security policies) if an
+ operator used in the WHERE clause is associated with the
+ operator family of the index, but its underlying function is not marked
+ LEAKPROOF. The program's
+ \dAo+
+ meta-command is useful to list operator families and determine which of
+ their operators are marked as leakproof.
+
+
It is important to understand that even a view created with the
security_barrier option is intended to be secure only
diff --git a/doc/src/sgml/runtime.sgml b/doc/src/sgml/runtime.sgml
index 6047b8171d4e8..0c60bafac635d 100644
--- a/doc/src/sgml/runtime.sgml
+++ b/doc/src/sgml/runtime.sgml
@@ -637,7 +637,8 @@ psql: error: connection to server at "server.joe.com" (123.123.123.123), port 54
This is the generic I couldn't find a server to talk
to 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.
+ configure so that the server
+ accepts remote TCP connections.
@@ -781,13 +782,13 @@ psql: error: connection to server on socket "/tmp/.s.PGSQL.5432" failed: No such
SEMMNIMaximum number of semaphore identifiers (i.e., sets)
- at least ceil((max_connections + autovacuum_max_workers + max_wal_senders + max_worker_processes + 5) / 16) plus room for other applications
+ at least ceil(num_os_semaphores / 16) plus room for other applicationsSEMMNSMaximum number of semaphores system-wide
- ceil((max_connections + autovacuum_max_workers + max_wal_senders + max_worker_processes + 5) / 16) * 17 plus room for other applications
+ ceil(num_os_semaphores / 16) * 17 plus room for other applications
@@ -838,21 +839,29 @@ psql: error: connection to server on socket "/tmp/.s.PGSQL.5432" failed: No such
When using System V semaphores,
PostgreSQL uses one semaphore per allowed connection
(), allowed autovacuum worker process
- () and allowed background
- process (), in sets of 16.
- Each such set will
+ (), allowed WAL sender process
+ (), allowed background
+ process (), etc., in sets of 16.
+ The runtime-computed parameter
+ reports the number of semaphores required. This parameter can be viewed
+ before starting the server with a postgres command like:
+
+$ postgres -D $PGDATA -C num_os_semaphores
+
+
+
+
+ Each set of 16 semaphores will
also contain a 17th semaphore which contains a magic
number, to detect collision with semaphore sets used by
other applications. The maximum number of semaphores in the system
is set by SEMMNS, which consequently must be at least
- as high as max_connections plus
- autovacuum_max_workers plus max_wal_senders,
- plus max_worker_processes, plus one extra for each 16
- allowed connections plus workers (see the formula in num_os_semaphores plus one extra for
+ each set of 16 required semaphores (see the formula in ). The parameter SEMMNI
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 ceil((max_connections + autovacuum_max_workers + max_wal_senders + max_worker_processes + 5) / 16).
+ least ceil(num_os_semaphores / 16).
Lowering the number
of allowed connections is a temporary workaround for failures,
which are usually confusingly worded No space
@@ -883,8 +892,9 @@ psql: error: connection to server on socket "/tmp/.s.PGSQL.5432" failed: No such
When using POSIX semaphores, the number of semaphores needed is the
same as for System V, that is one semaphore per allowed connection
(), allowed autovacuum worker process
- () and allowed background
- process ().
+ (), allowed WAL sender process
+ (), allowed background
+ process (), etc.
On the platforms where this option is preferred, there is no specific
kernel limit on the number of POSIX semaphores.
@@ -943,10 +953,10 @@ psql: error: connection to server on socket "/tmp/.s.PGSQL.5432" failed: No such
The default shared memory settings are usually good enough, unless
you have set shared_memory_type to sysv.
- You will usually want to increase kern.ipc.semmni
+ However, you will need to increase kern.ipc.semmni
and kern.ipc.semmns,
as NetBSD's default settings
- for these are uncomfortably small.
+ for these are unworkably small.
@@ -977,11 +987,11 @@ psql: error: connection to server on socket "/tmp/.s.PGSQL.5432" failed: No such
The default shared memory settings are usually good enough, unless
you have set shared_memory_type to sysv.
- You will usually want to
+ However, you will need to
increase kern.seminfo.semmni
and kern.seminfo.semmns,
as OpenBSD's default settings
- for these are uncomfortably small.
+ for these are unworkably small.
@@ -1420,11 +1430,10 @@ export PG_OOM_ADJUST_VALUE=0
with CONFIG_HUGETLBFS=y and
CONFIG_HUGETLB_PAGE=y. 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
- postgres command to see the value of
- . Note that the
- server must be shut down to view this runtime-computed parameter.
- This might look like:
+ The runtime-computed parameter
+ reports the number
+ of huge pages required. This parameter can be viewed before starting the
+ server with a postgres command like:
$ postgres -D $PGDATA -C shared_memory_size_in_huge_pages
3170
@@ -1985,7 +1994,8 @@ pg_dumpall -p 5432 | psql -d postgres -p 5433
sslmode=verify-ca or
verify-full and have the appropriate root certificate
file installed (). Alternatively the
- system CA pool can be used using sslrootcert=system; in
+ system CA pool, as defined
+ by the SSL implementation, can be used using sslrootcert=system; in
this case, sslmode=verify-full is forced for safety, since
it is generally trivial to obtain certificates which are signed by a public
CA.
@@ -2044,6 +2054,16 @@ pg_dumpall -p 5432 | psql -d postgres -p 5433
is an Internet standard and is more secure than the PostgreSQL-specific
MD5 authentication protocol.
+
+
+
+ Support for MD5-encrypted passwords is deprecated and will be removed in
+ a future release of PostgreSQL. Refer to
+ for details about migrating to another
+ password type.
+
+
+
diff --git a/doc/src/sgml/sepgsql.sgml b/doc/src/sgml/sepgsql.sgml
index 1b848f1977c29..0708e48bcd950 100644
--- a/doc/src/sgml/sepgsql.sgml
+++ b/doc/src/sgml/sepgsql.sgml
@@ -87,7 +87,7 @@ Policy from config file: targeted
- To build this module specify (when using make and autoconf ) or (when using
Regression Tests
+
+ The sepgsql test suite is run if
+ PG_TEST_EXTRA contains sepgsql (see
+ ). This method is suitable during
+ development of PostgreSQL. Alternatively, there
+ is a way to run the tests to checks whether a database instance has been
+ set up properly for sepgsql.
+
+
Due to the nature of SELinux, running the
regression tests for sepgsql requires several extra
configuration steps, some of which must be done as root.
- The regression tests will not be run by an ordinary
- make check or make installcheck command; you must
- set up the configuration and then invoke the test script manually.
- The tests must be run in the contrib/sepgsql directory
+
+
+
+ The manual tests must be run in the contrib/sepgsql 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 make installcheck not
@@ -433,7 +442,7 @@ UPDATE t1 SET x = 2, y = func1(y) WHERE z = 100;
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
+ TOAST tables. These operations are prohibited when
sepgsql is enabled.
@@ -794,7 +803,7 @@ ERROR: SELinux: security policy violation
External Resources
- SE-PostgreSQL Introduction
+ SE-PostgreSQL Introduction
This wiki page provides a brief overview, security design, architecture,
diff --git a/doc/src/sgml/sources.sgml b/doc/src/sgml/sources.sgml
index fa68d4d024a93..261f19b3534b5 100644
--- a/doc/src/sgml/sources.sgml
+++ b/doc/src/sgml/sources.sgml
@@ -907,12 +907,12 @@ BETTER: unrecognized node type: 42
C Standard
Code in PostgreSQL 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
+ features available in the C11 standard. That means a conforming
+ C11 compiler has to be able to compile postgres, at least aside
from a few platform dependent pieces.
- A few features included in the C99 standard are, at this time, not
+ A few features included in the C11 standard are, at this time, not
permitted to be used in core PostgreSQL
code. This currently includes variable length arrays, intermingled
declarations and code, // comments, universal
@@ -924,13 +924,11 @@ BETTER: unrecognized node type: 42
features can be used, if a fallback is provided.
- For example _Static_assert() and
+ For example typeof() and
__builtin_constant_p are currently used, even though
they are from newer revisions of the C standard and a
GCC 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 __builtin_constant_p.
+ we do not use them.
diff --git a/doc/src/sgml/spi.sgml b/doc/src/sgml/spi.sgml
index bb3778688bdc0..7e2f2df965dba 100644
--- a/doc/src/sgml/spi.sgml
+++ b/doc/src/sgml/spi.sgml
@@ -126,16 +126,16 @@ int SPI_connect_ext(int options)
-
-
- SPI_ERROR_CONNECT
-
-
- on error
-
-
-
+
+
+ The fact that these functions return int
+ not void is historical. All failure cases are reported
+ via ereport or elog.
+ (In versions before PostgreSQL v10,
+ some but not all failures would be reported with a result value
+ of SPI_ERROR_CONNECT.)
+
@@ -752,7 +752,9 @@ int SPI_execute_extended(const char *command,
true allows non-atomic execution of CALL and DO
- statements
+ statements (but this field is ignored unless
+ the SPI_OPT_NONATOMIC flag was passed
+ to SPI_connect_ext)
@@ -1893,7 +1895,9 @@ int SPI_execute_plan_extended(SPIPlanPtr plan,
true allows non-atomic execution of CALL and DO
- statements
+ statements (but this field is ignored unless
+ the SPI_OPT_NONATOMIC flag was passed
+ to SPI_connect_ext)
diff --git a/doc/src/sgml/start.sgml b/doc/src/sgml/start.sgml
index f4ae1d0fcf781..0263a70059144 100644
--- a/doc/src/sgml/start.sgml
+++ b/doc/src/sgml/start.sgml
@@ -148,7 +148,7 @@
- To create a new database, in this example named
+ To create a new database from the command line, in this example named
mydb, you use the following command:
$createdb mydb
diff --git a/doc/src/sgml/storage.sgml b/doc/src/sgml/storage.sgml
index 61250799ec076..02ddfda834a2e 100644
--- a/doc/src/sgml/storage.sgml
+++ b/doc/src/sgml/storage.sgml
@@ -39,6 +39,8 @@ these required items, the cluster configuration files
Contents of <varname>PGDATA</varname>
+
+
@@ -743,6 +745,8 @@ There are five parts to each page.
Overall Page LayoutPage Layout
+
+
diff --git a/doc/src/sgml/stylesheet-fo.xsl b/doc/src/sgml/stylesheet-fo.xsl
index 3a4a88a728853..aec6de7064a7b 100644
--- a/doc/src/sgml/stylesheet-fo.xsl
+++ b/doc/src/sgml/stylesheet-fo.xsl
@@ -17,6 +17,8 @@
1.5em
+0
+0
@@ -27,6 +29,8 @@
solid1ptblack
+ 0.25in
+ 0.25in12pt12pt6pt
@@ -400,5 +404,21 @@
+
+
+
+
+
+
+
+
+
+
+
+
diff --git a/doc/src/sgml/syntax.sgml b/doc/src/sgml/syntax.sgml
index 4dfbbd0862614..916189a7d68ce 100644
--- a/doc/src/sgml/syntax.sgml
+++ b/doc/src/sgml/syntax.sgml
@@ -2496,7 +2496,7 @@ SELECT getf1(CAST(ROW(11,'this is a test',2.5) AS myrowtype));
linkend="functions-comparison"/>, to compare one row against another
as described in , and to
use them in connection with subqueries, as discussed in ,
+ linkend="functions-subquery"/>.
diff --git a/doc/src/sgml/system-views.sgml b/doc/src/sgml/system-views.sgml
index 8c18bea902fba..4187191ea7413 100644
--- a/doc/src/sgml/system-views.sgml
+++ b/doc/src/sgml/system-views.sgml
@@ -51,6 +51,11 @@
+
+ pg_aios
+ In-use asynchronous IO handles
+
+
pg_available_extensionsavailable extensions
@@ -76,6 +81,11 @@
open cursors
+
+ pg_dsm_registry_allocations
+ shared memory allocations tracked in the DSM registry
+
+
pg_file_settingssummary of configuration file contents
@@ -176,6 +186,11 @@
shared memory allocations
+
+ pg_shmem_allocations_numa
+ NUMA node mappings for shared memory allocations
+
+
pg_statsplanner statistics
@@ -231,6 +246,295 @@
+
+ <structname>pg_aios</structname>
+
+
+ pg_aios
+
+
+
+ The pg_aios view lists all handles that are currently in-use. An I/O handle
+ is used to reference an I/O operation that is being prepared, executed or
+ is in the process of completing. pg_aios contains
+ one row for each I/O handle.
+
+
+
+ This view is mainly useful for developers of
+ PostgreSQL, but may also be useful when tuning
+ PostgreSQL.
+
+
+
+ <structname>pg_aios</structname> Columns
+
+
+
+
+ Column Type
+
+
+ Description
+
+
+
+
+
+
+
+ pidint4
+
+
+ Process ID of the server process that is issuing this I/O.
+
+
+
+
+
+ io_idint4
+
+
+ Identifier of the I/O handle. Handles are reused once the I/O
+ completed (or if the handle is released before I/O is started). On reuse
+
+ pg_aios.io_generation
+
+ is incremented.
+
+
+
+
+
+ io_generationint8
+
+
+ Generation of the I/O handle.
+
+
+
+
+
+ statetext
+
+
+ State of the I/O handle:
+
+
+
+ HANDED_OUT, referenced by code but not yet used
+
+
+
+
+ DEFINED, information necessary for execution is known
+
+
+
+
+ STAGED, ready for execution
+
+
+
+
+ SUBMITTED, submitted for execution
+
+
+
+
+ COMPLETED_IO, finished, but result has not yet been processed
+
+
+
+
+ COMPLETED_SHARED, shared completion processing completed
+
+
+
+
+ COMPLETED_LOCAL, backend local completion processing completed
+
+
+
+
+
+
+
+
+ operationtext
+
+
+ Operation performed using the I/O handle:
+
+
+
+ invalid, not yet known
+
+
+
+
+ readv, a vectored read
+
+
+
+
+ writev, a vectored write
+
+
+
+
+
+
+
+
+ offint8
+
+
+ Offset of the I/O operation.
+
+
+
+
+
+ lengthint8
+
+
+ Length of the I/O operation.
+
+
+
+
+
+ targettext
+
+
+ What kind of object is the I/O targeting:
+
+
+
+ smgr, I/O on relations
+
+
+
+
+
+
+
+
+ handle_data_lenint2
+
+
+ Length of the data associated with the I/O operation. For I/O to/from
+ and , this indicates the number of buffers the
+ I/O is operating on.
+
+
+
+
+
+ raw_resultint4
+
+
+ Low-level result of the I/O operation, or NULL if the operation has not
+ yet completed.
+
+
+
+
+
+ resulttext
+
+
+ High-level result of the I/O operation:
+
+
+
+ UNKNOWN means that the result of the
+ operation is not yet known.
+
+
+
+
+ OK means the I/O completed successfully.
+
+
+
+
+ PARTIAL means that the I/O completed without
+ error, but did not process all data. Commonly callers will need to
+ retry and perform the remainder of the work in a separate I/O.
+
+
+
+
+ WARNING means that the I/O completed without
+ error, but that execution of the IO triggered a warning. E.g. when
+ encountering a corrupted buffer with enabled.
+
+
+
+
+ ERROR means the I/O failed with an error.
+
+
+
+
+
+
+
+
+ target_desctext
+
+
+ Description of what the I/O operation is targeting.
+
+
+
+
+
+ f_syncbool
+
+
+ Flag indicating whether the I/O is executed synchronously.
+
+
+
+
+
+ f_localmembool
+
+
+ Flag indicating whether the I/O references process local memory.
+
+
+
+
+
+ f_bufferedbool
+
+
+ Flag indicating whether the I/O is buffered I/O.
+
+
+
+
+
+
+
+
+ The pg_aios view is read-only.
+
+
+
+ By default, the pg_aios view can be read only by
+ superusers or roles with privileges of the
+ pg_read_all_stats role.
+
+
+
<structname>pg_available_extensions</structname>
@@ -483,10 +787,10 @@
- parenttext
+ typetext
- Name of the parent of this memory context
+ Type of the memory context
@@ -495,7 +799,22 @@
levelint4
- Distance from TopMemoryContext in context tree
+ The 1-based level of the context in the memory context hierarchy. The
+ level of a context also shows the position of that context in the
+ path column.
+
+
+
+
+
+ pathint4[]
+
+
+ Array of transient numerical identifiers to describe the memory
+ context hierarchy. The first element is for
+ TopMemoryContext, subsequent elements contain
+ intermediate parents and the final element contains the identifier for
+ the current context.
@@ -552,6 +871,29 @@
read only by superusers or roles with the privileges of the
pg_read_all_stats role.
+
+
+ Since memory contexts are created and destroyed during the running of a
+ query, the identifiers stored in the path column
+ can be unstable between multiple invocations of the view in the same query.
+ The example below demonstrates an effective usage of this column and
+ calculates the total number of bytes used by
+ CacheMemoryContext and all of its children:
+
+
+WITH memory_contexts AS (
+ SELECT * FROM pg_backend_memory_contexts
+)
+SELECT sum(c1.total_bytes)
+FROM memory_contexts c1, memory_contexts c2
+WHERE c2.name = 'CacheMemoryContext'
+AND c1.path[c2.level] = c2.path[c2.level];
+
+
+ The Common Table Expression is used
+ to ensure the context IDs in the path column
+ match between both evaluations of the view.
+
@@ -749,6 +1091,75 @@
+
+ <structname>pg_dsm_registry_allocations</structname>
+
+
+ pg_dsm_registry_allocations
+
+
+
+ The pg_dsm_registry_allocations view shows shared
+ memory allocations tracked in the dynamic shared memory (DSM) registry.
+ This includes memory allocated by extensions using the mechanisms detailed
+ in .
+
+
+
+ <structname>pg_dsm_registry_allocations</structname> Columns
+
+
+
+
+ Column Type
+
+
+ Description
+
+
+
+
+
+
+
+ nametext
+
+
+ The name of the allocation in the DSM registry.
+
+
+
+
+
+ typetext
+
+
+ The type of allocation. Possible values are segment,
+ area, and hash, which correspond
+ to dynamic shared memory segments, areas, and hash tables, respectively.
+
+
+
+
+
+ sizeint8
+
+
+ Size of the allocation in bytes. NULL for entries of type
+ area and hash.
+
+
+
+
+
+
+
+ By default, the pg_dsm_registry_allocations view
+ can be read only by superusers or roles with privileges of the
+ pg_read_all_stats role.
+
+
+
<structname>pg_file_settings</structname>
@@ -2397,7 +2808,7 @@ SELECT * FROM pg_locks pl LEFT JOIN pg_prepared_xacts ppx
activebool
- True if this slot is currently actively being used
+ True if this slot is currently being streamed
@@ -2406,9 +2817,8 @@ SELECT * FROM pg_locks pl LEFT JOIN pg_prepared_xacts ppx
active_pidint4
- The process ID of the session using this slot if the slot
- is currently actively being used. NULL if
- inactive.
+ The process ID of the session streaming data for this slot.
+ NULL if inactive.
@@ -2483,21 +2893,18 @@ SELECT * FROM pg_locks pl LEFT JOIN pg_prepared_xacts ppx
unreserved 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
+ the next checkpoint. This typically occurs when
+ is set to
+ a non-negative value. This state can return
to reserved or extended.
- lost means that some required WAL files have
- been removed and this slot is no longer usable.
+ lost means that this slot is no longer usable.
- The last two states are seen only when
- is
- non-negative. If restart_lsn is NULL, this
- field is null.
@@ -2523,20 +2930,33 @@ SELECT * FROM pg_locks pl LEFT JOIN pg_prepared_xacts ppx
+
+
+ two_phase_atpg_lsn
+
+
+ The address (LSN) from which the decoding of prepared
+ transactions is enabled. NULL for logical slots
+ where two_phase is false and for physical slots.
+
+
+
inactive_sincetimestamptz
- The time since the slot has become inactive.
- NULL if the slot is currently being used.
- Note that for slots on the standby that are being synced from a
+ The time when the slot became inactive. NULL if the
+ slot is currently being streamed. If the slot becomes invalid,
+ this value will never be updated.
+ For standby slots that are being synced from a
primary server (whose synced field is
- true), the
- inactive_since indicates the last
- synchronization (see
- )
- time.
+ true), the inactive_since
+ indicates the time when slot synchronization (see )
+ was most recently stopped. NULL if the slot
+ has always been synchronized. This helps standby slots track when
+ synchronization was interrupted.
@@ -2548,7 +2968,7 @@ SELECT * FROM pg_locks pl LEFT JOIN pg_prepared_xacts ppx
True if this logical slot conflicted with recovery (and so is now
invalidated). When this column is true, check
invalidation_reason column for the conflict
- reason. Always NULL for physical slots.
+ reason. Always NULL for physical slots.
@@ -2580,6 +3000,13 @@ SELECT * FROM pg_locks pl LEFT JOIN pg_prepared_xacts ppx
perform logical decoding. It is set only for logical slots.
+
+
+ idle_timeout means that the slot has remained
+ inactive longer than the configured
+ duration.
+
+
@@ -3576,7 +4003,7 @@ SELECT * FROM pg_locks pl LEFT JOIN pg_prepared_xacts ppx
passwdtext
- Password (possibly encrypted); null if none. See
+ Encrypted password; null if none. See
pg_authid
for details of how encrypted passwords are stored.
@@ -3700,6 +4127,96 @@ SELECT * FROM pg_locks pl LEFT JOIN pg_prepared_xacts ppx
+
+ <structname>pg_shmem_allocations_numa</structname>
+
+
+ pg_shmem_allocations_numa
+
+
+
+ The pg_shmem_allocations_numa shows how shared
+ memory allocations in the server's main shared memory segment are distributed
+ across NUMA nodes. This includes both memory allocated by
+ PostgreSQL itself and memory allocated
+ by extensions using the mechanisms detailed in
+ . This view will output multiple rows
+ for each of the shared memory segments provided that they are spread across
+ multiple NUMA nodes. This view should not be queried by monitoring systems
+ as it is very slow and may end up allocating shared memory in case it was not
+ used earlier.
+ Current limitation for this view is that won't show anonymous shared memory
+ allocations.
+
+
+
+ Note that this view does not include memory allocated using the dynamic
+ shared memory infrastructure.
+
+
+
+
+ When determining the NUMA node, the view touches
+ all memory pages for the shared memory segment. This will force
+ allocation of the shared memory, if it wasn't allocated already,
+ and the memory may get allocated in a single NUMA
+ node (depending on system configuration).
+
+
+
+
+ <structname>pg_shmem_allocations_numa</structname> Columns
+
+
+
+
+ Column Type
+
+
+ Description
+
+
+
+
+
+
+
+ nametext
+
+
+ The name of the shared memory allocation.
+
+
+
+
+
+ numa_nodeint4
+
+
+ ID of NUMA node
+
+
+
+
+
+ sizeint8
+
+
+ Size of the allocation on this particular NUMA memory node in bytes
+
+
+
+
+
+
+
+
+ By default, the pg_shmem_allocations_numa view can be
+ read only by superusers or roles with privileges of the
+ pg_read_all_stats role.
+
+
+
<structname>pg_stats</structname>
@@ -3907,7 +4424,7 @@ SELECT * FROM pg_locks pl LEFT JOIN pg_prepared_xacts ppx
range type column. (Null for non-range types.)
- This histogram is calculated using the subtype_diff
+ This histogram is calculated using the subtype_diff
range function regardless of whether range bounds are inclusive.
@@ -4526,7 +5043,9 @@ SELECT * FROM pg_locks pl LEFT JOIN pg_prepared_xacts ppx
The view pg_timezone_abbrevs provides a list
of time zone abbreviations that are currently recognized by the datetime
input routines. The contents of this view change when the
- run-time parameter is modified.
+ or
+ run-time parameters are
+ modified.
diff --git a/doc/src/sgml/tableam.sgml b/doc/src/sgml/tableam.sgml
index 4b37f2e5a601c..9ccf5b739ed60 100644
--- a/doc/src/sgml/tableam.sgml
+++ b/doc/src/sgml/tableam.sgml
@@ -35,13 +35,60 @@
argument of type internal and to return the pseudo-type
table_am_handler. The argument is a dummy value that simply
serves to prevent handler functions from being called directly from SQL commands.
+
+
+
+ Here is how an extension SQL script file might create a table access
+ method handler:
+
+
+
+CREATE OR REPLACE FUNCTION my_tableam_handler(internal)
+ RETURNS table_am_handler AS 'my_extension', 'my_tableam_handler'
+ LANGUAGE C STRICT;
+CREATE ACCESS METHOD myam TYPE TABLE HANDLER my_tableam_handler;
+
+
+
The result of the function must be a pointer to a struct of type
TableAmRoutine, 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 static const variable in global
- scope. The TableAmRoutine struct, also called the
+ defining it as a static const variable in global scope.
+
+
+
+ Here is how a source file with the table access method handler might
+ look like:
+
+
+
+
+
+
+ The TableAmRoutine struct, also called the
access method's API struct, 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
diff --git a/doc/src/sgml/targets-meson.txt b/doc/src/sgml/targets-meson.txt
index bd470c87a7090..d0021a5eb10d2 100644
--- a/doc/src/sgml/targets-meson.txt
+++ b/doc/src/sgml/targets-meson.txt
@@ -1,4 +1,4 @@
-# Copyright (c) 2023-2024, PostgreSQL Global Development Group
+# Copyright (c) 2023-2025, PostgreSQL Global Development Group
#
# Description of important meson targets, used for the 'help' target and
# installation.sgml (via generate-targets-meson.pl). Right now the parsers are
diff --git a/doc/src/sgml/test-decoding.sgml b/doc/src/sgml/test-decoding.sgml
index 5d1ae8f4f52e2..7d3d590471a32 100644
--- a/doc/src/sgml/test-decoding.sgml
+++ b/doc/src/sgml/test-decoding.sgml
@@ -25,16 +25,16 @@
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
+ lsn | xid | data
+------------+-----+--------------------------------------------------
+ 0/016D30F8 | 691 | BEGIN
+ 0/016D32A0 | 691 | table public.data: INSERT: id[int4]:2 data[text]:'arg'
+ 0/016D32A0 | 691 | table public.data: INSERT: id[int4]:3 data[text]:'demo'
+ 0/016D32A0 | 691 | COMMIT
+ 0/016D32D8 | 692 | BEGIN
+ 0/016D3398 | 692 | table public.data: DELETE: id[int4]:2
+ 0/016D3398 | 692 | table public.data: DELETE: id[int4]:3
+ 0/016D3398 | 692 | COMMIT
(8 rows)
@@ -45,18 +45,18 @@ postgres=# SELECT * FROM pg_logical_slot_get_changes('test_slot', NULL, NULL, 'i
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
+ lsn | xid | data
+------------+-----+--------------------------------------------------
+ 0/016B21F8 | 503 | opening a streamed block for transaction TXN 503
+ 0/016B21F8 | 503 | streaming change for TXN 503
+ 0/016B2300 | 503 | streaming change for TXN 503
+ 0/016B2408 | 503 | streaming change for TXN 503
+ 0/016BEBA0 | 503 | closing a streamed block for transaction TXN 503
+ 0/016B21F8 | 503 | opening a streamed block for transaction TXN 503
+ 0/016BECA8 | 503 | streaming change for TXN 503
+ 0/016BEDB0 | 503 | streaming change for TXN 503
+ 0/016BEEB8 | 503 | streaming change for TXN 503
+ 0/016BEBA0 | 503 | closing a streamed block for transaction TXN 503
(10 rows)
diff --git a/doc/src/sgml/textsearch.sgml b/doc/src/sgml/textsearch.sgml
index bde5f391e5c06..89928ed182913 100644
--- a/doc/src/sgml/textsearch.sgml
+++ b/doc/src/sgml/textsearch.sgml
@@ -1342,7 +1342,7 @@ ts_headline(config<b> and
</b>, which can be suitable
- for HTML output.
+ for HTML output (but see the warning below).
@@ -1354,6 +1354,21 @@ ts_headline(config
+
+ Warning: Cross-site Scripting (XSS) Safety
+
+ The output from ts_headline is not guaranteed to
+ be safe for direct inclusion in web pages. When
+ HighlightAll is false (the
+ default), some simple XML tags are removed from the document, but this
+ is not guaranteed to remove all HTML markup. Therefore, this does not
+ provide an effective defense against attacks such as cross-site
+ scripting (XSS) attacks, when working with untrusted input. To guard
+ against such attacks, all HTML markup should be removed from the input
+ document, or an HTML sanitizer should be used on the output.
+
+
+
These option names are recognized case-insensitively.
You must double-quote string values if they contain spaces or commas.
@@ -2225,6 +2240,18 @@ LIMIT 10;
Specifically, the only non-alphanumeric characters supported for
email user names are period, dash, and underscore.
+
+
+ tag does not support all valid tag names as defined by
+ W3C Recommendation, XML.
+ Specifically, the only tag names supported are those starting with an
+ ASCII letter, underscore, or colon, and containing only letters, digits,
+ hyphens, underscores, periods, and colons. tag also
+ includes XML comments starting with <!-- and ending
+ with -->, and XML declarations (but note that this
+ includes anything starting with <?x and ending with
+ >).
+
@@ -3852,6 +3879,7 @@ Parser: "pg_catalog.default"
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 | estonian_stem | snowball stemmer for estonian 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
diff --git a/doc/src/sgml/trigger.sgml b/doc/src/sgml/trigger.sgml
index 31626536a2e29..bb1b5faf34e31 100644
--- a/doc/src/sgml/trigger.sgml
+++ b/doc/src/sgml/trigger.sgml
@@ -129,6 +129,9 @@
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.
+ Also, the trigger will always run as the role that queued the trigger
+ event, unless the trigger function is marked as SECURITY
+ DEFINER, in which case it will run as the function owner.
@@ -289,6 +292,10 @@
BEFORE trigger. Changes to the value of a generated
column in a BEFORE trigger are ignored and will be
overwritten.
+ Virtual generated columns are never computed when triggers fire. In the C
+ language interface, their content is undefined in a trigger function.
+ Higher-level programming languages should prevent access to virtual
+ generated columns in triggers.
@@ -357,7 +364,8 @@
If a foreign key constraint specifies referential actions (that
is, cascading updates or deletes), those actions are performed via
- ordinary SQL update or delete commands on the referencing table.
+ ordinary SQL UPDATE or DELETE
+ commands on the referencing table.
In particular, any triggers that exist on the referencing table
will be fired for those changes. If such a trigger modifies or
blocks the effect of one of these commands, the end result could
@@ -915,8 +923,7 @@ trigf(PG_FUNCTION_ARGS)
tupdesc = trigdata->tg_relation->rd_att;
/* connect to SPI manager */
- if ((ret = SPI_connect()) < 0)
- elog(ERROR, "trigf (fired %s): SPI_connect returned %d", when, ret);
+ SPI_connect();
/* get number of rows in table */
ret = SPI_exec("SELECT count(*) FROM ttest", 0);
diff --git a/doc/src/sgml/user-manag.sgml b/doc/src/sgml/user-manag.sgml
index 07a16247d76f1..ed18704a9c2ab 100644
--- a/doc/src/sgml/user-manag.sgml
+++ b/doc/src/sgml/user-manag.sgml
@@ -407,7 +407,7 @@ REVOKE group_role FROM role1become 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
+ considered owned by the group role, not the login role. Second, member
roles that have been granted membership with the
INHERIT option automatically have use of the
privileges of those directly or indirectly a member of, though the
@@ -590,101 +590,73 @@ DROP ROLE doomed_role;
and information. Administrators (including roles that have the
CREATEROLE privilege) can GRANT these
roles to users and/or other roles in their environment, providing those
- users with access to the specified capabilities and information.
+ users with access to the specified capabilities and information. For
+ example:
+
+
+GRANT pg_signal_backend TO admin_user;
+
+
+
+ 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.
+
+
+
- The predefined roles are described in .
+ The predefined roles are described below.
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.
-
-
- Predefined Roles
-
-
-
-
-
- Role
- Allowed Access
-
-
-
-
- pg_read_all_data
- Read all data (tables, views, sequences), as if having
- SELECT rights on those objects, and USAGE rights on
- all schemas, even without having it explicitly. This role does not have
- the role attribute BYPASSRLS set. If RLS is being
- used, an administrator may wish to set BYPASSRLS on
- roles which this role is GRANTed to.
-
-
- pg_write_all_data
- Write all data (tables, views, sequences), as if having
- INSERT, UPDATE, and
- DELETE rights on those objects, and USAGE rights on
- all schemas, even without having it explicitly. This role does not have
- the role attribute BYPASSRLS set. If RLS is being
- used, an administrator may wish to set BYPASSRLS on
- roles which this role is GRANTed to.
-
-
- pg_read_all_settings
- Read all configuration variables, even those normally visible only to
- superusers.
-
-
- pg_read_all_stats
- Read all pg_stat_* views and use various statistics related extensions,
- even those normally visible only to superusers.
-
-
- pg_stat_scan_tables
- Execute monitoring functions that may take ACCESS SHARE locks on tables,
- potentially for a long time.
-
-
- pg_monitor
- Read/execute various monitoring views and functions.
- This role is a member of pg_read_all_settings,
- pg_read_all_stats and
- pg_stat_scan_tables.
-
-
- pg_database_owner
- None. Membership consists, implicitly, of the current database owner.
-
-
- pg_signal_backend
- Signal another backend to cancel a query or terminate its session.
-
-
- pg_read_server_files
- Allow reading files from any location the database can access on the server with COPY and
- other file-access functions.
-
-
- pg_write_server_files
- Allow writing to files in any location the database can access on the server with COPY and
- other file-access functions.
-
-
- pg_execute_server_program
- 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.
-
-
- pg_checkpoint
- Allow executing
- the CHECKPOINT
- command.
-
-
- pg_maintain
- Allow executing
+
+
+ pg_checkpoint
+
+
+ pg_checkpoint allows executing the
+ CHECKPOINT command.
+
+
+
+
+
+ pg_create_subscription
+
+
+ pg_create_subscription allows users with
+ CREATE permission on the database to issue
+ CREATE SUBSCRIPTION.
+
+
+
+
+
+ pg_database_owner
+
+
+ pg_database_owner always has exactly one implicit
+ member: the current database owner. It cannot be granted membership in
+ any role, and no role can be granted membership in
+ pg_database_owner. However, like any other role, it
+ can own objects and receive grants of access privileges. Consequently,
+ once pg_database_owner has rights within a template
+ database, each owner of a database instantiated from that template will
+ possess those rights. Initially, this role owns the
+ public schema, so each database owner governs local
+ use of that schema.
+
+
+
+
+
+ pg_maintain
+
+
+ pg_maintain allows executing
VACUUM,
ANALYZE,
CLUSTER,
@@ -692,76 +664,138 @@ DROP ROLE doomed_role;
REINDEX,
and LOCK TABLE on all
relations, as if having MAINTAIN rights on those
- objects, even without having it explicitly.
-
-
- pg_use_reserved_connections
- Allow use of connection slots reserved via
- .
-
-
- pg_create_subscription
- Allow users with CREATE permission on the
- database to issue
- CREATE SUBSCRIPTION.
-
-
-
-
-
-
- The pg_monitor, pg_read_all_settings,
- pg_read_all_stats and pg_stat_scan_tables
- 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.
-
-
-
- The pg_database_owner 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 pg_database_owner has rights within a
- template database, each owner of a database instantiated from that template
- will exercise those rights. pg_database_owner cannot be
- a member of any role, and it cannot have non-implicit members. Initially,
- this role owns the public schema, so each database owner
- governs local use of the schema.
-
-
-
- The pg_signal_backend 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 .
-
-
-
- The pg_read_server_files, pg_write_server_files and
- pg_execute_server_program 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.
-
-
-
- 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.
-
-
-
- Administrators can grant access to these roles to users using the
- GRANT command, for example:
-
-
-GRANT pg_signal_backend TO admin_user;
-
+ objects.
+
+
+
+
+
+ pg_monitor
+ pg_read_all_settings
+ pg_read_all_stats
+ pg_stat_scan_tables
+
+
+ These 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.
+
+
+ pg_monitor allows reading/executing various
+ monitoring views and functions. This role is a member of
+ pg_read_all_settings,
+ pg_read_all_stats and
+ pg_stat_scan_tables.
+
+
+ pg_read_all_settings allows reading all configuration
+ variables, even those normally visible only to superusers.
+
+
+ pg_read_all_stats allows reading all pg_stat_* views
+ and use various statistics related extensions, even those normally
+ visible only to superusers.
+
+
+ pg_stat_scan_tables allows executing monitoring
+ functions that may take ACCESS SHARE locks on tables,
+ potentially for a long time (e.g., pgrowlocks(text)
+ in the extension).
+
+
+
+
+
+ pg_read_all_data
+ pg_write_all_data
+
+
+ pg_read_all_data allows reading all data (tables,
+ views, sequences), as if having SELECT rights on
+ those objects and USAGE rights on all schemas. This
+ role does not bypass row-level security (RLS) policies. If RLS is being
+ used, an administrator may wish to set BYPASSRLS on
+ roles which this role is granted to.
+
+
+ pg_write_all_data allows writing all data (tables,
+ views, sequences), as if having INSERT,
+ UPDATE, and DELETE rights on those
+ objects and USAGE rights on all schemas. This role
+ does not bypass row-level security (RLS) policies. If RLS is being
+ used, an administrator may wish to set BYPASSRLS on
+ roles which this role is granted to.
+
+
+
+
+
+ pg_read_server_files
+ pg_write_server_files
+ pg_execute_server_program
+
+
+ These 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. 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.
+
+
+ pg_read_server_files allows reading files from any
+ location the database can access on the server using
+ COPY and other file-access functions.
+
+
+ pg_write_server_files allows writing to files in any
+ location the database can access on the server using
+ COPY and other file-access functions.
+
+
+ pg_execute_server_program allows executing programs
+ on the database server as the user the database runs as using
+ COPY and other functions which allow executing a
+ server-side program.
+
+
+
+
+
+ pg_signal_autovacuum_worker
+
+
+ pg_signal_autovacuum_worker allows signaling
+ autovacuum workers to cancel the current table's vacuum or terminate its
+ session. See .
+
+
+
+
+
+ pg_signal_backend
+
+
+ pg_signal_backend allows signaling another backend to
+ cancel a query or terminate its session. Note that this role does not
+ permit signaling backends owned by a superuser. See
+ .
+
+
+
+
+
+ pg_use_reserved_connections
+
+
+ pg_use_reserved_connections allows use of connection
+ slots reserved via .
+
+
+
+
diff --git a/doc/src/sgml/wal.sgml b/doc/src/sgml/wal.sgml
index 05e2a8f8be959..f3b86b26be905 100644
--- a/doc/src/sgml/wal.sgml
+++ b/doc/src/sgml/wal.sgml
@@ -186,7 +186,7 @@
- Each individual record in a WAL file is protected by a CRC-32 (32-bit) check
+ Each individual record in a WAL file is protected by a CRC-32C (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.
@@ -194,10 +194,8 @@
- Data pages are not currently checksummed by default, though full page images
- recorded in WAL records will be protected; see initdb
- for details about enabling data checksums.
+ Data pages are checksummed by default, and full page images
+ recorded in WAL records are always checksum protected.
@@ -212,7 +210,7 @@
- Individual state files in pg_twophase are protected by CRC-32.
+ Individual state files in pg_twophase are protected by CRC-32C.
@@ -238,15 +236,15 @@
- By default, data pages are not protected by checksums, but this can
- optionally be enabled for a cluster. When enabled, each data page includes
+ By default, data pages are protected by checksums, but this can
+ optionally be disabled 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.
- Checksums are normally enabled when the cluster is initialized using initdb.
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
@@ -643,6 +641,9 @@
until the situation is resolved. A slow or failed standby server that
uses a replication slot will have the same effect (see
).
+ Similarly, if
+ WAL summarization is enabled, old segments are kept
+ until they are summarized.
@@ -679,11 +680,11 @@
In some cases, when the WAL size on the primary increases quickly,
- for instance during massive INSERT,
+ for instance during massive INSERT,
the restartpoints_req counter on the standby
may demonstrate a peak growth.
This occurs because requests to create a new restartpoint due to increased
- XLOG consumption cannot be performed because the safe checkpoint record
+ WAL consumption cannot be performed because the safe checkpoint record
since the last restartpoint has not yet been replayed on the standby.
This behavior is normal and does not lead to an increase in system resource
consumption.
@@ -810,8 +811,9 @@
When is enabled, the total
amounts of time XLogWrite writes and
issue_xlog_fsync syncs WAL data to disk are counted as
- wal_write_time and wal_sync_time in
- , respectively.
+ write_time and fsync_time in
+ for the object
+ wal, respectively.
XLogWrite is normally called by
XLogInsertRecord (when there is no space for the new
record in WAL buffers), XLogFlush and the WAL writer,
@@ -829,8 +831,9 @@
of the setting of track_wal_io_timing, the number
of times XLogWrite writes and
issue_xlog_fsync syncs WAL data to disk are also
- counted as wal_write and wal_sync
- in pg_stat_wal, respectively.
+ counted as writes and fsyncs
+ in pg_stat_io for the object
+ wal, respectively.
@@ -841,8 +844,8 @@
The and
settings limit prefetching
concurrency and distance, respectively. By default, it is set to
- try, which enables the feature on systems where
- posix_fadvise is available.
+ try, which enables the feature on systems that support
+ issuing read-ahead advice.
diff --git a/doc/src/sgml/xfunc.sgml b/doc/src/sgml/xfunc.sgml
index a7c170476af8e..04bf919b34384 100644
--- a/doc/src/sgml/xfunc.sgml
+++ b/doc/src/sgml/xfunc.sgml
@@ -234,21 +234,6 @@ CALL clean_emp();
whereas returning void is a PostgreSQL extension.
-
-
- 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., CREATE TABLE), the effects
- of such commands will not be visible during parse analysis of
- later commands in the function. Thus, for example,
- CREATE TABLE foo (...); INSERT INTO foo VALUES(...);
- will not work as desired if packaged up into a single SQL function,
- since foo won't exist yet when the INSERT
- command is parsed. It's recommended to use PL/pgSQL
- instead of an SQL function in this type of situation.
-
-
-
The syntax of the CREATE FUNCTION command requires
the function body to be written as a string constant. It is usually
@@ -1954,6 +1939,9 @@ CREATE FUNCTION square_root(double precision) RETURNS double precision
magic block
+
+ PG_MODULE_MAGIC
+
To ensure that a dynamically loaded object file is not loaded into an
@@ -1968,6 +1956,30 @@ CREATE FUNCTION square_root(double precision) RETURNS double precision
PG_MODULE_MAGIC;
+or
+
+PG_MODULE_MAGIC_EXT(parameters);
+
+
+
+
+ The PG_MODULE_MAGIC_EXT variant allows the specification
+ of additional information about the module; currently, a name and/or a
+ version string can be added. (More fields might be allowed in future.)
+ Write something like this:
+
+
+PG_MODULE_MAGIC_EXT(
+ .name = "my_module_name",
+ .version = "1.2.3"
+);
+
+
+ Subsequently the name and version can be examined via
+ the pg_get_loaded_modules() function.
+ The meaning of the version string is not restricted
+ by PostgreSQL, but use of semantic versioning
+ rules is recommended.
@@ -2039,8 +2051,7 @@ PG_MODULE_MAGIC;
- By-value types can only be 1, 2, or 4 bytes in length
- (also 8 bytes, if sizeof(Datum) is 8 on your machine).
+ By-value types can only be 1, 2, 4, or 8 bytes in length.
You should be careful to define your types such that they will be the
same size (in bytes) on all architectures. For example, the
long type is dangerous because it is 4 bytes on some
@@ -2153,7 +2164,7 @@ memcpy(destination->data, buffer, 40);
it's considered good style to use the macro VARHDRSZ
to refer to the size of the overhead for a variable-length type.
Also, the length field must be set using the
- SET_VARSIZE macro, not by simple assignment.
+ SET_VARSIZE function, not by simple assignment.
@@ -2384,6 +2395,56 @@ PG_FUNCTION_INFO_V1(funcname);
takes as its argument the actual value to return.
+
+ To call another version-1 function, you can use
+ DirectFunctionCalln(func,
+ arg1, ..., argn). This is particularly useful when you want
+ to call functions defined in the standard internal library, by using an
+ interface similar to their SQL signature.
+
+
+
+ These convenience functions and similar ones can be found
+ in fmgr.h.
+ The DirectFunctionCalln
+ family expect a C function name as their first argument. There are also
+ OidFunctionCalln which
+ take the OID of the target function, and some other variants. All of
+ these expect the function's arguments to be supplied
+ as Datums, and likewise they return Datum.
+ Note that neither arguments nor result are allowed to be NULL when
+ using these convenience functions.
+
+
+
+ For example, to call the starts_with(text, text)
+ function from C, you can search through the catalog and find out that
+ its C implementation is the
+ Datum text_starts_with(PG_FUNCTION_ARGS)
+ function. Typically you would
+ use DirectFunctionCall2(text_starts_with, ...) to
+ call such a function. However, starts_with(text,
+ text) requires collation information, so it will fail
+ with could not determine which collation to use for string
+ comparison if called that way. Instead you must
+ use DirectFunctionCall2Coll(text_starts_with, ...)
+ and provide the desired collation, which typically is just passed
+ through from PG_GET_COLLATION(), as shown in the
+ example below.
+
+
+
+ fmgr.h also supplies macros that facilitate
+ conversions between C types and Datum. For example to
+ turn Datum into text*, you can
+ use DatumGetTextPP(X). While some types have macros
+ named like TypeGetDatum(X) for the reverse
+ conversion, text* does not; it's sufficient to use the
+ generic macro PointerGetDatum(X) for that.
+ If your extension defines additional types, it is usually convenient to
+ define similar macros for your types too.
+
+
Here are some examples using the version-1 calling convention:
@@ -2482,6 +2543,25 @@ concat_text(PG_FUNCTION_ARGS)
memcpy(VARDATA(new_text) + arg1_size, VARDATA_ANY(arg2), arg2_size);
PG_RETURN_TEXT_P(new_text);
}
+
+/* A wrapper around starts_with(text, text) */
+
+PG_FUNCTION_INFO_V1(t_starts_with);
+
+Datum
+t_starts_with(PG_FUNCTION_ARGS)
+{
+ text *t1 = PG_GETARG_TEXT_PP(0);
+ text *t2 = PG_GETARG_TEXT_PP(1);
+ Oid collid = PG_GET_COLLATION();
+ bool result;
+
+ result = DatumGetBool(DirectFunctionCall2Coll(text_starts_with,
+ collid,
+ PointerGetDatum(t1),
+ PointerGetDatum(t2)));
+ PG_RETURN_BOOL(result);
+}
]]>
@@ -2513,6 +2593,10 @@ CREATE FUNCTION copytext(text) RETURNS text
CREATE FUNCTION concat_text(text, text) RETURNS text
AS 'DIRECTORY/funcs', 'concat_text'
LANGUAGE C STRICT;
+
+CREATE FUNCTION t_starts_with(text, text) RETURNS boolean
+ AS 'DIRECTORY/funcs', 't_starts_with'
+ LANGUAGE C STRICT;
@@ -2704,6 +2788,142 @@ CREATE FUNCTION concat_text(text, text) RETURNS text
&dfunc;
+
+ Server API and ABI Stability Guidance
+
+
+ This section contains guidance to authors of extensions and other server
+ plugins about API and ABI stability in the
+ PostgreSQL server.
+
+
+
+ General
+
+
+ The PostgreSQL server contains several
+ well-demarcated APIs for server plugins, such as the function manager
+ (fmgr, described in this chapter),
+ SPI (), and various hooks
+ specifically designed for extensions. These interfaces are carefully
+ managed for long-term stability and compatibility. However, the entire
+ set of global functions and variables in the server effectively
+ constitutes the publicly usable API, and most of it was not designed
+ with extensibility and long-term stability in mind.
+
+
+
+ Therefore, while taking advantage of these interfaces is valid, the
+ further one strays from the well-trodden path, the likelier it will be
+ that one might encounter API or ABI compatibility issues at some point.
+ Extension authors are encouraged to provide feedback about their
+ requirements, so that over time, as new use patterns arise, certain
+ interfaces can be considered more stabilized or new, better-designed
+ interfaces can be added.
+
+
+
+
+ API Compatibility
+
+ The API, or application programming interface, is the
+ interface used at compile time.
+
+
+
+ Major Versions
+
+ There is no promise of API compatibility between
+ PostgreSQL major versions. Extension code
+ therefore might require source code changes to work with multiple major
+ versions. These can usually be managed with preprocessor conditions
+ such as #if PG_VERSION_NUM >= 160000.
+ Sophisticated extensions that use interfaces beyond the well-demarcated
+ ones usually require a few such changes for each major server version.
+
+
+
+
+ Minor Versions
+
+ PostgreSQL makes an effort to avoid server
+ API breaks in minor releases. In general, extension code that compiles
+ and works with a minor release should also compile and work with any
+ other minor release of the same major version, past or future.
+
+
+
+ When a change is required, it will be carefully
+ managed, taking the requirements of extensions into account. Such
+ changes will be communicated in the release notes ().
+
+
+
+
+
+ ABI Compatibility
+
+ The ABI, or application binary interface, is the
+ interface used at run time.
+
+
+
+ Major Versions
+
+ Servers of different major versions have intentionally incompatible
+ ABIs. Extensions that use server APIs must therefore be re-compiled for
+ each major release. The inclusion of PG_MODULE_MAGIC
+ (see ) ensures that code compiled for
+ one major version will be rejected by other major versions.
+
+
+
+
+ Minor Versions
+
+ PostgreSQL makes an effort to avoid server
+ ABI breaks in minor releases. In general, an extension compiled against
+ any minor release should work with any other minor release of the same
+ major version, past or future.
+
+
+
+ When a change is required,
+ PostgreSQL will choose the least invasive
+ change possible, for example by squeezing a new field into padding
+ space or appending it to the end of a struct. These sorts of changes
+ should not impact extensions unless they use very unusual code
+ patterns.
+
+
+
+ In rare cases, however, even such non-invasive changes may be
+ impractical or impossible. In such an event, the change will be
+ carefully managed, taking the requirements of extensions into account.
+ Such changes will also be documented in the release notes ().
+
+
+
+ Note, however, that many parts of the server are not designed or
+ maintained as publicly-consumable APIs (and that, in most cases, the
+ actual boundary is also not well-defined). If urgent needs arise,
+ changes in those parts will naturally be made with less consideration
+ for extension code than changes in well-defined and widely used
+ interfaces.
+
+
+
+ Also, in the absence of automated detection of such changes, this is
+ not a guarantee, but historically such breaking changes have been
+ extremely rare.
+
+
+
+
+
+
Composite-Type Arguments
@@ -3448,11 +3668,14 @@ LWLockRelease(AddinShmemInitLock);
shmem_startup_hook provides a convenient place for the
initialization code, but it is not strictly required that all such code
- be placed in this hook. Each backend will execute the registered
- shmem_startup_hook shortly after it attaches to shared
- memory. Note that add-ins should still acquire
+ be placed in this hook. On Windows (and anywhere else where
+ EXEC_BACKEND is defined), each backend executes the
+ registered shmem_startup_hook shortly after it
+ attaches to shared memory, so add-ins should still acquire
AddinShmemInitLock within this hook, as shown in the
- example above.
+ example above. On other platforms, only the postmaster process executes
+ the shmem_startup_hook, and each backend automatically
+ inherits the pointers to shared memory.
@@ -3539,7 +3762,7 @@ LWLockPadded *GetNamedLWLockTranche(const char *tranche_name)
shmem_request_hook. To do so, first allocate a
tranche_id by calling:
-int LWLockNewTrancheId(void)
+int LWLockNewTrancheId(const char *name)
Next, initialize each LWLock, passing the new
tranche_id as an argument:
@@ -3557,17 +3780,8 @@ void LWLockInitialize(LWLock *lock, int tranche_id)
- Finally, each backend using the tranche_id should
- associate it with a tranche_name by calling:
-
-void LWLockRegisterTranche(int tranche_id, const char *tranche_name)
-
-
-
-
- A complete usage example of LWLockNewTrancheId,
- LWLockInitialize, and
- LWLockRegisterTranche can be found in
+ A complete usage example of LWLockNewTrancheId and
+ LWLockInitialize can be found in
contrib/pg_prewarm/autoprewarm.c in the
PostgreSQL source tree.
@@ -3608,14 +3822,34 @@ uint32 WaitEventExtensionNew(const char *wait_event_name)
An injection point with a given name is declared using
macro:
-INJECTION_POINT(name);
+INJECTION_POINT(name, arg);
There are a few injection points already declared at strategic points
within the server code. After adding a new injection point the code needs
to be compiled in order for that injection point to be available in the
binary. Add-ins written in C-language can declare injection points in
- their own code using the same macro.
+ their own code using the same macro. The injection point names should use
+ lower-case characters, with terms separated by
+ dashes. arg is an optional argument value given to the
+ callback at run-time.
+
+
+
+ Executing an injection point can require allocating a small amount of
+ memory, which can fail. If you need to have an injection point in a
+ critical section where dynamic allocations are not allowed, you can use
+ a two-step approach with the following macros:
+
+INJECTION_POINT_LOAD(name);
+INJECTION_POINT_CACHED(name, arg);
+
+
+ Before entering the critical section,
+ call INJECTION_POINT_LOAD. It checks the shared
+ memory state, and loads the callback into backend-private memory if it is
+ active. Inside the critical section, use
+ INJECTION_POINT_CACHED to execute the callback.
@@ -3641,9 +3875,15 @@ extern void InjectionPointAttach(const char *name,
InjectionPointCallback:
static void
-custom_injection_callback(const char *name, const void *private_data)
+custom_injection_callback(const char *name,
+ const void *private_data,
+ void *arg)
{
+ uint32 wait_event_info = WaitEventInjectionPointNew(name);
+
+ pgstat_report_wait_start(wait_event_info);
elog(NOTICE, "%s: executed custom callback", name);
+ pgstat_report_wait_end();
}
This callback prints a message to server error log with severity
@@ -3651,6 +3891,31 @@ custom_injection_callback(const char *name, const void *private_data)
logic.
+
+ An alternative way to define the action to take when an injection point
+ is reached is to add the testing code alongside the normal source
+ code. This can be useful if the action e.g. depends on local variables
+ that are not accessible to loaded modules. The
+ IS_INJECTION_POINT_ATTACHED macro can then be used
+ to check if an injection point is attached, for example:
+
+#ifdef USE_INJECTION_POINTS
+if (IS_INJECTION_POINT_ATTACHED("before-foobar"))
+{
+ /* change a local variable if injection point is attached */
+ local_var = 123;
+
+ /* also execute the callback */
+ INJECTION_POINT_CACHED("before-foobar", NULL);
+}
+#endif
+
+ Note that the callback attached to the injection point will not be
+ executed by the IS_INJECTION_POINT_ATTACHED
+ macro. If you want to execute the callback, you must also call
+ INJECTION_POINT_CACHED like in the above example.
+
+
Optionally, it is possible to detach an injection point by calling:
@@ -3668,6 +3933,12 @@ extern bool InjectionPointDetach(const char *name);
using InjectionPointDetach.
+
+ An example can be found in
+ src/test/modules/injection_points in the PostgreSQL
+ source tree.
+
+
Enabling injections points requires
with
@@ -3676,6 +3947,68 @@ extern bool InjectionPointDetach(const char *name);
+
+ Custom Cumulative Statistics
+
+
+ It is possible for add-ins written in C-language to use custom types
+ of cumulative statistics registered in the
+ Cumulative Statistics System.
+
+
+
+ First, define a PgStat_KindInfo that includes all
+ the information related to the custom type registered. For example:
+
+static const PgStat_KindInfo custom_stats = {
+ .name = "custom_stats",
+ .fixed_amount = false,
+ .shared_size = sizeof(PgStatShared_Custom),
+ .shared_data_off = offsetof(PgStatShared_Custom, stats),
+ .shared_data_len = sizeof(((PgStatShared_Custom *) 0)->stats),
+ .pending_size = sizeof(PgStat_StatCustomEntry),
+}
+
+
+ Then, each backend that needs to use this custom type needs to register
+ it with pgstat_register_kind and a unique ID used to
+ store the entries related to this type of statistics:
+
+extern PgStat_Kind pgstat_register_kind(PgStat_Kind kind,
+ const PgStat_KindInfo *kind_info);
+
+ While developing a new extension, use
+ PGSTAT_KIND_EXPERIMENTAL for
+ kind. When you are ready to release the extension
+ to users, reserve a kind ID at the
+
+ Custom Cumulative Statistics page.
+
+
+
+ The details of the API for PgStat_KindInfo can
+ be found in src/include/utils/pgstat_internal.h.
+
+
+
+ The type of statistics registered is associated with a name and a unique
+ ID shared across the server in shared memory. Each backend using a
+ custom type of statistics maintains a local cache storing the information
+ of each custom PgStat_KindInfo.
+
+
+
+ Place the extension module implementing the custom cumulative statistics
+ type in so that it will
+ be loaded early during PostgreSQL startup.
+
+
+
+ An example describing how to register and use custom statistics can be
+ found in src/test/modules/injection_points.
+
+
+
Using C++ for Extensibility
diff --git a/doc/src/sgml/xindex.sgml b/doc/src/sgml/xindex.sgml
index 22d8ad1aac43b..3d315df2f9803 100644
--- a/doc/src/sgml/xindex.sgml
+++ b/doc/src/sgml/xindex.sgml
@@ -461,6 +461,13 @@
5
+
+
+ Return the addresses of C-callable skip support function(s)
+ (optional)
+
+ 6
+
@@ -508,7 +515,7 @@
- GiST indexes have eleven support functions, six of which are optional,
+ GiST indexes have twelve support functions, seven of which are optional,
as shown in .
(For more information see .)
@@ -590,6 +597,12 @@
(optional)
11
+
+ translate_cmptype
+ translate compare types to strategy numbers
+ used by the operator class (optional)
+ 12
+
@@ -1056,7 +1069,8 @@ DEFAULT FOR TYPE int8 USING btree FAMILY integer_ops AS
FUNCTION 1 btint8cmp(int8, int8) ,
FUNCTION 2 btint8sortsupport(internal) ,
FUNCTION 3 in_range(int8, int8, int8, boolean, boolean) ,
- FUNCTION 4 btequalimage(oid) ;
+ FUNCTION 4 btequalimage(oid) ,
+ FUNCTION 6 btint8skipsupport(internal) ;
CREATE OPERATOR CLASS int4_ops
DEFAULT FOR TYPE int4 USING btree FAMILY integer_ops AS
@@ -1069,7 +1083,8 @@ DEFAULT FOR TYPE int4 USING btree FAMILY integer_ops AS
FUNCTION 1 btint4cmp(int4, int4) ,
FUNCTION 2 btint4sortsupport(internal) ,
FUNCTION 3 in_range(int4, int4, int4, boolean, boolean) ,
- FUNCTION 4 btequalimage(oid) ;
+ FUNCTION 4 btequalimage(oid) ,
+ FUNCTION 6 btint4skipsupport(internal) ;
CREATE OPERATOR CLASS int2_ops
DEFAULT FOR TYPE int2 USING btree FAMILY integer_ops AS
@@ -1082,7 +1097,8 @@ DEFAULT FOR TYPE int2 USING btree FAMILY integer_ops AS
FUNCTION 1 btint2cmp(int2, int2) ,
FUNCTION 2 btint2sortsupport(internal) ,
FUNCTION 3 in_range(int2, int2, int2, boolean, boolean) ,
- FUNCTION 4 btequalimage(oid) ;
+ FUNCTION 4 btequalimage(oid) ,
+ FUNCTION 6 btint2skipsupport(internal) ;
ALTER OPERATOR FAMILY integer_ops USING btree ADD
-- cross-type comparisons int8 vs int2
diff --git a/doc/src/sgml/xoper.sgml b/doc/src/sgml/xoper.sgml
index 954a90d77d0ed..853b07a9f1489 100644
--- a/doc/src/sgml/xoper.sgml
+++ b/doc/src/sgml/xoper.sgml
@@ -21,7 +21,7 @@
PostgreSQL supports prefix
- and infix operators. Operators can be
+ and binary (or infix) operators. Operators can be
overloaded;overloadingoperators
that is, the same operator name can be used for different operators
that have different numbers and types of operands. When a query is
diff --git a/meson.build b/meson.build
index f5ca5cfed49ef..ab8101d67b26d 100644
--- a/meson.build
+++ b/meson.build
@@ -1,4 +1,4 @@
-# Copyright (c) 2022-2024, PostgreSQL Global Development Group
+# Copyright (c) 2022-2025, PostgreSQL Global Development Group
# Entry point for building PostgreSQL with meson
#
@@ -8,13 +8,14 @@
project('postgresql',
['c'],
- version: '17beta1',
+ version: '19devel',
license: 'PostgreSQL',
- # We want < 0.56 for python 3.5 compatibility on old platforms. EPEL for
- # RHEL 7 has 0.55. < 0.54 would require replacing some uses of the fs
- # module, < 0.53 all uses of fs. So far there's no need to go to >=0.56.
- meson_version: '>=0.54',
+ # We want < 0.62 for python 3.6 compatibility on old platforms.
+ # RHEL 8 has 0.58. < 0.57 would require various additional
+ # backward-compatibility conditionals.
+ # Meson 0.57.0 and 0.57.1 are buggy, therefore >=0.57.2.
+ meson_version: '>=0.57.2',
default_options: [
'warning_level=1', #-Wall equivalent
'b_pch=false',
@@ -107,6 +108,7 @@ os_deps = []
backend_both_deps = []
backend_deps = []
libpq_deps = []
+libpq_oauth_deps = []
pg_sysroot = ''
@@ -201,7 +203,7 @@ if host_system == 'cygwin'
cppflags += '-D_GNU_SOURCE'
dlsuffix = '.dll'
mod_link_args_fmt = ['@0@']
- mod_link_with_name = 'lib@0@.exe.a'
+ mod_link_with_name = 'lib@0@.a'
mod_link_with_dir = 'libdir'
elif host_system == 'darwin'
@@ -261,22 +263,32 @@ elif host_system == 'openbsd'
elif host_system == 'sunos'
portname = 'solaris'
export_fmt = '-Wl,-M@0@'
- cppflags += '-D_POSIX_PTHREAD_SEMANTICS'
+ # We need these #defines to get POSIX-conforming versions
+ # of many interfaces (sigwait, getpwuid_r, shmdt, ...).
+ cppflags += [
+ '-D_POSIX_C_SOURCE=200112L',
+ '-D__EXTENSIONS__',
+ '-D_POSIX_PTHREAD_SEMANTICS',
+ ]
elif host_system == 'windows'
portname = 'win32'
exesuffix = '.exe'
dlsuffix = '.dll'
library_path_var = ''
+ if cc.get_id() != 'msvc'
+ # define before including for getting localtime_r() etc. on MinGW
+ cppflags += '-D_POSIX_C_SOURCE'
+ endif
export_file_format = 'win'
export_file_suffix = 'def'
if cc.get_id() == 'msvc'
export_fmt = '/DEF:@0@'
- mod_link_with_name = '@0@.exe.lib'
+ mod_link_with_name = '@0@.lib'
else
export_fmt = '@0@'
- mod_link_with_name = 'lib@0@.exe.a'
+ mod_link_with_name = 'lib@0@.a'
endif
mod_link_args_fmt = ['@0@']
mod_link_with_dir = 'libdir'
@@ -324,7 +336,7 @@ endif
# External programs
perl = find_program(get_option('PERL'), required: true, native: true)
python = find_program(get_option('PYTHON'), required: true, native: true)
-flex = find_program(get_option('FLEX'), native: true, version: '>= 2.5.35')
+flex = find_program(get_option('FLEX'), native: true)
bison = find_program(get_option('BISON'), native: true, version: '>= 2.3')
sed = find_program(get_option('SED'), 'sed', native: true, required: false)
prove = find_program(get_option('PROVE'), native: true, required: false)
@@ -534,6 +546,33 @@ dir_doc_extension = dir_doc / 'extension'
# used, they need to be added to test_c_args as well.
###############################################################
+# Do we need an option to enable C11?
+c11_test = '''
+#if !defined __STDC_VERSION__ || __STDC_VERSION__ < 201112L
+# error "Compiler does not advertise C11 conformance"
+#endif
+'''
+
+if not cc.compiles(c11_test, name: 'C11')
+ c11_ok = false
+ if cc.get_id() == 'msvc'
+ c11_test_args = ['/std:c11']
+ else
+ c11_test_args = ['-std=gnu11', '-std=c11']
+ endif
+ foreach arg : c11_test_args
+ if cc.compiles(c11_test, name: 'C11 with @0@'.format(arg), args: [arg])
+ c11_ok = true
+ cflags += arg
+ break
+ endif
+ endforeach
+ if not c11_ok
+ error('C compiler does not support C11')
+ endif
+endif
+
+
postgres_inc = [include_directories(postgres_inc_d)]
test_lib_d = postgres_lib_d
test_c_args = cppflags + cflags
@@ -547,7 +586,8 @@ test_c_args = cppflags + cflags
bsd_authopt = get_option('bsd_auth')
bsd_auth = not_found_dep
if cc.check_header('bsd_auth.h', required: bsd_authopt,
- args: test_c_args, include_directories: postgres_inc)
+ args: test_c_args, prefix: '#include ',
+ include_directories: postgres_inc)
cdata.set('USE_BSD_AUTH', 1)
bsd_auth = declare_dependency()
endif
@@ -614,31 +654,66 @@ gssapiopt = get_option('gssapi')
krb_srvtab = ''
have_gssapi = false
if not gssapiopt.disabled()
- gssapi = dependency('krb5-gssapi', required: gssapiopt)
+ gssapi = dependency('krb5-gssapi', required: false)
have_gssapi = gssapi.found()
+ if have_gssapi
+ gssapi_deps = [gssapi]
+ elif not have_gssapi
+ # Hardcoded lookup for gssapi. This is necessary as gssapi on windows does
+ # not install neither pkg-config nor cmake dependency information.
+ if host_system == 'windows'
+ is_64 = cc.sizeof('void *', args: test_c_args) == 8
+ if is_64
+ gssapi_search_libs = ['gssapi64', 'krb5_64', 'comerr64']
+ else
+ gssapi_search_libs = ['gssapi32', 'krb5_32', 'comerr32']
+ endif
+ else
+ gssapi_search_libs = ['gssapi_krb5']
+ endif
+
+ gssapi_deps = []
+ foreach libname : gssapi_search_libs
+ lib = cc.find_library(libname, dirs: test_lib_d, required: false)
+ if lib.found()
+ have_gssapi = true
+ gssapi_deps += lib
+ endif
+ endforeach
+
+ if have_gssapi
+ # Meson before 0.57.0 did not support using check_header() etc with
+ # declare_dependency(). Thus the tests below use the library looked up
+ # above. Once we require a newer meson version, we can simplify.
+ gssapi = declare_dependency(dependencies: gssapi_deps)
+ endif
+ endif
+
if not have_gssapi
- elif cc.check_header('gssapi/gssapi.h', dependencies: gssapi, required: false,
+ elif cc.check_header('gssapi/gssapi.h', dependencies: gssapi_deps, required: false,
args: test_c_args, include_directories: postgres_inc)
cdata.set('HAVE_GSSAPI_GSSAPI_H', 1)
- elif cc.check_header('gssapi.h', args: test_c_args, dependencies: gssapi, required: gssapiopt)
+ elif cc.check_header('gssapi.h', dependencies: gssapi_deps, required: gssapiopt,
+ args: test_c_args, include_directories: postgres_inc)
cdata.set('HAVE_GSSAPI_H', 1)
else
have_gssapi = false
endif
if not have_gssapi
- elif cc.check_header('gssapi/gssapi_ext.h', dependencies: gssapi, required: false,
+ elif cc.check_header('gssapi/gssapi_ext.h', dependencies: gssapi_deps, required: false,
args: test_c_args, include_directories: postgres_inc)
cdata.set('HAVE_GSSAPI_GSSAPI_EXT_H', 1)
- elif cc.check_header('gssapi_ext.h', args: test_c_args, dependencies: gssapi, required: gssapiopt)
+ elif cc.check_header('gssapi_ext.h', dependencies: gssapi_deps, required: gssapiopt,
+ args: test_c_args, include_directories: postgres_inc)
cdata.set('HAVE_GSSAPI_EXT_H', 1)
else
have_gssapi = false
endif
if not have_gssapi
- elif cc.has_function('gss_store_cred_into', dependencies: gssapi,
+ elif cc.has_function('gss_store_cred_into', dependencies: gssapi_deps,
args: test_c_args, include_directories: postgres_inc)
cdata.set('ENABLE_GSS', 1)
@@ -649,6 +724,11 @@ if not gssapiopt.disabled()
else
have_gssapi = false
endif
+
+ if not have_gssapi and gssapiopt.enabled()
+ error('dependency lookup for gssapi failed')
+ endif
+
endif
if not have_gssapi
gssapi = not_found_dep
@@ -748,7 +828,7 @@ endif
llvmopt = get_option('llvm')
llvm = not_found_dep
if add_languages('cpp', required: llvmopt, native: false)
- llvm = dependency('llvm', version: '>=10', method: 'config-tool', required: llvmopt)
+ llvm = dependency('llvm', version: '>=14', method: 'config-tool', required: llvmopt)
if llvm.found()
@@ -759,7 +839,10 @@ if add_languages('cpp', required: llvmopt, native: false)
llvm_binpath = llvm.get_variable(configtool: 'bindir')
ccache = find_program('ccache', native: true, required: false)
- clang = find_program(llvm_binpath / 'clang', required: true)
+
+ # Some distros put LLVM and clang in different paths, so fallback to
+ # find via PATH, too.
+ clang = find_program(llvm_binpath / 'clang', 'clang', required: true)
endif
elif llvmopt.auto()
message('llvm requires a C++ compiler')
@@ -773,11 +856,25 @@ endif
icuopt = get_option('icu')
if not icuopt.disabled()
- icu = dependency('icu-uc', required: icuopt)
- icu_i18n = dependency('icu-i18n', required: icuopt)
+ icu = dependency('icu-uc', required: false)
+ if icu.found()
+ icu_i18n = dependency('icu-i18n', required: true)
+ endif
+
+ # Unfortunately the dependency is named differently with cmake
+ if not icu.found() # combine with above once meson 0.60.0 is required
+ icu = dependency('ICU', required: icuopt,
+ components: ['uc'], modules: ['ICU::uc'], method: 'cmake')
+ if icu.found()
+ icu_i18n = dependency('ICU', required: true,
+ components: ['i18n'], modules: ['ICU::i18n'])
+ endif
+ endif
if icu.found()
cdata.set('USE_ICU', 1)
+ else
+ icu_i18n = not_found_dep
endif
else
@@ -787,13 +884,162 @@ endif
+###############################################################
+# Library: libcurl
+###############################################################
+
+libcurlopt = get_option('libcurl')
+oauth_flow_supported = false
+
+if not libcurlopt.disabled()
+ # Check for libcurl 7.61.0 or higher (corresponding to RHEL8 and the ability
+ # to explicitly set TLS 1.3 ciphersuites).
+ libcurl = dependency('libcurl', version: '>= 7.61.0', required: libcurlopt)
+ if libcurl.found()
+ # Check to see whether the current platform supports thread-safe Curl
+ # initialization.
+ libcurl_threadsafe_init = false
+
+ if not meson.is_cross_build()
+ r = cc.run('''
+ #include
+
+ int main(void)
+ {
+ curl_version_info_data *info;
+
+ if (curl_global_init(CURL_GLOBAL_ALL))
+ return -1;
+
+ info = curl_version_info(CURLVERSION_NOW);
+ #ifdef CURL_VERSION_THREADSAFE
+ if (info->features & CURL_VERSION_THREADSAFE)
+ return 0;
+ #endif
+
+ return 1;
+ }''',
+ name: 'test for curl_global_init thread safety',
+ dependencies: libcurl,
+ )
+
+ assert(r.compiled())
+ if r.returncode() == 0
+ libcurl_threadsafe_init = true
+ message('curl_global_init is thread-safe')
+ elif r.returncode() == 1
+ message('curl_global_init is not thread-safe')
+ else
+ message('curl_global_init failed; assuming not thread-safe')
+ endif
+ endif
+
+ if libcurl_threadsafe_init
+ cdata.set('HAVE_THREADSAFE_CURL_GLOBAL_INIT', 1)
+ endif
+
+ # Fail if a thread-friendly DNS resolver isn't built.
+ if not meson.is_cross_build()
+ r = cc.run('''
+ #include
+
+ int main(void)
+ {
+ curl_version_info_data *info;
+
+ if (curl_global_init(CURL_GLOBAL_ALL))
+ return -1;
+
+ info = curl_version_info(CURLVERSION_NOW);
+ return (info->features & CURL_VERSION_ASYNCHDNS) ? 0 : 1;
+ }''',
+ name: 'test for curl support for asynchronous DNS',
+ dependencies: libcurl,
+ )
+
+ assert(r.compiled())
+ if r.returncode() != 0
+ error('''
+*** The installed version of libcurl does not support asynchronous DNS
+*** lookups. Rebuild libcurl with the AsynchDNS feature enabled in order
+*** to use it with libpq.''')
+ endif
+ endif
+ endif
+
+ # Check that the current platform supports our builtin flow. This requires
+ # libcurl and one of either epoll or kqueue.
+ oauth_flow_supported = (
+ libcurl.found()
+ and (cc.has_header('sys/event.h',
+ args: test_c_args, include_directories: postgres_inc)
+ or cc.has_header('sys/epoll.h',
+ args: test_c_args, include_directories: postgres_inc))
+ )
+
+ if oauth_flow_supported
+ cdata.set('USE_LIBCURL', 1)
+ elif libcurlopt.enabled()
+ error('client-side OAuth is not supported on this platform')
+ endif
+
+else
+ libcurl = not_found_dep
+endif
+
+
+###############################################################
+# Library: libnuma
+###############################################################
+
+libnumaopt = get_option('libnuma')
+if not libnumaopt.disabled()
+ # via pkg-config
+ libnuma = dependency('numa', required: false)
+ if not libnuma.found()
+ libnuma = cc.find_library('numa', required: libnumaopt)
+ endif
+ if not cc.has_header('numa.h', dependencies: libnuma, required: libnumaopt)
+ libnuma = not_found_dep
+ endif
+ if libnuma.found()
+ cdata.set('USE_LIBNUMA', 1)
+ endif
+else
+ libnuma = not_found_dep
+endif
+
+
+###############################################################
+# Library: liburing
+###############################################################
+
+liburingopt = get_option('liburing')
+liburing = dependency('liburing', required: liburingopt)
+if liburing.found()
+ cdata.set('USE_LIBURING', 1)
+
+ if cc.has_function('io_uring_queue_init_mem',
+ dependencies: liburing, args: test_c_args)
+ cdata.set('HAVE_LIBURING_QUEUE_INIT_MEM', 1)
+ endif
+
+endif
+
+
+
###############################################################
# Library: libxml
###############################################################
libxmlopt = get_option('libxml')
if not libxmlopt.disabled()
- libxml = dependency('libxml-2.0', required: libxmlopt, version: '>= 2.6.23')
+ libxml = dependency('libxml-2.0', required: false, version: '>= 2.6.23')
+ # Unfortunately the dependency is named differently with cmake
+ if not libxml.found() # combine with above once meson 0.60.0 is required
+ libxml = dependency('LibXml2', required: libxmlopt, version: '>= 2.6.23',
+ method: 'cmake')
+ endif
if libxml.found()
cdata.set('USE_LIBXML', 1)
@@ -810,7 +1056,11 @@ endif
libxsltopt = get_option('libxslt')
if not libxsltopt.disabled()
- libxslt = dependency('libxslt', required: libxsltopt)
+ libxslt = dependency('libxslt', required: false)
+ # Unfortunately the dependency is named differently with cmake
+ if not libxslt.found() # combine with above once meson 0.60.0 is required
+ libxslt = dependency('LibXslt', required: libxsltopt, method: 'cmake')
+ endif
if libxslt.found()
cdata.set('USE_LIBXSLT', 1)
@@ -827,7 +1077,13 @@ endif
lz4opt = get_option('lz4')
if not lz4opt.disabled()
- lz4 = dependency('liblz4', required: lz4opt)
+ lz4 = dependency('liblz4', required: false)
+ # Unfortunately the dependency is named differently with cmake
+ if not lz4.found() # combine with above once meson 0.60.0 is required
+ lz4 = dependency('lz4', required: lz4opt,
+ method: 'cmake', modules: ['LZ4::lz4_shared'],
+ )
+ endif
if lz4.found()
cdata.set('USE_LZ4', 1)
@@ -914,6 +1170,7 @@ endif
perlopt = get_option('plperl')
perl_dep = not_found_dep
+perlversion = ''
if not perlopt.disabled()
perl_may_work = true
@@ -931,7 +1188,7 @@ if not perlopt.disabled()
# Then inquire perl about its configuration
if perl_may_work
perl_conf_cmd = [perl, '-MConfig', '-e', 'print $Config{$ARGV[0]}']
- perlversion = run_command(perl_conf_cmd, 'api_versionstring', check: true).stdout()
+ perlversion = run_command(perl_conf_cmd, 'version', check: true).stdout()
archlibexp = run_command(perl_conf_cmd, 'archlibexp', check: true).stdout()
privlibexp = run_command(perl_conf_cmd, 'privlibexp', check: true).stdout()
useshrplib = run_command(perl_conf_cmd, 'useshrplib', check: true).stdout()
@@ -982,7 +1239,10 @@ if not perlopt.disabled()
if cc.get_id() == 'msvc'
# prevent binary mismatch between MSVC built plperl and Strawberry or
# msys ucrt perl libraries
- perl_ccflags += ['-DNO_THREAD_SAFE_LOCALE']
+ perl_v = run_command(perl, '-V', check: false).stdout()
+ if not perl_v.contains('USE_THREAD_SAFE_LOCALE')
+ perl_ccflags += ['-DNO_THREAD_SAFE_LOCALE']
+ endif
endif
endif
@@ -993,20 +1253,19 @@ if not perlopt.disabled()
# Config's ccdlflags and ldflags. (Those are the choices of those who
# built the Perl installation, which are not necessarily appropriate
# for building PostgreSQL.)
- ldopts = run_command(perl, '-MExtUtils::Embed', '-e', 'ldopts', check: true).stdout().strip()
- undesired = run_command(perl_conf_cmd, 'ccdlflags', check: true).stdout().split()
- undesired += run_command(perl_conf_cmd, 'ldflags', check: true).stdout().split()
-
- perl_ldopts = []
- foreach ldopt : ldopts.split(' ')
- if ldopt == '' or ldopt in undesired
- continue
- endif
-
- perl_ldopts += ldopt.strip('"')
- endforeach
+ perl_ldopts = run_command(perl, '-e', '''
+use ExtUtils::Embed;
+use Text::ParseWords;
+# tell perl to suppress including these in ldopts
+*ExtUtils::Embed::_ldflags =*ExtUtils::Embed::_ccdlflags = sub { return ""; };
+# adding an argument to ldopts makes it return a value instead of printing
+# print one of these per line so splitting will preserve spaces in file names.
+# shellwords eats backslashes, so we need to escape them.
+(my $opts = ldopts(undef)) =~ s!\\!\\\\!g;
+print "$_\n" foreach shellwords($opts);
+''',
+ check: true).stdout().strip().split('\n')
- message('LDFLAGS recommended by perl: "@0@"'.format(ldopts))
message('LDFLAGS for embedding perl: "@0@"'.format(' '.join(perl_ldopts)))
perl_dep_int = declare_dependency(
@@ -1059,11 +1318,11 @@ pyopt = get_option('plpython')
python3_dep = not_found_dep
if not pyopt.disabled()
pm = import('python')
- python3_inst = pm.find_installation(python.path(), required: pyopt)
+ python3_inst = pm.find_installation(python.full_path(), required: pyopt)
if python3_inst.found()
python3_dep = python3_inst.dependency(embed: true, required: pyopt)
# Remove this check after we depend on Meson >= 1.1.0
- if not cc.check_header('Python.h', dependencies: python3_dep, required: pyopt)
+ if not cc.check_header('Python.h', dependencies: python3_dep, required: pyopt, include_directories: postgres_inc)
python3_dep = not_found_dep
endif
endif
@@ -1077,15 +1336,26 @@ endif
if not get_option('readline').disabled()
libedit_preferred = get_option('libedit_preferred')
- # Set the order of readline dependencies
- check_readline_deps = libedit_preferred ? \
- ['libedit', 'readline'] : ['readline', 'libedit']
+ # Set the order of readline dependencies.
+ # cc.find_library breaks and throws on the first dependency which
+ # is marked as required=true and can't be found. Thus, we only mark
+ # the last dependency to look up as required, to not throw too early.
+ check_readline_deps = [
+ {
+ 'name': libedit_preferred ? 'libedit' : 'readline',
+ 'required': false
+ },
+ {
+ 'name': libedit_preferred ? 'readline' : 'libedit',
+ 'required': get_option('readline')
+ }
+ ]
foreach readline_dep : check_readline_deps
- readline = dependency(readline_dep, required: false)
+ readline = dependency(readline_dep['name'], required: false)
if not readline.found()
- readline = cc.find_library(readline_dep,
- required: get_option('readline'),
+ readline = cc.find_library(readline_dep['name'],
+ required: readline_dep['required'],
dirs: test_lib_d)
endif
if readline.found()
@@ -1272,27 +1542,16 @@ if sslopt in ['auto', 'openssl']
['CRYPTO_new_ex_data', {'required': true}],
['SSL_new', {'required': true}],
+ # Functions introduced in OpenSSL 1.1.1.
+ ['SSL_CTX_set_ciphersuites', {'required': true}],
+
# Function introduced in OpenSSL 1.0.2, not in LibreSSL.
['SSL_CTX_set_cert_cb'],
- # Functions introduced in OpenSSL 1.1.0. We used to check for
- # OPENSSL_VERSION_NUMBER, but that didn't work with 1.1.0, because LibreSSL
- # defines OPENSSL_VERSION_NUMBER to claim version 2.0.0, even though it
- # doesn't have these OpenSSL 1.1.0 functions. So check for individual
- # functions.
- ['OPENSSL_init_ssl'],
- ['BIO_meth_new'],
- ['ASN1_STRING_get0_data'],
- ['HMAC_CTX_new'],
- ['HMAC_CTX_free'],
-
- # OpenSSL versions before 1.1.0 required setting callback functions, for
- # thread-safety. In 1.1.0, it's no longer required, and CRYPTO_lock()
- # function was removed.
- ['CRYPTO_lock'],
-
- # Function introduced in OpenSSL 1.1.1
+ # Function introduced in OpenSSL 1.1.1, not in LibreSSL.
['X509_get_signature_info'],
+ ['SSL_CTX_set_num_tickets'],
+ ['SSL_CTX_set_keylog_callback'],
]
are_openssl_funcs_complete = true
@@ -1314,7 +1573,7 @@ if sslopt in ['auto', 'openssl']
if are_openssl_funcs_complete
cdata.set('USE_OPENSSL', 1,
description: 'Define to 1 to build with OpenSSL support. (-Dssl=openssl)')
- cdata.set('OPENSSL_API_COMPAT', '0x10002000L',
+ cdata.set('OPENSSL_API_COMPAT', '0x10101000L',
description: 'Define to the OpenSSL API version in use. This avoids deprecation warnings from newer OpenSSL versions.')
ssl_library = 'openssl'
else
@@ -1346,14 +1605,34 @@ if uuidopt != 'none'
uuidfunc = 'uuid_to_string'
uuidheader = 'uuid.h'
elif uuidopt == 'ossp'
- uuid = dependency('ossp-uuid', required: true)
+ # In upstream, the package and library is called just 'uuid', but many
+ # distros change it to 'ossp-uuid'.
+ uuid = dependency('ossp-uuid', 'uuid', required: false)
uuidfunc = 'uuid_export'
uuidheader = 'uuid.h'
+
+ # Hardcoded lookup for ossp-uuid. This is necessary as ossp-uuid on
+ # windows installs neither a pkg-config nor a cmake dependency
+ # information. Nor is there another supported uuid implementation
+ # available on windows.
+ if not uuid.found()
+ uuid = cc.find_library('ossp-uuid',
+ required: false, dirs: test_lib_d,
+ has_headers: uuidheader, header_include_directories: postgres_inc)
+ endif
+ if not uuid.found()
+ uuid = cc.find_library('uuid',
+ required: true, dirs: test_lib_d,
+ has_headers: uuidheader, header_include_directories: postgres_inc)
+ endif
else
error('unknown uuid build option value: @0@'.format(uuidopt))
endif
- if not cc.has_header_symbol(uuidheader, uuidfunc, args: test_c_args, dependencies: uuid)
+ if not cc.has_header_symbol(uuidheader, uuidfunc,
+ args: test_c_args,
+ include_directories: postgres_inc,
+ dependencies: uuid)
error('uuid library @0@ missing required function @1@'.format(uuidopt, uuidfunc))
endif
cdata.set('HAVE_@0@'.format(uuidheader.underscorify().to_upper()), 1)
@@ -1426,7 +1705,12 @@ endif
zstdopt = get_option('zstd')
if not zstdopt.disabled()
- zstd = dependency('libzstd', required: zstdopt, version: '>=1.4.0')
+ zstd = dependency('libzstd', required: false, version: '>=1.4.0')
+ # Unfortunately the dependency is named differently with cmake
+ if not zstd.found() # combine with above once meson 0.60.0 is required
+ zstd = dependency('zstd', required: zstdopt, version: '>=1.4.0',
+ method: 'cmake', modules: ['zstd::libzstd_shared'])
+ endif
if zstd.found()
cdata.set('USE_ZSTD', 1)
@@ -1443,64 +1727,6 @@ endif
# Compiler tests
###############################################################
-# Do we need -std=c99 to compile C99 code? We don't want to add -std=c99
-# unnecessarily, because we optionally rely on newer features.
-c99_test = '''
-#include
-#include
-#include
-#include
-
-struct named_init_test {
- int a;
- int b;
-};
-
-extern void structfunc(struct named_init_test);
-
-int main(int argc, char **argv)
-{
- struct named_init_test nit = {
- .a = 3,
- .b = 5,
- };
-
- for (int loop_var = 0; loop_var < 3; loop_var++)
- {
- nit.a += nit.b;
- }
-
- structfunc((struct named_init_test){1, 0});
-
- return nit.a != 0;
-}
-'''
-
-if not cc.compiles(c99_test, name: 'c99', args: test_c_args)
- if cc.compiles(c99_test, name: 'c99 with -std=c99',
- args: test_c_args + ['-std=c99'])
- test_c_args += '-std=c99'
- cflags += '-std=c99'
- else
- error('C compiler does not support C99')
- endif
-endif
-
-sizeof_long = cc.sizeof('long', args: test_c_args)
-cdata.set('SIZEOF_LONG', sizeof_long)
-if sizeof_long == 8
- cdata.set('HAVE_LONG_INT_64', 1)
- pg_int64_type = 'long int'
- cdata.set_quoted('INT64_MODIFIER', 'l')
-elif sizeof_long == 4 and cc.sizeof('long long', args: test_c_args) == 8
- cdata.set('HAVE_LONG_LONG_INT_64', 1)
- pg_int64_type = 'long long int'
- cdata.set_quoted('INT64_MODIFIER', 'll')
-else
- error('do not know how to get a 64bit int')
-endif
-cdata.set('PG_INT64_TYPE', pg_int64_type)
-
if host_machine.endian() == 'big'
cdata.set('WORDS_BIGENDIAN', 1)
endif
@@ -1524,16 +1750,18 @@ endforeach
# of MAXIMUM_ALIGNOF to avoid that, but we no longer support any platforms
# where TYPALIGN_DOUBLE != MAXIMUM_ALIGNOF.
#
-# We assume without checking that int64's alignment is at least as strong
+# We assume without checking that int64_t's alignment is at least as strong
# as long, char, short, or int. Note that we intentionally do not consider
# any types wider than 64 bits, as allowing MAXIMUM_ALIGNOF to exceed 8
# would be too much of a penalty for disk and memory space.
alignof_double = cdata.get('ALIGNOF_DOUBLE')
-if cc.alignment(pg_int64_type, args: test_c_args) > alignof_double
- error('alignment of int64 is greater than the alignment of double')
+if cc.alignment('int64_t', args: test_c_args, prefix: '#include ') > alignof_double
+ error('alignment of int64_t is greater than the alignment of double')
endif
cdata.set('MAXIMUM_ALIGNOF', alignof_double)
+cdata.set('SIZEOF_LONG', cc.sizeof('long', args: test_c_args))
+cdata.set('SIZEOF_LONG_LONG', cc.sizeof('long long', args: test_c_args))
cdata.set('SIZEOF_VOID_P', cc.sizeof('void *', args: test_c_args))
cdata.set('SIZEOF_SIZE_T', cc.sizeof('size_t', args: test_c_args))
@@ -1632,6 +1860,7 @@ if cc.compiles('''
my_label:
return 1;
}''',
+ name: 'computed goto',
args: test_c_args)
cdata.set('HAVE_COMPUTED_GOTO', 1)
endif
@@ -1648,21 +1877,12 @@ if cc.compiles('''
({ _Static_assert(1, "foo"); });
}
''',
+ name: '_Static_assert',
args: test_c_args)
cdata.set('HAVE__STATIC_ASSERT', 1)
endif
-# We use if we have it and it declares type bool as having
-# size 1. Otherwise, c.h will fall back to declaring bool as unsigned char.
-if cc.has_type('_Bool', args: test_c_args) \
- and cc.has_type('bool', prefix: '#include ', args: test_c_args) \
- and cc.sizeof('bool', prefix: '#include ', args: test_c_args) == 1
- cdata.set('HAVE__BOOL', 1)
- cdata.set('PG_USE_STDBOOL', 1)
-endif
-
-
# Need to check a call with %m because netbsd supports gnu_printf but emits a
# warning for each use of %m.
printf_attributes = ['gnu_printf', '__syslog__', 'printf']
@@ -1742,24 +1962,21 @@ endif
# compile, and store the results in global variables so the compiler doesn't
# optimize away the call.
if cc.links('''
- INT64 a = 1;
- INT64 b = 1;
- INT64 result;
+ #include
+ int64_t a = 1;
+ int64_t b = 1;
+ int64_t result;
int main(void)
{
return __builtin_mul_overflow(a, b, &result);
}''',
name: '__builtin_mul_overflow',
- args: test_c_args + ['-DINT64=@0@'.format(cdata.get('PG_INT64_TYPE'))],
- )
+ args: test_c_args)
cdata.set('HAVE__BUILTIN_OP_OVERFLOW', 1)
endif
-
-# XXX: The configure.ac check for __cpuid() is broken, we don't copy that
-# here. To prevent problems due to two detection methods working, stop
-# checking after one.
+# Check for __get_cpuid() and __cpuid().
if cc.links('''
#include
int main(int arg, char **argv)
@@ -1877,6 +2094,16 @@ if cc.has_argument('-Wdeclaration-after-statement')
cflags_no_decl_after_statement += '-Wno-declaration-after-statement'
endif
+# Some code is not clean for -Wmissing-variable-declarations, so we
+# make the "no" option available. Also, while clang supports this
+# option for C++, gcc does not, so for consistency, leave it off for
+# C++.
+cflags_no_missing_var_decls = []
+if cc.has_argument('-Wmissing-variable-declarations')
+ cflags_warn += '-Wmissing-variable-declarations'
+ cflags_no_missing_var_decls += '-Wno-missing-variable-declarations'
+endif
+
# The following tests want to suppress various unhelpful warnings by adding
# -Wno-foo switches. But gcc won't complain about unrecognized -Wno-foo
@@ -1943,106 +2170,121 @@ if cc.get_id() == 'msvc'
endif
+# Compute flags that are built into Meson. We need these to
+# substitute into Makefile.global and for pg_config. We only compute
+# the flags for Unix-style compilers, since that's the only style that
+# would use Makefile.global or pg_config.
+
+# We don't use get_option('warning_level') here, because the other
+# warning levels are not useful with PostgreSQL source code.
+common_builtin_flags = ['-Wall']
+
+if get_option('debug')
+ common_builtin_flags += ['-g']
+endif
+
+optimization = get_option('optimization')
+if optimization == '0'
+ common_builtin_flags += ['-O0']
+elif optimization == '1'
+ common_builtin_flags += ['-O1']
+elif optimization == '2'
+ common_builtin_flags += ['-O2']
+elif optimization == '3'
+ common_builtin_flags += ['-O3']
+elif optimization == 's'
+ common_builtin_flags += ['-Os']
+endif
+
+cflags_builtin = cc.get_supported_arguments(common_builtin_flags)
+if llvm.found()
+ cxxflags_builtin = cpp.get_supported_arguments(common_builtin_flags)
+endif
+
+
###############################################################
# Atomics
###############################################################
-if not get_option('spinlocks')
- warning('Not using spinlocks will cause poor performance')
-else
- cdata.set('HAVE_SPINLOCKS', 1)
-endif
-
-if not get_option('atomics')
- warning('Not using atomics will cause poor performance')
-else
- # XXX: perhaps we should require some atomics support in this case these
- # days?
- cdata.set('HAVE_ATOMICS', 1)
-
- atomic_checks = [
- {'name': 'HAVE_GCC__SYNC_CHAR_TAS',
- 'desc': '__sync_lock_test_and_set(char)',
- 'test': '''
+atomic_checks = [
+ {'name': 'HAVE_GCC__SYNC_CHAR_TAS',
+ 'desc': '__sync_lock_test_and_set(char)',
+ 'test': '''
char lock = 0;
__sync_lock_test_and_set(&lock, 1);
__sync_lock_release(&lock);'''},
- {'name': 'HAVE_GCC__SYNC_INT32_TAS',
- 'desc': '__sync_lock_test_and_set(int32)',
- 'test': '''
+ {'name': 'HAVE_GCC__SYNC_INT32_TAS',
+ 'desc': '__sync_lock_test_and_set(int32)',
+ 'test': '''
int lock = 0;
__sync_lock_test_and_set(&lock, 1);
__sync_lock_release(&lock);'''},
- {'name': 'HAVE_GCC__SYNC_INT32_CAS',
- 'desc': '__sync_val_compare_and_swap(int32)',
- 'test': '''
+ {'name': 'HAVE_GCC__SYNC_INT32_CAS',
+ 'desc': '__sync_val_compare_and_swap(int32)',
+ 'test': '''
int val = 0;
__sync_val_compare_and_swap(&val, 0, 37);'''},
- {'name': 'HAVE_GCC__SYNC_INT64_CAS',
- 'desc': '__sync_val_compare_and_swap(int64)',
- 'test': '''
-INT64 val = 0;
+ {'name': 'HAVE_GCC__SYNC_INT64_CAS',
+ 'desc': '__sync_val_compare_and_swap(int64)',
+ 'test': '''
+int64_t val = 0;
__sync_val_compare_and_swap(&val, 0, 37);'''},
- {'name': 'HAVE_GCC__ATOMIC_INT32_CAS',
- 'desc': ' __atomic_compare_exchange_n(int32)',
- 'test': '''
+ {'name': 'HAVE_GCC__ATOMIC_INT32_CAS',
+ 'desc': ' __atomic_compare_exchange_n(int32)',
+ 'test': '''
int val = 0;
int expect = 0;
__atomic_compare_exchange_n(&val, &expect, 37, 0, __ATOMIC_SEQ_CST, __ATOMIC_RELAXED);'''},
- {'name': 'HAVE_GCC__ATOMIC_INT64_CAS',
- 'desc': ' __atomic_compare_exchange_n(int64)',
- 'test': '''
-INT64 val = 0;
-INT64 expect = 0;
+ {'name': 'HAVE_GCC__ATOMIC_INT64_CAS',
+ 'desc': ' __atomic_compare_exchange_n(int64)',
+ 'test': '''
+int64_t val = 0;
+int64_t expect = 0;
__atomic_compare_exchange_n(&val, &expect, 37, 0, __ATOMIC_SEQ_CST, __ATOMIC_RELAXED);'''},
- ]
+]
- foreach check : atomic_checks
- test = '''
+foreach check : atomic_checks
+ test = '''
+#include
int main(void)
{
@0@
}'''.format(check['test'])
- cdata.set(check['name'],
- cc.links(test,
- name: check['desc'],
- args: test_c_args + ['-DINT64=@0@'.format(cdata.get('PG_INT64_TYPE'))]) ? 1 : false
- )
- endforeach
-
-endif
+ cdata.set(check['name'],
+ cc.links(test,
+ name: check['desc'],
+ args: test_c_args) ? 1 : false
+ )
+endforeach
###############################################################
# Check for the availability of XSAVE intrinsics.
###############################################################
-cflags_xsave = []
if host_cpu == 'x86' or host_cpu == 'x86_64'
prog = '''
#include
+#if defined(__has_attribute) && __has_attribute (target)
+__attribute__((target("xsave")))
+#endif
int main(void)
{
return _xgetbv(0) & 0xe0;
}
'''
- if cc.links(prog, name: 'XSAVE intrinsics without -mxsave',
- args: test_c_args)
- cdata.set('HAVE_XSAVE_INTRINSICS', 1)
- elif cc.links(prog, name: 'XSAVE intrinsics with -mxsave',
- args: test_c_args + ['-mxsave'])
+ if cc.links(prog, name: 'XSAVE intrinsics', args: test_c_args)
cdata.set('HAVE_XSAVE_INTRINSICS', 1)
- cflags_xsave += '-mxsave'
endif
endif
@@ -2052,19 +2294,22 @@ endif
# Check for the availability of AVX-512 popcount intrinsics.
###############################################################
-cflags_popcnt = []
if host_cpu == 'x86_64'
prog = '''
#include
+#include
+char buf[sizeof(__m512i)];
+#if defined(__has_attribute) && __has_attribute (target)
+__attribute__((target("avx512vpopcntdq,avx512bw")))
+#endif
int main(void)
{
- const char buf[sizeof(__m512i)];
- INT64 popcnt = 0;
+ int64_t popcnt = 0;
__m512i accum = _mm512_setzero_si512();
- const __m512i val = _mm512_maskz_loadu_epi8((__mmask64) 0xf0f0f0f0f0f0f0f0, (const __m512i *) buf);
- const __m512i cnt = _mm512_popcnt_epi64(val);
+ __m512i val = _mm512_maskz_loadu_epi8((__mmask64) 0xf0f0f0f0f0f0f0f0, (const __m512i *) buf);
+ __m512i cnt = _mm512_popcnt_epi64(val);
accum = _mm512_add_epi64(accum, cnt);
popcnt = _mm512_reduce_add_epi64(accum);
/* return computed value, to prevent the above being optimized away */
@@ -2072,13 +2317,56 @@ int main(void)
}
'''
- if cc.links(prog, name: 'AVX-512 popcount without -mavx512vpopcntdq -mavx512bw',
- args: test_c_args + ['-DINT64=@0@'.format(cdata.get('PG_INT64_TYPE'))])
+ if cc.links(prog, name: 'AVX-512 popcount', args: test_c_args)
cdata.set('USE_AVX512_POPCNT_WITH_RUNTIME_CHECK', 1)
- elif cc.links(prog, name: 'AVX-512 popcount with -mavx512vpopcntdq -mavx512bw',
- args: test_c_args + ['-DINT64=@0@'.format(cdata.get('PG_INT64_TYPE'))] + ['-mavx512vpopcntdq'] + ['-mavx512bw'])
- cdata.set('USE_AVX512_POPCNT_WITH_RUNTIME_CHECK', 1)
- cflags_popcnt += ['-mavx512vpopcntdq'] + ['-mavx512bw']
+ endif
+
+endif
+
+
+###############################################################
+# Check for the availability of SVE popcount intrinsics.
+###############################################################
+
+if host_cpu == 'aarch64'
+
+ prog = '''
+#include
+
+char buf[128];
+
+#if defined(__has_attribute) && __has_attribute (target)
+__attribute__((target("arch=armv8-a+sve")))
+#endif
+int main(void)
+{
+ svbool_t pred = svptrue_b64();
+ svuint8_t vec8;
+ svuint64_t accum1 = svdup_u64(0),
+ accum2 = svdup_u64(0),
+ vec64;
+ char *p = buf;
+ uint64_t popcnt,
+ mask = 0x5555555555555555;
+
+ vec64 = svand_n_u64_x(pred, svld1_u64(pred, (const uint64_t *) p), mask);
+ accum1 = svadd_u64_x(pred, accum1, svcnt_u64_x(pred, vec64));
+ p += svcntb();
+
+ vec64 = svand_n_u64_x(pred, svld1_u64(pred, (const uint64_t *) p), mask);
+ accum2 = svadd_u64_x(pred, accum2, svcnt_u64_x(pred, vec64));
+ p += svcntb();
+
+ popcnt = svaddv_u64(pred, svadd_u64_x(pred, accum1, accum2));
+
+ pred = svwhilelt_b8_s32(0, sizeof(buf));
+ vec8 = svand_n_u8_x(pred, svld1_u8(pred, (const uint8_t *) p), 0x55);
+ return (int) (popcnt + svaddv_u8(pred, svcnt_u8_x(pred, vec8)));
+}
+'''
+
+ if cc.links(prog, name: 'SVE popcount', args: test_c_args)
+ cdata.set('USE_SVE_POPCNT_WITH_RUNTIME_CHECK', 1)
endif
endif
@@ -2087,17 +2375,26 @@ endif
###############################################################
# Select CRC-32C implementation.
#
-# If we are targeting a processor that has Intel SSE 4.2 instructions, we can
-# use the special CRC instructions for calculating CRC-32C. If we're not
-# targeting such a processor, but we can nevertheless produce code that uses
-# the SSE intrinsics, perhaps with some extra CFLAGS, compile both
-# implementations and select which one to use at runtime, depending on whether
-# SSE 4.2 is supported by the processor we're running on.
+# There are three methods of calculating CRC, in order of increasing
+# performance:
+#
+# 1. The fallback using a lookup table, called slicing-by-8
+# 2. CRC-32C instructions (found in e.g. Intel SSE 4.2 and ARMv8 CRC Extension)
+# 3. Algorithms using carryless multiplication instructions
+# (e.g. Intel PCLMUL and Arm PMULL)
#
-# Similarly, if we are targeting an ARM processor that has the CRC
-# instructions that are part of the ARMv8 CRC Extension, use them. And if
-# we're not targeting such a processor, but can nevertheless produce code that
-# uses the CRC instructions, compile both, and select at runtime.
+# If we can produce code (via function attributes or additional compiler
+# flags) that uses #2 (and possibly #3), we compile all implementations
+# and select which one to use at runtime, depending on what is supported
+# by the processor we're running on.
+#
+# If we are targeting a processor that has #2, we can use that without
+# runtime selection.
+#
+# Note that we do not use __attribute__((target("..."))) for the ARM CRC
+# instructions because until clang 16, using the ARM intrinsics still requires
+# special -march flags. Perhaps we can re-evaluate this decision after some
+# time has passed.
###############################################################
have_optimized_crc = false
@@ -2112,10 +2409,13 @@ if host_cpu == 'x86' or host_cpu == 'x86_64'
prog = '''
#include
+unsigned int crc;
+#if defined(__has_attribute) && __has_attribute (target)
+__attribute__((target("sse4.2")))
+#endif
int main(void)
{
- unsigned int crc = 0;
crc = _mm_crc32_u8(crc, 0);
crc = _mm_crc32_u32(crc, 0);
/* return computed value, to prevent the above being optimized away */
@@ -2123,31 +2423,64 @@ int main(void)
}
'''
- if cc.links(prog, name: '_mm_crc32_u8 and _mm_crc32_u32 without -msse4.2',
+ if not cc.links(prog, name: 'SSE 4.2 CRC32C',
args: test_c_args)
+ # Do not use Intel SSE 4.2
+ elif (cc.get_define('__SSE4_2__') != '')
# Use Intel SSE 4.2 unconditionally.
cdata.set('USE_SSE42_CRC32C', 1)
have_optimized_crc = true
- elif cc.links(prog, name: '_mm_crc32_u8 and _mm_crc32_u32 with -msse4.2',
- args: test_c_args + ['-msse4.2'])
+ else
# Use Intel SSE 4.2, with runtime check. The CPUID instruction is needed for
# the runtime check.
- cflags_crc += '-msse4.2'
cdata.set('USE_SSE42_CRC32C', false)
cdata.set('USE_SSE42_CRC32C_WITH_RUNTIME_CHECK', 1)
have_optimized_crc = true
endif
+ # Check if the compiler supports AVX-512 carryless multiplication
+ # and three-way exclusive-or instructions used for computing CRC.
+ # AVX-512F is assumed to be supported if the above are.
+ prog = '''
+#include
+__m512i x;
+__m512i y;
+
+#if defined(__has_attribute) && __has_attribute (target)
+__attribute__((target("vpclmulqdq,avx512vl")))
+#endif
+int main(void)
+{
+ __m128i z;
+
+ x = _mm512_xor_si512(_mm512_zextsi128_si512(_mm_cvtsi32_si128(0)), x);
+ y = _mm512_clmulepi64_epi128(x, y, 0);
+ z = _mm_ternarylogic_epi64(
+ _mm512_castsi512_si128(y),
+ _mm512_extracti32x4_epi32(y, 1),
+ _mm512_extracti32x4_epi32(y, 2),
+ 0x96);
+ /* return computed value, to prevent the above being optimized away */
+ return _mm_crc32_u64(0, _mm_extract_epi64(z, 0));
+}
+'''
+
+ if cc.links(prog,
+ name: 'AVX-512 CRC32C',
+ args: test_c_args)
+ cdata.set('USE_AVX512_CRC32C_WITH_RUNTIME_CHECK', 1)
+ endif
+
endif
elif host_cpu == 'arm' or host_cpu == 'aarch64'
prog = '''
#include
+unsigned int crc;
int main(void)
{
- unsigned int crc = 0;
crc = __crc32cb(crc, 0);
crc = __crc32ch(crc, 0);
crc = __crc32cw(crc, 0);
@@ -2163,6 +2496,13 @@ int main(void)
# Use ARM CRC Extension unconditionally
cdata.set('USE_ARMV8_CRC32C', 1)
have_optimized_crc = true
+ elif cc.links(prog, name: '__crc32cb, __crc32ch, __crc32cw, and __crc32cd with -march=armv8-a+crc+simd',
+ args: test_c_args + ['-march=armv8-a+crc+simd'])
+ # Use ARM CRC Extension, with runtime check
+ cflags_crc += '-march=armv8-a+crc+simd'
+ cdata.set('USE_ARMV8_CRC32C', false)
+ cdata.set('USE_ARMV8_CRC32C_WITH_RUNTIME_CHECK', 1)
+ have_optimized_crc = true
elif cc.links(prog, name: '__crc32cb, __crc32ch, __crc32cw, and __crc32cd with -march=armv8-a+crc',
args: test_c_args + ['-march=armv8-a+crc'])
# Use ARM CRC Extension, with runtime check
@@ -2175,9 +2515,10 @@ int main(void)
elif host_cpu == 'loongarch64'
prog = '''
+unsigned int crc;
+
int main(void)
{
- unsigned int crc = 0;
crc = __builtin_loongarch_crcc_w_b_w(0, crc);
crc = __builtin_loongarch_crcc_w_h_w(0, crc);
crc = __builtin_loongarch_crcc_w_w_w(0, crc);
@@ -2237,6 +2578,7 @@ elif host_cpu == 'ppc' or host_cpu == 'ppc64'
}
int test_adds(int x) { return addi(3, x) + addi(x, 5); }
''',
+ name: '@0@: "i"(x) when __builtin_constant_p(x)'.format(host_cpu),
args: test_c_args)
cdata.set('HAVE_I_CONSTRAINT__BUILTIN_CONSTANT_P', 1)
endif
@@ -2258,9 +2600,7 @@ header_checks = [
'execinfo.h',
'getopt.h',
'ifaddrs.h',
- 'langinfo.h',
'mbarrier.h',
- 'stdbool.h',
'strings.h',
'sys/epoll.h',
'sys/event.h',
@@ -2271,6 +2611,7 @@ header_checks = [
'sys/ucred.h',
'termios.h',
'ucred.h',
+ 'xlocale.h',
]
foreach header : header_checks
@@ -2291,6 +2632,8 @@ decl_checks = [
['strlcat', 'string.h'],
['strlcpy', 'string.h'],
['strnlen', 'string.h'],
+ ['strsep', 'string.h'],
+ ['timingsafe_bcmp', 'string.h'],
]
# Need to check for function declarations for these functions, because
@@ -2299,6 +2642,8 @@ decl_checks = [
decl_checks += [
['preadv', 'sys/uio.h'],
['pwritev', 'sys/uio.h'],
+ ['strchrnul', 'string.h'],
+ ['memset_s', 'string.h', '#define __STDC_WANT_LIB_EXT1__ 1'],
]
# Check presence of some optional LLVM functions.
@@ -2312,11 +2657,28 @@ endif
foreach c : decl_checks
func = c.get(0)
header = c.get(1)
- args = c.get(2, {})
+ prologue = c.get(2, '')
+ args = c.get(3, {})
varname = 'HAVE_DECL_' + func.underscorify().to_upper()
- found = cc.has_header_symbol(header, func,
- args: test_c_args, include_directories: postgres_inc,
+ found = cc.compiles('''
+@0@
+#include <@1@>
+
+int main()
+{
+#ifndef @2@
+ (void) @2@;
+#endif
+
+return 0;
+}
+'''.format(prologue, header, func),
+ name: 'test whether @0@ is declared'.format(func),
+ # need to add cflags_warn to get at least
+ # -Werror=unguarded-availability-new if applicable
+ args: test_c_args + cflags_warn,
+ include_directories: postgres_inc,
kwargs: args)
cdata.set10(varname, found, description:
'''Define to 1 if you have the declaration of `@0@', and to 0 if you
@@ -2413,18 +2775,9 @@ else
cdata.set('STRERROR_R_INT', false)
endif
-# Find the right header file for the locale_t type. macOS needs xlocale.h;
-# standard is locale.h, but glibc <= 2.25 also had an xlocale.h file that
-# we should not use so we check the standard header first. MSVC has a
-# replacement defined in src/include/port/win32_port.h.
-if not cc.has_type('locale_t', prefix: '#include ') and \
- cc.has_type('locale_t', prefix: '#include ')
- cdata.set('LOCALE_T_IN_XLOCALE', 1)
-endif
-
# Check if the C compiler understands typeof or a variant. Define
# HAVE_TYPEOF if so, and define 'typeof' to the actual key word.
-foreach kw : ['typeof', '__typeof__', 'decltype']
+foreach kw : ['typeof', '__typeof__']
if cc.compiles('''
int main(void)
{
@@ -2434,7 +2787,7 @@ int main(void)
return y;
}
'''.format(kw),
- name: 'typeof()',
+ name: kw,
args: test_c_args, include_directories: postgres_inc)
cdata.set('HAVE_TYPEOF', 1)
@@ -2447,29 +2800,6 @@ int main(void)
endforeach
-# Try to find a declaration for wcstombs_l(). It might be in stdlib.h
-# (following the POSIX requirement for wcstombs()), or in locale.h, or in
-# xlocale.h. If it's in the latter, define WCSTOMBS_L_IN_XLOCALE.
-wcstombs_l_test = '''
-#include
-#include
-@0@
-
-void main(void)
-{
-#ifndef wcstombs_l
- (void) wcstombs_l;
-#endif
-}
-'''
-if (not cc.compiles(wcstombs_l_test.format(''),
- name: 'wcstombs_l') and
- cc.compiles(wcstombs_l_test.format('#include '),
- name: 'wcstombs_l in xlocale.h'))
- cdata.set('WCSTOMBS_L_IN_XLOCALE', 1)
-endif
-
-
# MSVC doesn't cope well with defining restrict to __restrict, the spelling it
# understands, because it conflicts with __declspec(restrict). Therefore we
# define pg_restrict to the appropriate definition, which presumably won't
@@ -2521,7 +2851,6 @@ endif
# XXX: Might be worth conditioning some checks on the OS, to avoid doing
# unnecessary checks over and over, particularly on windows.
func_checks = [
- ['_configthreadlocale', {'skip': host_system != 'windows'}],
['backtrace_symbols', {'dependencies': [execinfo_dep]}],
['clock_gettime', {'dependencies': [rt_dep], 'define': false}],
['copyfile'],
@@ -2530,7 +2859,9 @@ func_checks = [
# when enabling asan the dlopen check doesn't notice that -ldl is actually
# required. Just checking for dlsym() ought to suffice.
['dlsym', {'dependencies': [dl_dep], 'define': false}],
+ ['elf_aux_info'],
['explicit_bzero'],
+ ['getauxval'],
['getifaddrs'],
['getopt', {'dependencies': [getopt_dep, gnugetopt_dep], 'skip': always_replace_getopt}],
['getopt_long', {'dependencies': [getopt_dep, gnugetopt_dep], 'skip': always_replace_getopt_long}],
@@ -2539,8 +2870,8 @@ func_checks = [
['inet_aton'],
['inet_pton'],
['kqueue'],
+ ['localeconv_l'],
['mbstowcs_l'],
- ['memset_s'],
['mkdtemp'],
['posix_fadvise'],
['posix_fallocate'],
@@ -2554,14 +2885,15 @@ func_checks = [
['shm_unlink', {'dependencies': [rt_dep], 'define': false}],
['shmget', {'dependencies': [cygipc_dep], 'define': false}],
['socket', {'dependencies': [socket_dep], 'define': false}],
- ['strchrnul'],
['strerror_r', {'dependencies': [thread_dep]}],
['strlcat'],
['strlcpy'],
['strnlen'],
+ ['strsep'],
['strsignal'],
['sync_file_range'],
['syncfs'],
+ ['timingsafe_bcmp'],
['uselocale'],
['wcstombs_l'],
]
@@ -2781,6 +3113,8 @@ gen_export_kwargs = {
'install': false,
}
+# command to create stamp files on all OSs
+stamp_cmd = [python, '-c', 'import sys; open(sys.argv[1], "w")', '@OUTPUT0@']
###
@@ -2802,13 +3136,13 @@ gen_kwlist_cmd = [
###
if host_system == 'windows'
- pg_ico = meson.source_root() / 'src' / 'port' / 'win32.ico'
+ pg_ico = meson.project_source_root() / 'src' / 'port' / 'win32.ico'
win32ver_rc = files('src/port/win32ver.rc')
rcgen = find_program('src/tools/rcgen', native: true)
rcgen_base_args = [
'--srcdir', '@SOURCE_DIR@',
- '--builddir', meson.build_root(),
+ '--builddir', meson.project_build_root(),
'--rcout', '@OUTPUT0@',
'--out', '@OUTPUT1@',
'--input', '@INPUT@',
@@ -2817,11 +3151,11 @@ if host_system == 'windows'
if cc.get_argument_syntax() == 'msvc'
rc = find_program('rc', required: true)
- rcgen_base_args += ['--rc', rc.path()]
+ rcgen_base_args += ['--rc', rc.full_path()]
rcgen_outputs = ['@BASENAME@.rc', '@BASENAME@.res']
else
windres = find_program('windres', required: true)
- rcgen_base_args += ['--windres', windres.path()]
+ rcgen_base_args += ['--windres', windres.full_path()]
rcgen_outputs = ['@BASENAME@.rc', '@BASENAME@.obj']
endif
@@ -2898,14 +3232,14 @@ subdir('src/port')
frontend_common_code = declare_dependency(
compile_args: ['-DFRONTEND'],
include_directories: [postgres_inc],
- sources: generated_headers,
- dependencies: [os_deps, zlib, zstd],
+ sources: generated_headers_stamp,
+ dependencies: [os_deps, zlib, zstd, lz4],
)
backend_common_code = declare_dependency(
compile_args: ['-DBUILDING_DLL'],
include_directories: [postgres_inc],
- sources: generated_headers,
+ sources: generated_headers_stamp,
dependencies: [os_deps, zlib, zstd],
)
@@ -2920,7 +3254,7 @@ shlib_code = declare_dependency(
frontend_stlib_code = declare_dependency(
include_directories: [postgres_inc],
link_with: [common_static, pgport_static],
- sources: generated_headers,
+ sources: generated_headers_stamp,
dependencies: [os_deps, libintl],
)
@@ -2928,10 +3262,20 @@ frontend_stlib_code = declare_dependency(
frontend_shlib_code = declare_dependency(
include_directories: [postgres_inc],
link_with: [common_shlib, pgport_shlib],
- sources: generated_headers,
+ sources: generated_headers_stamp,
dependencies: [shlib_code, os_deps, libintl],
)
+# For frontend code that doesn't use fe_utils - this mainly exists for libpq's
+# tests, which are defined before fe_utils is defined, as fe_utils depends on
+# libpq.
+frontend_no_fe_utils_code = declare_dependency(
+ include_directories: [postgres_inc],
+ link_with: [common_static, pgport_static],
+ sources: generated_headers_stamp,
+ dependencies: [os_deps, libintl],
+)
+
# Dependencies both for static and shared libpq
libpq_deps += [
thread_dep,
@@ -2942,15 +3286,21 @@ libpq_deps += [
ssl,
]
+libpq_oauth_deps += [
+ thread_dep,
+ libcurl,
+]
+
subdir('src/interfaces/libpq')
-# fe_utils depends on libpq
+# fe_utils and libpq-oauth depends on libpq
subdir('src/fe_utils')
+subdir('src/interfaces/libpq-oauth')
# for frontend binaries
frontend_code = declare_dependency(
include_directories: [postgres_inc],
link_with: [fe_utils, common_static, pgport_static],
- sources: generated_headers,
+ sources: generated_headers_stamp,
dependencies: [os_deps, libintl],
)
@@ -2962,6 +3312,8 @@ backend_both_deps += [
icu_i18n,
ldap,
libintl,
+ libnuma,
+ liburing,
libxml,
lz4,
pam,
@@ -2978,7 +3330,7 @@ backend_code = declare_dependency(
include_directories: [postgres_inc],
link_args: ldflags_be,
link_with: [],
- sources: generated_headers + generated_backend_headers,
+ sources: generated_backend_headers_stamp,
dependencies: os_deps + backend_both_deps + backend_deps,
)
@@ -2999,7 +3351,6 @@ subdir('src')
subdir('contrib')
subdir('src/test')
-subdir('src/interfaces/libpq/test')
subdir('src/interfaces/ecpg/test')
subdir('doc/src/sgml')
@@ -3038,7 +3389,7 @@ foreach t1 : configure_files
potentially_conflicting_files += meson.current_build_dir() / t
endforeach
foreach sub, fnames : generated_sources_ac
- sub = meson.build_root() / sub
+ sub = meson.project_build_root() / sub
foreach fname : fnames
potentially_conflicting_files += sub / fname
endforeach
@@ -3093,24 +3444,37 @@ if libintl.found() and meson.version().version_compare('>=0.60')
endif
-all_built = [
+# all targets that 'meson install' needs
+installed_targets = [
backend_targets,
bin_targets,
libpq_st,
pl_targets,
contrib_targets,
nls_mo_targets,
- testprep_targets,
ecpg_targets,
]
+if oauth_flow_supported
+ installed_targets += [
+ libpq_oauth_so,
+ libpq_oauth_st,
+ ]
+endif
+
+# all targets that require building code
+all_built = [
+ installed_targets,
+ testprep_targets,
+]
+
# Meson's default install target is quite verbose. Provide one that is quiet.
install_quiet = custom_target('install-quiet',
output: 'install-quiet',
build_always_stale: true,
build_by_default: false,
command: [meson_bin, meson_args, 'install', '--quiet', '--no-rebuild'],
- depends: all_built,
+ depends: installed_targets,
)
# Target to install files used for tests, which aren't installed by default
@@ -3132,21 +3496,23 @@ run_target('install-test-files',
###############################################################
# DESTDIR for the installation we'll run tests in
-test_install_destdir = meson.build_root() / 'tmp_install/'
+test_install_destdir = meson.project_build_root() / 'tmp_install/'
# DESTDIR + prefix appropriately munged
if build_system != 'windows'
# On unixoid systems this is trivial, we just prepend the destdir
assert(dir_prefix.startswith('/')) # enforced by meson
- test_install_location = '@0@@1@'.format(test_install_destdir, dir_prefix)
+ temp_install_bindir = '@0@@1@'.format(test_install_destdir, dir_prefix / dir_bin)
+ temp_install_libdir = '@0@@1@'.format(test_install_destdir, dir_prefix / dir_lib)
else
# drives, drive-relative paths, etc make this complicated on windows, call
# into a copy of meson's logic for it
command = [
python, '-c',
'import sys; from pathlib import PurePath; d1=sys.argv[1]; d2=sys.argv[2]; print(str(PurePath(d1, *PurePath(d2).parts[1:])))',
- test_install_destdir, dir_prefix]
- test_install_location = run_command(command, check: true).stdout().strip()
+ test_install_destdir]
+ temp_install_bindir = run_command(command, dir_prefix / dir_bin, check: true).stdout().strip()
+ temp_install_libdir = run_command(command, dir_prefix / dir_lib, check: true).stdout().strip()
endif
meson_install_args = meson_args + ['install'] + {
@@ -3163,6 +3529,7 @@ test('tmp_install',
priority: setup_tests_priority,
timeout: 300,
is_parallel: false,
+ depends: installed_targets,
suite: ['setup'])
test('install_test_files',
@@ -3172,7 +3539,7 @@ test('install_test_files',
is_parallel: false,
suite: ['setup'])
-test_result_dir = meson.build_root() / 'testrun'
+test_result_dir = meson.project_build_root() / 'testrun'
# XXX: pg_regress doesn't assign unique ports on windows. To avoid the
@@ -3183,22 +3550,18 @@ testport = 40000
test_env = environment()
-temp_install_bindir = test_install_location / get_option('bindir')
-test_initdb_template = meson.build_root() / 'tmp_install' / 'initdb-template'
+test_initdb_template = meson.project_build_root() / 'tmp_install' / 'initdb-template'
test_env.set('PG_REGRESS', pg_regress.full_path())
test_env.set('REGRESS_SHLIB', regress_module.full_path())
test_env.set('INITDB_TEMPLATE', test_initdb_template)
-
-# Test suites that are not safe by default but can be run if selected
-# by the user via the whitespace-separated list in variable PG_TEST_EXTRA.
-# Export PG_TEST_EXTRA so it can be checked in individual tap tests.
-test_env.set('PG_TEST_EXTRA', get_option('PG_TEST_EXTRA'))
+# for Cluster.pm's portlock logic
+test_env.set('top_builddir', meson.project_build_root())
# Add the temporary installation to the library search path on platforms where
# that works (everything but windows, basically). On windows everything
# library-like gets installed into bindir, solving that issue.
if library_path_var != ''
- test_env.prepend(library_path_var, test_install_location / get_option('libdir'))
+ test_env.prepend(library_path_var, temp_install_libdir)
endif
@@ -3236,27 +3599,26 @@ sys.exit(sp.returncode)
# Test Generation
###############################################################
-# When using a meson version understanding exclude_suites, define a
-# 'tmp_install' test setup (the default) that excludes tests running against a
-# pre-existing install and a 'running' setup that conflicts with creation of
-# the temporary installation and tap tests (which don't support running
-# against a running server).
+# Define a 'tmp_install' test setup (the default) that excludes tests
+# running against a pre-existing install and a 'running' setup that
+# conflicts with creation of the temporary installation and tap tests
+# (which don't support running against a running server).
running_suites = []
install_suites = []
-if meson.version().version_compare('>=0.57')
- runningcheck = true
-else
- runningcheck = false
-endif
testwrap = files('src/tools/testwrap')
foreach test_dir : tests
testwrap_base = [
testwrap,
- '--basedir', meson.build_root(),
+ '--basedir', meson.project_build_root(),
'--srcdir', test_dir['sd'],
+ # Some test suites are not run by default but can be run if selected by the
+ # user via variable PG_TEST_EXTRA. Pass configuration time value of
+ # PG_TEST_EXTRA as an argument to testwrap so that it can be overridden by
+ # run time value, if any.
+ '--pg-test-extra', get_option('PG_TEST_EXTRA'),
]
foreach kind, v : test_dir
@@ -3340,7 +3702,7 @@ foreach test_dir : tests
install_suites += test_group
# some tests can't support running against running DB
- if runningcheck and t.get('runningcheck', true)
+ if t.get('runningcheck', true)
test(test_group_running / kind,
python,
args: [
@@ -3367,8 +3729,8 @@ foreach test_dir : tests
endif
test_command = [
- perl.path(),
- '-I', meson.source_root() / 'src/test/perl',
+ perl.full_path(),
+ '-I', meson.project_source_root() / 'src/test/perl',
'-I', test_dir['sd'],
]
@@ -3376,6 +3738,8 @@ foreach test_dir : tests
# also test/ for non-installed test binaries built separately.
env = test_env
env.prepend('PATH', temp_install_bindir, test_dir['bd'], test_dir['bd'] / 'test')
+ temp_install_datadir = '@0@@1@'.format(test_install_destdir, dir_prefix / dir_data)
+ env.set('share_contrib_dir', temp_install_datadir / 'contrib')
foreach name, value : t.get('env', {})
env.set(name, value)
@@ -3421,13 +3785,11 @@ foreach test_dir : tests
endforeach # directories with tests
# repeat condition so meson realizes version dependency
-if meson.version().version_compare('>=0.57')
- add_test_setup('tmp_install',
- is_default: true,
- exclude_suites: running_suites)
- add_test_setup('running',
- exclude_suites: ['setup'] + install_suites)
-endif
+add_test_setup('tmp_install',
+ is_default: true,
+ exclude_suites: running_suites)
+add_test_setup('running',
+ exclude_suites: ['setup'] + install_suites)
@@ -3484,7 +3846,7 @@ tar_gz = custom_target('tar.gz',
'--format', 'tar.gz',
'-9',
'--prefix', distdir + '/',
- '-o', join_paths(meson.build_root(), '@OUTPUT@'),
+ '-o', join_paths(meson.project_build_root(), '@OUTPUT@'),
pg_git_revision],
output: distdir + '.tar.gz',
)
@@ -3494,11 +3856,11 @@ if bzip2.found()
build_always_stale: true,
command: [git, '-C', '@SOURCE_ROOT@',
'-c', 'core.autocrlf=false',
- '-c', 'tar.tar.bz2.command="@0@" -c'.format(bzip2.path()),
+ '-c', 'tar.tar.bz2.command="@0@" -c'.format(bzip2.full_path()),
'archive',
'--format', 'tar.bz2',
'--prefix', distdir + '/',
- '-o', join_paths(meson.build_root(), '@OUTPUT@'),
+ '-o', join_paths(meson.project_build_root(), '@OUTPUT@'),
pg_git_revision],
output: distdir + '.tar.bz2',
)
@@ -3515,10 +3877,7 @@ alias_target('pgdist', [tar_gz, tar_bz2])
# But not if we are in a subproject, in case the parent project wants to
# create a dist using the standard Meson command.
if not meson.is_subproject()
- # We can only pass the identifier perl here when we depend on >= 0.55
- if meson.version().version_compare('>=0.55')
- meson.add_dist_script(perl, '-e', 'exit 1')
- endif
+ meson.add_dist_script(perl, '-e', 'exit 1')
endif
@@ -3527,102 +3886,102 @@ endif
# The End, The End, My Friend
###############################################################
-if meson.version().version_compare('>=0.57')
+summary(
+ {
+ 'data block size': '@0@ kB'.format(cdata.get('BLCKSZ') / 1024),
+ 'WAL block size': '@0@ kB'.format(cdata.get('XLOG_BLCKSZ') / 1024),
+ 'segment size': get_option('segsize_blocks') != 0 ?
+ '@0@ blocks'.format(cdata.get('RELSEG_SIZE')) :
+ '@0@ GB'.format(get_option('segsize')),
+ },
+ section: 'Data layout',
+)
- summary(
- {
- 'data block size': '@0@ kB'.format(cdata.get('BLCKSZ') / 1024),
- 'WAL block size': '@0@ kB'.format(cdata.get('XLOG_BLCKSZ') / 1024),
- 'segment size': get_option('segsize_blocks') != 0 ?
- '@0@ blocks'.format(cdata.get('RELSEG_SIZE')) :
- '@0@ GB'.format(get_option('segsize')),
- },
- section: 'Data layout',
- )
+summary(
+ {
+ 'host system': '@0@ @1@'.format(host_system, host_cpu),
+ 'build system': '@0@ @1@'.format(build_machine.system(),
+ build_machine.cpu_family()),
+ },
+ section: 'System',
+)
- summary(
- {
- 'host system': '@0@ @1@'.format(host_system, host_cpu),
- 'build system': '@0@ @1@'.format(build_machine.system(),
- build_machine.cpu_family()),
- },
- section: 'System',
- )
+summary(
+ {
+ 'linker': '@0@'.format(cc.get_linker_id()),
+ 'C compiler': '@0@ @1@'.format(cc.get_id(), cc.version()),
+ },
+ section: 'Compiler',
+)
+summary(
+ {
+ 'CPP FLAGS': ' '.join(cppflags),
+ 'C FLAGS, functional': ' '.join(cflags),
+ 'C FLAGS, warnings': ' '.join(cflags_warn),
+ 'C FLAGS, modules': ' '.join(cflags_mod),
+ 'C FLAGS, user specified': ' '.join(get_option('c_args')),
+ 'LD FLAGS': ' '.join(ldflags + get_option('c_link_args')),
+ },
+ section: 'Compiler Flags',
+)
+
+if llvm.found()
summary(
{
- 'linker': '@0@'.format(cc.get_linker_id()),
- 'C compiler': '@0@ @1@'.format(cc.get_id(), cc.version()),
+ 'C++ compiler': '@0@ @1@'.format(cpp.get_id(), cpp.version()),
},
section: 'Compiler',
)
summary(
{
- 'CPP FLAGS': ' '.join(cppflags),
- 'C FLAGS, functional': ' '.join(cflags),
- 'C FLAGS, warnings': ' '.join(cflags_warn),
- 'C FLAGS, modules': ' '.join(cflags_mod),
- 'C FLAGS, user specified': ' '.join(get_option('c_args')),
- 'LD FLAGS': ' '.join(ldflags + get_option('c_link_args')),
+ 'C++ FLAGS, functional': ' '.join(cxxflags),
+ 'C++ FLAGS, warnings': ' '.join(cxxflags_warn),
+ 'C++ FLAGS, user specified': ' '.join(get_option('cpp_args')),
},
section: 'Compiler Flags',
)
+endif
- if llvm.found()
- summary(
- {
- 'C++ compiler': '@0@ @1@'.format(cpp.get_id(), cpp.version()),
- },
- section: 'Compiler',
- )
-
- summary(
- {
- 'C++ FLAGS, functional': ' '.join(cxxflags),
- 'C++ FLAGS, warnings': ' '.join(cxxflags_warn),
- 'C++ FLAGS, user specified': ' '.join(get_option('cpp_args')),
- },
- section: 'Compiler Flags',
- )
- endif
-
- summary(
- {
- 'bison': '@0@ @1@'.format(bison.full_path(), bison_version),
- 'dtrace': dtrace,
- 'flex': '@0@ @1@'.format(flex.full_path(), flex_version),
- },
- section: 'Programs',
- )
-
- summary(
- {
- 'bonjour': bonjour,
- 'bsd_auth': bsd_auth,
- 'docs': docs_dep,
- 'docs_pdf': docs_pdf_dep,
- 'gss': gssapi,
- 'icu': icu,
- 'ldap': ldap,
- 'libxml': libxml,
- 'libxslt': libxslt,
- 'llvm': llvm,
- 'lz4': lz4,
- 'nls': libintl,
- 'openssl': ssl,
- 'pam': pam,
- 'plperl': perl_dep,
- 'plpython': python3_dep,
- 'pltcl': tcl_dep,
- 'readline': readline,
- 'selinux': selinux,
- 'systemd': systemd,
- 'uuid': uuid,
- 'zlib': zlib,
- 'zstd': zstd,
- },
- section: 'External libraries',
- )
+summary(
+ {
+ 'bison': '@0@ @1@'.format(bison.full_path(), bison_version),
+ 'dtrace': dtrace,
+ 'flex': '@0@ @1@'.format(flex.full_path(), flex_version),
+ },
+ section: 'Programs',
+)
-endif
+summary(
+ {
+ 'bonjour': bonjour,
+ 'bsd_auth': bsd_auth,
+ 'docs': docs_dep,
+ 'docs_pdf': docs_pdf_dep,
+ 'gss': gssapi,
+ 'icu': icu,
+ 'ldap': ldap,
+ 'libcurl': libcurl,
+ 'libnuma': libnuma,
+ 'liburing': liburing,
+ 'libxml': libxml,
+ 'libxslt': libxslt,
+ 'llvm': llvm,
+ 'lz4': lz4,
+ 'nls': libintl,
+ 'openssl': ssl,
+ 'pam': pam,
+ 'plperl': [perl_dep, perlversion],
+ 'plpython': python3_dep,
+ 'pltcl': tcl_dep,
+ 'readline': readline,
+ 'selinux': selinux,
+ 'systemd': systemd,
+ 'uuid': uuid,
+ 'zlib': zlib,
+ 'zstd': zstd,
+ },
+ section: 'External libraries',
+ list_sep: ' ',
+)
diff --git a/meson_options.txt b/meson_options.txt
index 246cecf382712..06bf5627d3c03 100644
--- a/meson_options.txt
+++ b/meson_options.txt
@@ -1,4 +1,4 @@
-# Copyright (c) 2022-2024, PostgreSQL Global Development Group
+# Copyright (c) 2022-2025, PostgreSQL Global Development Group
# Data layout influencing options
@@ -47,13 +47,7 @@ option('injection_points', type: 'boolean', value: false,
description: 'Enable injection points')
option('PG_TEST_EXTRA', type: 'string', value: '',
- description: 'Enable selected extra tests')
-
-option('atomics', type: 'boolean', value: true,
- description: 'Use atomic operations')
-
-option('spinlocks', type: 'boolean', value: true,
- description: 'Use spinlocks')
+ description: 'Enable selected extra tests. Overridden by PG_TEST_EXTRA environment variable.')
option('PG_GIT_REVISION', type: 'string', value: 'HEAD',
description: 'git revision to be packaged by pgdist target')
@@ -106,9 +100,18 @@ option('icu', type: 'feature', value: 'auto',
option('ldap', type: 'feature', value: 'auto',
description: 'LDAP support')
+option('libcurl', type : 'feature', value: 'auto',
+ description: 'libcurl support')
+
option('libedit_preferred', type: 'boolean', value: false,
description: 'Prefer BSD Libedit over GNU Readline')
+option('libnuma', type: 'feature', value: 'auto',
+ description: 'NUMA support')
+
+option('liburing', type : 'feature', value: 'auto',
+ description: 'io_uring support, for asynchronous I/O')
+
option('libxml', type: 'feature', value: 'auto',
description: 'XML support')
diff --git a/src/Makefile.global.in b/src/Makefile.global.in
index a00c909681eb1..8b1b357beaa04 100644
--- a/src/Makefile.global.in
+++ b/src/Makefile.global.in
@@ -87,9 +87,19 @@ endif # not PGXS
#
# In a PGXS build, we cannot use the values inserted into Makefile.global
# by configure, since the installation tree may have been relocated.
-# Instead get the path values from pg_config.
+# Instead get the path values from pg_config. But users can specify
+# prefix explicitly, if they want to select their own installation
+# location.
-ifndef PGXS
+ifdef PGXS
+# Extension makefiles should set PG_CONFIG, but older ones might not
+ifndef PG_CONFIG
+PG_CONFIG = pg_config
+endif
+endif
+
+# This means: if ((not PGXS) or prefix)
+ifneq (,$(if $(PGXS),,1)$(prefix))
# Note that prefix, exec_prefix, and datarootdir aren't defined in a PGXS build;
# makefiles may only use the derived variables such as bindir.
@@ -147,11 +157,6 @@ localedir := @localedir@
else # PGXS case
-# Extension makefiles should set PG_CONFIG, but older ones might not
-ifndef PG_CONFIG
-PG_CONFIG = pg_config
-endif
-
bindir := $(shell $(PG_CONFIG) --bindir)
datadir := $(shell $(PG_CONFIG) --sharedir)
sysconfdir := $(shell $(PG_CONFIG) --sysconfdir)
@@ -190,6 +195,9 @@ with_systemd = @with_systemd@
with_gssapi = @with_gssapi@
with_krb_srvnam = @with_krb_srvnam@
with_ldap = @with_ldap@
+with_libcurl = @with_libcurl@
+with_libnuma = @with_libnuma@
+with_liburing = @with_liburing@
with_libxml = @with_libxml@
with_libxslt = @with_libxslt@
with_llvm = @with_llvm@
@@ -216,6 +224,12 @@ krb_srvtab = @krb_srvtab@
ICU_CFLAGS = @ICU_CFLAGS@
ICU_LIBS = @ICU_LIBS@
+LIBNUMA_CFLAGS = @LIBNUMA_CFLAGS@
+LIBNUMA_LIBS = @LIBNUMA_LIBS@
+
+LIBURING_CFLAGS = @LIBURING_CFLAGS@
+LIBURING_LIBS = @LIBURING_LIBS@
+
TCLSH = @TCLSH@
TCL_LIBS = @TCL_LIBS@
TCL_LIB_SPEC = @TCL_LIB_SPEC@
@@ -240,7 +254,7 @@ CPP = @CPP@
CPPFLAGS = @CPPFLAGS@
PG_SYSROOT = @PG_SYSROOT@
-override CPPFLAGS := $(ICU_CFLAGS) $(CPPFLAGS)
+override CPPFLAGS += $(ICU_CFLAGS) $(LIBNUMA_CFLAGS) $(LIBURING_CFLAGS)
ifdef PGXS
override CPPFLAGS := -I$(includedir_server) -I$(includedir_internal) $(CPPFLAGS)
@@ -262,10 +276,9 @@ CFLAGS_SL_MODULE = @CFLAGS_SL_MODULE@
CXXFLAGS_SL_MODULE = @CXXFLAGS_SL_MODULE@
CFLAGS_UNROLL_LOOPS = @CFLAGS_UNROLL_LOOPS@
CFLAGS_VECTORIZE = @CFLAGS_VECTORIZE@
-CFLAGS_POPCNT = @CFLAGS_POPCNT@
CFLAGS_CRC = @CFLAGS_CRC@
-CFLAGS_XSAVE = @CFLAGS_XSAVE@
PERMIT_DECLARATION_AFTER_STATEMENT = @PERMIT_DECLARATION_AFTER_STATEMENT@
+PERMIT_MISSING_VARIABLE_DECLARATIONS = @PERMIT_MISSING_VARIABLE_DECLARATIONS@
CXXFLAGS = @CXXFLAGS@
LLVM_CPPFLAGS = @LLVM_CPPFLAGS@
@@ -334,6 +347,9 @@ perl_embed_ldflags = @perl_embed_ldflags@
AWK = @AWK@
LN_S = @LN_S@
+LIBCURL_CPPFLAGS = @LIBCURL_CPPFLAGS@
+LIBCURL_LDFLAGS = @LIBCURL_LDFLAGS@
+LIBCURL_LDLIBS = @LIBCURL_LDLIBS@
MSGFMT = @MSGFMT@
MSGFMT_FLAGS = @MSGFMT_FLAGS@
MSGMERGE = @MSGMERGE@
@@ -358,10 +374,10 @@ DOWNLOAD = wget -O $@ --no-use-server-timestamps
# Pick a release from here: . Note
# that the most recent release listed there is often a pre-release;
# don't pick that one, except for testing.
-UNICODE_VERSION = 15.1.0
+UNICODE_VERSION = 16.0.0
# Pick a release from here:
-CLDR_VERSION = 45
+CLDR_VERSION = 47
# Tree-wide build support
@@ -455,6 +471,7 @@ cd $(srcdir) && \
PATH="$(bindir):$(CURDIR):$$PATH" \
PGPORT='6$(DEF_PGPORT)' top_builddir='$(CURDIR)/$(top_builddir)' \
PG_REGRESS='$(CURDIR)/$(top_builddir)/src/test/regress/pg_regress' \
+ share_contrib_dir='$(DESTDIR)$(datadir)/$(datamoduledir)' \
$(PROVE) $(PG_PROVE_FLAGS) $(PROVE_FLAGS) $(if $(PROVE_TESTS),$(PROVE_TESTS),t/*.pl)
endef
else # PGXS case
@@ -482,6 +499,7 @@ cd $(srcdir) && \
$(with_temp_install) \
PGPORT='6$(DEF_PGPORT)' top_builddir='$(CURDIR)/$(top_builddir)' \
PG_REGRESS='$(CURDIR)/$(top_builddir)/src/test/regress/pg_regress' \
+ share_contrib_dir='$(abs_top_builddir)/tmp_install$(datadir)/$(datamoduledir)' \
$(PROVE) $(PG_PROVE_FLAGS) $(PROVE_FLAGS) $(if $(PROVE_TESTS),$(PROVE_TESTS),t/*.pl)
endef
@@ -641,6 +659,16 @@ submake-libpgfeutils: | submake-generated-headers
#
# Testing support
+# Store any configure-time setting for PG_TEST_EXTRA, but let environment
+# variables override it to maintain the historical behavior of the tests.
+# (Standard `=` assignment would require devs to use a commandline option.)
+# This is skipped in PGXS mode to keep the setting from escaping into other
+# projects' builds.
+ifndef PGXS
+PG_TEST_EXTRA ?= @PG_TEST_EXTRA@
+export PG_TEST_EXTRA
+endif
+
ifneq ($(USE_MODULE_DB),)
PL_TESTDB = pl_regression_$(NAME)
ifneq ($(MODULE_big),)
@@ -741,6 +769,7 @@ endif
#
ifdef COPT
CFLAGS += $(COPT)
+ CXXFLAGS += $(COPT)
LDFLAGS += $(COPT)
endif
@@ -760,9 +789,6 @@ LIBOBJS = @LIBOBJS@
# files needed for the chosen CRC-32C implementation
PG_CRC32C_OBJS = @PG_CRC32C_OBJS@
-# files needed for the chosen popcount implementation
-PG_POPCNT_OBJS = @PG_POPCNT_OBJS@
-
LIBS := -lpgcommon -lpgport $(LIBS)
# to make ws2_32.lib the last library
@@ -781,7 +807,6 @@ TAS = @TAS@
%.c: %.l
$(FLEX) $(if $(FLEX_NO_BACKUP),-b) $(FLEXFLAGS) -o'$@' $<
@$(if $(FLEX_NO_BACKUP),if [ `wc -l &2; exit 1; fi)
- $(if $(FLEX_FIX_WARNING),$(PERL) $(top_srcdir)/src/tools/fix-old-flex-code.pl '$@')
%.c: %.y
$(if $(BISON_CHECK_CMD),$(BISON_CHECK_CMD))
@@ -833,12 +858,6 @@ $(top_builddir)/src/include/pg_config.h: $(top_builddir)/src/include/stamp-h ;
$(top_builddir)/src/include/stamp-h: $(top_srcdir)/src/include/pg_config.h.in $(top_builddir)/config.status
cd $(top_builddir) && ./config.status src/include/pg_config.h
-# Also remake pg_config_ext.h from pg_config_ext.h.in, same logic as above.
-$(top_builddir)/src/include/pg_config_ext.h: $(top_builddir)/src/include/stamp-ext-h ;
-
-$(top_builddir)/src/include/stamp-ext-h: $(top_srcdir)/src/include/pg_config_ext.h.in $(top_builddir)/config.status
- cd $(top_builddir) && ./config.status src/include/pg_config_ext.h
-
# Also remake ecpg_config.h from ecpg_config.h.in if the latter changed, same
# logic as above.
$(top_builddir)/src/interfaces/ecpg/include/ecpg_config.h: $(top_builddir)/src/interfaces/ecpg/include/stamp-h ;
diff --git a/src/Makefile.shlib b/src/Makefile.shlib
index fa81f6ffdd6d9..3825af5b22872 100644
--- a/src/Makefile.shlib
+++ b/src/Makefile.shlib
@@ -112,7 +112,7 @@ ifeq ($(PORTNAME), darwin)
ifneq ($(SO_MAJOR_VERSION), 0)
version_link = -compatibility_version $(SO_MAJOR_VERSION) -current_version $(SO_MAJOR_VERSION).$(SO_MINOR_VERSION)
endif
- LINK.shared = $(COMPILER) -dynamiclib -install_name '$(libdir)/lib$(NAME).$(SO_MAJOR_VERSION)$(DLSUFFIX)' $(version_link) $(exported_symbols_list)
+ LINK.shared = $(COMPILER) -dynamiclib -install_name '$(libdir)/lib$(NAME).$(SO_MAJOR_VERSION)$(DLSUFFIX)' $(version_link)
shlib = lib$(NAME).$(SO_MAJOR_VERSION)$(DLSUFFIX)
shlib_major = lib$(NAME).$(SO_MAJOR_VERSION)$(DLSUFFIX)
else
@@ -122,7 +122,7 @@ ifeq ($(PORTNAME), darwin)
BUILD.exports = $(AWK) '/^[^\#]/ {printf "_%s\n",$$1}' $< >$@
exports_file = $(SHLIB_EXPORTS:%.txt=%.list)
ifneq (,$(exports_file))
- exported_symbols_list = -exported_symbols_list $(exports_file)
+ LINK.shared += -exported_symbols_list $(exports_file)
endif
endif
diff --git a/src/backend/Makefile b/src/backend/Makefile
index 6700aec039629..7344c8c7f5c65 100644
--- a/src/backend/Makefile
+++ b/src/backend/Makefile
@@ -2,7 +2,7 @@
#
# Makefile for the postgres backend
#
-# Portions Copyright (c) 1996-2024, PostgreSQL Global Development Group
+# Portions Copyright (c) 1996-2025, PostgreSQL Global Development Group
# Portions Copyright (c) 1994, Regents of the University of California
#
# src/backend/Makefile
@@ -43,9 +43,10 @@ OBJS = \
$(top_builddir)/src/common/libpgcommon_srv.a \
$(top_builddir)/src/port/libpgport_srv.a
-# We put libpgport and libpgcommon into OBJS, so remove it from LIBS; also add
-# libldap and ICU
-LIBS := $(filter-out -lpgport -lpgcommon, $(LIBS)) $(LDAP_LIBS_BE) $(ICU_LIBS)
+# We put libpgport and libpgcommon into OBJS, so remove it from LIBS.
+LIBS := $(filter-out -lpgport -lpgcommon, $(LIBS))
+# The backend conditionally needs libraries that most executables don't need.
+LIBS += $(LDAP_LIBS_BE) $(ICU_LIBS) $(LIBURING_LIBS)
# The backend doesn't need everything that's in LIBS, however
LIBS := $(filter-out -lreadline -ledit -ltermcap -lncurses -lcurses, $(LIBS))
@@ -133,18 +134,24 @@ submake-utils-headers:
# Make symlinks for these headers in the include directory. That way
# we can cut down on the -I options. Also, a symlink is automatically
# up to date when we update the base file.
+#
+# The point of the prereqdir incantation in some of the rules below is to
+# force the symlink to use an absolute path rather than a relative path.
+# This is needed to support platforms without ln -s.
.PHONY: generated-headers
generated-headers: $(top_builddir)/src/include/storage/lwlocknames.h $(top_builddir)/src/include/utils/wait_event_types.h submake-catalog-headers submake-nodes-headers submake-utils-headers parser/gram.h
$(top_builddir)/src/include/storage/lwlocknames.h: storage/lmgr/lwlocknames.h
- rm -f '$@'
- $(LN_S) ../../backend/$< '$@'
+ prereqdir=`cd '$(dir $<)' >/dev/null && pwd` && \
+ cd '$(dir $@)' && rm -f $(notdir $@) && \
+ $(LN_S) "$$prereqdir/$(notdir $<)" .
$(top_builddir)/src/include/utils/wait_event_types.h: utils/activity/wait_event_types.h
- rm -f '$@'
- $(LN_S) ../../backend/$< '$@'
+ prereqdir=`cd '$(dir $<)' >/dev/null && pwd` && \
+ cd '$(dir $@)' && rm -f $(notdir $@) && \
+ $(LN_S) "$$prereqdir/$(notdir $<)" .
utils/probes.o: utils/probes.d $(SUBDIROBJS)
$(DTRACE) $(DTRACEFLAGS) -C -G -s $(call expand_subsys,$^) -o $@
diff --git a/src/backend/access/brin/brin.c b/src/backend/access/brin/brin.c
index d0f3848c9525e..7ff7467e462b0 100644
--- a/src/backend/access/brin/brin.c
+++ b/src/backend/access/brin/brin.c
@@ -4,7 +4,7 @@
*
* See src/backend/access/brin/README for details.
*
- * Portions Copyright (c) 1996-2024, PostgreSQL Global Development Group
+ * Portions Copyright (c) 1996-2025, PostgreSQL Global Development Group
* Portions Copyright (c) 1994, Regents of the University of California
*
* IDENTIFICATION
@@ -33,7 +33,7 @@
#include "postmaster/autovacuum.h"
#include "storage/bufmgr.h"
#include "storage/freespace.h"
-#include "tcop/tcopprot.h" /* pgrminclude ignore */
+#include "tcop/tcopprot.h"
#include "utils/acl.h"
#include "utils/datum.h"
#include "utils/fmgrprotos.h"
@@ -67,6 +67,9 @@ typedef struct BrinShared
BlockNumber pagesPerRange;
int scantuplesortstates;
+ /* Query ID, for report in worker processes */
+ int64 queryid;
+
/*
* workersdonecv is used to monitor the progress of workers. All parallel
* participants must indicate that they are done before leader can use
@@ -229,11 +232,11 @@ static void _brin_begin_parallel(BrinBuildState *buildstate, Relation heap, Rela
bool isconcurrent, int request);
static void _brin_end_parallel(BrinLeader *brinleader, BrinBuildState *state);
static Size _brin_parallel_estimate_shared(Relation heap, Snapshot snapshot);
-static double _brin_parallel_heapscan(BrinBuildState *buildstate);
-static double _brin_parallel_merge(BrinBuildState *buildstate);
+static double _brin_parallel_heapscan(BrinBuildState *state);
+static double _brin_parallel_merge(BrinBuildState *state);
static void _brin_leader_participate_as_worker(BrinBuildState *buildstate,
Relation heap, Relation index);
-static void _brin_parallel_scan_and_build(BrinBuildState *buildstate,
+static void _brin_parallel_scan_and_build(BrinBuildState *state,
BrinShared *brinshared,
Sharedsort *sharedsort,
Relation heap, Relation index,
@@ -253,6 +256,9 @@ brinhandler(PG_FUNCTION_ARGS)
amroutine->amoptsprocnum = BRIN_PROCNUM_OPTIONS;
amroutine->amcanorder = false;
amroutine->amcanorderbyop = false;
+ amroutine->amcanhash = false;
+ amroutine->amconsistentequality = false;
+ amroutine->amconsistentordering = false;
amroutine->amcanbackward = false;
amroutine->amcanunique = false;
amroutine->amcanmulticol = true;
@@ -279,6 +285,7 @@ brinhandler(PG_FUNCTION_ARGS)
amroutine->amvacuumcleanup = brinvacuumcleanup;
amroutine->amcanreturn = NULL;
amroutine->amcostestimate = brincostestimate;
+ amroutine->amgettreeheight = NULL;
amroutine->amoptions = brinoptions;
amroutine->amproperty = NULL;
amroutine->ambuildphasename = NULL;
@@ -294,6 +301,8 @@ brinhandler(PG_FUNCTION_ARGS)
amroutine->amestimateparallelscan = NULL;
amroutine->aminitparallelscan = NULL;
amroutine->amparallelrescan = NULL;
+ amroutine->amtranslatestrategy = NULL;
+ amroutine->amtranslatecmptype = NULL;
PG_RETURN_POINTER(amroutine);
}
@@ -505,16 +514,18 @@ brininsertcleanup(Relation index, IndexInfo *indexInfo)
BrinInsertState *bistate = (BrinInsertState *) indexInfo->ii_AmCache;
/* bail out if cache not initialized */
- if (indexInfo->ii_AmCache == NULL)
+ if (bistate == NULL)
return;
+ /* do this first to avoid dangling pointer if we fail partway through */
+ indexInfo->ii_AmCache = NULL;
+
/*
* Clean up the revmap. Note that the brinDesc has already been cleaned up
* as part of its own memory context.
*/
brinRevmapTerminate(bistate->bis_rmAccess);
- bistate->bis_rmAccess = NULL;
- bistate->bis_desc = NULL;
+ pfree(bistate);
}
/*
@@ -563,7 +574,7 @@ bringetbitmap(IndexScanDesc scan, TIDBitmap *tbm)
BrinOpaque *opaque;
BlockNumber nblocks;
BlockNumber heapBlk;
- int totalpages = 0;
+ int64 totalpages = 0;
FmgrInfo *consistentFn;
MemoryContext oldcxt;
MemoryContext perRangeCxt;
@@ -581,6 +592,8 @@ bringetbitmap(IndexScanDesc scan, TIDBitmap *tbm)
opaque = (BrinOpaque *) scan->opaque;
bdesc = opaque->bo_bdesc;
pgstat_count_index_scan(idxRel);
+ if (scan->instrument)
+ scan->instrument->nsearches++;
/*
* We need to know the size of the table so that we know how long to
@@ -955,8 +968,7 @@ brinrescan(IndexScanDesc scan, ScanKey scankey, int nscankeys,
*/
if (scankey && scan->numberOfKeys > 0)
- memmove(scan->keyData, scankey,
- scan->numberOfKeys * sizeof(ScanKeyData));
+ memcpy(scan->keyData, scankey, scan->numberOfKeys * sizeof(ScanKeyData));
}
/*
@@ -1130,7 +1142,7 @@ brinbuild(Relation heap, Relation index, IndexInfo *indexInfo)
xlrec.pagesPerRange = BrinGetPagesPerRange(index);
XLogBeginInsert();
- XLogRegisterData((char *) &xlrec, SizeOfBrinCreateIdx);
+ XLogRegisterData(&xlrec, SizeOfBrinCreateIdx);
XLogRegisterBuffer(0, meta, REGBUF_WILL_INIT | REGBUF_STANDARD);
recptr = XLogInsert(RM_BRIN_ID, XLOG_BRIN_CREATE_INDEX);
@@ -1219,7 +1231,7 @@ brinbuild(Relation heap, Relation index, IndexInfo *indexInfo)
* generate summary for the same range twice).
*/
reltuples = table_index_build_scan(heap, index, indexInfo, false, true,
- brinbuildCallback, (void *) state, NULL);
+ brinbuildCallback, state, NULL);
/*
* process the final batch
@@ -1388,8 +1400,7 @@ brin_summarize_range(PG_FUNCTION_ARGS)
if (heapBlk64 > BRIN_ALL_BLOCKRANGES || heapBlk64 < 0)
ereport(ERROR,
(errcode(ERRCODE_NUMERIC_VALUE_OUT_OF_RANGE),
- errmsg("block number out of range: %lld",
- (long long) heapBlk64)));
+ errmsg("block number out of range: %" PRId64, heapBlk64)));
heapBlk = (BlockNumber) heapBlk64;
/*
@@ -1496,8 +1507,8 @@ brin_desummarize_range(PG_FUNCTION_ARGS)
if (heapBlk64 > MaxBlockNumber || heapBlk64 < 0)
ereport(ERROR,
(errcode(ERRCODE_NUMERIC_VALUE_OUT_OF_RANGE),
- errmsg("block number out of range: %lld",
- (long long) heapBlk64)));
+ errmsg("block number out of range: %" PRId64,
+ heapBlk64)));
heapBlk = (BlockNumber) heapBlk64;
/*
@@ -1597,7 +1608,7 @@ brin_build_desc(Relation rel)
opcInfoFn = index_getprocinfo(rel, keyno + 1, BRIN_PROCNUM_OPCINFO);
opcinfo[keyno] = (BrinOpcInfo *)
- DatumGetPointer(FunctionCall1(opcInfoFn, attr->atttypid));
+ DatumGetPointer(FunctionCall1(opcInfoFn, ObjectIdGetDatum(attr->atttypid)));
totalstored += opcinfo[keyno]->oi_nstored;
}
@@ -1805,7 +1816,7 @@ summarize_range(IndexInfo *indexInfo, BrinBuildState *state, Relation heapRel,
state->bs_currRangeStart = heapBlk;
table_index_build_range_scan(heapRel, state->bs_irel, indexInfo, false, true, false,
heapBlk, scanNumBlks,
- brinbuildCallback, (void *) state, NULL);
+ brinbuildCallback, state, NULL);
/*
* Now we update the values obtained by the scan with the placeholder
@@ -2251,7 +2262,7 @@ add_values_to_range(Relation idxRel, BrinDesc *bdesc, BrinMemTuple *dtup,
PointerGetDatum(bdesc),
PointerGetDatum(bval),
values[keyno],
- nulls[keyno]);
+ BoolGetDatum(nulls[keyno]));
/* if that returned true, we need to insert the updated tuple */
modified |= DatumGetBool(result);
@@ -2448,6 +2459,7 @@ _brin_begin_parallel(BrinBuildState *buildstate, Relation heap, Relation index,
brinshared->isconcurrent = isconcurrent;
brinshared->scantuplesortstates = scantuplesortstates;
brinshared->pagesPerRange = buildstate->bs_pagesPerRange;
+ brinshared->queryid = pgstat_get_my_query_id();
ConditionVariableInit(&brinshared->workersdonecv);
SpinLockInit(&brinshared->mutex);
@@ -2891,6 +2903,9 @@ _brin_parallel_build_main(dsm_segment *seg, shm_toc *toc)
indexLockmode = RowExclusiveLock;
}
+ /* Track query ID */
+ pgstat_report_query_id(brinshared->queryid, false);
+
/* Open relations within worker */
heapRel = table_open(brinshared->heaprelid, heapLockmode);
indexRel = index_open(brinshared->indexrelid, indexLockmode);
diff --git a/src/backend/access/brin/brin_bloom.c b/src/backend/access/brin/brin_bloom.c
index f94e2b0bfbd95..7c3f7d454fc25 100644
--- a/src/backend/access/brin/brin_bloom.c
+++ b/src/backend/access/brin/brin_bloom.c
@@ -2,7 +2,7 @@
* brin_bloom.c
* Implementation of Bloom opclass for BRIN
*
- * Portions Copyright (c) 1996-2024, PostgreSQL Global Development Group
+ * Portions Copyright (c) 1996-2025, PostgreSQL Global Development Group
* Portions Copyright (c) 1994, Regents of the University of California
*
*
@@ -124,7 +124,6 @@
#include "access/htup_details.h"
#include "access/reloptions.h"
#include "catalog/pg_am.h"
-#include "catalog/pg_amop.h"
#include "catalog/pg_type.h"
#include "common/hashfn.h"
#include "utils/fmgrprotos.h"
@@ -439,7 +438,6 @@ typedef struct BloomOpaque
* consistency. We may need additional procs in the future.
*/
FmgrInfo extra_procinfos[BLOOM_MAX_PROCNUMS];
- bool extra_proc_missing[BLOOM_MAX_PROCNUMS];
} BloomOpaque;
static FmgrInfo *bloom_get_procinfo(BrinDesc *bdesc, uint16 attno,
@@ -542,7 +540,7 @@ brin_bloom_add_value(PG_FUNCTION_ARGS)
BrinDesc *bdesc = (BrinDesc *) PG_GETARG_POINTER(0);
BrinValues *column = (BrinValues *) PG_GETARG_POINTER(1);
Datum newval = PG_GETARG_DATUM(2);
- bool isnull PG_USED_FOR_ASSERTS_ONLY = PG_GETARG_DATUM(3);
+ bool isnull PG_USED_FOR_ASSERTS_ONLY = PG_GETARG_BOOL(3);
BloomOptions *opts = (BloomOptions *) PG_GET_OPCLASS_OPTIONS();
Oid colloid = PG_GET_COLLATION();
FmgrInfo *hashFn;
@@ -694,6 +692,17 @@ brin_bloom_union(PG_FUNCTION_ARGS)
/* update the number of bits set in the filter */
filter_a->nbits_set = pg_popcount((const char *) filter_a->data, nbytes);
+ /* if we decompressed filter_a, update the summary */
+ if (PointerGetDatum(filter_a) != col_a->bv_values[0])
+ {
+ pfree(DatumGetPointer(col_a->bv_values[0]));
+ col_a->bv_values[0] = PointerGetDatum(filter_a);
+ }
+
+ /* also free filter_b, if it was decompressed */
+ if (PointerGetDatum(filter_b) != col_b->bv_values[0])
+ pfree(filter_b);
+
PG_RETURN_VOID();
}
@@ -715,27 +724,19 @@ bloom_get_procinfo(BrinDesc *bdesc, uint16 attno, uint16 procnum)
*/
opaque = (BloomOpaque *) bdesc->bd_info[attno - 1]->oi_opaque;
- /*
- * If we already searched for this proc and didn't find it, don't bother
- * searching again.
- */
- if (opaque->extra_proc_missing[basenum])
- return NULL;
-
if (opaque->extra_procinfos[basenum].fn_oid == InvalidOid)
{
if (RegProcedureIsValid(index_getprocid(bdesc->bd_index, attno,
procnum)))
- {
fmgr_info_copy(&opaque->extra_procinfos[basenum],
index_getprocinfo(bdesc->bd_index, attno, procnum),
bdesc->bd_context);
- }
else
- {
- opaque->extra_proc_missing[basenum] = true;
- return NULL;
- }
+ ereport(ERROR,
+ errcode(ERRCODE_INVALID_OBJECT_DEFINITION),
+ errmsg_internal("invalid opclass definition"),
+ errdetail_internal("The operator class is missing support function %d for column %d.",
+ procnum, attno));
}
return &opaque->extra_procinfos[basenum];
diff --git a/src/backend/access/brin/brin_inclusion.c b/src/backend/access/brin/brin_inclusion.c
index 750276998c5a1..b86ca5744a348 100644
--- a/src/backend/access/brin/brin_inclusion.c
+++ b/src/backend/access/brin/brin_inclusion.c
@@ -16,7 +16,7 @@
* writing is the INET type, where IPv6 values cannot be merged with IPv4
* values.
*
- * Portions Copyright (c) 1996-2024, PostgreSQL Global Development Group
+ * Portions Copyright (c) 1996-2025, PostgreSQL Global Development Group
* Portions Copyright (c) 1994, Regents of the University of California
*
* IDENTIFICATION
@@ -82,7 +82,7 @@ typedef struct InclusionOpaque
} InclusionOpaque;
static FmgrInfo *inclusion_get_procinfo(BrinDesc *bdesc, uint16 attno,
- uint16 procnum);
+ uint16 procnum, bool missing_ok);
static FmgrInfo *inclusion_get_strategy_procinfo(BrinDesc *bdesc, uint16 attno,
Oid subtype, uint16 strategynum);
@@ -146,12 +146,12 @@ brin_inclusion_add_value(PG_FUNCTION_ARGS)
Datum result;
bool new = false;
AttrNumber attno;
- Form_pg_attribute attr;
+ CompactAttribute *attr;
Assert(!isnull);
attno = column->bv_attno;
- attr = TupleDescAttr(bdesc->bd_tupdesc, attno - 1);
+ attr = TupleDescCompactAttr(bdesc->bd_tupdesc, attno - 1);
/*
* If the recorded value is null, copy the new value (which we know to be
@@ -179,7 +179,7 @@ brin_inclusion_add_value(PG_FUNCTION_ARGS)
* new value for emptiness; if it returns true, we need to set the
* "contains empty" flag in the element (unless already set).
*/
- finfo = inclusion_get_procinfo(bdesc, attno, PROCNUM_EMPTY);
+ finfo = inclusion_get_procinfo(bdesc, attno, PROCNUM_EMPTY, true);
if (finfo != NULL && DatumGetBool(FunctionCall1Coll(finfo, colloid, newval)))
{
if (!DatumGetBool(column->bv_values[INCLUSION_CONTAINS_EMPTY]))
@@ -195,7 +195,7 @@ brin_inclusion_add_value(PG_FUNCTION_ARGS)
PG_RETURN_BOOL(true);
/* Check if the new value is already contained. */
- finfo = inclusion_get_procinfo(bdesc, attno, PROCNUM_CONTAINS);
+ finfo = inclusion_get_procinfo(bdesc, attno, PROCNUM_CONTAINS, true);
if (finfo != NULL &&
DatumGetBool(FunctionCall2Coll(finfo, colloid,
column->bv_values[INCLUSION_UNION],
@@ -210,7 +210,7 @@ brin_inclusion_add_value(PG_FUNCTION_ARGS)
* it's not going to be used any longer. However, the BRIN framework
* doesn't allow for the value not being present. Improve someday.
*/
- finfo = inclusion_get_procinfo(bdesc, attno, PROCNUM_MERGEABLE);
+ finfo = inclusion_get_procinfo(bdesc, attno, PROCNUM_MERGEABLE, true);
if (finfo != NULL &&
!DatumGetBool(FunctionCall2Coll(finfo, colloid,
column->bv_values[INCLUSION_UNION],
@@ -221,8 +221,7 @@ brin_inclusion_add_value(PG_FUNCTION_ARGS)
}
/* Finally, merge the new value to the existing union. */
- finfo = inclusion_get_procinfo(bdesc, attno, PROCNUM_MERGE);
- Assert(finfo != NULL);
+ finfo = inclusion_get_procinfo(bdesc, attno, PROCNUM_MERGE, false);
result = FunctionCall2Coll(finfo, colloid,
column->bv_values[INCLUSION_UNION], newval);
if (!attr->attbyval &&
@@ -479,7 +478,7 @@ brin_inclusion_union(PG_FUNCTION_ARGS)
BrinValues *col_b = (BrinValues *) PG_GETARG_POINTER(2);
Oid colloid = PG_GET_COLLATION();
AttrNumber attno;
- Form_pg_attribute attr;
+ CompactAttribute *attr;
FmgrInfo *finfo;
Datum result;
@@ -487,7 +486,7 @@ brin_inclusion_union(PG_FUNCTION_ARGS)
Assert(!col_a->bv_allnulls && !col_b->bv_allnulls);
attno = col_a->bv_attno;
- attr = TupleDescAttr(bdesc->bd_tupdesc, attno - 1);
+ attr = TupleDescCompactAttr(bdesc->bd_tupdesc, attno - 1);
/* If B includes empty elements, mark A similarly, if needed. */
if (!DatumGetBool(col_a->bv_values[INCLUSION_CONTAINS_EMPTY]) &&
@@ -506,7 +505,7 @@ brin_inclusion_union(PG_FUNCTION_ARGS)
}
/* Check if A and B are mergeable; if not, mark A unmergeable. */
- finfo = inclusion_get_procinfo(bdesc, attno, PROCNUM_MERGEABLE);
+ finfo = inclusion_get_procinfo(bdesc, attno, PROCNUM_MERGEABLE, true);
if (finfo != NULL &&
!DatumGetBool(FunctionCall2Coll(finfo, colloid,
col_a->bv_values[INCLUSION_UNION],
@@ -517,8 +516,7 @@ brin_inclusion_union(PG_FUNCTION_ARGS)
}
/* Finally, merge B to A. */
- finfo = inclusion_get_procinfo(bdesc, attno, PROCNUM_MERGE);
- Assert(finfo != NULL);
+ finfo = inclusion_get_procinfo(bdesc, attno, PROCNUM_MERGE, false);
result = FunctionCall2Coll(finfo, colloid,
col_a->bv_values[INCLUSION_UNION],
col_b->bv_values[INCLUSION_UNION]);
@@ -539,10 +537,12 @@ brin_inclusion_union(PG_FUNCTION_ARGS)
* Cache and return inclusion opclass support procedure
*
* Return the procedure corresponding to the given function support number
- * or null if it is not exists.
+ * or null if it is not exists. If missing_ok is true and the procedure
+ * isn't set up for this opclass, return NULL instead of raising an error.
*/
static FmgrInfo *
-inclusion_get_procinfo(BrinDesc *bdesc, uint16 attno, uint16 procnum)
+inclusion_get_procinfo(BrinDesc *bdesc, uint16 attno, uint16 procnum,
+ bool missing_ok)
{
InclusionOpaque *opaque;
uint16 basenum = procnum - PROCNUM_BASE;
@@ -564,13 +564,18 @@ inclusion_get_procinfo(BrinDesc *bdesc, uint16 attno, uint16 procnum)
{
if (RegProcedureIsValid(index_getprocid(bdesc->bd_index, attno,
procnum)))
- {
fmgr_info_copy(&opaque->extra_procinfos[basenum],
index_getprocinfo(bdesc->bd_index, attno, procnum),
bdesc->bd_context);
- }
else
{
+ if (!missing_ok)
+ ereport(ERROR,
+ errcode(ERRCODE_INVALID_OBJECT_DEFINITION),
+ errmsg_internal("invalid opclass definition"),
+ errdetail_internal("The operator class is missing support function %d for column %d.",
+ procnum, attno));
+
opaque->extra_proc_missing[basenum] = true;
return NULL;
}
diff --git a/src/backend/access/brin/brin_minmax.c b/src/backend/access/brin/brin_minmax.c
index caf6991eb1b01..79c5a0aa18578 100644
--- a/src/backend/access/brin/brin_minmax.c
+++ b/src/backend/access/brin/brin_minmax.c
@@ -2,7 +2,7 @@
* brin_minmax.c
* Implementation of Min/Max opclass for BRIN
*
- * Portions Copyright (c) 1996-2024, PostgreSQL Global Development Group
+ * Portions Copyright (c) 1996-2025, PostgreSQL Global Development Group
* Portions Copyright (c) 1994, Regents of the University of California
*
* IDENTIFICATION
@@ -66,7 +66,7 @@ brin_minmax_add_value(PG_FUNCTION_ARGS)
BrinDesc *bdesc = (BrinDesc *) PG_GETARG_POINTER(0);
BrinValues *column = (BrinValues *) PG_GETARG_POINTER(1);
Datum newval = PG_GETARG_DATUM(2);
- bool isnull PG_USED_FOR_ASSERTS_ONLY = PG_GETARG_DATUM(3);
+ bool isnull PG_USED_FOR_ASSERTS_ONLY = PG_GETARG_BOOL(3);
Oid colloid = PG_GET_COLLATION();
FmgrInfo *cmpFn;
Datum compar;
@@ -225,8 +225,8 @@ brin_minmax_union(PG_FUNCTION_ARGS)
/* Adjust minimum, if B's min is less than A's min */
finfo = minmax_get_strategy_procinfo(bdesc, attno, attr->atttypid,
BTLessStrategyNumber);
- needsadj = FunctionCall2Coll(finfo, colloid, col_b->bv_values[0],
- col_a->bv_values[0]);
+ needsadj = DatumGetBool(FunctionCall2Coll(finfo, colloid, col_b->bv_values[0],
+ col_a->bv_values[0]));
if (needsadj)
{
if (!attr->attbyval)
@@ -238,8 +238,8 @@ brin_minmax_union(PG_FUNCTION_ARGS)
/* Adjust maximum, if B's max is greater than A's max */
finfo = minmax_get_strategy_procinfo(bdesc, attno, attr->atttypid,
BTGreaterStrategyNumber);
- needsadj = FunctionCall2Coll(finfo, colloid, col_b->bv_values[1],
- col_a->bv_values[1]);
+ needsadj = DatumGetBool(FunctionCall2Coll(finfo, colloid, col_b->bv_values[1],
+ col_a->bv_values[1]));
if (needsadj)
{
if (!attr->attbyval)
diff --git a/src/backend/access/brin/brin_minmax_multi.c b/src/backend/access/brin/brin_minmax_multi.c
index e5d95de5d84a7..c87f1b9cd7eb2 100644
--- a/src/backend/access/brin/brin_minmax_multi.c
+++ b/src/backend/access/brin/brin_minmax_multi.c
@@ -2,7 +2,7 @@
* brin_minmax_multi.c
* Implementation of Multi Min/Max opclass for BRIN
*
- * Portions Copyright (c) 1996-2024, PostgreSQL Global Development Group
+ * Portions Copyright (c) 1996-2025, PostgreSQL Global Development Group
* Portions Copyright (c) 1994, Regents of the University of California
*
*
@@ -111,7 +111,6 @@
typedef struct MinmaxMultiOpaque
{
FmgrInfo extra_procinfos[MINMAX_MAX_PROCNUMS];
- bool extra_proc_missing[MINMAX_MAX_PROCNUMS];
Oid cached_subtype;
FmgrInfo strategy_procinfos[BTMaxStrategyNumber];
} MinmaxMultiOpaque;
@@ -413,7 +412,7 @@ AssertCheckRanges(Ranges *ranges, FmgrInfo *cmpFn, Oid colloid)
Assert(bsearch_arg(&value, &ranges->values[2 * ranges->nranges],
ranges->nsorted, sizeof(Datum),
- compare_values, (void *) &cxt) == NULL);
+ compare_values, &cxt) == NULL);
}
}
#endif
@@ -550,7 +549,7 @@ range_deduplicate_values(Ranges *range)
/* same as preceding value, so store it */
if (compare_values(&range->values[start + i - 1],
&range->values[start + i],
- (void *) &cxt) == 0)
+ &cxt) == 0)
continue;
range->values[start + n] = range->values[start + i];
@@ -625,7 +624,7 @@ brin_range_serialize(Ranges *range)
for (i = 0; i < nvalues; i++)
{
- len += VARSIZE_ANY(range->values[i]);
+ len += VARSIZE_ANY(DatumGetPointer(range->values[i]));
}
}
else if (typlen == -2) /* cstring */
@@ -1085,7 +1084,7 @@ range_contains_value(BrinDesc *bdesc, Oid colloid,
if (bsearch_arg(&newval, &ranges->values[2 * ranges->nranges],
ranges->nsorted, sizeof(Datum),
- compare_values, (void *) &cxt) != NULL)
+ compare_values, &cxt) != NULL)
return true;
}
else
@@ -1206,7 +1205,7 @@ sort_expanded_ranges(FmgrInfo *cmp, Oid colloid,
for (i = 1; i < neranges; i++)
{
/* if the current range is equal to the preceding one, do nothing */
- if (!compare_expanded_ranges(&eranges[i - 1], &eranges[i], (void *) &cxt))
+ if (!compare_expanded_ranges(&eranges[i - 1], &eranges[i], &cxt))
continue;
/* otherwise, copy it to n-th place (if not already there) */
@@ -1993,8 +1992,8 @@ brin_minmax_multi_distance_tid(PG_FUNCTION_ARGS)
double da1,
da2;
- ItemPointer pa1 = (ItemPointer) PG_GETARG_DATUM(0);
- ItemPointer pa2 = (ItemPointer) PG_GETARG_DATUM(1);
+ ItemPointer pa1 = (ItemPointer) PG_GETARG_POINTER(0);
+ ItemPointer pa2 = (ItemPointer) PG_GETARG_POINTER(1);
/*
* We know the values are range boundaries, but the range may be collapsed
@@ -2033,7 +2032,7 @@ brin_minmax_multi_distance_numeric(PG_FUNCTION_ARGS)
d = DirectFunctionCall2(numeric_sub, a2, a1); /* a2 - a1 */
- PG_RETURN_FLOAT8(DirectFunctionCall1(numeric_float8, d));
+ PG_RETURN_DATUM(DirectFunctionCall1(numeric_float8, d));
}
/*
@@ -2415,7 +2414,7 @@ brin_minmax_multi_add_value(PG_FUNCTION_ARGS)
BrinDesc *bdesc = (BrinDesc *) PG_GETARG_POINTER(0);
BrinValues *column = (BrinValues *) PG_GETARG_POINTER(1);
Datum newval = PG_GETARG_DATUM(2);
- bool isnull PG_USED_FOR_ASSERTS_ONLY = PG_GETARG_DATUM(3);
+ bool isnull PG_USED_FOR_ASSERTS_ONLY = PG_GETARG_BOOL(3);
MinMaxMultiOptions *opts = (MinMaxMultiOptions *) PG_GET_OPCLASS_OPTIONS();
Oid colloid = PG_GET_COLLATION();
bool modified = false;
@@ -2872,27 +2871,19 @@ minmax_multi_get_procinfo(BrinDesc *bdesc, uint16 attno, uint16 procnum)
*/
opaque = (MinmaxMultiOpaque *) bdesc->bd_info[attno - 1]->oi_opaque;
- /*
- * If we already searched for this proc and didn't find it, don't bother
- * searching again.
- */
- if (opaque->extra_proc_missing[basenum])
- return NULL;
-
if (opaque->extra_procinfos[basenum].fn_oid == InvalidOid)
{
if (RegProcedureIsValid(index_getprocid(bdesc->bd_index, attno,
procnum)))
- {
fmgr_info_copy(&opaque->extra_procinfos[basenum],
index_getprocinfo(bdesc->bd_index, attno, procnum),
bdesc->bd_context);
- }
else
- {
- opaque->extra_proc_missing[basenum] = true;
- return NULL;
- }
+ ereport(ERROR,
+ errcode(ERRCODE_INVALID_OBJECT_DEFINITION),
+ errmsg_internal("invalid opclass definition"),
+ errdetail_internal("The operator class is missing support function %d for column %d.",
+ procnum, attno));
}
return &opaque->extra_procinfos[basenum];
diff --git a/src/backend/access/brin/brin_pageops.c b/src/backend/access/brin/brin_pageops.c
index b69217c1ec6d5..6d8dd1512d6a7 100644
--- a/src/backend/access/brin/brin_pageops.c
+++ b/src/backend/access/brin/brin_pageops.c
@@ -2,7 +2,7 @@
* brin_pageops.c
* Page-handling routines for BRIN indexes
*
- * Portions Copyright (c) 1996-2024, PostgreSQL Global Development Group
+ * Portions Copyright (c) 1996-2025, PostgreSQL Global Development Group
* Portions Copyright (c) 1994, Regents of the University of California
*
* IDENTIFICATION
@@ -190,10 +190,10 @@ brin_doupdate(Relation idxrel, BlockNumber pagesPerRange,
xlrec.offnum = oldoff;
XLogBeginInsert();
- XLogRegisterData((char *) &xlrec, SizeOfBrinSamepageUpdate);
+ XLogRegisterData(&xlrec, SizeOfBrinSamepageUpdate);
XLogRegisterBuffer(0, oldbuf, REGBUF_STANDARD);
- XLogRegisterBufData(0, (char *) unconstify(BrinTuple *, newtup), newsz);
+ XLogRegisterBufData(0, newtup, newsz);
recptr = XLogInsert(RM_BRIN_ID, info);
@@ -282,10 +282,10 @@ brin_doupdate(Relation idxrel, BlockNumber pagesPerRange,
XLogBeginInsert();
/* new page */
- XLogRegisterData((char *) &xlrec, SizeOfBrinUpdate);
+ XLogRegisterData(&xlrec, SizeOfBrinUpdate);
XLogRegisterBuffer(0, newbuf, REGBUF_STANDARD | (extended ? REGBUF_WILL_INIT : 0));
- XLogRegisterBufData(0, (char *) unconstify(BrinTuple *, newtup), newsz);
+ XLogRegisterBufData(0, newtup, newsz);
/* revmap page */
XLogRegisterBuffer(1, revmapbuf, 0);
@@ -435,10 +435,10 @@ brin_doinsert(Relation idxrel, BlockNumber pagesPerRange,
xlrec.offnum = off;
XLogBeginInsert();
- XLogRegisterData((char *) &xlrec, SizeOfBrinInsert);
+ XLogRegisterData(&xlrec, SizeOfBrinInsert);
XLogRegisterBuffer(0, *buffer, REGBUF_STANDARD | (extended ? REGBUF_WILL_INIT : 0));
- XLogRegisterBufData(0, (char *) tup, itemsz);
+ XLogRegisterBufData(0, tup, itemsz);
XLogRegisterBuffer(1, revmapbuf, 0);
diff --git a/src/backend/access/brin/brin_revmap.c b/src/backend/access/brin/brin_revmap.c
index 5a9ed40ab64a2..4e380ecc71097 100644
--- a/src/backend/access/brin/brin_revmap.c
+++ b/src/backend/access/brin/brin_revmap.c
@@ -12,7 +12,7 @@
* the metapage. When the revmap needs to be expanded, all tuples on the
* regular BRIN page at that block (if any) are moved out of the way.
*
- * Portions Copyright (c) 1996-2024, PostgreSQL Global Development Group
+ * Portions Copyright (c) 1996-2025, PostgreSQL Global Development Group
* Portions Copyright (c) 1994, Regents of the University of California
*
* IDENTIFICATION
@@ -416,7 +416,7 @@ brinRevmapDesummarizeRange(Relation idxrel, BlockNumber heapBlk)
xlrec.regOffset = regOffset;
XLogBeginInsert();
- XLogRegisterData((char *) &xlrec, SizeOfBrinDesummarize);
+ XLogRegisterData(&xlrec, SizeOfBrinDesummarize);
XLogRegisterBuffer(0, revmapBuf, 0);
XLogRegisterBuffer(1, regBuf, REGBUF_STANDARD);
recptr = XLogInsert(RM_BRIN_ID, XLOG_BRIN_DESUMMARIZE);
@@ -627,7 +627,7 @@ revmap_physical_extend(BrinRevmap *revmap)
xlrec.targetBlk = mapBlk;
XLogBeginInsert();
- XLogRegisterData((char *) &xlrec, SizeOfBrinRevmapExtend);
+ XLogRegisterData(&xlrec, SizeOfBrinRevmapExtend);
XLogRegisterBuffer(0, revmap->rm_metaBuf, REGBUF_STANDARD);
XLogRegisterBuffer(1, buf, REGBUF_WILL_INIT);
diff --git a/src/backend/access/brin/brin_tuple.c b/src/backend/access/brin/brin_tuple.c
index 997eb6d822cd6..861f397e6db58 100644
--- a/src/backend/access/brin/brin_tuple.c
+++ b/src/backend/access/brin/brin_tuple.c
@@ -23,7 +23,7 @@
* Note the size of the null bitmask may not be the same as that of the
* datum array.
*
- * Portions Copyright (c) 1996-2024, PostgreSQL Global Development Group
+ * Portions Copyright (c) 1996-2025, PostgreSQL Global Development Group
* Portions Copyright (c) 1994, Regents of the University of California
*
* IDENTIFICATION
@@ -699,17 +699,19 @@ brin_deconstruct_tuple(BrinDesc *brdesc,
datumno < brdesc->bd_info[attnum]->oi_nstored;
datumno++)
{
- Form_pg_attribute thisatt = TupleDescAttr(diskdsc, stored);
+ CompactAttribute *thisatt = TupleDescCompactAttr(diskdsc, stored);
if (thisatt->attlen == -1)
{
- off = att_align_pointer(off, thisatt->attalign, -1,
- tp + off);
+ off = att_pointer_alignby(off,
+ thisatt->attalignby,
+ -1,
+ tp + off);
}
else
{
- /* not varlena, so safe to use att_align_nominal */
- off = att_align_nominal(off, thisatt->attalign);
+ /* not varlena, so safe to use att_nominal_alignby */
+ off = att_nominal_alignby(off, thisatt->attalignby);
}
values[stored++] = fetchatt(thisatt, tp + off);
diff --git a/src/backend/access/brin/brin_validate.c b/src/backend/access/brin/brin_validate.c
index 539ac9cb0645f..915b8628b460e 100644
--- a/src/backend/access/brin/brin_validate.c
+++ b/src/backend/access/brin/brin_validate.c
@@ -3,7 +3,7 @@
* brin_validate.c
* Opclass validator for BRIN.
*
- * Portions Copyright (c) 1996-2024, PostgreSQL Global Development Group
+ * Portions Copyright (c) 1996-2025, PostgreSQL Global Development Group
* Portions Copyright (c) 1994, Regents of the University of California
*
* IDENTIFICATION
@@ -19,9 +19,9 @@
#include "catalog/pg_amop.h"
#include "catalog/pg_amproc.h"
#include "catalog/pg_opclass.h"
-#include "catalog/pg_opfamily.h"
#include "catalog/pg_type.h"
#include "utils/builtins.h"
+#include "utils/lsyscache.h"
#include "utils/regproc.h"
#include "utils/syscache.h"
@@ -42,8 +42,6 @@ brinvalidate(Oid opclassoid)
Oid opfamilyoid;
Oid opcintype;
char *opclassname;
- HeapTuple familytup;
- Form_pg_opfamily familyform;
char *opfamilyname;
CatCList *proclist,
*oprlist;
@@ -65,12 +63,7 @@ brinvalidate(Oid opclassoid)
opclassname = NameStr(classform->opcname);
/* Fetch opfamily information */
- familytup = SearchSysCache1(OPFAMILYOID, ObjectIdGetDatum(opfamilyoid));
- if (!HeapTupleIsValid(familytup))
- elog(ERROR, "cache lookup failed for operator family %u", opfamilyoid);
- familyform = (Form_pg_opfamily) GETSTRUCT(familytup);
-
- opfamilyname = NameStr(familyform->opfname);
+ opfamilyname = get_opfamily_name(opfamilyoid, false);
/* Fetch all operators and support functions of the opfamily */
oprlist = SearchSysCacheList1(AMOPSTRATEGY, ObjectIdGetDatum(opfamilyoid));
@@ -274,7 +267,6 @@ brinvalidate(Oid opclassoid)
ReleaseCatCacheList(proclist);
ReleaseCatCacheList(oprlist);
- ReleaseSysCache(familytup);
ReleaseSysCache(classtup);
return result;
diff --git a/src/backend/access/brin/brin_xlog.c b/src/backend/access/brin/brin_xlog.c
index eb48d5e90da0b..55348140fad3b 100644
--- a/src/backend/access/brin/brin_xlog.c
+++ b/src/backend/access/brin/brin_xlog.c
@@ -2,7 +2,7 @@
* brin_xlog.c
* XLog replay routines for BRIN indexes
*
- * Portions Copyright (c) 1996-2024, PostgreSQL Global Development Group
+ * Portions Copyright (c) 1996-2025, PostgreSQL Global Development Group
* Portions Copyright (c) 1994, Regents of the University of California
*
* IDENTIFICATION
@@ -31,7 +31,7 @@ brin_xlog_createidx(XLogReaderState *record)
/* create the index' metapage */
buf = XLogInitBufferForRedo(record, 0);
Assert(BufferIsValid(buf));
- page = (Page) BufferGetPage(buf);
+ page = BufferGetPage(buf);
brin_metapage_init(page, xlrec->pagesPerRange, xlrec->version);
PageSetLSN(page, lsn);
MarkBufferDirty(buf);
@@ -82,7 +82,7 @@ brin_xlog_insert_update(XLogReaderState *record,
Assert(tuple->bt_blkno == xlrec->heapBlk);
- page = (Page) BufferGetPage(buffer);
+ page = BufferGetPage(buffer);
offnum = xlrec->offnum;
if (PageGetMaxOffsetNumber(page) + 1 < offnum)
elog(PANIC, "brin_xlog_insert_update: invalid max offset number");
@@ -104,7 +104,7 @@ brin_xlog_insert_update(XLogReaderState *record,
ItemPointerData tid;
ItemPointerSet(&tid, regpgno, xlrec->offnum);
- page = (Page) BufferGetPage(buffer);
+ page = BufferGetPage(buffer);
brinSetHeapBlockItemptr(buffer, xlrec->pagesPerRange, xlrec->heapBlk,
tid);
@@ -146,7 +146,7 @@ brin_xlog_update(XLogReaderState *record)
Page page;
OffsetNumber offnum;
- page = (Page) BufferGetPage(buffer);
+ page = BufferGetPage(buffer);
offnum = xlrec->oldOffnum;
@@ -185,7 +185,7 @@ brin_xlog_samepage_update(XLogReaderState *record)
brintuple = (BrinTuple *) XLogRecGetBlockData(record, 0, &tuplen);
- page = (Page) BufferGetPage(buffer);
+ page = BufferGetPage(buffer);
offnum = xlrec->offnum;
@@ -254,7 +254,7 @@ brin_xlog_revmap_extend(XLogReaderState *record)
*/
buf = XLogInitBufferForRedo(record, 1);
- page = (Page) BufferGetPage(buf);
+ page = BufferGetPage(buf);
brin_page_init(page, BRIN_PAGETYPE_REVMAP);
PageSetLSN(page, lsn);
diff --git a/src/backend/access/brin/meson.build b/src/backend/access/brin/meson.build
index 1c784cadbe094..4aa1439721d11 100644
--- a/src/backend/access/brin/meson.build
+++ b/src/backend/access/brin/meson.build
@@ -1,4 +1,4 @@
-# Copyright (c) 2022-2024, PostgreSQL Global Development Group
+# Copyright (c) 2022-2025, PostgreSQL Global Development Group
backend_sources += files(
'brin.c',
diff --git a/src/backend/access/common/attmap.c b/src/backend/access/common/attmap.c
index b0fe27ef57da4..4901ebecef73f 100644
--- a/src/backend/access/common/attmap.c
+++ b/src/backend/access/common/attmap.c
@@ -10,7 +10,7 @@
* columns in a different order, taking into account dropped columns.
* They are also used by the tuple conversion routines in tupconvert.c.
*
- * Portions Copyright (c) 1996-2024, PostgreSQL Global Development Group
+ * Portions Copyright (c) 1996-2025, PostgreSQL Global Development Group
* Portions Copyright (c) 1994, Regents of the University of California
*
*
@@ -96,33 +96,31 @@ build_attrmap_by_position(TupleDesc indesc,
same = true;
for (i = 0; i < n; i++)
{
- Form_pg_attribute att = TupleDescAttr(outdesc, i);
- Oid atttypid;
- int32 atttypmod;
+ Form_pg_attribute outatt = TupleDescAttr(outdesc, i);
- if (att->attisdropped)
+ if (outatt->attisdropped)
continue; /* attrMap->attnums[i] is already 0 */
noutcols++;
- atttypid = att->atttypid;
- atttypmod = att->atttypmod;
for (; j < indesc->natts; j++)
{
- att = TupleDescAttr(indesc, j);
- if (att->attisdropped)
+ Form_pg_attribute inatt = TupleDescAttr(indesc, j);
+
+ if (inatt->attisdropped)
continue;
nincols++;
/* Found matching column, now check type */
- if (atttypid != att->atttypid ||
- (atttypmod != att->atttypmod && atttypmod >= 0))
+ if (outatt->atttypid != inatt->atttypid ||
+ (outatt->atttypmod != inatt->atttypmod && outatt->atttypmod >= 0))
ereport(ERROR,
(errcode(ERRCODE_DATATYPE_MISMATCH),
errmsg_internal("%s", _(msg)),
- errdetail("Returned type %s does not match expected type %s in column %d.",
- format_type_with_typemod(att->atttypid,
- att->atttypmod),
- format_type_with_typemod(atttypid,
- atttypmod),
+ errdetail("Returned type %s does not match expected type %s in column \"%s\" (position %d).",
+ format_type_with_typemod(inatt->atttypid,
+ inatt->atttypmod),
+ format_type_with_typemod(outatt->atttypid,
+ outatt->atttypmod),
+ NameStr(outatt->attname),
noutcols)));
attrMap->attnums[i] = (AttrNumber) (j + 1);
j++;
@@ -135,7 +133,7 @@ build_attrmap_by_position(TupleDesc indesc,
/* Check for unused input columns */
for (; j < indesc->natts; j++)
{
- if (TupleDescAttr(indesc, j)->attisdropped)
+ if (TupleDescCompactAttr(indesc, j)->attisdropped)
continue;
nincols++;
same = false; /* we'll complain below */
@@ -299,8 +297,8 @@ check_attrmap_match(TupleDesc indesc,
for (i = 0; i < attrMap->maplen; i++)
{
- Form_pg_attribute inatt = TupleDescAttr(indesc, i);
- Form_pg_attribute outatt = TupleDescAttr(outdesc, i);
+ CompactAttribute *inatt = TupleDescCompactAttr(indesc, i);
+ CompactAttribute *outatt;
/*
* If the input column has a missing attribute, we need a conversion.
@@ -311,15 +309,17 @@ check_attrmap_match(TupleDesc indesc,
if (attrMap->attnums[i] == (i + 1))
continue;
+ outatt = TupleDescCompactAttr(outdesc, i);
+
/*
* If it's a dropped column and the corresponding input column is also
- * dropped, we don't need a conversion. However, attlen and attalign
- * must agree.
+ * dropped, we don't need a conversion. However, attlen and
+ * attalignby must agree.
*/
if (attrMap->attnums[i] == 0 &&
inatt->attisdropped &&
inatt->attlen == outatt->attlen &&
- inatt->attalign == outatt->attalign)
+ inatt->attalignby == outatt->attalignby)
continue;
return false;
diff --git a/src/backend/access/common/bufmask.c b/src/backend/access/common/bufmask.c
index 10a1e4d7c6c64..bb260cffa6828 100644
--- a/src/backend/access/common/bufmask.c
+++ b/src/backend/access/common/bufmask.c
@@ -5,7 +5,7 @@
* in a page which can be different when the WAL is generated
* and when the WAL is applied.
*
- * Portions Copyright (c) 2016-2024, PostgreSQL Global Development Group
+ * Portions Copyright (c) 2016-2025, PostgreSQL Global Development Group
*
* Contains common routines required for masking a page.
*
diff --git a/src/backend/access/common/detoast.c b/src/backend/access/common/detoast.c
index 3547cdba56eae..6265178774221 100644
--- a/src/backend/access/common/detoast.c
+++ b/src/backend/access/common/detoast.c
@@ -3,7 +3,7 @@
* detoast.c
* Retrieve compressed or external variable size attributes.
*
- * Copyright (c) 2000-2024, PostgreSQL Global Development Group
+ * Copyright (c) 2000-2025, PostgreSQL Global Development Group
*
* IDENTIFICATION
* src/backend/access/common/detoast.c
@@ -88,7 +88,7 @@ detoast_external_attr(struct varlena *attr)
eoh = DatumGetEOHP(PointerGetDatum(attr));
resultsize = EOH_get_flat_size(eoh);
result = (struct varlena *) palloc(resultsize);
- EOH_flatten_into(eoh, (void *) result, resultsize);
+ EOH_flatten_into(eoh, result, resultsize);
}
else
{
diff --git a/src/backend/access/common/heaptuple.c b/src/backend/access/common/heaptuple.c
index 5c89fbbef83a8..1173a6d81b5ed 100644
--- a/src/backend/access/common/heaptuple.c
+++ b/src/backend/access/common/heaptuple.c
@@ -45,7 +45,7 @@
* and we'd like to still refer to them via C struct offsets.
*
*
- * Portions Copyright (c) 1996-2024, PostgreSQL Global Development Group
+ * Portions Copyright (c) 1996-2025, PostgreSQL Global Development Group
* Portions Copyright (c) 1994, Regents of the University of California
*
*
@@ -83,6 +83,10 @@
#define VARLENA_ATT_IS_PACKABLE(att) \
((att)->attstorage != TYPSTORAGE_PLAIN)
+/* FormData_pg_attribute.attstorage != TYPSTORAGE_PLAIN and an attlen of -1 */
+#define COMPACT_ATTR_IS_PACKABLE(att) \
+ ((att)->attlen == -1 && (att)->attispackable)
+
/*
* Setup for caching pass-by-ref missing attributes in a way that survives
* tupleDesc destruction.
@@ -101,7 +105,7 @@ missing_hash(const void *key, Size keysize)
{
const missing_cache_key *entry = (missing_cache_key *) key;
- return hash_bytes((const unsigned char *) entry->value, entry->len);
+ return hash_bytes((const unsigned char *) DatumGetPointer(entry->value), entry->len);
}
static int
@@ -147,12 +151,12 @@ Datum
getmissingattr(TupleDesc tupleDesc,
int attnum, bool *isnull)
{
- Form_pg_attribute att;
+ CompactAttribute *att;
Assert(attnum <= tupleDesc->natts);
Assert(attnum > 0);
- att = TupleDescAttr(tupleDesc, attnum - 1);
+ att = TupleDescCompactAttr(tupleDesc, attnum - 1);
if (att->atthasmissing)
{
@@ -185,7 +189,7 @@ getmissingattr(TupleDesc tupleDesc,
if (att->attlen > 0)
key.len = att->attlen;
else
- key.len = VARSIZE_ANY(attrmiss->am_value);
+ key.len = VARSIZE_ANY(DatumGetPointer(attrmiss->am_value));
key.value = attrmiss->am_value;
entry = hash_search(missing_cache, &key, HASH_ENTER, &found);
@@ -223,15 +227,15 @@ heap_compute_data_size(TupleDesc tupleDesc,
for (i = 0; i < numberOfAttributes; i++)
{
Datum val;
- Form_pg_attribute atti;
+ CompactAttribute *atti;
if (isnull[i])
continue;
val = values[i];
- atti = TupleDescAttr(tupleDesc, i);
+ atti = TupleDescCompactAttr(tupleDesc, i);
- if (ATT_IS_PACKABLE(atti) &&
+ if (COMPACT_ATTR_IS_PACKABLE(atti) &&
VARATT_CAN_MAKE_SHORT(DatumGetPointer(val)))
{
/*
@@ -247,13 +251,13 @@ heap_compute_data_size(TupleDesc tupleDesc,
* we want to flatten the expanded value so that the constructed
* tuple doesn't depend on it
*/
- data_length = att_align_nominal(data_length, atti->attalign);
+ data_length = att_nominal_alignby(data_length, atti->attalignby);
data_length += EOH_get_flat_size(DatumGetEOHP(val));
}
else
{
- data_length = att_align_datum(data_length, atti->attalign,
- atti->attlen, val);
+ data_length = att_datum_alignby(data_length, atti->attalignby,
+ atti->attlen, val);
data_length = att_addlength_datum(data_length, atti->attlen,
val);
}
@@ -268,7 +272,7 @@ heap_compute_data_size(TupleDesc tupleDesc,
* Fill in either a data value or a bit in the null bitmask
*/
static inline void
-fill_val(Form_pg_attribute att,
+fill_val(CompactAttribute *att,
bits8 **bit,
int *bitmask,
char **dataP,
@@ -304,13 +308,13 @@ fill_val(Form_pg_attribute att,
}
/*
- * XXX we use the att_align macros on the pointer value itself, not on an
- * offset. This is a bit of a hack.
+ * XXX we use the att_nominal_alignby macro on the pointer value itself,
+ * not on an offset. This is a bit of a hack.
*/
if (att->attbyval)
{
/* pass-by-value */
- data = (char *) att_align_nominal(data, att->attalign);
+ data = (char *) att_nominal_alignby(data, att->attalignby);
store_att_byval(data, datum, att->attlen);
data_length = att->attlen;
}
@@ -330,8 +334,7 @@ fill_val(Form_pg_attribute att,
*/
ExpandedObjectHeader *eoh = DatumGetEOHP(datum);
- data = (char *) att_align_nominal(data,
- att->attalign);
+ data = (char *) att_nominal_alignby(data, att->attalignby);
data_length = EOH_get_flat_size(eoh);
EOH_flatten_into(eoh, data, data_length);
}
@@ -349,8 +352,7 @@ fill_val(Form_pg_attribute att,
data_length = VARSIZE_SHORT(val);
memcpy(data, val, data_length);
}
- else if (VARLENA_ATT_IS_PACKABLE(att) &&
- VARATT_CAN_MAKE_SHORT(val))
+ else if (att->attispackable && VARATT_CAN_MAKE_SHORT(val))
{
/* convert to short varlena -- no alignment */
data_length = VARATT_CONVERTED_SHORT_SIZE(val);
@@ -360,8 +362,7 @@ fill_val(Form_pg_attribute att,
else
{
/* full 4-byte header varlena */
- data = (char *) att_align_nominal(data,
- att->attalign);
+ data = (char *) att_nominal_alignby(data, att->attalignby);
data_length = VARSIZE(val);
memcpy(data, val, data_length);
}
@@ -370,14 +371,14 @@ fill_val(Form_pg_attribute att,
{
/* cstring ... never needs alignment */
*infomask |= HEAP_HASVARWIDTH;
- Assert(att->attalign == TYPALIGN_CHAR);
+ Assert(att->attalignby == sizeof(char));
data_length = strlen(DatumGetCString(datum)) + 1;
memcpy(data, DatumGetPointer(datum), data_length);
}
else
{
/* fixed-length pass-by-reference */
- data = (char *) att_align_nominal(data, att->attalign);
+ data = (char *) att_nominal_alignby(data, att->attalignby);
Assert(att->attlen > 0);
data_length = att->attlen;
memcpy(data, DatumGetPointer(datum), data_length);
@@ -427,7 +428,7 @@ heap_fill_tuple(TupleDesc tupleDesc,
for (i = 0; i < numberOfAttributes; i++)
{
- Form_pg_attribute attr = TupleDescAttr(tupleDesc, i);
+ CompactAttribute *attr = TupleDescCompactAttr(tupleDesc, i);
fill_val(attr,
bitP ? &bitP : NULL,
@@ -461,7 +462,8 @@ heap_attisnull(HeapTuple tup, int attnum, TupleDesc tupleDesc)
Assert(!tupleDesc || attnum <= tupleDesc->natts);
if (attnum > (int) HeapTupleHeaderGetNatts(tup->t_data))
{
- if (tupleDesc && TupleDescAttr(tupleDesc, attnum - 1)->atthasmissing)
+ if (tupleDesc &&
+ TupleDescCompactAttr(tupleDesc, attnum - 1)->atthasmissing)
return false;
else
return true;
@@ -495,8 +497,8 @@ heap_attisnull(HeapTuple tup, int attnum, TupleDesc tupleDesc)
/* ----------------
* nocachegetattr
*
- * This only gets called from fastgetattr() macro, in cases where
- * we can't use a cacheoffset and the value is not null.
+ * This only gets called from fastgetattr(), in cases where we
+ * can't use a cacheoffset and the value is not null.
*
* This caches attribute offsets in the attribute descriptor.
*
@@ -570,13 +572,13 @@ nocachegetattr(HeapTuple tup,
if (!slow)
{
- Form_pg_attribute att;
+ CompactAttribute *att;
/*
* If we get here, there are no nulls up to and including the target
* attribute. If we have a cached offset, we can use it.
*/
- att = TupleDescAttr(tupleDesc, attnum);
+ att = TupleDescCompactAttr(tupleDesc, attnum);
if (att->attcacheoff >= 0)
return fetchatt(att, tp + att->attcacheoff);
@@ -591,7 +593,7 @@ nocachegetattr(HeapTuple tup,
for (j = 0; j <= attnum; j++)
{
- if (TupleDescAttr(tupleDesc, j)->attlen <= 0)
+ if (TupleDescCompactAttr(tupleDesc, j)->attlen <= 0)
{
slow = true;
break;
@@ -614,23 +616,23 @@ nocachegetattr(HeapTuple tup,
* fixed-width columns, in hope of avoiding future visits to this
* routine.
*/
- TupleDescAttr(tupleDesc, 0)->attcacheoff = 0;
+ TupleDescCompactAttr(tupleDesc, 0)->attcacheoff = 0;
/* we might have set some offsets in the slow path previously */
- while (j < natts && TupleDescAttr(tupleDesc, j)->attcacheoff > 0)
+ while (j < natts && TupleDescCompactAttr(tupleDesc, j)->attcacheoff > 0)
j++;
- off = TupleDescAttr(tupleDesc, j - 1)->attcacheoff +
- TupleDescAttr(tupleDesc, j - 1)->attlen;
+ off = TupleDescCompactAttr(tupleDesc, j - 1)->attcacheoff +
+ TupleDescCompactAttr(tupleDesc, j - 1)->attlen;
for (; j < natts; j++)
{
- Form_pg_attribute att = TupleDescAttr(tupleDesc, j);
+ CompactAttribute *att = TupleDescCompactAttr(tupleDesc, j);
if (att->attlen <= 0)
break;
- off = att_align_nominal(off, att->attalign);
+ off = att_nominal_alignby(off, att->attalignby);
att->attcacheoff = off;
@@ -639,7 +641,7 @@ nocachegetattr(HeapTuple tup,
Assert(j > attnum);
- off = TupleDescAttr(tupleDesc, attnum)->attcacheoff;
+ off = TupleDescCompactAttr(tupleDesc, attnum)->attcacheoff;
}
else
{
@@ -659,7 +661,7 @@ nocachegetattr(HeapTuple tup,
off = 0;
for (i = 0;; i++) /* loop exit is at "break" */
{
- Form_pg_attribute att = TupleDescAttr(tupleDesc, i);
+ CompactAttribute *att = TupleDescCompactAttr(tupleDesc, i);
if (HeapTupleHasNulls(tup) && att_isnull(i, bp))
{
@@ -679,19 +681,19 @@ nocachegetattr(HeapTuple tup,
* either an aligned or unaligned value.
*/
if (usecache &&
- off == att_align_nominal(off, att->attalign))
+ off == att_nominal_alignby(off, att->attalignby))
att->attcacheoff = off;
else
{
- off = att_align_pointer(off, att->attalign, -1,
- tp + off);
+ off = att_pointer_alignby(off, att->attalignby, -1,
+ tp + off);
usecache = false;
}
}
else
{
- /* not varlena, so safe to use att_align_nominal */
- off = att_align_nominal(off, att->attalign);
+ /* not varlena, so safe to use att_nominal_alignby */
+ off = att_nominal_alignby(off, att->attalignby);
if (usecache)
att->attcacheoff = off;
@@ -707,7 +709,7 @@ nocachegetattr(HeapTuple tup,
}
}
- return fetchatt(TupleDescAttr(tupleDesc, attnum), tp + off);
+ return fetchatt(TupleDescCompactAttr(tupleDesc, attnum), tp + off);
}
/* ----------------
@@ -715,8 +717,8 @@ nocachegetattr(HeapTuple tup,
*
* Fetch the value of a system attribute for a tuple.
*
- * This is a support routine for the heap_getattr macro. The macro
- * has already determined that the attnum refers to a system attribute.
+ * This is a support routine for heap_getattr(). The function has already
+ * determined that the attnum refers to a system attribute.
* ----------------
*/
Datum
@@ -785,7 +787,7 @@ heap_copytuple(HeapTuple tuple)
newTuple->t_self = tuple->t_self;
newTuple->t_tableOid = tuple->t_tableOid;
newTuple->t_data = (HeapTupleHeader) ((char *) newTuple + HEAPTUPLESIZE);
- memcpy((char *) newTuple->t_data, (char *) tuple->t_data, tuple->t_len);
+ memcpy(newTuple->t_data, tuple->t_data, tuple->t_len);
return newTuple;
}
@@ -811,7 +813,7 @@ heap_copytuple_with_tuple(HeapTuple src, HeapTuple dest)
dest->t_self = src->t_self;
dest->t_tableOid = src->t_tableOid;
dest->t_data = (HeapTupleHeader) palloc(src->t_len);
- memcpy((char *) dest->t_data, (char *) src->t_data, src->t_len);
+ memcpy(dest->t_data, src->t_data, src->t_len);
}
/*
@@ -892,16 +894,16 @@ expand_tuple(HeapTuple *targetHeapTuple,
{
if (attrmiss[attnum].am_present)
{
- Form_pg_attribute att = TupleDescAttr(tupleDesc, attnum);
+ CompactAttribute *att = TupleDescCompactAttr(tupleDesc, attnum);
- targetDataLen = att_align_datum(targetDataLen,
- att->attalign,
- att->attlen,
- attrmiss[attnum].am_value);
+ targetDataLen = att_datum_alignby(targetDataLen,
+ att->attalignby,
+ att->attlen,
+ attrmiss[attnum].am_value);
- targetDataLen = att_addlength_pointer(targetDataLen,
- att->attlen,
- attrmiss[attnum].am_value);
+ targetDataLen = att_addlength_datum(targetDataLen,
+ att->attlen,
+ attrmiss[attnum].am_value);
}
else
{
@@ -1020,8 +1022,7 @@ expand_tuple(HeapTuple *targetHeapTuple,
/* Now fill in the missing values */
for (attnum = sourceNatts; attnum < natts; attnum++)
{
-
- Form_pg_attribute attr = TupleDescAttr(tupleDesc, attnum);
+ CompactAttribute *attr = TupleDescCompactAttr(tupleDesc, attnum);
if (attrmiss && attrmiss[attnum].am_present)
{
@@ -1096,7 +1097,7 @@ heap_copy_tuple_as_datum(HeapTuple tuple, TupleDesc tupleDesc)
* the given tuple came from disk, rather than from heap_form_tuple).
*/
td = (HeapTupleHeader) palloc(tuple->t_len);
- memcpy((char *) td, (char *) tuple->t_data, tuple->t_len);
+ memcpy(td, tuple->t_data, tuple->t_len);
HeapTupleHeaderSetDatumLength(td, tuple->t_len);
HeapTupleHeaderSetTypeId(td, tupleDesc->tdtypeid);
@@ -1370,7 +1371,7 @@ heap_deform_tuple(HeapTuple tuple, TupleDesc tupleDesc,
for (attnum = 0; attnum < natts; attnum++)
{
- Form_pg_attribute thisatt = TupleDescAttr(tupleDesc, attnum);
+ CompactAttribute *thisatt = TupleDescCompactAttr(tupleDesc, attnum);
if (hasnulls && att_isnull(attnum, bp))
{
@@ -1393,19 +1394,19 @@ heap_deform_tuple(HeapTuple tuple, TupleDesc tupleDesc,
* an aligned or unaligned value.
*/
if (!slow &&
- off == att_align_nominal(off, thisatt->attalign))
+ off == att_nominal_alignby(off, thisatt->attalignby))
thisatt->attcacheoff = off;
else
{
- off = att_align_pointer(off, thisatt->attalign, -1,
- tp + off);
+ off = att_pointer_alignby(off, thisatt->attalignby, -1,
+ tp + off);
slow = true;
}
}
else
{
- /* not varlena, so safe to use att_align_nominal */
- off = att_align_nominal(off, thisatt->attalign);
+ /* not varlena, so safe to use att_nominal_alignby */
+ off = att_nominal_alignby(off, thisatt->attalignby);
if (!slow)
thisatt->attcacheoff = off;
@@ -1451,9 +1452,11 @@ heap_freetuple(HeapTuple htup)
MinimalTuple
heap_form_minimal_tuple(TupleDesc tupleDescriptor,
const Datum *values,
- const bool *isnull)
+ const bool *isnull,
+ Size extra)
{
MinimalTuple tuple; /* return tuple */
+ char *mem;
Size len,
data_len;
int hoff;
@@ -1461,6 +1464,8 @@ heap_form_minimal_tuple(TupleDesc tupleDescriptor,
int numberOfAttributes = tupleDescriptor->natts;
int i;
+ Assert(extra == MAXALIGN(extra));
+
if (numberOfAttributes > MaxTupleAttributeNumber)
ereport(ERROR,
(errcode(ERRCODE_TOO_MANY_COLUMNS),
@@ -1496,7 +1501,9 @@ heap_form_minimal_tuple(TupleDesc tupleDescriptor,
/*
* Allocate and zero the space needed.
*/
- tuple = (MinimalTuple) palloc0(len);
+ mem = palloc0(len + extra);
+ memset(mem, 0, extra);
+ tuple = (MinimalTuple) (mem + extra);
/*
* And fill in the information.
@@ -1532,11 +1539,15 @@ heap_free_minimal_tuple(MinimalTuple mtup)
* The result is allocated in the current memory context.
*/
MinimalTuple
-heap_copy_minimal_tuple(MinimalTuple mtup)
+heap_copy_minimal_tuple(MinimalTuple mtup, Size extra)
{
MinimalTuple result;
+ char *mem;
- result = (MinimalTuple) palloc(mtup->t_len);
+ Assert(extra == MAXALIGN(extra));
+ mem = palloc(mtup->t_len + extra);
+ memset(mem, 0, extra);
+ result = (MinimalTuple) (mem + extra);
memcpy(result, mtup, mtup->t_len);
return result;
}
@@ -1573,15 +1584,20 @@ heap_tuple_from_minimal_tuple(MinimalTuple mtup)
* The result is allocated in the current memory context.
*/
MinimalTuple
-minimal_tuple_from_heap_tuple(HeapTuple htup)
+minimal_tuple_from_heap_tuple(HeapTuple htup, Size extra)
{
MinimalTuple result;
+ char *mem;
uint32 len;
+ Assert(extra == MAXALIGN(extra));
Assert(htup->t_len > MINIMAL_TUPLE_OFFSET);
len = htup->t_len - MINIMAL_TUPLE_OFFSET;
- result = (MinimalTuple) palloc(len);
+ mem = palloc(len + extra);
+ memset(mem, 0, extra);
+ result = (MinimalTuple) (mem + extra);
memcpy(result, (char *) htup->t_data + MINIMAL_TUPLE_OFFSET, len);
+
result->t_len = len;
return result;
}
diff --git a/src/backend/access/common/indextuple.c b/src/backend/access/common/indextuple.c
index bb2c6a2bcc15d..1986b943a28be 100644
--- a/src/backend/access/common/indextuple.c
+++ b/src/backend/access/common/indextuple.c
@@ -4,7 +4,7 @@
* This file contains index tuple accessor and mutator routines,
* as well as various tuple utilities.
*
- * Portions Copyright (c) 1996-2024, PostgreSQL Global Development Group
+ * Portions Copyright (c) 1996-2025, PostgreSQL Global Development Group
* Portions Copyright (c) 1994, Regents of the University of California
*
*
@@ -303,13 +303,13 @@ nocache_index_getattr(IndexTuple tup,
if (!slow)
{
- Form_pg_attribute att;
+ CompactAttribute *att;
/*
* If we get here, there are no nulls up to and including the target
* attribute. If we have a cached offset, we can use it.
*/
- att = TupleDescAttr(tupleDesc, attnum);
+ att = TupleDescCompactAttr(tupleDesc, attnum);
if (att->attcacheoff >= 0)
return fetchatt(att, tp + att->attcacheoff);
@@ -324,7 +324,7 @@ nocache_index_getattr(IndexTuple tup,
for (j = 0; j <= attnum; j++)
{
- if (TupleDescAttr(tupleDesc, j)->attlen <= 0)
+ if (TupleDescCompactAttr(tupleDesc, j)->attlen <= 0)
{
slow = true;
break;
@@ -347,23 +347,23 @@ nocache_index_getattr(IndexTuple tup,
* fixed-width columns, in hope of avoiding future visits to this
* routine.
*/
- TupleDescAttr(tupleDesc, 0)->attcacheoff = 0;
+ TupleDescCompactAttr(tupleDesc, 0)->attcacheoff = 0;
/* we might have set some offsets in the slow path previously */
- while (j < natts && TupleDescAttr(tupleDesc, j)->attcacheoff > 0)
+ while (j < natts && TupleDescCompactAttr(tupleDesc, j)->attcacheoff > 0)
j++;
- off = TupleDescAttr(tupleDesc, j - 1)->attcacheoff +
- TupleDescAttr(tupleDesc, j - 1)->attlen;
+ off = TupleDescCompactAttr(tupleDesc, j - 1)->attcacheoff +
+ TupleDescCompactAttr(tupleDesc, j - 1)->attlen;
for (; j < natts; j++)
{
- Form_pg_attribute att = TupleDescAttr(tupleDesc, j);
+ CompactAttribute *att = TupleDescCompactAttr(tupleDesc, j);
if (att->attlen <= 0)
break;
- off = att_align_nominal(off, att->attalign);
+ off = att_nominal_alignby(off, att->attalignby);
att->attcacheoff = off;
@@ -372,7 +372,7 @@ nocache_index_getattr(IndexTuple tup,
Assert(j > attnum);
- off = TupleDescAttr(tupleDesc, attnum)->attcacheoff;
+ off = TupleDescCompactAttr(tupleDesc, attnum)->attcacheoff;
}
else
{
@@ -392,7 +392,7 @@ nocache_index_getattr(IndexTuple tup,
off = 0;
for (i = 0;; i++) /* loop exit is at "break" */
{
- Form_pg_attribute att = TupleDescAttr(tupleDesc, i);
+ CompactAttribute *att = TupleDescCompactAttr(tupleDesc, i);
if (IndexTupleHasNulls(tup) && att_isnull(i, bp))
{
@@ -412,19 +412,19 @@ nocache_index_getattr(IndexTuple tup,
* either an aligned or unaligned value.
*/
if (usecache &&
- off == att_align_nominal(off, att->attalign))
+ off == att_nominal_alignby(off, att->attalignby))
att->attcacheoff = off;
else
{
- off = att_align_pointer(off, att->attalign, -1,
- tp + off);
+ off = att_pointer_alignby(off, att->attalignby, -1,
+ tp + off);
usecache = false;
}
}
else
{
- /* not varlena, so safe to use att_align_nominal */
- off = att_align_nominal(off, att->attalign);
+ /* not varlena, so safe to use att_nominal_alignby */
+ off = att_nominal_alignby(off, att->attalignby);
if (usecache)
att->attcacheoff = off;
@@ -440,7 +440,7 @@ nocache_index_getattr(IndexTuple tup,
}
}
- return fetchatt(TupleDescAttr(tupleDesc, attnum), tp + off);
+ return fetchatt(TupleDescCompactAttr(tupleDesc, attnum), tp + off);
}
/*
@@ -490,7 +490,7 @@ index_deform_tuple_internal(TupleDesc tupleDescriptor,
for (attnum = 0; attnum < natts; attnum++)
{
- Form_pg_attribute thisatt = TupleDescAttr(tupleDescriptor, attnum);
+ CompactAttribute *thisatt = TupleDescCompactAttr(tupleDescriptor, attnum);
if (hasnulls && att_isnull(attnum, bp))
{
@@ -513,19 +513,19 @@ index_deform_tuple_internal(TupleDesc tupleDescriptor,
* an aligned or unaligned value.
*/
if (!slow &&
- off == att_align_nominal(off, thisatt->attalign))
+ off == att_nominal_alignby(off, thisatt->attalignby))
thisatt->attcacheoff = off;
else
{
- off = att_align_pointer(off, thisatt->attalign, -1,
- tp + off);
+ off = att_pointer_alignby(off, thisatt->attalignby, -1,
+ tp + off);
slow = true;
}
}
else
{
- /* not varlena, so safe to use att_align_nominal */
- off = att_align_nominal(off, thisatt->attalign);
+ /* not varlena, so safe to use att_nominal_alignby */
+ off = att_nominal_alignby(off, thisatt->attalignby);
if (!slow)
thisatt->attcacheoff = off;
@@ -587,10 +587,8 @@ index_truncate_tuple(TupleDesc sourceDescriptor, IndexTuple source,
if (leavenatts == sourceDescriptor->natts)
return CopyIndexTuple(source);
- /* Create temporary descriptor to scribble on */
- truncdesc = palloc(TupleDescSize(sourceDescriptor));
- TupleDescCopy(truncdesc, sourceDescriptor);
- truncdesc->natts = leavenatts;
+ /* Create temporary truncated tuple descriptor */
+ truncdesc = CreateTupleDescTruncatedCopy(sourceDescriptor, leavenatts);
/* Deform, form copy of tuple with fewer attributes */
index_deform_tuple(source, truncdesc, values, isnull);
diff --git a/src/backend/access/common/meson.build b/src/backend/access/common/meson.build
index 14090c728fb3a..e3cdbe7a22e1a 100644
--- a/src/backend/access/common/meson.build
+++ b/src/backend/access/common/meson.build
@@ -1,4 +1,4 @@
-# Copyright (c) 2022-2024, PostgreSQL Global Development Group
+# Copyright (c) 2022-2025, PostgreSQL Global Development Group
backend_sources += files(
'attmap.c',
diff --git a/src/backend/access/common/printsimple.c b/src/backend/access/common/printsimple.c
index 4c5eedcdc1795..a09c8fcd3323e 100644
--- a/src/backend/access/common/printsimple.c
+++ b/src/backend/access/common/printsimple.c
@@ -8,7 +8,7 @@
* doesn't handle standalone backends or protocol versions other than
* 3.0, because we don't need such handling for current applications.
*
- * Portions Copyright (c) 1996-2024, PostgreSQL Global Development Group
+ * Portions Copyright (c) 1996-2025, PostgreSQL Global Development Group
* Portions Copyright (c) 1994, Regents of the University of California
*
* IDENTIFICATION
@@ -123,7 +123,7 @@ printsimple(TupleTableSlot *slot, DestReceiver *self)
case OIDOID:
{
- Oid num = ObjectIdGetDatum(value);
+ Oid num = DatumGetObjectId(value);
char str[10]; /* 10 digits */
int len;
diff --git a/src/backend/access/common/printtup.c b/src/backend/access/common/printtup.c
index f2d5ca14feea5..6d3045e233211 100644
--- a/src/backend/access/common/printtup.c
+++ b/src/backend/access/common/printtup.c
@@ -5,7 +5,7 @@
* clients and standalone backends are supported here).
*
*
- * Portions Copyright (c) 1996-2024, PostgreSQL Global Development Group
+ * Portions Copyright (c) 1996-2025, PostgreSQL Global Development Group
* Portions Copyright (c) 1994, Regents of the University of California
*
* IDENTIFICATION
@@ -17,6 +17,7 @@
#include "access/printtup.h"
#include "libpq/pqformat.h"
+#include "libpq/protocol.h"
#include "tcop/pquery.h"
#include "utils/lsyscache.h"
#include "utils/memdebug.h"
@@ -170,7 +171,7 @@ SendRowDescriptionMessage(StringInfo buf, TupleDesc typeinfo,
ListCell *tlist_item = list_head(targetlist);
/* tuple descriptor message type */
- pq_beginmessage_reuse(buf, 'T');
+ pq_beginmessage_reuse(buf, PqMsg_RowDescription);
/* # of attrs in tuples */
pq_sendint16(buf, natts);
@@ -322,7 +323,7 @@ printtup(TupleTableSlot *slot, DestReceiver *self)
/*
* Prepare a DataRow message (note buffer is in per-query context)
*/
- pq_beginmessage_reuse(buf, 'D');
+ pq_beginmessage_reuse(buf, PqMsg_DataRow);
pq_sendint16(buf, natts);
@@ -349,7 +350,7 @@ printtup(TupleTableSlot *slot, DestReceiver *self)
*/
if (thisState->typisvarlena)
VALGRIND_CHECK_MEM_IS_DEFINED(DatumGetPointer(attr),
- VARSIZE_ANY(attr));
+ VARSIZE_ANY(DatumGetPointer(attr)));
if (thisState->format == 0)
{
diff --git a/src/backend/access/common/relation.c b/src/backend/access/common/relation.c
index d8a313a2c906f..22c4cd5a25658 100644
--- a/src/backend/access/common/relation.c
+++ b/src/backend/access/common/relation.c
@@ -3,7 +3,7 @@
* relation.c
* Generic relation related routines.
*
- * Portions Copyright (c) 1996-2024, PostgreSQL Global Development Group
+ * Portions Copyright (c) 1996-2025, PostgreSQL Global Development Group
* Portions Copyright (c) 1994, Regents of the University of California
*
*
diff --git a/src/backend/access/common/reloptions.c b/src/backend/access/common/reloptions.c
index d6eb5d8559939..0af3fea68fa48 100644
--- a/src/backend/access/common/reloptions.c
+++ b/src/backend/access/common/reloptions.c
@@ -3,7 +3,7 @@
* reloptions.c
* Core support for relation options (pg_class.reloptions)
*
- * Portions Copyright (c) 1996-2024, PostgreSQL Global Development Group
+ * Portions Copyright (c) 1996-2025, PostgreSQL Global Development Group
* Portions Copyright (c) 1994, Regents of the University of California
*
*
@@ -231,6 +231,15 @@ static relopt_int intRelOpts[] =
},
-1, 0, INT_MAX
},
+ {
+ {
+ "autovacuum_vacuum_max_threshold",
+ "Maximum number of tuple updates or deletes prior to vacuum",
+ RELOPT_KIND_HEAP | RELOPT_KIND_TOAST,
+ ShareUpdateExclusiveLock
+ },
+ -2, -1, INT_MAX
+ },
{
{
"autovacuum_vacuum_insert_threshold",
@@ -352,11 +361,7 @@ static relopt_int intRelOpts[] =
RELOPT_KIND_TABLESPACE,
ShareUpdateExclusiveLock
},
-#ifdef USE_PREFETCH
-1, 0, MAX_IO_CONCURRENCY
-#else
- 0, 0, 0
-#endif
},
{
{
@@ -365,11 +370,7 @@ static relopt_int intRelOpts[] =
RELOPT_KIND_TABLESPACE,
ShareUpdateExclusiveLock
},
-#ifdef USE_PREFETCH
-1, 0, MAX_IO_CONCURRENCY
-#else
- 0, 0, 0
-#endif
},
{
{
@@ -423,6 +424,16 @@ static relopt_real realRelOpts[] =
},
-1, 0.0, 100.0
},
+ {
+ {
+ "vacuum_max_eager_freeze_failure_rate",
+ "Fraction of pages in a relation vacuum can scan and fail to freeze before disabling eager scanning.",
+ RELOPT_KIND_HEAP | RELOPT_KIND_TOAST,
+ ShareUpdateExclusiveLock
+ },
+ -1, 0.0, 1.0
+ },
+
{
{
"seq_page_cost",
@@ -1153,8 +1164,8 @@ add_local_string_reloption(local_relopts *relopts, const char *name,
* but we declare them as Datums to avoid including array.h in reloptions.h.
*/
Datum
-transformRelOptions(Datum oldOptions, List *defList, const char *namspace,
- char *validnsps[], bool acceptOidsOff, bool isReset)
+transformRelOptions(Datum oldOptions, List *defList, const char *nameSpace,
+ const char *const validnsps[], bool acceptOidsOff, bool isReset)
{
Datum result;
ArrayBuildState *astate;
@@ -1179,8 +1190,8 @@ transformRelOptions(Datum oldOptions, List *defList, const char *namspace,
for (i = 0; i < noldoptions; i++)
{
- char *text_str = VARDATA(oldoptions[i]);
- int text_len = VARSIZE(oldoptions[i]) - VARHDRSZ;
+ char *text_str = VARDATA(DatumGetPointer(oldoptions[i]));
+ int text_len = VARSIZE(DatumGetPointer(oldoptions[i])) - VARHDRSZ;
/* Search for a match in defList */
foreach(cell, defList)
@@ -1189,14 +1200,14 @@ transformRelOptions(Datum oldOptions, List *defList, const char *namspace,
int kw_len;
/* ignore if not in the same namespace */
- if (namspace == NULL)
+ if (nameSpace == NULL)
{
if (def->defnamespace != NULL)
continue;
}
else if (def->defnamespace == NULL)
continue;
- else if (strcmp(def->defnamespace, namspace) != 0)
+ else if (strcmp(def->defnamespace, nameSpace) != 0)
continue;
kw_len = strlen(def->defname);
@@ -1232,8 +1243,9 @@ transformRelOptions(Datum oldOptions, List *defList, const char *namspace,
}
else
{
- text *t;
+ const char *name;
const char *value;
+ text *t;
Size len;
/*
@@ -1265,14 +1277,14 @@ transformRelOptions(Datum oldOptions, List *defList, const char *namspace,
}
/* ignore if not in the same namespace */
- if (namspace == NULL)
+ if (nameSpace == NULL)
{
if (def->defnamespace != NULL)
continue;
}
else if (def->defnamespace == NULL)
continue;
- else if (strcmp(def->defnamespace, namspace) != 0)
+ else if (strcmp(def->defnamespace, nameSpace) != 0)
continue;
/*
@@ -1280,11 +1292,19 @@ transformRelOptions(Datum oldOptions, List *defList, const char *namspace,
* have just "name", assume "name=true" is meant. Note: the
* namespace is not output.
*/
+ name = def->defname;
if (def->arg != NULL)
value = defGetString(def);
else
value = "true";
+ /* Insist that name not contain "=", else "a=b=c" is ambiguous */
+ if (strchr(name, '=') != NULL)
+ ereport(ERROR,
+ (errcode(ERRCODE_INVALID_PARAMETER_VALUE),
+ errmsg("invalid option name \"%s\": must not contain \"=\"",
+ name)));
+
/*
* This is not a great place for this test, but there's no other
* convenient place to filter the option out. As WITH (oids =
@@ -1292,7 +1312,7 @@ transformRelOptions(Datum oldOptions, List *defList, const char *namspace,
* amount of ugly.
*/
if (acceptOidsOff && def->defnamespace == NULL &&
- strcmp(def->defname, "oids") == 0)
+ strcmp(name, "oids") == 0)
{
if (defGetBoolean(def))
ereport(ERROR,
@@ -1302,11 +1322,11 @@ transformRelOptions(Datum oldOptions, List *defList, const char *namspace,
continue;
}
- len = VARHDRSZ + strlen(def->defname) + 1 + strlen(value);
+ len = VARHDRSZ + strlen(name) + 1 + strlen(value);
/* +1 leaves room for sprintf's trailing null */
t = (text *) palloc(len + 1);
SET_VARSIZE(t, len);
- sprintf(VARDATA(t), "%s=%s", def->defname, value);
+ sprintf(VARDATA(t), "%s=%s", name, value);
astate = accumArrayResult(astate, PointerGetDatum(t),
false, TEXTOID,
@@ -1436,8 +1456,8 @@ parseRelOptionsInternal(Datum options, bool validate,
for (i = 0; i < noptions; i++)
{
- char *text_str = VARDATA(optiondatums[i]);
- int text_len = VARSIZE(optiondatums[i]) - VARHDRSZ;
+ char *text_str = VARDATA(DatumGetPointer(optiondatums[i]));
+ int text_len = VARSIZE(DatumGetPointer(optiondatums[i])) - VARHDRSZ;
int j;
/* Search for a match in reloptions */
@@ -1760,6 +1780,17 @@ fillRelOptions(void *rdopts, Size basesize,
char *itempos = ((char *) rdopts) + elems[j].offset;
char *string_val;
+ /*
+ * If isset_offset is provided, store whether the reloption is
+ * set there.
+ */
+ if (elems[j].isset_offset > 0)
+ {
+ char *setpos = ((char *) rdopts) + elems[j].isset_offset;
+
+ *(bool *) setpos = options[i].isset;
+ }
+
switch (options[i].gen->type)
{
case RELOPT_TYPE_BOOL:
@@ -1843,6 +1874,8 @@ default_reloptions(Datum reloptions, bool validate, relopt_kind kind)
offsetof(StdRdOptions, autovacuum) + offsetof(AutoVacOpts, enabled)},
{"autovacuum_vacuum_threshold", RELOPT_TYPE_INT,
offsetof(StdRdOptions, autovacuum) + offsetof(AutoVacOpts, vacuum_threshold)},
+ {"autovacuum_vacuum_max_threshold", RELOPT_TYPE_INT,
+ offsetof(StdRdOptions, autovacuum) + offsetof(AutoVacOpts, vacuum_max_threshold)},
{"autovacuum_vacuum_insert_threshold", RELOPT_TYPE_INT,
offsetof(StdRdOptions, autovacuum) + offsetof(AutoVacOpts, vacuum_ins_threshold)},
{"autovacuum_analyze_threshold", RELOPT_TYPE_INT,
@@ -1880,7 +1913,9 @@ default_reloptions(Datum reloptions, bool validate, relopt_kind kind)
{"vacuum_index_cleanup", RELOPT_TYPE_ENUM,
offsetof(StdRdOptions, vacuum_index_cleanup)},
{"vacuum_truncate", RELOPT_TYPE_BOOL,
- offsetof(StdRdOptions, vacuum_truncate)}
+ offsetof(StdRdOptions, vacuum_truncate), offsetof(StdRdOptions, vacuum_truncate_set)},
+ {"vacuum_max_eager_freeze_failure_rate", RELOPT_TYPE_REAL,
+ offsetof(StdRdOptions, vacuum_max_eager_freeze_failure_rate)}
};
return (bytea *) build_reloptions(reloptions, validate, kind,
@@ -1958,6 +1993,7 @@ build_local_reloptions(local_relopts *relopts, Datum options, bool validate)
elems[i].optname = opt->option->name;
elems[i].opttype = opt->option->type;
elems[i].offset = opt->offset;
+ elems[i].isset_offset = 0; /* not supported for local relopts yet */
i++;
}
diff --git a/src/backend/access/common/scankey.c b/src/backend/access/common/scankey.c
index 704363af3f54d..2d65ab02dd38e 100644
--- a/src/backend/access/common/scankey.c
+++ b/src/backend/access/common/scankey.c
@@ -3,7 +3,7 @@
* scankey.c
* scan key support code
*
- * Portions Copyright (c) 1996-2024, PostgreSQL Global Development Group
+ * Portions Copyright (c) 1996-2025, PostgreSQL Global Development Group
* Portions Copyright (c) 1994, Regents of the University of California
*
*
diff --git a/src/backend/access/common/session.c b/src/backend/access/common/session.c
index 3f2256f491525..8836f73c90bf1 100644
--- a/src/backend/access/common/session.c
+++ b/src/backend/access/common/session.c
@@ -12,7 +12,7 @@
* Currently this infrastructure is used to share:
* - typemod registry for ephemeral row-types, i.e. BlessTupleDesc etc.
*
- * Portions Copyright (c) 2017-2024, PostgreSQL Global Development Group
+ * Portions Copyright (c) 2017-2025, PostgreSQL Global Development Group
*
* src/backend/access/common/session.c
*
diff --git a/src/backend/access/common/syncscan.c b/src/backend/access/common/syncscan.c
index 8d78d28a6fced..4e2cfc1f7c91c 100644
--- a/src/backend/access/common/syncscan.c
+++ b/src/backend/access/common/syncscan.c
@@ -36,7 +36,7 @@
* ss_report_location - update current scan location
*
*
- * Portions Copyright (c) 1996-2024, PostgreSQL Global Development Group
+ * Portions Copyright (c) 1996-2025, PostgreSQL Global Development Group
* Portions Copyright (c) 1994, Regents of the University of California
*
* IDENTIFICATION
diff --git a/src/backend/access/common/tidstore.c b/src/backend/access/common/tidstore.c
index fb3949d69f69f..5bd75fb499cef 100644
--- a/src/backend/access/common/tidstore.c
+++ b/src/backend/access/common/tidstore.c
@@ -11,7 +11,7 @@
* TidStoreCreateShared(). Other backends can attach to the shared TidStore
* by TidStoreAttach().
*
- * Portions Copyright (c) 1996-2024, PostgreSQL Global Development Group
+ * Portions Copyright (c) 1996-2025, PostgreSQL Global Development Group
* Portions Copyright (c) 1994, Regents of the University of California
*
* IDENTIFICATION
@@ -113,10 +113,10 @@ typedef struct BlocktableEntry
/* Per-backend state for a TidStore */
struct TidStore
{
- /* MemoryContext where the TidStore is allocated */
- MemoryContext context;
-
- /* MemoryContext that the radix tree uses */
+ /*
+ * MemoryContext for the radix tree when using local memory, NULL for
+ * shared memory
+ */
MemoryContext rt_context;
/* Storage for TIDs. Use either one depending on TidStoreIsShared() */
@@ -147,9 +147,6 @@ struct TidStoreIter
TidStoreIterResult output;
};
-static void tidstore_iter_extract_tids(TidStoreIter *iter, BlockNumber blkno,
- BlocktableEntry *page);
-
/*
* Create a TidStore. The TidStore will live in the memory context that is
* CurrentMemoryContext at the time of this call. The TID storage, backed
@@ -170,7 +167,6 @@ TidStoreCreateLocal(size_t max_bytes, bool insert_only)
size_t maxBlockSize = ALLOCSET_DEFAULT_MAXSIZE;
ts = palloc0(sizeof(TidStore));
- ts->context = CurrentMemoryContext;
/* choose the maxBlockSize to be no larger than 1/16 of max_bytes */
while (16 * maxBlockSize > max_bytes)
@@ -204,8 +200,7 @@ TidStoreCreateLocal(size_t max_bytes, bool insert_only)
/*
* Similar to TidStoreCreateLocal() but create a shared TidStore on a
- * DSA area. The TID storage will live in the DSA area, and the memory
- * context rt_context will have only meta data of the radix tree.
+ * DSA area.
*
* The returned object is allocated in backend-local memory.
*/
@@ -218,11 +213,6 @@ TidStoreCreateShared(size_t max_bytes, int tranche_id)
size_t dsa_max_size = DSA_MAX_SEGMENT_SIZE;
ts = palloc0(sizeof(TidStore));
- ts->context = CurrentMemoryContext;
-
- ts->rt_context = AllocSetContextCreate(CurrentMemoryContext,
- "TID storage meta data",
- ALLOCSET_SMALL_SIZES);
/*
* Choose the initial and maximum DSA segment sizes to be no longer than
@@ -238,8 +228,7 @@ TidStoreCreateShared(size_t max_bytes, int tranche_id)
dsa_init_size = dsa_max_size;
area = dsa_create_ext(tranche_id, dsa_init_size, dsa_max_size);
- ts->tree.shared = shared_ts_create(ts->rt_context, area,
- tranche_id);
+ ts->tree.shared = shared_ts_create(area, tranche_id);
ts->area = area;
return ts;
@@ -331,13 +320,13 @@ TidStoreDestroy(TidStore *ts)
if (TidStoreIsShared(ts))
{
shared_ts_free(ts->tree.shared);
-
dsa_detach(ts->area);
}
else
+ {
local_ts_free(ts->tree.local);
-
- MemoryContextDelete(ts->rt_context);
+ MemoryContextDelete(ts->rt_context);
+ }
pfree(ts);
}
@@ -486,13 +475,6 @@ TidStoreBeginIterate(TidStore *ts)
iter = palloc0(sizeof(TidStoreIter));
iter->ts = ts;
- /*
- * We start with an array large enough to contain at least the offsets
- * from one completely full bitmap element.
- */
- iter->output.max_offset = 2 * BITS_PER_BITMAPWORD;
- iter->output.offsets = palloc(sizeof(OffsetNumber) * iter->output.max_offset);
-
if (TidStoreIsShared(ts))
iter->tree_iter.shared = shared_ts_begin_iterate(ts->tree.shared);
else
@@ -503,9 +485,9 @@ TidStoreBeginIterate(TidStore *ts)
/*
- * Scan the TidStore and return the TIDs of the next block. The offsets in
- * each iteration result are ordered, as are the block numbers over all
- * iterations.
+ * Return a result that contains the next block number and that can be used to
+ * obtain the set of offsets by calling TidStoreGetBlockOffsets(). The result
+ * is copyable.
*/
TidStoreIterResult *
TidStoreIterateNext(TidStoreIter *iter)
@@ -521,8 +503,8 @@ TidStoreIterateNext(TidStoreIter *iter)
if (page == NULL)
return NULL;
- /* Collect TIDs from the key-value pair */
- tidstore_iter_extract_tids(iter, (BlockNumber) key, page);
+ iter->output.blkno = key;
+ iter->output.internal_page = page;
return &(iter->output);
}
@@ -540,7 +522,6 @@ TidStoreEndIterate(TidStoreIter *iter)
else
local_ts_end_iterate(iter->tree_iter.local);
- pfree(iter->output.offsets);
pfree(iter);
}
@@ -575,24 +556,32 @@ TidStoreGetHandle(TidStore *ts)
return (dsa_pointer) shared_ts_get_handle(ts->tree.shared);
}
-/* Extract TIDs from the given key-value pair */
-static void
-tidstore_iter_extract_tids(TidStoreIter *iter, BlockNumber blkno,
- BlocktableEntry *page)
+/*
+ * Given a TidStoreIterResult returned by TidStoreIterateNext(), extract the
+ * offset numbers. Returns the number of offsets filled in, if <=
+ * max_offsets. Otherwise, fills in as much as it can in the given space, and
+ * returns the size of the buffer that would be needed.
+ */
+int
+TidStoreGetBlockOffsets(TidStoreIterResult *result,
+ OffsetNumber *offsets,
+ int max_offsets)
{
- TidStoreIterResult *result = (&iter->output);
+ BlocktableEntry *page = result->internal_page;
+ int num_offsets = 0;
int wordnum;
- result->num_offsets = 0;
- result->blkno = blkno;
-
if (page->header.nwords == 0)
{
/* we have offsets in the header */
for (int i = 0; i < NUM_FULL_OFFSETS; i++)
{
if (page->header.full_offsets[i] != InvalidOffsetNumber)
- result->offsets[result->num_offsets++] = page->header.full_offsets[i];
+ {
+ if (num_offsets < max_offsets)
+ offsets[num_offsets] = page->header.full_offsets[i];
+ num_offsets++;
+ }
}
}
else
@@ -602,21 +591,19 @@ tidstore_iter_extract_tids(TidStoreIter *iter, BlockNumber blkno,
bitmapword w = page->words[wordnum];
int off = wordnum * BITS_PER_BITMAPWORD;
- /* Make sure there is enough space to add offsets */
- if ((result->num_offsets + BITS_PER_BITMAPWORD) > result->max_offset)
- {
- result->max_offset *= 2;
- result->offsets = repalloc(result->offsets,
- sizeof(OffsetNumber) * result->max_offset);
- }
-
while (w != 0)
{
if (w & 1)
- result->offsets[result->num_offsets++] = (OffsetNumber) off;
+ {
+ if (num_offsets < max_offsets)
+ offsets[num_offsets] = (OffsetNumber) off;
+ num_offsets++;
+ }
off++;
w >>= 1;
}
}
}
+
+ return num_offsets;
}
diff --git a/src/backend/access/common/toast_compression.c b/src/backend/access/common/toast_compression.c
index 52230f31c6821..926f1e4008abe 100644
--- a/src/backend/access/common/toast_compression.c
+++ b/src/backend/access/common/toast_compression.c
@@ -3,7 +3,7 @@
* toast_compression.c
* Functions for toast compression.
*
- * Copyright (c) 2021-2024, PostgreSQL Global Development Group
+ * Copyright (c) 2021-2025, PostgreSQL Global Development Group
*
*
* IDENTIFICATION
@@ -25,11 +25,11 @@
/* GUC */
int default_toast_compression = TOAST_PGLZ_COMPRESSION;
-#define NO_LZ4_SUPPORT() \
+#define NO_COMPRESSION_SUPPORT(method) \
ereport(ERROR, \
(errcode(ERRCODE_FEATURE_NOT_SUPPORTED), \
- errmsg("compression method lz4 not supported"), \
- errdetail("This functionality requires the server to be built with lz4 support.")))
+ errmsg("compression method %s not supported", method), \
+ errdetail("This functionality requires the server to be built with %s support.", method)))
/*
* Compress a varlena using PGLZ.
@@ -139,7 +139,7 @@ struct varlena *
lz4_compress_datum(const struct varlena *value)
{
#ifndef USE_LZ4
- NO_LZ4_SUPPORT();
+ NO_COMPRESSION_SUPPORT("lz4");
return NULL; /* keep compiler quiet */
#else
int32 valsize;
@@ -182,7 +182,7 @@ struct varlena *
lz4_decompress_datum(const struct varlena *value)
{
#ifndef USE_LZ4
- NO_LZ4_SUPPORT();
+ NO_COMPRESSION_SUPPORT("lz4");
return NULL; /* keep compiler quiet */
#else
int32 rawsize;
@@ -215,7 +215,7 @@ struct varlena *
lz4_decompress_datum_slice(const struct varlena *value, int32 slicelength)
{
#ifndef USE_LZ4
- NO_LZ4_SUPPORT();
+ NO_COMPRESSION_SUPPORT("lz4");
return NULL; /* keep compiler quiet */
#else
int32 rawsize;
@@ -289,7 +289,7 @@ CompressionNameToMethod(const char *compression)
else if (strcmp(compression, "lz4") == 0)
{
#ifndef USE_LZ4
- NO_LZ4_SUPPORT();
+ NO_COMPRESSION_SUPPORT("lz4");
#endif
return TOAST_LZ4_COMPRESSION;
}
diff --git a/src/backend/access/common/toast_internals.c b/src/backend/access/common/toast_internals.c
index 90d0654e6298b..a1d0eed8953ba 100644
--- a/src/backend/access/common/toast_internals.c
+++ b/src/backend/access/common/toast_internals.c
@@ -3,7 +3,7 @@
* toast_internals.c
* Functions for internal use by the TOAST system.
*
- * Copyright (c) 2000-2024, PostgreSQL Global Development Group
+ * Copyright (c) 2000-2025, PostgreSQL Global Development Group
*
* IDENTIFICATION
* src/backend/access/common/toast_internals.c
@@ -64,11 +64,11 @@ toast_compress_datum(Datum value, char cmethod)
switch (cmethod)
{
case TOAST_PGLZ_COMPRESSION:
- tmp = pglz_compress_datum((const struct varlena *) value);
+ tmp = pglz_compress_datum((const struct varlena *) DatumGetPointer(value));
cmid = TOAST_PGLZ_COMPRESSION_ID;
break;
case TOAST_LZ4_COMPRESSION:
- tmp = lz4_compress_datum((const struct varlena *) value);
+ tmp = lz4_compress_datum((const struct varlena *) DatumGetPointer(value));
cmid = TOAST_LZ4_COMPRESSION_ID;
break;
default:
@@ -144,7 +144,7 @@ toast_save_datum(Relation rel, Datum value,
int num_indexes;
int validIndex;
- Assert(!VARATT_IS_EXTERNAL(value));
+ Assert(!VARATT_IS_EXTERNAL(dval));
/*
* Open the toast relation and its indexes. We can use the index to check
@@ -393,7 +393,6 @@ toast_delete_datum(Relation rel, Datum value, bool is_speculative)
HeapTuple toasttup;
int num_indexes;
int validIndex;
- SnapshotData SnapshotToast;
if (!VARATT_IS_EXTERNAL_ONDISK(attr))
return;
@@ -425,9 +424,8 @@ toast_delete_datum(Relation rel, Datum value, bool is_speculative)
* sequence or not, but since we've already locked the index we might as
* well use systable_beginscan_ordered.)
*/
- init_toast_snapshot(&SnapshotToast);
toastscan = systable_beginscan_ordered(toastrel, toastidxs[validIndex],
- &SnapshotToast, 1, &toastkey);
+ get_toast_snapshot(), 1, &toastkey);
while ((toasttup = systable_getnext_ordered(toastscan, ForwardScanDirection)) != NULL)
{
/*
@@ -631,41 +629,28 @@ toast_close_indexes(Relation *toastidxs, int num_indexes, LOCKMODE lock)
}
/* ----------
- * init_toast_snapshot
+ * get_toast_snapshot
*
- * Initialize an appropriate TOAST snapshot. We must use an MVCC snapshot
- * to initialize the TOAST snapshot; since we don't know which one to use,
- * just use the oldest one.
+ * Return the TOAST snapshot. Detoasting *must* happen in the same
+ * transaction that originally fetched the toast pointer.
*/
-void
-init_toast_snapshot(Snapshot toast_snapshot)
+Snapshot
+get_toast_snapshot(void)
{
- Snapshot snapshot = GetOldestSnapshot();
-
/*
- * GetOldestSnapshot returns NULL if the session has no active snapshots.
- * We can get that if, for example, a procedure fetches a toasted value
- * into a local variable, commits, and then tries to detoast the value.
- * Such coding is unsafe, because once we commit there is nothing to
- * prevent the toast data from being deleted. Detoasting *must* happen in
- * the same transaction that originally fetched the toast pointer. Hence,
- * rather than trying to band-aid over the problem, throw an error. (This
- * is not very much protection, because in many scenarios the procedure
- * would have already created a new transaction snapshot, preventing us
- * from detecting the problem. But it's better than nothing, and for sure
- * we shouldn't expend code on masking the problem more.)
+ * We cannot directly check that detoasting happens in the same
+ * transaction that originally fetched the toast pointer, but at least
+ * check that the session has some active snapshots. It might not if, for
+ * example, a procedure fetches a toasted value into a local variable,
+ * commits, and then tries to detoast the value. Such coding is unsafe,
+ * because once we commit there is nothing to prevent the toast data from
+ * being deleted. (This is not very much protection, because in many
+ * scenarios the procedure would have already created a new transaction
+ * snapshot, preventing us from detecting the problem. But it's better
+ * than nothing.)
*/
- if (snapshot == NULL)
+ if (!HaveRegisteredOrActiveSnapshot())
elog(ERROR, "cannot fetch toast data without an active snapshot");
- /*
- * Catalog snapshots can be returned by GetOldestSnapshot() even if not
- * registered or active. That easily hides bugs around not having a
- * snapshot set up - most of the time there is a valid catalog snapshot.
- * So additionally insist that the current snapshot is registered or
- * active.
- */
- Assert(HaveRegisteredOrActiveSnapshot());
-
- InitToastSnapshot(*toast_snapshot, snapshot->lsn, snapshot->whenTaken);
+ return &SnapshotToastData;
}
diff --git a/src/backend/access/common/tupconvert.c b/src/backend/access/common/tupconvert.c
index 4d596c4bef60a..54dc2f4ab80ab 100644
--- a/src/backend/access/common/tupconvert.c
+++ b/src/backend/access/common/tupconvert.c
@@ -7,7 +7,7 @@
* equivalent but might have columns in a different order or different sets of
* dropped columns.
*
- * Portions Copyright (c) 1996-2024, PostgreSQL Global Development Group
+ * Portions Copyright (c) 1996-2025, PostgreSQL Global Development Group
* Portions Copyright (c) 1994, Regents of the University of California
*
*
diff --git a/src/backend/access/common/tupdesc.c b/src/backend/access/common/tupdesc.c
index 47379fef220b7..568edacb9bdae 100644
--- a/src/backend/access/common/tupdesc.c
+++ b/src/backend/access/common/tupdesc.c
@@ -3,7 +3,7 @@
* tupdesc.c
* POSTGRES tuple descriptor support code
*
- * Portions Copyright (c) 1996-2024, PostgreSQL Global Development Group
+ * Portions Copyright (c) 1996-2025, PostgreSQL Global Development Group
* Portions Copyright (c) 1994, Regents of the University of California
*
*
@@ -22,6 +22,7 @@
#include "access/htup_details.h"
#include "access/toast_compression.h"
#include "access/tupdesc_details.h"
+#include "catalog/catalog.h"
#include "catalog/pg_collation.h"
#include "catalog/pg_type.h"
#include "common/hashfn.h"
@@ -56,6 +57,120 @@ ResourceOwnerForgetTupleDesc(ResourceOwner owner, TupleDesc tupdesc)
ResourceOwnerForget(owner, PointerGetDatum(tupdesc), &tupdesc_resowner_desc);
}
+/*
+ * populate_compact_attribute_internal
+ * Helper function for populate_compact_attribute()
+ */
+static inline void
+populate_compact_attribute_internal(Form_pg_attribute src,
+ CompactAttribute *dst)
+{
+ memset(dst, 0, sizeof(CompactAttribute));
+
+ dst->attcacheoff = -1;
+ dst->attlen = src->attlen;
+
+ dst->attbyval = src->attbyval;
+ dst->attispackable = (src->attstorage != TYPSTORAGE_PLAIN);
+ dst->atthasmissing = src->atthasmissing;
+ dst->attisdropped = src->attisdropped;
+ dst->attgenerated = (src->attgenerated != '\0');
+
+ /*
+ * Assign nullability status for this column. Assuming that a constraint
+ * exists, at this point we don't know if a not-null constraint is valid,
+ * so we assign UNKNOWN unless the table is a catalog, in which case we
+ * know it's valid.
+ */
+ dst->attnullability = !src->attnotnull ? ATTNULLABLE_UNRESTRICTED :
+ IsCatalogRelationOid(src->attrelid) ? ATTNULLABLE_VALID :
+ ATTNULLABLE_UNKNOWN;
+
+ switch (src->attalign)
+ {
+ case TYPALIGN_INT:
+ dst->attalignby = ALIGNOF_INT;
+ break;
+ case TYPALIGN_CHAR:
+ dst->attalignby = sizeof(char);
+ break;
+ case TYPALIGN_DOUBLE:
+ dst->attalignby = ALIGNOF_DOUBLE;
+ break;
+ case TYPALIGN_SHORT:
+ dst->attalignby = ALIGNOF_SHORT;
+ break;
+ default:
+ dst->attalignby = 0;
+ elog(ERROR, "invalid attalign value: %c", src->attalign);
+ break;
+ }
+}
+
+/*
+ * populate_compact_attribute
+ * Fill in the corresponding CompactAttribute element from the
+ * Form_pg_attribute for the given attribute number. This must be called
+ * whenever a change is made to a Form_pg_attribute in the TupleDesc.
+ */
+void
+populate_compact_attribute(TupleDesc tupdesc, int attnum)
+{
+ Form_pg_attribute src = TupleDescAttr(tupdesc, attnum);
+ CompactAttribute *dst;
+
+ /*
+ * Don't use TupleDescCompactAttr to prevent infinite recursion in assert
+ * builds.
+ */
+ dst = &tupdesc->compact_attrs[attnum];
+
+ populate_compact_attribute_internal(src, dst);
+}
+
+/*
+ * verify_compact_attribute
+ * In Assert enabled builds, we verify that the CompactAttribute is
+ * populated correctly. This helps find bugs in places such as ALTER
+ * TABLE where code makes changes to the FormData_pg_attribute but
+ * forgets to call populate_compact_attribute().
+ *
+ * This is used in TupleDescCompactAttr(), but declared here to allow access
+ * to populate_compact_attribute_internal().
+ */
+void
+verify_compact_attribute(TupleDesc tupdesc, int attnum)
+{
+#ifdef USE_ASSERT_CHECKING
+ CompactAttribute cattr;
+ Form_pg_attribute attr = TupleDescAttr(tupdesc, attnum);
+ CompactAttribute tmp;
+
+ /*
+ * Make a temp copy of the TupleDesc's CompactAttribute. This may be a
+ * shared TupleDesc and the attcacheoff might get changed by another
+ * backend.
+ */
+ memcpy(&cattr, &tupdesc->compact_attrs[attnum], sizeof(CompactAttribute));
+
+ /*
+ * Populate the temporary CompactAttribute from the corresponding
+ * Form_pg_attribute
+ */
+ populate_compact_attribute_internal(attr, &tmp);
+
+ /*
+ * Make the attcacheoff match since it's been reset to -1 by
+ * populate_compact_attribute_internal. Same with attnullability.
+ */
+ tmp.attcacheoff = cattr.attcacheoff;
+ tmp.attnullability = cattr.attnullability;
+
+ /* Check the freshly populated CompactAttribute matches the TupleDesc's */
+ Assert(memcmp(&tmp, &cattr, sizeof(CompactAttribute)) == 0);
+#endif
+}
+
/*
* CreateTemplateTupleDesc
* This function allocates an empty tuple descriptor structure.
@@ -74,18 +189,20 @@ CreateTemplateTupleDesc(int natts)
Assert(natts >= 0);
/*
- * Allocate enough memory for the tuple descriptor, including the
- * attribute rows.
+ * Allocate enough memory for the tuple descriptor, the CompactAttribute
+ * array and also an array of FormData_pg_attribute.
*
- * Note: the attribute array stride is sizeof(FormData_pg_attribute),
- * since we declare the array elements as FormData_pg_attribute for
- * notational convenience. However, we only guarantee that the first
- * ATTRIBUTE_FIXED_PART_SIZE bytes of each entry are valid; most code that
- * copies tupdesc entries around copies just that much. In principle that
- * could be less due to trailing padding, although with the current
- * definition of pg_attribute there probably isn't any padding.
+ * Note: the FormData_pg_attribute array stride is
+ * sizeof(FormData_pg_attribute), since we declare the array elements as
+ * FormData_pg_attribute for notational convenience. However, we only
+ * guarantee that the first ATTRIBUTE_FIXED_PART_SIZE bytes of each entry
+ * are valid; most code that copies tupdesc entries around copies just
+ * that much. In principle that could be less due to trailing padding,
+ * although with the current definition of pg_attribute there probably
+ * isn't any padding.
*/
- desc = (TupleDesc) palloc(offsetof(struct TupleDescData, attrs) +
+ desc = (TupleDesc) palloc(offsetof(struct TupleDescData, compact_attrs) +
+ natts * sizeof(CompactAttribute) +
natts * sizeof(FormData_pg_attribute));
/*
@@ -117,8 +234,10 @@ CreateTupleDesc(int natts, Form_pg_attribute *attrs)
desc = CreateTemplateTupleDesc(natts);
for (i = 0; i < natts; ++i)
+ {
memcpy(TupleDescAttr(desc, i), attrs[i], ATTRIBUTE_FIXED_PART_SIZE);
-
+ populate_compact_attribute(desc, i);
+ }
return desc;
}
@@ -155,6 +274,54 @@ CreateTupleDescCopy(TupleDesc tupdesc)
att->atthasmissing = false;
att->attidentity = '\0';
att->attgenerated = '\0';
+
+ populate_compact_attribute(desc, i);
+ }
+
+ /* We can copy the tuple type identification, too */
+ desc->tdtypeid = tupdesc->tdtypeid;
+ desc->tdtypmod = tupdesc->tdtypmod;
+
+ return desc;
+}
+
+/*
+ * CreateTupleDescTruncatedCopy
+ * This function creates a new TupleDesc with only the first 'natts'
+ * attributes from an existing TupleDesc
+ *
+ * !!! Constraints and defaults are not copied !!!
+ */
+TupleDesc
+CreateTupleDescTruncatedCopy(TupleDesc tupdesc, int natts)
+{
+ TupleDesc desc;
+ int i;
+
+ Assert(natts <= tupdesc->natts);
+
+ desc = CreateTemplateTupleDesc(natts);
+
+ /* Flat-copy the attribute array */
+ memcpy(TupleDescAttr(desc, 0),
+ TupleDescAttr(tupdesc, 0),
+ desc->natts * sizeof(FormData_pg_attribute));
+
+ /*
+ * Since we're not copying constraints and defaults, clear fields
+ * associated with them.
+ */
+ for (i = 0; i < desc->natts; i++)
+ {
+ Form_pg_attribute att = TupleDescAttr(desc, i);
+
+ att->attnotnull = false;
+ att->atthasdef = false;
+ att->atthasmissing = false;
+ att->attidentity = '\0';
+ att->attgenerated = '\0';
+
+ populate_compact_attribute(desc, i);
}
/* We can copy the tuple type identification, too */
@@ -183,6 +350,14 @@ CreateTupleDescCopyConstr(TupleDesc tupdesc)
TupleDescAttr(tupdesc, 0),
desc->natts * sizeof(FormData_pg_attribute));
+ for (i = 0; i < desc->natts; i++)
+ {
+ populate_compact_attribute(desc, i);
+
+ TupleDescCompactAttr(desc, i)->attnullability =
+ TupleDescCompactAttr(tupdesc, i)->attnullability;
+ }
+
/* Copy the TupleConstr data structure, if any */
if (constr)
{
@@ -190,6 +365,7 @@ CreateTupleDescCopyConstr(TupleDesc tupdesc)
cpy->has_not_null = constr->has_not_null;
cpy->has_generated_stored = constr->has_generated_stored;
+ cpy->has_generated_virtual = constr->has_generated_virtual;
if ((cpy->num_defval = constr->num_defval) > 0)
{
@@ -207,7 +383,7 @@ CreateTupleDescCopyConstr(TupleDesc tupdesc)
{
if (constr->missing[i].am_present)
{
- Form_pg_attribute attr = TupleDescAttr(tupdesc, i);
+ CompactAttribute *attr = TupleDescCompactAttr(tupdesc, i);
cpy->missing[i].am_value = datumCopy(constr->missing[i].am_value,
attr->attbyval,
@@ -224,6 +400,7 @@ CreateTupleDescCopyConstr(TupleDesc tupdesc)
{
cpy->check[i].ccname = pstrdup(constr->check[i].ccname);
cpy->check[i].ccbin = pstrdup(constr->check[i].ccbin);
+ cpy->check[i].ccenforced = constr->check[i].ccenforced;
cpy->check[i].ccvalid = constr->check[i].ccvalid;
cpy->check[i].ccnoinherit = constr->check[i].ccnoinherit;
}
@@ -252,7 +429,7 @@ TupleDescCopy(TupleDesc dst, TupleDesc src)
{
int i;
- /* Flat-copy the header and attribute array */
+ /* Flat-copy the header and attribute arrays */
memcpy(dst, src, TupleDescSize(src));
/*
@@ -268,6 +445,8 @@ TupleDescCopy(TupleDesc dst, TupleDesc src)
att->atthasmissing = false;
att->attidentity = '\0';
att->attgenerated = '\0';
+
+ populate_compact_attribute(dst, i);
}
dst->constr = NULL;
@@ -304,17 +483,7 @@ TupleDescCopyEntry(TupleDesc dst, AttrNumber dstAttno,
memcpy(dstAtt, srcAtt, ATTRIBUTE_FIXED_PART_SIZE);
- /*
- * Aside from updating the attno, we'd better reset attcacheoff.
- *
- * XXX Actually, to be entirely safe we'd need to reset the attcacheoff of
- * all following columns in dst as well. Current usage scenarios don't
- * require that though, because all following columns will get initialized
- * by other uses of this function or TupleDescInitEntry. So we cheat a
- * bit to avoid a useless O(N^2) penalty.
- */
dstAtt->attnum = dstAttno;
- dstAtt->attcacheoff = -1;
/* since we're not copying constraints or defaults, clear these */
dstAtt->attnotnull = false;
@@ -322,6 +491,8 @@ TupleDescCopyEntry(TupleDesc dst, AttrNumber dstAttno,
dstAtt->atthasmissing = false;
dstAtt->attidentity = '\0';
dstAtt->attgenerated = '\0';
+
+ populate_compact_attribute(dst, dstAttno - 1);
}
/*
@@ -442,9 +613,8 @@ equalTupleDescs(TupleDesc tupdesc1, TupleDesc tupdesc2)
* them (since atttypid will be zero for all dropped columns) and in
* general it seems safer to check them always.
*
- * attcacheoff must NOT be checked since it's possibly not set in both
- * copies. We also intentionally ignore atthasmissing, since that's
- * not very relevant in tupdescs, which lack the attmissingval field.
+ * We intentionally ignore atthasmissing, since that's not very
+ * relevant in tupdescs, which lack the attmissingval field.
*/
if (strcmp(NameStr(attr1->attname), NameStr(attr2->attname)) != 0)
return false;
@@ -466,6 +636,24 @@ equalTupleDescs(TupleDesc tupdesc1, TupleDesc tupdesc2)
return false;
if (attr1->attnotnull != attr2->attnotnull)
return false;
+
+ /*
+ * When the column has a not-null constraint, we also need to consider
+ * its validity aspect, which only manifests in CompactAttribute->
+ * attnullability, so verify that.
+ */
+ if (attr1->attnotnull)
+ {
+ CompactAttribute *cattr1 = TupleDescCompactAttr(tupdesc1, i);
+ CompactAttribute *cattr2 = TupleDescCompactAttr(tupdesc2, i);
+
+ Assert(cattr1->attnullability != ATTNULLABLE_UNKNOWN);
+ Assert((cattr1->attnullability == ATTNULLABLE_UNKNOWN) ==
+ (cattr2->attnullability == ATTNULLABLE_UNKNOWN));
+
+ if (cattr1->attnullability != cattr2->attnullability)
+ return false;
+ }
if (attr1->atthasdef != attr2->atthasdef)
return false;
if (attr1->attidentity != attr2->attidentity)
@@ -494,6 +682,8 @@ equalTupleDescs(TupleDesc tupdesc1, TupleDesc tupdesc2)
return false;
if (constr1->has_generated_stored != constr2->has_generated_stored)
return false;
+ if (constr1->has_generated_virtual != constr2->has_generated_virtual)
+ return false;
n = constr1->num_defval;
if (n != (int) constr2->num_defval)
return false;
@@ -521,7 +711,7 @@ equalTupleDescs(TupleDesc tupdesc1, TupleDesc tupdesc2)
return false;
if (missval1->am_present)
{
- Form_pg_attribute missatt1 = TupleDescAttr(tupdesc1, i);
+ CompactAttribute *missatt1 = TupleDescCompactAttr(tupdesc1, i);
if (!datumIsEqual(missval1->am_value, missval2->am_value,
missatt1->attbyval, missatt1->attlen))
@@ -547,6 +737,7 @@ equalTupleDescs(TupleDesc tupdesc1, TupleDesc tupdesc2)
if (!(strcmp(check1->ccname, check2->ccname) == 0 &&
strcmp(check1->ccbin, check2->ccbin) == 0 &&
+ check1->ccenforced == check2->ccenforced &&
check1->ccvalid == check2->ccvalid &&
check1->ccnoinherit == check2->ccnoinherit))
return false;
@@ -624,10 +815,10 @@ hashRowType(TupleDesc desc)
uint32 s;
int i;
- s = hash_combine(0, hash_uint32(desc->natts));
- s = hash_combine(s, hash_uint32(desc->tdtypeid));
+ s = hash_combine(0, hash_bytes_uint32(desc->natts));
+ s = hash_combine(s, hash_bytes_uint32(desc->tdtypeid));
for (i = 0; i < desc->natts; ++i)
- s = hash_combine(s, hash_uint32(TupleDescAttr(desc, i)->atttypid));
+ s = hash_combine(s, hash_bytes_uint32(TupleDescAttr(desc, i)->atttypid));
return s;
}
@@ -685,7 +876,6 @@ TupleDescInitEntry(TupleDesc desc,
else if (attributeName != NameStr(att->attname))
namestrcpy(&(att->attname), attributeName);
- att->attcacheoff = -1;
att->atttypmod = typmod;
att->attnum = attributeNumber;
@@ -714,6 +904,8 @@ TupleDescInitEntry(TupleDesc desc,
att->attcompression = InvalidCompressionMethod;
att->attcollation = typeForm->typcollation;
+ populate_compact_attribute(desc, attributeNumber - 1);
+
ReleaseSysCache(tuple);
}
@@ -747,7 +939,6 @@ TupleDescInitBuiltinEntry(TupleDesc desc,
Assert(attributeName != NULL);
namestrcpy(&(att->attname), attributeName);
- att->attcacheoff = -1;
att->atttypmod = typmod;
att->attnum = attributeNumber;
@@ -802,7 +993,7 @@ TupleDescInitBuiltinEntry(TupleDesc desc,
case INT8OID:
att->attlen = 8;
- att->attbyval = FLOAT8PASSBYVAL;
+ att->attbyval = true;
att->attalign = TYPALIGN_DOUBLE;
att->attstorage = TYPSTORAGE_PLAIN;
att->attcompression = InvalidCompressionMethod;
@@ -821,6 +1012,8 @@ TupleDescInitBuiltinEntry(TupleDesc desc,
default:
elog(ERROR, "unsupported type %u", oidtypeid);
}
+
+ populate_compact_attribute(desc, attributeNumber - 1);
}
/*
diff --git a/src/backend/access/gin/README b/src/backend/access/gin/README
index b08073162128a..742bcbad499fa 100644
--- a/src/backend/access/gin/README
+++ b/src/backend/access/gin/README
@@ -237,10 +237,10 @@ GIN packs keys and downlinks into tuples in a different way.
P_i is grouped with K_{i+1}. -Inf key is not needed.
-There are couple of additional notes regarding K_{n+1} key.
-1) In entry tree rightmost page, a key coupled with P_n doesn't really matter.
+There are a couple of additional notes regarding K_{n+1} key.
+1) In the entry tree on the rightmost page, a key coupled with P_n doesn't really matter.
Highkey is assumed to be infinity.
-2) In posting tree, a key coupled with P_n always doesn't matter. Highkey for
+2) In the posting tree, a key coupled with P_n always doesn't matter. Highkey for
non-rightmost pages is stored separately and accessed via
GinDataPageGetRightBound().
diff --git a/src/backend/access/gin/ginarrayproc.c b/src/backend/access/gin/ginarrayproc.c
index 2373e76f77e4f..1f821323eb0a0 100644
--- a/src/backend/access/gin/ginarrayproc.c
+++ b/src/backend/access/gin/ginarrayproc.c
@@ -4,7 +4,7 @@
* support functions for GIN's indexing of any array
*
*
- * Portions Copyright (c) 1996-2024, PostgreSQL Global Development Group
+ * Portions Copyright (c) 1996-2025, PostgreSQL Global Development Group
* Portions Copyright (c) 1994, Regents of the University of California
*
* IDENTIFICATION
diff --git a/src/backend/access/gin/ginbtree.c b/src/backend/access/gin/ginbtree.c
index b7a5013896adb..644d484ea53c6 100644
--- a/src/backend/access/gin/ginbtree.c
+++ b/src/backend/access/gin/ginbtree.c
@@ -4,7 +4,7 @@
* page utilities routines for the postgres inverted index access method.
*
*
- * Portions Copyright (c) 1996-2024, PostgreSQL Global Development Group
+ * Portions Copyright (c) 1996-2025, PostgreSQL Global Development Group
* Portions Copyright (c) 1994, Regents of the University of California
*
* IDENTIFICATION
@@ -423,7 +423,7 @@ ginPlaceToPage(GinBtree btree, GinBtreeStack *stack,
xlrec.flags = xlflags;
- XLogRegisterData((char *) &xlrec, sizeof(ginxlogInsert));
+ XLogRegisterData(&xlrec, sizeof(ginxlogInsert));
/*
* Log information about child if this was an insertion of a
@@ -433,7 +433,7 @@ ginPlaceToPage(GinBtree btree, GinBtreeStack *stack,
{
BlockIdSet(&childblknos[0], BufferGetBlockNumber(childbuf));
BlockIdSet(&childblknos[1], GinPageGetOpaque(childpage)->rightlink);
- XLogRegisterData((char *) childblknos,
+ XLogRegisterData(childblknos,
sizeof(BlockIdData) * 2);
}
@@ -617,7 +617,7 @@ ginPlaceToPage(GinBtree btree, GinBtreeStack *stack,
if (BufferIsValid(childbuf))
XLogRegisterBuffer(3, childbuf, REGBUF_STANDARD);
- XLogRegisterData((char *) &data, sizeof(ginxlogSplit));
+ XLogRegisterData(&data, sizeof(ginxlogSplit));
recptr = XLogInsert(RM_GIN_ID, XLOG_GIN_SPLIT);
@@ -685,9 +685,9 @@ ginFinishSplit(GinBtree btree, GinBtreeStack *stack, bool freestack,
#ifdef USE_INJECTION_POINTS
if (GinPageIsLeaf(BufferGetPage(stack->buffer)))
- INJECTION_POINT("gin-leave-leaf-split-incomplete");
+ INJECTION_POINT("gin-leave-leaf-split-incomplete", NULL);
else
- INJECTION_POINT("gin-leave-internal-split-incomplete");
+ INJECTION_POINT("gin-leave-internal-split-incomplete", NULL);
#endif
/* search parent to lock */
@@ -778,7 +778,7 @@ ginFinishSplit(GinBtree btree, GinBtreeStack *stack, bool freestack,
static void
ginFinishOldSplit(GinBtree btree, GinBtreeStack *stack, GinStatsData *buildStats, int access)
{
- INJECTION_POINT("gin-finish-incomplete-split");
+ INJECTION_POINT("gin-finish-incomplete-split", NULL);
elog(DEBUG1, "finishing incomplete split of block %u in gin index \"%s\"",
stack->blkno, RelationGetRelationName(btree->index));
diff --git a/src/backend/access/gin/ginbulk.c b/src/backend/access/gin/ginbulk.c
index 7f89cd5e8261e..302cb2092a9a8 100644
--- a/src/backend/access/gin/ginbulk.c
+++ b/src/backend/access/gin/ginbulk.c
@@ -4,7 +4,7 @@
* routines for fast build of inverted index
*
*
- * Portions Copyright (c) 1996-2024, PostgreSQL Global Development Group
+ * Portions Copyright (c) 1996-2025, PostgreSQL Global Development Group
* Portions Copyright (c) 1994, Regents of the University of California
*
* IDENTIFICATION
@@ -117,7 +117,7 @@ ginInitBA(BuildAccumulator *accum)
ginCombineData,
ginAllocEntryAccumulator,
NULL, /* no freefunc needed */
- (void *) accum);
+ accum);
}
/*
@@ -127,10 +127,10 @@ ginInitBA(BuildAccumulator *accum)
static Datum
getDatumCopy(BuildAccumulator *accum, OffsetNumber attnum, Datum value)
{
- Form_pg_attribute att;
+ CompactAttribute *att;
Datum res;
- att = TupleDescAttr(accum->ginstate->origTupdesc, attnum - 1);
+ att = TupleDescCompactAttr(accum->ginstate->origTupdesc, attnum - 1);
if (att->attbyval)
res = value;
else
diff --git a/src/backend/access/gin/gindatapage.c b/src/backend/access/gin/gindatapage.c
index 126c4dd4504e8..6c2c61947204a 100644
--- a/src/backend/access/gin/gindatapage.c
+++ b/src/backend/access/gin/gindatapage.c
@@ -4,7 +4,7 @@
* routines for handling GIN posting tree pages.
*
*
- * Portions Copyright (c) 1996-2024, PostgreSQL Global Development Group
+ * Portions Copyright (c) 1996-2025, PostgreSQL Global Development Group
* Portions Copyright (c) 1994, Regents of the University of California
*
* IDENTIFICATION
@@ -63,7 +63,7 @@ typedef struct
* If we need WAL data representing the reconstructed leaf page, it's
* stored here by computeLeafRecompressWALData.
*/
- char *walinfo; /* buffer start */
+ void *walinfo; /* buffer start */
int walinfolen; /* and length */
} disassembledLeaf;
@@ -1173,7 +1173,7 @@ dataExecPlaceToPageInternal(GinBtree btree, Buffer buf, GinBtreeStack *stack,
data.newitem = *pitem;
XLogRegisterBuffer(0, buf, REGBUF_STANDARD);
- XLogRegisterBufData(0, (char *) &data,
+ XLogRegisterBufData(0, &data,
sizeof(ginxlogInsertDataInternal));
}
}
@@ -1844,9 +1844,9 @@ createPostingTree(Relation index, ItemPointerData *items, uint32 nitems,
data.size = rootsize;
XLogBeginInsert();
- XLogRegisterData((char *) &data, sizeof(ginxlogCreatePostingTree));
+ XLogRegisterData(&data, sizeof(ginxlogCreatePostingTree));
- XLogRegisterData((char *) GinDataLeafPageGetPostingList(page),
+ XLogRegisterData(GinDataLeafPageGetPostingList(page),
rootsize);
XLogRegisterBuffer(0, buffer, REGBUF_WILL_INIT);
diff --git a/src/backend/access/gin/ginentrypage.c b/src/backend/access/gin/ginentrypage.c
index 94ef951e14fda..ba6bbd562df0c 100644
--- a/src/backend/access/gin/ginentrypage.c
+++ b/src/backend/access/gin/ginentrypage.c
@@ -4,7 +4,7 @@
* routines for handling GIN entry tree pages.
*
*
- * Portions Copyright (c) 1996-2024, PostgreSQL Global Development Group
+ * Portions Copyright (c) 1996-2025, PostgreSQL Global Development Group
* Portions Copyright (c) 1994, Regents of the University of California
*
* IDENTIFICATION
@@ -585,9 +585,9 @@ entryExecPlaceToPage(GinBtree btree, Buffer buf, GinBtreeStack *stack,
data.offset = off;
XLogRegisterBuffer(0, buf, REGBUF_STANDARD);
- XLogRegisterBufData(0, (char *) &data,
+ XLogRegisterBufData(0, &data,
offsetof(ginxlogInsertEntry, tuple));
- XLogRegisterBufData(0, (char *) insertData->entry,
+ XLogRegisterBufData(0, insertData->entry,
IndexTupleSize(insertData->entry));
}
}
diff --git a/src/backend/access/gin/ginfast.c b/src/backend/access/gin/ginfast.c
index eeca3ed318f4c..a6d88572cc29b 100644
--- a/src/backend/access/gin/ginfast.c
+++ b/src/backend/access/gin/ginfast.c
@@ -7,7 +7,7 @@
* transfer pending entries into the regular index structure. This
* wins because bulk insertion is much more efficient than retail.
*
- * Portions Copyright (c) 1996-2024, PostgreSQL Global Development Group
+ * Portions Copyright (c) 1996-2025, PostgreSQL Global Development Group
* Portions Copyright (c) 1994, Regents of the University of California
*
* IDENTIFICATION
@@ -39,7 +39,7 @@
int gin_pending_list_limit = 0;
#define GIN_PAGE_FREESIZE \
- ( BLCKSZ - MAXALIGN(SizeOfPageHeaderData) - MAXALIGN(sizeof(GinPageOpaqueData)) )
+ ( (Size) BLCKSZ - MAXALIGN(SizeOfPageHeaderData) - MAXALIGN(sizeof(GinPageOpaqueData)) )
typedef struct KeyArray
{
@@ -122,7 +122,7 @@ writeListPage(Relation index, Buffer buffer,
data.ntuples = ntuples;
XLogBeginInsert();
- XLogRegisterData((char *) &data, sizeof(ginxlogInsertListPage));
+ XLogRegisterData(&data, sizeof(ginxlogInsertListPage));
XLogRegisterBuffer(0, buffer, REGBUF_WILL_INIT);
XLogRegisterBufData(0, workspace.data, size);
@@ -431,7 +431,7 @@ ginHeapTupleFastInsert(GinState *ginstate, GinTupleCollector *collector)
memcpy(&data.metadata, metadata, sizeof(GinMetaPageData));
XLogRegisterBuffer(0, metabuffer, REGBUF_WILL_INIT | REGBUF_STANDARD);
- XLogRegisterData((char *) &data, sizeof(ginxlogUpdateMeta));
+ XLogRegisterData(&data, sizeof(ginxlogUpdateMeta));
recptr = XLogInsert(RM_GIN_ID, XLOG_GIN_UPDATE_META_PAGE);
PageSetLSN(metapage, recptr);
@@ -456,7 +456,7 @@ ginHeapTupleFastInsert(GinState *ginstate, GinTupleCollector *collector)
* ginInsertCleanup() should not be called inside our CRIT_SECTION.
*/
cleanupSize = GinGetPendingListCleanupSize(index);
- if (metadata->nPendingPages * GIN_PAGE_FREESIZE > cleanupSize * 1024L)
+ if (metadata->nPendingPages * GIN_PAGE_FREESIZE > cleanupSize * (Size) 1024)
needCleanup = true;
UnlockReleaseBuffer(metabuffer);
@@ -646,7 +646,7 @@ shiftList(Relation index, Buffer metabuffer, BlockNumber newHead,
memcpy(&data.metadata, metadata, sizeof(GinMetaPageData));
- XLogRegisterData((char *) &data,
+ XLogRegisterData(&data,
sizeof(ginxlogDeleteListPages));
recptr = XLogInsert(RM_GIN_ID, XLOG_GIN_DELETE_LISTPAGE);
@@ -795,7 +795,7 @@ ginInsertCleanup(GinState *ginstate, bool full_clean,
blknoFinish;
bool cleanupFinish = false;
bool fsm_vac = false;
- Size workMemory;
+ int workMemory;
/*
* We would like to prevent concurrent cleanup process. For that we will
@@ -892,7 +892,7 @@ ginInsertCleanup(GinState *ginstate, bool full_clean,
*/
processPendingPage(&accum, &datums, page, FirstOffsetNumber);
- vacuum_delay_point();
+ vacuum_delay_point(false);
/*
* Is it time to flush memory to disk? Flush if we are at the end of
@@ -901,7 +901,7 @@ ginInsertCleanup(GinState *ginstate, bool full_clean,
*/
if (GinPageGetOpaque(page)->rightlink == InvalidBlockNumber ||
(GinPageHasFullRow(page) &&
- (accum.allocatedMemory >= workMemory * 1024L)))
+ accum.allocatedMemory >= workMemory * (Size) 1024))
{
ItemPointerData *list;
uint32 nlist;
@@ -929,7 +929,7 @@ ginInsertCleanup(GinState *ginstate, bool full_clean,
{
ginEntryInsert(ginstate, attnum, key, category,
list, nlist, NULL);
- vacuum_delay_point();
+ vacuum_delay_point(false);
}
/*
@@ -1002,7 +1002,7 @@ ginInsertCleanup(GinState *ginstate, bool full_clean,
/*
* Read next page in pending list
*/
- vacuum_delay_point();
+ vacuum_delay_point(false);
buffer = ReadBuffer(index, blkno);
LockBuffer(buffer, GIN_SHARE);
page = BufferGetPage(buffer);
diff --git a/src/backend/access/gin/ginget.c b/src/backend/access/gin/ginget.c
index 0b4f2ebadb6c8..656299b1b528f 100644
--- a/src/backend/access/gin/ginget.c
+++ b/src/backend/access/gin/ginget.c
@@ -4,7 +4,7 @@
* fetch tuples from a GIN scan.
*
*
- * Portions Copyright (c) 1996-2024, PostgreSQL Global Development Group
+ * Portions Copyright (c) 1996-2025, PostgreSQL Global Development Group
* Portions Copyright (c) 1994, Regents of the University of California
*
* IDENTIFICATION
@@ -122,10 +122,10 @@ collectMatchBitmap(GinBtreeData *btree, GinBtreeStack *stack,
GinScanEntry scanEntry, Snapshot snapshot)
{
OffsetNumber attnum;
- Form_pg_attribute attr;
+ CompactAttribute *attr;
/* Initialize empty bitmap result */
- scanEntry->matchBitmap = tbm_create(work_mem * 1024L, NULL);
+ scanEntry->matchBitmap = tbm_create(work_mem * (Size) 1024, NULL);
/* Null query cannot partial-match anything */
if (scanEntry->isPartialMatch &&
@@ -134,7 +134,7 @@ collectMatchBitmap(GinBtreeData *btree, GinBtreeStack *stack,
/* Locate tupdesc entry for key column (for attbyval/attlen data) */
attnum = scanEntry->attnum;
- attr = TupleDescAttr(btree->ginstate->origTupdesc, attnum - 1);
+ attr = TupleDescCompactAttr(btree->ginstate->origTupdesc, attnum - 1);
/*
* Predicate lock entry leaf page, following pages will be locked by
@@ -332,7 +332,8 @@ startScanEntry(GinState *ginstate, GinScanEntry entry, Snapshot snapshot)
entry->list = NULL;
entry->nlist = 0;
entry->matchBitmap = NULL;
- entry->matchResult = NULL;
+ entry->matchNtuples = -1;
+ entry->matchResult.blockno = InvalidBlockNumber;
entry->reduceResult = false;
entry->predictNumberResult = 0;
@@ -373,7 +374,7 @@ startScanEntry(GinState *ginstate, GinScanEntry entry, Snapshot snapshot)
if (entry->matchBitmap)
{
if (entry->matchIterator)
- tbm_end_iterate(entry->matchIterator);
+ tbm_end_private_iterate(entry->matchIterator);
entry->matchIterator = NULL;
tbm_free(entry->matchBitmap);
entry->matchBitmap = NULL;
@@ -385,7 +386,8 @@ startScanEntry(GinState *ginstate, GinScanEntry entry, Snapshot snapshot)
if (entry->matchBitmap && !tbm_is_empty(entry->matchBitmap))
{
- entry->matchIterator = tbm_begin_iterate(entry->matchBitmap);
+ entry->matchIterator =
+ tbm_begin_private_iterate(entry->matchBitmap);
entry->isFinished = false;
}
}
@@ -556,16 +558,18 @@ startScanKey(GinState *ginstate, GinScanOpaque so, GinScanKey key)
qsort_arg(entryIndexes, key->nentries, sizeof(int),
entryIndexByFrequencyCmp, key);
+ for (i = 1; i < key->nentries; i++)
+ key->entryRes[entryIndexes[i]] = GIN_MAYBE;
for (i = 0; i < key->nentries - 1; i++)
{
/* Pass all entries <= i as FALSE, and the rest as MAYBE */
- for (j = 0; j <= i; j++)
- key->entryRes[entryIndexes[j]] = GIN_FALSE;
- for (j = i + 1; j < key->nentries; j++)
- key->entryRes[entryIndexes[j]] = GIN_MAYBE;
+ key->entryRes[entryIndexes[i]] = GIN_FALSE;
if (key->triConsistentFn(key) == GIN_FALSE)
break;
+
+ /* Make this loop interruptible in case there are many keys */
+ CHECK_FOR_INTERRUPTS();
}
/* i is now the last required entry. */
@@ -823,29 +827,35 @@ entryGetItem(GinState *ginstate, GinScanEntry entry,
{
/*
* If we've exhausted all items on this block, move to next block
- * in the bitmap.
+ * in the bitmap. tbm_private_iterate() sets matchResult.blockno
+ * to InvalidBlockNumber when the bitmap is exhausted.
*/
- while (entry->matchResult == NULL ||
- (entry->matchResult->ntuples >= 0 &&
- entry->offset >= entry->matchResult->ntuples) ||
- entry->matchResult->blockno < advancePastBlk ||
+ while ((!BlockNumberIsValid(entry->matchResult.blockno)) ||
+ (!entry->matchResult.lossy &&
+ entry->offset >= entry->matchNtuples) ||
+ entry->matchResult.blockno < advancePastBlk ||
(ItemPointerIsLossyPage(&advancePast) &&
- entry->matchResult->blockno == advancePastBlk))
+ entry->matchResult.blockno == advancePastBlk))
{
- entry->matchResult = tbm_iterate(entry->matchIterator);
-
- if (entry->matchResult == NULL)
+ if (!tbm_private_iterate(entry->matchIterator, &entry->matchResult))
{
+ Assert(!BlockNumberIsValid(entry->matchResult.blockno));
ItemPointerSetInvalid(&entry->curItem);
- tbm_end_iterate(entry->matchIterator);
+ tbm_end_private_iterate(entry->matchIterator);
entry->matchIterator = NULL;
entry->isFinished = true;
break;
}
+ /* Exact pages need their tuple offsets extracted. */
+ if (!entry->matchResult.lossy)
+ entry->matchNtuples = tbm_extract_page_tuple(&entry->matchResult,
+ entry->matchOffsets,
+ TBM_MAX_TUPLES_PER_PAGE);
+
/*
* Reset counter to the beginning of entry->matchResult. Note:
- * entry->offset is still greater than matchResult->ntuples if
+ * entry->offset is still greater than matchResult.ntuples if
* matchResult is lossy. So, on next call we will get next
* result from TIDBitmap.
*/
@@ -858,10 +868,10 @@ entryGetItem(GinState *ginstate, GinScanEntry entry,
* We're now on the first page after advancePast which has any
* items on it. If it's a lossy result, return that.
*/
- if (entry->matchResult->ntuples < 0)
+ if (entry->matchResult.lossy)
{
ItemPointerSetLossyPage(&entry->curItem,
- entry->matchResult->blockno);
+ entry->matchResult.blockno);
/*
* We might as well fall out of the loop; we could not
@@ -872,30 +882,35 @@ entryGetItem(GinState *ginstate, GinScanEntry entry,
}
/*
- * Not a lossy page. Skip over any offsets <= advancePast, and
- * return that.
+ * Not a lossy page. If tuple offsets were extracted,
+ * entry->matchNtuples must be > -1
*/
- if (entry->matchResult->blockno == advancePastBlk)
+ Assert(entry->matchNtuples > -1);
+
+ /* Skip over any offsets <= advancePast, and return that. */
+ if (entry->matchResult.blockno == advancePastBlk)
{
+ Assert(entry->matchNtuples > 0);
+
/*
* First, do a quick check against the last offset on the
* page. If that's > advancePast, so are all the other
* offsets, so just go back to the top to get the next page.
*/
- if (entry->matchResult->offsets[entry->matchResult->ntuples - 1] <= advancePastOff)
+ if (entry->matchOffsets[entry->matchNtuples - 1] <= advancePastOff)
{
- entry->offset = entry->matchResult->ntuples;
+ entry->offset = entry->matchNtuples;
continue;
}
/* Otherwise scan to find the first item > advancePast */
- while (entry->matchResult->offsets[entry->offset] <= advancePastOff)
+ while (entry->matchOffsets[entry->offset] <= advancePastOff)
entry->offset++;
}
ItemPointerSet(&entry->curItem,
- entry->matchResult->blockno,
- entry->matchResult->offsets[entry->offset]);
+ entry->matchResult.blockno,
+ entry->matchOffsets[entry->offset]);
entry->offset++;
/* Done unless we need to reduce the result */
@@ -1312,6 +1327,8 @@ scanGetItem(IndexScanDesc scan, ItemPointerData advancePast,
*/
do
{
+ CHECK_FOR_INTERRUPTS();
+
ItemPointerSetMin(item);
match = true;
for (i = 0; i < so->nkeys && match; i++)
@@ -1951,8 +1968,6 @@ gingetbitmap(IndexScanDesc scan, TIDBitmap *tbm)
for (;;)
{
- CHECK_FOR_INTERRUPTS();
-
if (!scanGetItem(scan, iptr, &iptr, &recheck))
break;
diff --git a/src/backend/access/gin/gininsert.c b/src/backend/access/gin/gininsert.c
index 71f38be90c3b1..e9d4b27427e59 100644
--- a/src/backend/access/gin/gininsert.c
+++ b/src/backend/access/gin/gininsert.c
@@ -4,7 +4,7 @@
* insert routines for the postgres inverted index access method.
*
*
- * Portions Copyright (c) 1996-2024, PostgreSQL Global Development Group
+ * Portions Copyright (c) 1996-2025, PostgreSQL Global Development Group
* Portions Copyright (c) 1994, Regents of the University of California
*
* IDENTIFICATION
@@ -15,14 +15,126 @@
#include "postgres.h"
#include "access/gin_private.h"
+#include "access/gin_tuple.h"
+#include "access/parallel.h"
+#include "access/table.h"
#include "access/tableam.h"
#include "access/xloginsert.h"
+#include "catalog/index.h"
+#include "catalog/pg_collation.h"
+#include "commands/progress.h"
#include "miscadmin.h"
#include "nodes/execnodes.h"
+#include "pgstat.h"
#include "storage/bufmgr.h"
#include "storage/predicate.h"
+#include "tcop/tcopprot.h"
+#include "utils/datum.h"
#include "utils/memutils.h"
#include "utils/rel.h"
+#include "utils/builtins.h"
+
+
+/* Magic numbers for parallel state sharing */
+#define PARALLEL_KEY_GIN_SHARED UINT64CONST(0xB000000000000001)
+#define PARALLEL_KEY_TUPLESORT UINT64CONST(0xB000000000000002)
+#define PARALLEL_KEY_QUERY_TEXT UINT64CONST(0xB000000000000003)
+#define PARALLEL_KEY_WAL_USAGE UINT64CONST(0xB000000000000004)
+#define PARALLEL_KEY_BUFFER_USAGE UINT64CONST(0xB000000000000005)
+
+/*
+ * Status for index builds performed in parallel. This is allocated in a
+ * dynamic shared memory segment.
+ */
+typedef struct GinBuildShared
+{
+ /*
+ * These fields are not modified during the build. They primarily exist
+ * for the benefit of worker processes that need to create state
+ * corresponding to that used by the leader.
+ */
+ Oid heaprelid;
+ Oid indexrelid;
+ bool isconcurrent;
+ int scantuplesortstates;
+
+ /*
+ * workersdonecv is used to monitor the progress of workers. All parallel
+ * participants must indicate that they are done before leader can use
+ * results built by the workers (and before leader can write the data into
+ * the index).
+ */
+ ConditionVariable workersdonecv;
+
+ /*
+ * mutex protects all following fields
+ *
+ * These fields contain status information of interest to GIN index builds
+ * that must work just the same when an index is built in parallel.
+ */
+ slock_t mutex;
+
+ /*
+ * Mutable state that is maintained by workers, and reported back to
+ * leader at end of the scans.
+ *
+ * nparticipantsdone is number of worker processes finished.
+ *
+ * reltuples is the total number of input heap tuples.
+ *
+ * indtuples is the total number of tuples that made it into the index.
+ */
+ int nparticipantsdone;
+ double reltuples;
+ double indtuples;
+
+ /*
+ * ParallelTableScanDescData data follows. Can't directly embed here, as
+ * implementations of the parallel table scan desc interface might need
+ * stronger alignment.
+ */
+} GinBuildShared;
+
+/*
+ * Return pointer to a GinBuildShared's parallel table scan.
+ *
+ * c.f. shm_toc_allocate as to why BUFFERALIGN is used, rather than just
+ * MAXALIGN.
+ */
+#define ParallelTableScanFromGinBuildShared(shared) \
+ (ParallelTableScanDesc) ((char *) (shared) + BUFFERALIGN(sizeof(GinBuildShared)))
+
+/*
+ * Status for leader in parallel index build.
+ */
+typedef struct GinLeader
+{
+ /* parallel context itself */
+ ParallelContext *pcxt;
+
+ /*
+ * nparticipanttuplesorts is the exact number of worker processes
+ * successfully launched, plus one leader process if it participates as a
+ * worker (only DISABLE_LEADER_PARTICIPATION builds avoid leader
+ * participating as a worker).
+ */
+ int nparticipanttuplesorts;
+
+ /*
+ * Leader process convenience pointers to shared state (leader avoids TOC
+ * lookups).
+ *
+ * GinBuildShared is the shared state for entire build. sharedsort is the
+ * shared, tuplesort-managed state passed to each process tuplesort.
+ * snapshot is the snapshot used by the scan iff an MVCC snapshot is
+ * required.
+ */
+ GinBuildShared *ginshared;
+ Sharedsort *sharedsort;
+ Snapshot snapshot;
+ WalUsage *walusage;
+ BufferUsage *bufferusage;
+} GinLeader;
typedef struct
{
@@ -32,9 +144,60 @@ typedef struct
MemoryContext tmpCtx;
MemoryContext funcCtx;
BuildAccumulator accum;
+ ItemPointerData tid;
+ int work_mem;
+
+ /*
+ * bs_leader is only present when a parallel index build is performed, and
+ * only in the leader process.
+ */
+ GinLeader *bs_leader;
+ int bs_worker_id;
+
+ /* used to pass information from workers to leader */
+ double bs_numtuples;
+ double bs_reltuples;
+
+ /*
+ * The sortstate is used by workers (including the leader). It has to be
+ * part of the build state, because that's the only thing passed to the
+ * build callback etc.
+ */
+ Tuplesortstate *bs_sortstate;
+
+ /*
+ * The sortstate used only within a single worker for the first merge pass
+ * happening there. In principle it doesn't need to be part of the build
+ * state and we could pass it around directly, but it's more convenient
+ * this way. And it's part of the build state, after all.
+ */
+ Tuplesortstate *bs_worker_sort;
} GinBuildState;
+/* parallel index builds */
+static void _gin_begin_parallel(GinBuildState *buildstate, Relation heap, Relation index,
+ bool isconcurrent, int request);
+static void _gin_end_parallel(GinLeader *ginleader, GinBuildState *state);
+static Size _gin_parallel_estimate_shared(Relation heap, Snapshot snapshot);
+static double _gin_parallel_heapscan(GinBuildState *state);
+static double _gin_parallel_merge(GinBuildState *state);
+static void _gin_leader_participate_as_worker(GinBuildState *buildstate,
+ Relation heap, Relation index);
+static void _gin_parallel_scan_and_build(GinBuildState *state,
+ GinBuildShared *ginshared,
+ Sharedsort *sharedsort,
+ Relation heap, Relation index,
+ int sortmem, bool progress);
+
+static ItemPointer _gin_parse_tuple_items(GinTuple *a);
+static Datum _gin_parse_tuple_key(GinTuple *a);
+
+static GinTuple *_gin_build_tuple(OffsetNumber attrnum, unsigned char category,
+ Datum key, int16 typlen, bool typbyval,
+ ItemPointerData *items, uint32 nitems,
+ Size *len);
+
/*
* Adds array of item pointers to tuple's posting list, or
* creates posting tree and tuple pointing to tree in case
@@ -288,7 +451,7 @@ ginBuildCallback(Relation index, ItemPointer tid, Datum *values,
values[i], isnull[i], tid);
/* If we've maxed out our available memory, dump everything to the index */
- if (buildstate->accum.allocatedMemory >= (Size) maintenance_work_mem * 1024L)
+ if (buildstate->accum.allocatedMemory >= maintenance_work_mem * (Size) 1024)
{
ItemPointerData *list;
Datum key;
@@ -313,12 +476,114 @@ ginBuildCallback(Relation index, ItemPointer tid, Datum *values,
MemoryContextSwitchTo(oldCtx);
}
+/*
+ * ginFlushBuildState
+ * Write all data from BuildAccumulator into the tuplesort.
+ */
+static void
+ginFlushBuildState(GinBuildState *buildstate, Relation index)
+{
+ ItemPointerData *list;
+ Datum key;
+ GinNullCategory category;
+ uint32 nlist;
+ OffsetNumber attnum;
+ TupleDesc tdesc = RelationGetDescr(index);
+
+ ginBeginBAScan(&buildstate->accum);
+ while ((list = ginGetBAEntry(&buildstate->accum,
+ &attnum, &key, &category, &nlist)) != NULL)
+ {
+ /* information about the key */
+ Form_pg_attribute attr = TupleDescAttr(tdesc, (attnum - 1));
+
+ /* GIN tuple and tuple length */
+ GinTuple *tup;
+ Size tuplen;
+
+ /* there could be many entries, so be willing to abort here */
+ CHECK_FOR_INTERRUPTS();
+
+ tup = _gin_build_tuple(attnum, category,
+ key, attr->attlen, attr->attbyval,
+ list, nlist, &tuplen);
+
+ tuplesort_putgintuple(buildstate->bs_worker_sort, tup, tuplen);
+
+ pfree(tup);
+ }
+
+ MemoryContextReset(buildstate->tmpCtx);
+ ginInitBA(&buildstate->accum);
+}
+
+/*
+ * ginBuildCallbackParallel
+ * Callback for the parallel index build.
+ *
+ * This is similar to the serial build callback ginBuildCallback, but
+ * instead of writing the accumulated entries into the index, each worker
+ * writes them into a (local) tuplesort.
+ *
+ * The worker then sorts and combines these entries, before writing them
+ * into a shared tuplesort for the leader (see _gin_parallel_scan_and_build
+ * for the whole process).
+ */
+static void
+ginBuildCallbackParallel(Relation index, ItemPointer tid, Datum *values,
+ bool *isnull, bool tupleIsAlive, void *state)
+{
+ GinBuildState *buildstate = (GinBuildState *) state;
+ MemoryContext oldCtx;
+ int i;
+
+ oldCtx = MemoryContextSwitchTo(buildstate->tmpCtx);
+
+ /*
+ * if scan wrapped around - flush accumulated entries and start anew
+ *
+ * With parallel scans, we don't have a guarantee the scan does not start
+ * half-way through the relation (serial builds disable sync scans and
+ * always start from block 0, parallel scans require allow_sync=true).
+ *
+ * Building the posting lists assumes the TIDs are monotonic and never go
+ * back, and the wrap around would break that. We handle that by detecting
+ * the wraparound, and flushing all entries. This means we'll later see
+ * two separate entries with non-overlapping TID lists (which can be
+ * combined by merge sort).
+ *
+ * To detect a wraparound, we remember the last TID seen by each worker
+ * (for any key). If the next TID seen by the worker is lower, the scan
+ * must have wrapped around.
+ */
+ if (ItemPointerCompare(tid, &buildstate->tid) < 0)
+ ginFlushBuildState(buildstate, index);
+
+ /* remember the TID we're about to process */
+ buildstate->tid = *tid;
+
+ for (i = 0; i < buildstate->ginstate.origTupdesc->natts; i++)
+ ginHeapTupleBulkInsert(buildstate, (OffsetNumber) (i + 1),
+ values[i], isnull[i], tid);
+
+ /*
+ * If we've maxed out our available memory, dump everything to the
+ * tuplesort. We use half the per-worker fraction of maintenance_work_mem,
+ * the other half is used for the tuplesort.
+ */
+ if (buildstate->accum.allocatedMemory >= buildstate->work_mem * (Size) 1024)
+ ginFlushBuildState(buildstate, index);
+
+ MemoryContextSwitchTo(oldCtx);
+}
+
IndexBuildResult *
ginbuild(Relation heap, Relation index, IndexInfo *indexInfo)
{
IndexBuildResult *result;
double reltuples;
GinBuildState buildstate;
+ GinBuildState *state = &buildstate;
Buffer RootBuffer,
MetaBuffer;
ItemPointerData *list;
@@ -336,6 +601,12 @@ ginbuild(Relation heap, Relation index, IndexInfo *indexInfo)
buildstate.indtuples = 0;
memset(&buildstate.buildStats, 0, sizeof(GinStatsData));
+ /* Initialize fields for parallel build too. */
+ buildstate.bs_numtuples = 0;
+ buildstate.bs_reltuples = 0;
+ buildstate.bs_leader = NULL;
+ memset(&buildstate.tid, 0, sizeof(ItemPointerData));
+
/* initialize the meta page */
MetaBuffer = GinNewBuffer(index);
@@ -375,26 +646,96 @@ ginbuild(Relation heap, Relation index, IndexInfo *indexInfo)
buildstate.accum.ginstate = &buildstate.ginstate;
ginInitBA(&buildstate.accum);
+ /* Report table scan phase started */
+ pgstat_progress_update_param(PROGRESS_CREATEIDX_SUBPHASE,
+ PROGRESS_GIN_PHASE_INDEXBUILD_TABLESCAN);
+
/*
- * Do the heap scan. We disallow sync scan here because dataPlaceToPage
- * prefers to receive tuples in TID order.
+ * Attempt to launch parallel worker scan when required
+ *
+ * XXX plan_create_index_workers makes the number of workers dependent on
+ * maintenance_work_mem, requiring 32MB for each worker. For GIN that's
+ * reasonable too, because we sort the data just like btree. It does
+ * ignore the memory used to accumulate data in memory (set by work_mem),
+ * but there is no way to communicate that to plan_create_index_workers.
*/
- reltuples = table_index_build_scan(heap, index, indexInfo, false, true,
- ginBuildCallback, (void *) &buildstate,
- NULL);
+ if (indexInfo->ii_ParallelWorkers > 0)
+ _gin_begin_parallel(state, heap, index, indexInfo->ii_Concurrent,
+ indexInfo->ii_ParallelWorkers);
- /* dump remaining entries to the index */
- oldCtx = MemoryContextSwitchTo(buildstate.tmpCtx);
- ginBeginBAScan(&buildstate.accum);
- while ((list = ginGetBAEntry(&buildstate.accum,
- &attnum, &key, &category, &nlist)) != NULL)
+ /*
+ * If parallel build requested and at least one worker process was
+ * successfully launched, set up coordination state, wait for workers to
+ * complete. Then read all tuples from the shared tuplesort and insert
+ * them into the index.
+ *
+ * In serial mode, simply scan the table and build the index one index
+ * tuple at a time.
+ */
+ if (state->bs_leader)
{
- /* there could be many entries, so be willing to abort here */
- CHECK_FOR_INTERRUPTS();
- ginEntryInsert(&buildstate.ginstate, attnum, key, category,
- list, nlist, &buildstate.buildStats);
+ SortCoordinate coordinate;
+
+ coordinate = (SortCoordinate) palloc0(sizeof(SortCoordinateData));
+ coordinate->isWorker = false;
+ coordinate->nParticipants =
+ state->bs_leader->nparticipanttuplesorts;
+ coordinate->sharedsort = state->bs_leader->sharedsort;
+
+ /*
+ * Begin leader tuplesort.
+ *
+ * In cases where parallelism is involved, the leader receives the
+ * same share of maintenance_work_mem as a serial sort (it is
+ * generally treated in the same way as a serial sort once we return).
+ * Parallel worker Tuplesortstates will have received only a fraction
+ * of maintenance_work_mem, though.
+ *
+ * We rely on the lifetime of the Leader Tuplesortstate almost not
+ * overlapping with any worker Tuplesortstate's lifetime. There may
+ * be some small overlap, but that's okay because we rely on leader
+ * Tuplesortstate only allocating a small, fixed amount of memory
+ * here. When its tuplesort_performsort() is called (by our caller),
+ * and significant amounts of memory are likely to be used, all
+ * workers must have already freed almost all memory held by their
+ * Tuplesortstates (they are about to go away completely, too). The
+ * overall effect is that maintenance_work_mem always represents an
+ * absolute high watermark on the amount of memory used by a CREATE
+ * INDEX operation, regardless of the use of parallelism or any other
+ * factor.
+ */
+ state->bs_sortstate =
+ tuplesort_begin_index_gin(heap, index,
+ maintenance_work_mem, coordinate,
+ TUPLESORT_NONE);
+
+ /* scan the relation in parallel and merge per-worker results */
+ reltuples = _gin_parallel_merge(state);
+
+ _gin_end_parallel(state->bs_leader, state);
+ }
+ else /* no parallel index build */
+ {
+ /*
+ * Do the heap scan. We disallow sync scan here because
+ * dataPlaceToPage prefers to receive tuples in TID order.
+ */
+ reltuples = table_index_build_scan(heap, index, indexInfo, false, true,
+ ginBuildCallback, &buildstate, NULL);
+
+ /* dump remaining entries to the index */
+ oldCtx = MemoryContextSwitchTo(buildstate.tmpCtx);
+ ginBeginBAScan(&buildstate.accum);
+ while ((list = ginGetBAEntry(&buildstate.accum,
+ &attnum, &key, &category, &nlist)) != NULL)
+ {
+ /* there could be many entries, so be willing to abort here */
+ CHECK_FOR_INTERRUPTS();
+ ginEntryInsert(&buildstate.ginstate, attnum, key, category,
+ list, nlist, &buildstate.buildStats);
+ }
+ MemoryContextSwitchTo(oldCtx);
}
- MemoryContextSwitchTo(oldCtx);
MemoryContextDelete(buildstate.funcCtx);
MemoryContextDelete(buildstate.tmpCtx);
@@ -497,7 +838,7 @@ gininsert(Relation index, Datum *values, bool *isnull,
oldCtx = MemoryContextSwitchTo(indexInfo->ii_Context);
ginstate = (GinState *) palloc(sizeof(GinState));
initGinState(ginstate, index);
- indexInfo->ii_AmCache = (void *) ginstate;
+ indexInfo->ii_AmCache = ginstate;
MemoryContextSwitchTo(oldCtx);
}
@@ -534,3 +875,1565 @@ gininsert(Relation index, Datum *values, bool *isnull,
return false;
}
+
+/*
+ * Create parallel context, and launch workers for leader.
+ *
+ * buildstate argument should be initialized (with the exception of the
+ * tuplesort states, which may later be created based on shared
+ * state initially set up here).
+ *
+ * isconcurrent indicates if operation is CREATE INDEX CONCURRENTLY.
+ *
+ * request is the target number of parallel worker processes to launch.
+ *
+ * Sets buildstate's GinLeader, which caller must use to shut down parallel
+ * mode by passing it to _gin_end_parallel() at the very end of its index
+ * build. If not even a single worker process can be launched, this is
+ * never set, and caller should proceed with a serial index build.
+ */
+static void
+_gin_begin_parallel(GinBuildState *buildstate, Relation heap, Relation index,
+ bool isconcurrent, int request)
+{
+ ParallelContext *pcxt;
+ int scantuplesortstates;
+ Snapshot snapshot;
+ Size estginshared;
+ Size estsort;
+ GinBuildShared *ginshared;
+ Sharedsort *sharedsort;
+ GinLeader *ginleader = (GinLeader *) palloc0(sizeof(GinLeader));
+ WalUsage *walusage;
+ BufferUsage *bufferusage;
+ bool leaderparticipates = true;
+ int querylen;
+
+#ifdef DISABLE_LEADER_PARTICIPATION
+ leaderparticipates = false;
+#endif
+
+ /*
+ * Enter parallel mode, and create context for parallel build of gin index
+ */
+ EnterParallelMode();
+ Assert(request > 0);
+ pcxt = CreateParallelContext("postgres", "_gin_parallel_build_main",
+ request);
+
+ scantuplesortstates = leaderparticipates ? request + 1 : request;
+
+ /*
+ * Prepare for scan of the base relation. In a normal index build, we use
+ * SnapshotAny because we must retrieve all tuples and do our own time
+ * qual checks (because we have to index RECENTLY_DEAD tuples). In a
+ * concurrent build, we take a regular MVCC snapshot and index whatever's
+ * live according to that.
+ */
+ if (!isconcurrent)
+ snapshot = SnapshotAny;
+ else
+ snapshot = RegisterSnapshot(GetTransactionSnapshot());
+
+ /*
+ * Estimate size for our own PARALLEL_KEY_GIN_SHARED workspace.
+ */
+ estginshared = _gin_parallel_estimate_shared(heap, snapshot);
+ shm_toc_estimate_chunk(&pcxt->estimator, estginshared);
+ estsort = tuplesort_estimate_shared(scantuplesortstates);
+ shm_toc_estimate_chunk(&pcxt->estimator, estsort);
+
+ shm_toc_estimate_keys(&pcxt->estimator, 2);
+
+ /*
+ * Estimate space for WalUsage and BufferUsage -- PARALLEL_KEY_WAL_USAGE
+ * and PARALLEL_KEY_BUFFER_USAGE.
+ *
+ * If there are no extensions loaded that care, we could skip this. We
+ * have no way of knowing whether anyone's looking at pgWalUsage or
+ * pgBufferUsage, so do it unconditionally.
+ */
+ shm_toc_estimate_chunk(&pcxt->estimator,
+ mul_size(sizeof(WalUsage), pcxt->nworkers));
+ shm_toc_estimate_keys(&pcxt->estimator, 1);
+ shm_toc_estimate_chunk(&pcxt->estimator,
+ mul_size(sizeof(BufferUsage), pcxt->nworkers));
+ shm_toc_estimate_keys(&pcxt->estimator, 1);
+
+ /* Finally, estimate PARALLEL_KEY_QUERY_TEXT space */
+ if (debug_query_string)
+ {
+ querylen = strlen(debug_query_string);
+ shm_toc_estimate_chunk(&pcxt->estimator, querylen + 1);
+ shm_toc_estimate_keys(&pcxt->estimator, 1);
+ }
+ else
+ querylen = 0; /* keep compiler quiet */
+
+ /* Everyone's had a chance to ask for space, so now create the DSM */
+ InitializeParallelDSM(pcxt);
+
+ /* If no DSM segment was available, back out (do serial build) */
+ if (pcxt->seg == NULL)
+ {
+ if (IsMVCCSnapshot(snapshot))
+ UnregisterSnapshot(snapshot);
+ DestroyParallelContext(pcxt);
+ ExitParallelMode();
+ return;
+ }
+
+ /* Store shared build state, for which we reserved space */
+ ginshared = (GinBuildShared *) shm_toc_allocate(pcxt->toc, estginshared);
+ /* Initialize immutable state */
+ ginshared->heaprelid = RelationGetRelid(heap);
+ ginshared->indexrelid = RelationGetRelid(index);
+ ginshared->isconcurrent = isconcurrent;
+ ginshared->scantuplesortstates = scantuplesortstates;
+
+ ConditionVariableInit(&ginshared->workersdonecv);
+ SpinLockInit(&ginshared->mutex);
+
+ /* Initialize mutable state */
+ ginshared->nparticipantsdone = 0;
+ ginshared->reltuples = 0.0;
+ ginshared->indtuples = 0.0;
+
+ table_parallelscan_initialize(heap,
+ ParallelTableScanFromGinBuildShared(ginshared),
+ snapshot);
+
+ /*
+ * Store shared tuplesort-private state, for which we reserved space.
+ * Then, initialize opaque state using tuplesort routine.
+ */
+ sharedsort = (Sharedsort *) shm_toc_allocate(pcxt->toc, estsort);
+ tuplesort_initialize_shared(sharedsort, scantuplesortstates,
+ pcxt->seg);
+
+ shm_toc_insert(pcxt->toc, PARALLEL_KEY_GIN_SHARED, ginshared);
+ shm_toc_insert(pcxt->toc, PARALLEL_KEY_TUPLESORT, sharedsort);
+
+ /* Store query string for workers */
+ if (debug_query_string)
+ {
+ char *sharedquery;
+
+ sharedquery = (char *) shm_toc_allocate(pcxt->toc, querylen + 1);
+ memcpy(sharedquery, debug_query_string, querylen + 1);
+ shm_toc_insert(pcxt->toc, PARALLEL_KEY_QUERY_TEXT, sharedquery);
+ }
+
+ /*
+ * Allocate space for each worker's WalUsage and BufferUsage; no need to
+ * initialize.
+ */
+ walusage = shm_toc_allocate(pcxt->toc,
+ mul_size(sizeof(WalUsage), pcxt->nworkers));
+ shm_toc_insert(pcxt->toc, PARALLEL_KEY_WAL_USAGE, walusage);
+ bufferusage = shm_toc_allocate(pcxt->toc,
+ mul_size(sizeof(BufferUsage), pcxt->nworkers));
+ shm_toc_insert(pcxt->toc, PARALLEL_KEY_BUFFER_USAGE, bufferusage);
+
+ /* Launch workers, saving status for leader/caller */
+ LaunchParallelWorkers(pcxt);
+ ginleader->pcxt = pcxt;
+ ginleader->nparticipanttuplesorts = pcxt->nworkers_launched;
+ if (leaderparticipates)
+ ginleader->nparticipanttuplesorts++;
+ ginleader->ginshared = ginshared;
+ ginleader->sharedsort = sharedsort;
+ ginleader->snapshot = snapshot;
+ ginleader->walusage = walusage;
+ ginleader->bufferusage = bufferusage;
+
+ /* If no workers were successfully launched, back out (do serial build) */
+ if (pcxt->nworkers_launched == 0)
+ {
+ _gin_end_parallel(ginleader, NULL);
+ return;
+ }
+
+ /* Save leader state now that it's clear build will be parallel */
+ buildstate->bs_leader = ginleader;
+
+ /* Join heap scan ourselves */
+ if (leaderparticipates)
+ _gin_leader_participate_as_worker(buildstate, heap, index);
+
+ /*
+ * Caller needs to wait for all launched workers when we return. Make
+ * sure that the failure-to-start case will not hang forever.
+ */
+ WaitForParallelWorkersToAttach(pcxt);
+}
+
+/*
+ * Shut down workers, destroy parallel context, and end parallel mode.
+ */
+static void
+_gin_end_parallel(GinLeader *ginleader, GinBuildState *state)
+{
+ int i;
+
+ /* Shutdown worker processes */
+ WaitForParallelWorkersToFinish(ginleader->pcxt);
+
+ /*
+ * Next, accumulate WAL usage. (This must wait for the workers to finish,
+ * or we might get incomplete data.)
+ */
+ for (i = 0; i < ginleader->pcxt->nworkers_launched; i++)
+ InstrAccumParallelQuery(&ginleader->bufferusage[i], &ginleader->walusage[i]);
+
+ /* Free last reference to MVCC snapshot, if one was used */
+ if (IsMVCCSnapshot(ginleader->snapshot))
+ UnregisterSnapshot(ginleader->snapshot);
+ DestroyParallelContext(ginleader->pcxt);
+ ExitParallelMode();
+}
+
+/*
+ * Within leader, wait for end of heap scan.
+ *
+ * When called, parallel heap scan started by _gin_begin_parallel() will
+ * already be underway within worker processes (when leader participates
+ * as a worker, we should end up here just as workers are finishing).
+ *
+ * Returns the total number of heap tuples scanned.
+ */
+static double
+_gin_parallel_heapscan(GinBuildState *state)
+{
+ GinBuildShared *ginshared = state->bs_leader->ginshared;
+ int nparticipanttuplesorts;
+
+ nparticipanttuplesorts = state->bs_leader->nparticipanttuplesorts;
+ for (;;)
+ {
+ SpinLockAcquire(&ginshared->mutex);
+ if (ginshared->nparticipantsdone == nparticipanttuplesorts)
+ {
+ /* copy the data into leader state */
+ state->bs_reltuples = ginshared->reltuples;
+ state->bs_numtuples = ginshared->indtuples;
+
+ SpinLockRelease(&ginshared->mutex);
+ break;
+ }
+ SpinLockRelease(&ginshared->mutex);
+
+ ConditionVariableSleep(&ginshared->workersdonecv,
+ WAIT_EVENT_PARALLEL_CREATE_INDEX_SCAN);
+ }
+
+ ConditionVariableCancelSleep();
+
+ return state->bs_reltuples;
+}
+
+/*
+ * Buffer used to accumulate TIDs from multiple GinTuples for the same key
+ * (we read these from the tuplesort, sorted by the key).
+ *
+ * This is similar to BuildAccumulator in that it's used to collect TIDs
+ * in memory before inserting them into the index, but it's much simpler
+ * as it only deals with a single index key at a time.
+ *
+ * When adding TIDs to the buffer, we make sure to keep them sorted, both
+ * during the initial table scan (and detecting when the scan wraps around),
+ * and during merging (where we do mergesort).
+ */
+typedef struct GinBuffer
+{
+ OffsetNumber attnum;
+ GinNullCategory category;
+ Datum key; /* 0 if no key (and keylen == 0) */
+ Size keylen; /* number of bytes (not typlen) */
+
+ /* type info */
+ int16 typlen;
+ bool typbyval;
+
+ /* Number of TIDs to collect before attempt to write some out. */
+ int maxitems;
+
+ /* array of TID values */
+ int nitems;
+ int nfrozen;
+ SortSupport ssup; /* for sorting/comparing keys */
+ ItemPointerData *items;
+} GinBuffer;
+
+/*
+ * Check that TID array contains valid values, and that it's sorted (if we
+ * expect it to be).
+ */
+static void
+AssertCheckItemPointers(GinBuffer *buffer)
+{
+#ifdef USE_ASSERT_CHECKING
+ /* we should not have a buffer with no TIDs to sort */
+ Assert(buffer->items != NULL);
+ Assert(buffer->nitems > 0);
+
+ for (int i = 0; i < buffer->nitems; i++)
+ {
+ Assert(ItemPointerIsValid(&buffer->items[i]));
+
+ /* don't check ordering for the first TID item */
+ if (i == 0)
+ continue;
+
+ Assert(ItemPointerCompare(&buffer->items[i - 1], &buffer->items[i]) < 0);
+ }
+#endif
+}
+
+/*
+ * GinBuffer checks
+ *
+ * Make sure the nitems/items fields are consistent (either the array is empty
+ * or not empty, the fields need to agree). If there are items, check ordering.
+ */
+static void
+AssertCheckGinBuffer(GinBuffer *buffer)
+{
+#ifdef USE_ASSERT_CHECKING
+ /* if we have any items, the array must exist */
+ Assert(!((buffer->nitems > 0) && (buffer->items == NULL)));
+
+ /*
+ * The buffer may be empty, in which case we must not call the check of
+ * item pointers, because that assumes non-emptiness.
+ */
+ if (buffer->nitems == 0)
+ return;
+
+ /* Make sure the item pointers are valid and sorted. */
+ AssertCheckItemPointers(buffer);
+#endif
+}
+
+/*
+ * GinBufferInit
+ * Initialize buffer to store tuples for a GIN index.
+ *
+ * Initialize the buffer used to accumulate TID for a single key at a time
+ * (we process the data sorted), so we know when we received all data for
+ * a given key.
+ *
+ * Initializes sort support procedures for all index attributes.
+ */
+static GinBuffer *
+GinBufferInit(Relation index)
+{
+ GinBuffer *buffer = palloc0(sizeof(GinBuffer));
+ int i,
+ nKeys;
+ TupleDesc desc = RelationGetDescr(index);
+
+ /*
+ * How many items can we fit into the memory limit? We don't want to end
+ * with too many TIDs. and 64kB seems more than enough. But maybe this
+ * should be tied to maintenance_work_mem or something like that?
+ */
+ buffer->maxitems = (64 * 1024L) / sizeof(ItemPointerData);
+
+ nKeys = IndexRelationGetNumberOfKeyAttributes(index);
+
+ buffer->ssup = palloc0(sizeof(SortSupportData) * nKeys);
+
+ /*
+ * Lookup ordering operator for the index key data type, and initialize
+ * the sort support function.
+ */
+ for (i = 0; i < nKeys; i++)
+ {
+ Oid cmpFunc;
+ SortSupport sortKey = &buffer->ssup[i];
+ Form_pg_attribute att = TupleDescAttr(desc, i);
+
+ sortKey->ssup_cxt = CurrentMemoryContext;
+ sortKey->ssup_collation = index->rd_indcollation[i];
+
+ if (!OidIsValid(sortKey->ssup_collation))
+ sortKey->ssup_collation = DEFAULT_COLLATION_OID;
+
+ sortKey->ssup_nulls_first = false;
+ sortKey->ssup_attno = i + 1;
+ sortKey->abbreviate = false;
+
+ Assert(sortKey->ssup_attno != 0);
+
+ /*
+ * If the compare proc isn't specified in the opclass definition, look
+ * up the index key type's default btree comparator.
+ */
+ cmpFunc = index_getprocid(index, i + 1, GIN_COMPARE_PROC);
+ if (cmpFunc == InvalidOid)
+ {
+ TypeCacheEntry *typentry;
+
+ typentry = lookup_type_cache(att->atttypid,
+ TYPECACHE_CMP_PROC_FINFO);
+ if (!OidIsValid(typentry->cmp_proc_finfo.fn_oid))
+ ereport(ERROR,
+ (errcode(ERRCODE_UNDEFINED_FUNCTION),
+ errmsg("could not identify a comparison function for type %s",
+ format_type_be(att->atttypid))));
+
+ cmpFunc = typentry->cmp_proc_finfo.fn_oid;
+ }
+
+ PrepareSortSupportComparisonShim(cmpFunc, sortKey);
+ }
+
+ return buffer;
+}
+
+/* Is the buffer empty, i.e. has no TID values in the array? */
+static bool
+GinBufferIsEmpty(GinBuffer *buffer)
+{
+ return (buffer->nitems == 0);
+}
+
+/*
+ * GinBufferKeyEquals
+ * Can the buffer store TIDs for the provided GIN tuple (same key)?
+ *
+ * Compare if the tuple matches the already accumulated data in the GIN
+ * buffer. Compare scalar fields first, before the actual key.
+ *
+ * Returns true if the key matches, and the TID belongs to the buffer, or
+ * false if the key does not match.
+ */
+static bool
+GinBufferKeyEquals(GinBuffer *buffer, GinTuple *tup)
+{
+ int r;
+ Datum tupkey;
+
+ AssertCheckGinBuffer(buffer);
+
+ if (tup->attrnum != buffer->attnum)
+ return false;
+
+ /* same attribute should have the same type info */
+ Assert(tup->typbyval == buffer->typbyval);
+ Assert(tup->typlen == buffer->typlen);
+
+ if (tup->category != buffer->category)
+ return false;
+
+ /*
+ * For NULL/empty keys, this means equality, for normal keys we need to
+ * compare the actual key value.
+ */
+ if (buffer->category != GIN_CAT_NORM_KEY)
+ return true;
+
+ /*
+ * For the tuple, get either the first sizeof(Datum) bytes for byval
+ * types, or a pointer to the beginning of the data array.
+ */
+ tupkey = (buffer->typbyval) ? *(Datum *) tup->data : PointerGetDatum(tup->data);
+
+ r = ApplySortComparator(buffer->key, false,
+ tupkey, false,
+ &buffer->ssup[buffer->attnum - 1]);
+
+ return (r == 0);
+}
+
+/*
+ * GinBufferShouldTrim
+ * Should we trim the list of item pointers?
+ *
+ * By trimming we understand writing out and removing the tuple IDs that
+ * we know can't change by future merges. We can deduce the TID up to which
+ * this is guaranteed from the "first" TID in each GIN tuple, which provides
+ * a "horizon" (for a given key) thanks to the sort.
+ *
+ * We don't want to do this too often - compressing longer TID lists is more
+ * efficient. But we also don't want to accumulate too many TIDs, for two
+ * reasons. First, it consumes memory and we might exceed maintenance_work_mem
+ * (or whatever limit applies), even if that's unlikely because TIDs are very
+ * small so we can fit a lot of them. Second, and more importantly, long TID
+ * lists are an issue if the scan wraps around, because a key may get a very
+ * wide list (with min/max TID for that key), forcing "full" mergesorts for
+ * every list merged into it (instead of the efficient append).
+ *
+ * So we look at two things when deciding if to trim - if the resulting list
+ * (after adding TIDs from the new tuple) would be too long, and if there is
+ * enough TIDs to trim (with values less than "first" TID from the new tuple),
+ * we do the trim. By enough we mean at least 128 TIDs (mostly an arbitrary
+ * number).
+ */
+static bool
+GinBufferShouldTrim(GinBuffer *buffer, GinTuple *tup)
+{
+ /* not enough TIDs to trim (1024 is somewhat arbitrary number) */
+ if (buffer->nfrozen < 1024)
+ return false;
+
+ /* no need to trim if we have not hit the memory limit yet */
+ if ((buffer->nitems + tup->nitems) < buffer->maxitems)
+ return false;
+
+ /*
+ * OK, we have enough frozen TIDs to flush, and we have hit the memory
+ * limit, so it's time to write it out.
+ */
+ return true;
+}
+
+/*
+ * GinBufferStoreTuple
+ * Add data (especially TID list) from a GIN tuple to the buffer.
+ *
+ * The buffer is expected to be empty (in which case it's initialized), or
+ * having the same key. The TID values from the tuple are combined with the
+ * stored values using a merge sort.
+ *
+ * The tuples (for the same key) are expected to be sorted by first TID. But
+ * this does not guarantee the lists do not overlap, especially in the leader,
+ * because the workers process interleaving data. There should be no overlaps
+ * in a single worker - it could happen when the parallel scan wraps around,
+ * but we detect that and flush the data (see ginBuildCallbackParallel).
+ *
+ * By sorting the GinTuple not only by key, but also by the first TID, we make
+ * it more less likely the lists will overlap during merge. We merge them using
+ * mergesort, but it's cheaper to just append one list to the other.
+ *
+ * How often can the lists overlap? There should be no overlaps in workers,
+ * and in the leader we can see overlaps between lists built by different
+ * workers. But the workers merge the items as much as possible, so there
+ * should not be too many.
+ */
+static void
+GinBufferStoreTuple(GinBuffer *buffer, GinTuple *tup)
+{
+ ItemPointerData *items;
+ Datum key;
+
+ AssertCheckGinBuffer(buffer);
+
+ key = _gin_parse_tuple_key(tup);
+ items = _gin_parse_tuple_items(tup);
+
+ /* if the buffer is empty, set the fields (and copy the key) */
+ if (GinBufferIsEmpty(buffer))
+ {
+ buffer->category = tup->category;
+ buffer->keylen = tup->keylen;
+ buffer->attnum = tup->attrnum;
+
+ buffer->typlen = tup->typlen;
+ buffer->typbyval = tup->typbyval;
+
+ if (tup->category == GIN_CAT_NORM_KEY)
+ buffer->key = datumCopy(key, buffer->typbyval, buffer->typlen);
+ else
+ buffer->key = (Datum) 0;
+ }
+
+ /*
+ * Try freeze TIDs at the beginning of the list, i.e. exclude them from
+ * the mergesort. We can do that with TIDs before the first TID in the new
+ * tuple we're about to add into the buffer.
+ *
+ * We do this incrementally when adding data into the in-memory buffer,
+ * and not later (e.g. when hitting a memory limit), because it allows us
+ * to skip the frozen data during the mergesort, making it cheaper.
+ */
+
+ /*
+ * Check if the last TID in the current list is frozen. This is the case
+ * when merging non-overlapping lists, e.g. in each parallel worker.
+ */
+ if ((buffer->nitems > 0) &&
+ (ItemPointerCompare(&buffer->items[buffer->nitems - 1],
+ GinTupleGetFirst(tup)) == 0))
+ buffer->nfrozen = buffer->nitems;
+
+ /*
+ * Now find the last TID we know to be frozen, i.e. the last TID right
+ * before the new GIN tuple.
+ *
+ * Start with the first not-yet-frozen tuple, and walk until we find the
+ * first TID that's higher. If we already know the whole list is frozen
+ * (i.e. nfrozen == nitems), this does nothing.
+ *
+ * XXX This might do a binary search for sufficiently long lists, but it
+ * does not seem worth the complexity. Overlapping lists should be rare
+ * common, TID comparisons are cheap, and we should quickly freeze most of
+ * the list.
+ */
+ for (int i = buffer->nfrozen; i < buffer->nitems; i++)
+ {
+ /* Is the TID after the first TID of the new tuple? Can't freeze. */
+ if (ItemPointerCompare(&buffer->items[i],
+ GinTupleGetFirst(tup)) > 0)
+ break;
+
+ buffer->nfrozen++;
+ }
+
+ /* add the new TIDs into the buffer, combine using merge-sort */
+ {
+ int nnew;
+ ItemPointer new;
+
+ /*
+ * Resize the array - we do this first, because we'll dereference the
+ * first unfrozen TID, which would fail if the array is NULL. We'll
+ * still pass 0 as number of elements in that array though.
+ */
+ if (buffer->items == NULL)
+ buffer->items = palloc((buffer->nitems + tup->nitems) * sizeof(ItemPointerData));
+ else
+ buffer->items = repalloc(buffer->items,
+ (buffer->nitems + tup->nitems) * sizeof(ItemPointerData));
+
+ new = ginMergeItemPointers(&buffer->items[buffer->nfrozen], /* first unfrozen */
+ (buffer->nitems - buffer->nfrozen), /* num of unfrozen */
+ items, tup->nitems, &nnew);
+
+ Assert(nnew == (tup->nitems + (buffer->nitems - buffer->nfrozen)));
+
+ memcpy(&buffer->items[buffer->nfrozen], new,
+ nnew * sizeof(ItemPointerData));
+
+ pfree(new);
+
+ buffer->nitems += tup->nitems;
+
+ AssertCheckItemPointers(buffer);
+ }
+
+ /* free the decompressed TID list */
+ pfree(items);
+}
+
+/*
+ * GinBufferReset
+ * Reset the buffer into a state as if it contains no data.
+ */
+static void
+GinBufferReset(GinBuffer *buffer)
+{
+ Assert(!GinBufferIsEmpty(buffer));
+
+ /* release byref values, do nothing for by-val ones */
+ if ((buffer->category == GIN_CAT_NORM_KEY) && !buffer->typbyval)
+ pfree(DatumGetPointer(buffer->key));
+
+ /*
+ * Not required, but makes it more likely to trigger NULL dereference if
+ * using the value incorrectly, etc.
+ */
+ buffer->key = (Datum) 0;
+
+ buffer->attnum = 0;
+ buffer->category = 0;
+ buffer->keylen = 0;
+ buffer->nitems = 0;
+ buffer->nfrozen = 0;
+
+ buffer->typlen = 0;
+ buffer->typbyval = 0;
+}
+
+/*
+ * GinBufferTrim
+ * Discard the "frozen" part of the TID list (which should have been
+ * written to disk/index before this call).
+ */
+static void
+GinBufferTrim(GinBuffer *buffer)
+{
+ Assert((buffer->nfrozen > 0) && (buffer->nfrozen <= buffer->nitems));
+
+ memmove(&buffer->items[0], &buffer->items[buffer->nfrozen],
+ sizeof(ItemPointerData) * (buffer->nitems - buffer->nfrozen));
+
+ buffer->nitems -= buffer->nfrozen;
+ buffer->nfrozen = 0;
+}
+
+/*
+ * GinBufferFree
+ * Release memory associated with the GinBuffer (including TID array).
+ */
+static void
+GinBufferFree(GinBuffer *buffer)
+{
+ if (buffer->items)
+ pfree(buffer->items);
+
+ /* release byref values, do nothing for by-val ones */
+ if (!GinBufferIsEmpty(buffer) &&
+ (buffer->category == GIN_CAT_NORM_KEY) && !buffer->typbyval)
+ pfree(DatumGetPointer(buffer->key));
+
+ pfree(buffer);
+}
+
+/*
+ * GinBufferCanAddKey
+ * Check if a given GIN tuple can be added to the current buffer.
+ *
+ * Returns true if the buffer is either empty or for the same index key.
+ */
+static bool
+GinBufferCanAddKey(GinBuffer *buffer, GinTuple *tup)
+{
+ /* empty buffer can accept data for any key */
+ if (GinBufferIsEmpty(buffer))
+ return true;
+
+ /* otherwise just data for the same key */
+ return GinBufferKeyEquals(buffer, tup);
+}
+
+/*
+ * Within leader, wait for end of heap scan and merge per-worker results.
+ *
+ * After waiting for all workers to finish, merge the per-worker results into
+ * the complete index. The results from each worker are sorted by block number
+ * (start of the page range). While combining the per-worker results we merge
+ * summaries for the same page range, and also fill-in empty summaries for
+ * ranges without any tuples.
+ *
+ * Returns the total number of heap tuples scanned.
+ */
+static double
+_gin_parallel_merge(GinBuildState *state)
+{
+ GinTuple *tup;
+ Size tuplen;
+ double reltuples = 0;
+ GinBuffer *buffer;
+
+ /* GIN tuples from workers, merged by leader */
+ double numtuples = 0;
+
+ /* wait for workers to scan table and produce partial results */
+ reltuples = _gin_parallel_heapscan(state);
+
+ /* Execute the sort */
+ pgstat_progress_update_param(PROGRESS_CREATEIDX_SUBPHASE,
+ PROGRESS_GIN_PHASE_PERFORMSORT_2);
+
+ /* do the actual sort in the leader */
+ tuplesort_performsort(state->bs_sortstate);
+
+ /*
+ * Initialize buffer to combine entries for the same key.
+ *
+ * The leader is allowed to use the whole maintenance_work_mem buffer to
+ * combine data. The parallel workers already completed.
+ */
+ buffer = GinBufferInit(state->ginstate.index);
+
+ /*
+ * Set the progress target for the next phase. Reset the block number
+ * values set by table_index_build_scan
+ */
+ {
+ const int progress_index[] = {
+ PROGRESS_CREATEIDX_SUBPHASE,
+ PROGRESS_CREATEIDX_TUPLES_TOTAL,
+ PROGRESS_SCAN_BLOCKS_TOTAL,
+ PROGRESS_SCAN_BLOCKS_DONE
+ };
+ const int64 progress_vals[] = {
+ PROGRESS_GIN_PHASE_MERGE_2,
+ state->bs_numtuples,
+ 0, 0
+ };
+
+ pgstat_progress_update_multi_param(4, progress_index, progress_vals);
+ }
+
+ /*
+ * Read the GIN tuples from the shared tuplesort, sorted by category and
+ * key. That probably gives us order matching how data is organized in the
+ * index.
+ *
+ * We don't insert the GIN tuples right away, but instead accumulate as
+ * many TIDs for the same key as possible, and then insert that at once.
+ * This way we don't need to decompress/recompress the posting lists, etc.
+ */
+ while ((tup = tuplesort_getgintuple(state->bs_sortstate, &tuplen, true)) != NULL)
+ {
+ MemoryContext oldCtx;
+
+ CHECK_FOR_INTERRUPTS();
+
+ /*
+ * If the buffer can accept the new GIN tuple, just store it there and
+ * we're done. If it's a different key (or maybe too much data) flush
+ * the current contents into the index first.
+ */
+ if (!GinBufferCanAddKey(buffer, tup))
+ {
+ /*
+ * Buffer is not empty and it's storing a different key - flush
+ * the data into the insert, and start a new entry for current
+ * GinTuple.
+ */
+ AssertCheckItemPointers(buffer);
+
+ oldCtx = MemoryContextSwitchTo(state->tmpCtx);
+
+ ginEntryInsert(&state->ginstate,
+ buffer->attnum, buffer->key, buffer->category,
+ buffer->items, buffer->nitems, &state->buildStats);
+
+ MemoryContextSwitchTo(oldCtx);
+ MemoryContextReset(state->tmpCtx);
+
+ /* discard the existing data */
+ GinBufferReset(buffer);
+ }
+
+ /*
+ * We're about to add a GIN tuple to the buffer - check the memory
+ * limit first, and maybe write out some of the data into the index
+ * first, if needed (and possible). We only flush the part of the TID
+ * list that we know won't change, and only if there's enough data for
+ * compression to work well.
+ */
+ if (GinBufferShouldTrim(buffer, tup))
+ {
+ Assert(buffer->nfrozen > 0);
+
+ /*
+ * Buffer is not empty and it's storing a different key - flush
+ * the data into the insert, and start a new entry for current
+ * GinTuple.
+ */
+ AssertCheckItemPointers(buffer);
+
+ oldCtx = MemoryContextSwitchTo(state->tmpCtx);
+
+ ginEntryInsert(&state->ginstate,
+ buffer->attnum, buffer->key, buffer->category,
+ buffer->items, buffer->nfrozen, &state->buildStats);
+
+ MemoryContextSwitchTo(oldCtx);
+ MemoryContextReset(state->tmpCtx);
+
+ /* truncate the data we've just discarded */
+ GinBufferTrim(buffer);
+ }
+
+ /*
+ * Remember data for the current tuple (either remember the new key,
+ * or append if to the existing data).
+ */
+ GinBufferStoreTuple(buffer, tup);
+
+ /* Report progress */
+ pgstat_progress_update_param(PROGRESS_CREATEIDX_TUPLES_DONE,
+ ++numtuples);
+ }
+
+ /* flush data remaining in the buffer (for the last key) */
+ if (!GinBufferIsEmpty(buffer))
+ {
+ AssertCheckItemPointers(buffer);
+
+ ginEntryInsert(&state->ginstate,
+ buffer->attnum, buffer->key, buffer->category,
+ buffer->items, buffer->nitems, &state->buildStats);
+
+ /* discard the existing data */
+ GinBufferReset(buffer);
+
+ /* Report progress */
+ pgstat_progress_update_param(PROGRESS_CREATEIDX_TUPLES_DONE,
+ ++numtuples);
+ }
+
+ /* relase all the memory */
+ GinBufferFree(buffer);
+
+ tuplesort_end(state->bs_sortstate);
+
+ return reltuples;
+}
+
+/*
+ * Returns size of shared memory required to store state for a parallel
+ * gin index build based on the snapshot its parallel scan will use.
+ */
+static Size
+_gin_parallel_estimate_shared(Relation heap, Snapshot snapshot)
+{
+ /* c.f. shm_toc_allocate as to why BUFFERALIGN is used */
+ return add_size(BUFFERALIGN(sizeof(GinBuildShared)),
+ table_parallelscan_estimate(heap, snapshot));
+}
+
+/*
+ * Within leader, participate as a parallel worker.
+ */
+static void
+_gin_leader_participate_as_worker(GinBuildState *buildstate, Relation heap, Relation index)
+{
+ GinLeader *ginleader = buildstate->bs_leader;
+ int sortmem;
+
+ /*
+ * Might as well use reliable figure when doling out maintenance_work_mem
+ * (when requested number of workers were not launched, this will be
+ * somewhat higher than it is for other workers).
+ */
+ sortmem = maintenance_work_mem / ginleader->nparticipanttuplesorts;
+
+ /* Perform work common to all participants */
+ _gin_parallel_scan_and_build(buildstate, ginleader->ginshared,
+ ginleader->sharedsort, heap, index,
+ sortmem, true);
+}
+
+/*
+ * _gin_process_worker_data
+ * First phase of the key merging, happening in the worker.
+ *
+ * Depending on the number of distinct keys, the TID lists produced by the
+ * callback may be very short (due to frequent evictions in the callback).
+ * But combining many tiny lists is expensive, so we try to do as much as
+ * possible in the workers and only then pass the results to the leader.
+ *
+ * We read the tuples sorted by the key, and merge them into larger lists.
+ * At the moment there's no memory limit, so this will just produce one
+ * huge (sorted) list per key in each worker. Which means the leader will
+ * do a very limited number of mergesorts, which is good.
+ */
+static void
+_gin_process_worker_data(GinBuildState *state, Tuplesortstate *worker_sort,
+ bool progress)
+{
+ GinTuple *tup;
+ Size tuplen;
+
+ GinBuffer *buffer;
+
+ /*
+ * Initialize buffer to combine entries for the same key.
+ *
+ * The workers are limited to the same amount of memory as during the sort
+ * in ginBuildCallbackParallel. But this probably should be the 32MB used
+ * during planning, just like there.
+ */
+ buffer = GinBufferInit(state->ginstate.index);
+
+ /* sort the raw per-worker data */
+ if (progress)
+ pgstat_progress_update_param(PROGRESS_CREATEIDX_SUBPHASE,
+ PROGRESS_GIN_PHASE_PERFORMSORT_1);
+
+ tuplesort_performsort(state->bs_worker_sort);
+
+ /* reset the number of GIN tuples produced by this worker */
+ state->bs_numtuples = 0;
+
+ if (progress)
+ pgstat_progress_update_param(PROGRESS_CREATEIDX_SUBPHASE,
+ PROGRESS_GIN_PHASE_MERGE_1);
+
+ /*
+ * Read the GIN tuples from the shared tuplesort, sorted by the key, and
+ * merge them into larger chunks for the leader to combine.
+ */
+ while ((tup = tuplesort_getgintuple(worker_sort, &tuplen, true)) != NULL)
+ {
+
+ CHECK_FOR_INTERRUPTS();
+
+ /*
+ * If the buffer can accept the new GIN tuple, just store it there and
+ * we're done. If it's a different key (or maybe too much data) flush
+ * the current contents into the index first.
+ */
+ if (!GinBufferCanAddKey(buffer, tup))
+ {
+ GinTuple *ntup;
+ Size ntuplen;
+
+ /*
+ * Buffer is not empty and it's storing a different key - flush
+ * the data into the insert, and start a new entry for current
+ * GinTuple.
+ */
+ AssertCheckItemPointers(buffer);
+
+ ntup = _gin_build_tuple(buffer->attnum, buffer->category,
+ buffer->key, buffer->typlen, buffer->typbyval,
+ buffer->items, buffer->nitems, &ntuplen);
+
+ tuplesort_putgintuple(state->bs_sortstate, ntup, ntuplen);
+ state->bs_numtuples++;
+
+ pfree(ntup);
+
+ /* discard the existing data */
+ GinBufferReset(buffer);
+ }
+
+ /*
+ * We're about to add a GIN tuple to the buffer - check the memory
+ * limit first, and maybe write out some of the data into the index
+ * first, if needed (and possible). We only flush the part of the TID
+ * list that we know won't change, and only if there's enough data for
+ * compression to work well.
+ */
+ if (GinBufferShouldTrim(buffer, tup))
+ {
+ GinTuple *ntup;
+ Size ntuplen;
+
+ Assert(buffer->nfrozen > 0);
+
+ /*
+ * Buffer is not empty and it's storing a different key - flush
+ * the data into the insert, and start a new entry for current
+ * GinTuple.
+ */
+ AssertCheckItemPointers(buffer);
+
+ ntup = _gin_build_tuple(buffer->attnum, buffer->category,
+ buffer->key, buffer->typlen, buffer->typbyval,
+ buffer->items, buffer->nfrozen, &ntuplen);
+
+ tuplesort_putgintuple(state->bs_sortstate, ntup, ntuplen);
+
+ pfree(ntup);
+
+ /* truncate the data we've just discarded */
+ GinBufferTrim(buffer);
+ }
+
+ /*
+ * Remember data for the current tuple (either remember the new key,
+ * or append if to the existing data).
+ */
+ GinBufferStoreTuple(buffer, tup);
+ }
+
+ /* flush data remaining in the buffer (for the last key) */
+ if (!GinBufferIsEmpty(buffer))
+ {
+ GinTuple *ntup;
+ Size ntuplen;
+
+ AssertCheckItemPointers(buffer);
+
+ ntup = _gin_build_tuple(buffer->attnum, buffer->category,
+ buffer->key, buffer->typlen, buffer->typbyval,
+ buffer->items, buffer->nitems, &ntuplen);
+
+ tuplesort_putgintuple(state->bs_sortstate, ntup, ntuplen);
+ state->bs_numtuples++;
+
+ pfree(ntup);
+
+ /* discard the existing data */
+ GinBufferReset(buffer);
+ }
+
+ /* relase all the memory */
+ GinBufferFree(buffer);
+
+ tuplesort_end(worker_sort);
+}
+
+/*
+ * Perform a worker's portion of a parallel GIN index build sort.
+ *
+ * This generates a tuplesort for the worker portion of the table.
+ *
+ * sortmem is the amount of working memory to use within each worker,
+ * expressed in KBs.
+ *
+ * When this returns, workers are done, and need only release resources.
+ *
+ * Before feeding data into a shared tuplesort (for the leader process),
+ * the workers process data in two phases.
+ *
+ * 1) A worker reads a portion of rows from the table, accumulates entries
+ * in memory, and flushes them into a private tuplesort (e.g. because of
+ * using too much memory).
+ *
+ * 2) The private tuplesort gets sorted (by key and TID), the worker reads
+ * the data again, and combines the entries as much as possible. This has
+ * to happen eventually, and this way it's done in workers in parallel.
+ *
+ * Finally, the combined entries are written into the shared tuplesort, so
+ * that the leader can process them.
+ *
+ * How well this works (compared to just writing entries into the shared
+ * tuplesort) depends on the data set. For large tables with many distinct
+ * keys this helps a lot. With many distinct keys it's likely the buffers has
+ * to be flushed often, generating many entries with the same key and short
+ * TID lists. These entries need to be sorted and merged at some point,
+ * before writing them to the index. The merging is quite expensive, it can
+ * easily be ~50% of a serial build, and doing as much of it in the workers
+ * means it's parallelized. The leader still has to merge results from the
+ * workers, but it's much more efficient to merge few large entries than
+ * many tiny ones.
+ *
+ * This also reduces the amount of data the workers pass to the leader through
+ * the shared tuplesort. OTOH the workers need more space for the private sort,
+ * possibly up to 2x of the data, if no entries be merged in a worker. But this
+ * is very unlikely, and the only consequence is inefficiency, so we ignore it.
+ */
+static void
+_gin_parallel_scan_and_build(GinBuildState *state,
+ GinBuildShared *ginshared, Sharedsort *sharedsort,
+ Relation heap, Relation index,
+ int sortmem, bool progress)
+{
+ SortCoordinate coordinate;
+ TableScanDesc scan;
+ double reltuples;
+ IndexInfo *indexInfo;
+
+ /* Initialize local tuplesort coordination state */
+ coordinate = palloc0(sizeof(SortCoordinateData));
+ coordinate->isWorker = true;
+ coordinate->nParticipants = -1;
+ coordinate->sharedsort = sharedsort;
+
+ /* remember how much space is allowed for the accumulated entries */
+ state->work_mem = (sortmem / 2);
+
+ /* Begin "partial" tuplesort */
+ state->bs_sortstate = tuplesort_begin_index_gin(heap, index,
+ state->work_mem,
+ coordinate,
+ TUPLESORT_NONE);
+
+ /* Local per-worker sort of raw-data */
+ state->bs_worker_sort = tuplesort_begin_index_gin(heap, index,
+ state->work_mem,
+ NULL,
+ TUPLESORT_NONE);
+
+ /* Join parallel scan */
+ indexInfo = BuildIndexInfo(index);
+ indexInfo->ii_Concurrent = ginshared->isconcurrent;
+
+ scan = table_beginscan_parallel(heap,
+ ParallelTableScanFromGinBuildShared(ginshared));
+
+ reltuples = table_index_build_scan(heap, index, indexInfo, true, progress,
+ ginBuildCallbackParallel, state, scan);
+
+ /* write remaining accumulated entries */
+ ginFlushBuildState(state, index);
+
+ /*
+ * Do the first phase of in-worker processing - sort the data produced by
+ * the callback, and combine them into much larger chunks and place that
+ * into the shared tuplestore for leader to process.
+ */
+ _gin_process_worker_data(state, state->bs_worker_sort, progress);
+
+ /* sort the GIN tuples built by this worker */
+ tuplesort_performsort(state->bs_sortstate);
+
+ state->bs_reltuples += reltuples;
+
+ /*
+ * Done. Record ambuild statistics.
+ */
+ SpinLockAcquire(&ginshared->mutex);
+ ginshared->nparticipantsdone++;
+ ginshared->reltuples += state->bs_reltuples;
+ ginshared->indtuples += state->bs_numtuples;
+ SpinLockRelease(&ginshared->mutex);
+
+ /* Notify leader */
+ ConditionVariableSignal(&ginshared->workersdonecv);
+
+ tuplesort_end(state->bs_sortstate);
+}
+
+/*
+ * Perform work within a launched parallel process.
+ */
+void
+_gin_parallel_build_main(dsm_segment *seg, shm_toc *toc)
+{
+ char *sharedquery;
+ GinBuildShared *ginshared;
+ Sharedsort *sharedsort;
+ GinBuildState buildstate;
+ Relation heapRel;
+ Relation indexRel;
+ LOCKMODE heapLockmode;
+ LOCKMODE indexLockmode;
+ WalUsage *walusage;
+ BufferUsage *bufferusage;
+ int sortmem;
+
+ /*
+ * The only possible status flag that can be set to the parallel worker is
+ * PROC_IN_SAFE_IC.
+ */
+ Assert((MyProc->statusFlags == 0) ||
+ (MyProc->statusFlags == PROC_IN_SAFE_IC));
+
+ /* Set debug_query_string for individual workers first */
+ sharedquery = shm_toc_lookup(toc, PARALLEL_KEY_QUERY_TEXT, true);
+ debug_query_string = sharedquery;
+
+ /* Report the query string from leader */
+ pgstat_report_activity(STATE_RUNNING, debug_query_string);
+
+ /* Look up gin shared state */
+ ginshared = shm_toc_lookup(toc, PARALLEL_KEY_GIN_SHARED, false);
+
+ /* Open relations using lock modes known to be obtained by index.c */
+ if (!ginshared->isconcurrent)
+ {
+ heapLockmode = ShareLock;
+ indexLockmode = AccessExclusiveLock;
+ }
+ else
+ {
+ heapLockmode = ShareUpdateExclusiveLock;
+ indexLockmode = RowExclusiveLock;
+ }
+
+ /* Open relations within worker */
+ heapRel = table_open(ginshared->heaprelid, heapLockmode);
+ indexRel = index_open(ginshared->indexrelid, indexLockmode);
+
+ /* initialize the GIN build state */
+ initGinState(&buildstate.ginstate, indexRel);
+ buildstate.indtuples = 0;
+ memset(&buildstate.buildStats, 0, sizeof(GinStatsData));
+ memset(&buildstate.tid, 0, sizeof(ItemPointerData));
+
+ /*
+ * create a temporary memory context that is used to hold data not yet
+ * dumped out to the index
+ */
+ buildstate.tmpCtx = AllocSetContextCreate(CurrentMemoryContext,
+ "Gin build temporary context",
+ ALLOCSET_DEFAULT_SIZES);
+
+ /*
+ * create a temporary memory context that is used for calling
+ * ginExtractEntries(), and can be reset after each tuple
+ */
+ buildstate.funcCtx = AllocSetContextCreate(CurrentMemoryContext,
+ "Gin build temporary context for user-defined function",
+ ALLOCSET_DEFAULT_SIZES);
+
+ buildstate.accum.ginstate = &buildstate.ginstate;
+ ginInitBA(&buildstate.accum);
+
+
+ /* Look up shared state private to tuplesort.c */
+ sharedsort = shm_toc_lookup(toc, PARALLEL_KEY_TUPLESORT, false);
+ tuplesort_attach_shared(sharedsort, seg);
+
+ /* Prepare to track buffer usage during parallel execution */
+ InstrStartParallelQuery();
+
+ /*
+ * Might as well use reliable figure when doling out maintenance_work_mem
+ * (when requested number of workers were not launched, this will be
+ * somewhat higher than it is for other workers).
+ */
+ sortmem = maintenance_work_mem / ginshared->scantuplesortstates;
+
+ _gin_parallel_scan_and_build(&buildstate, ginshared, sharedsort,
+ heapRel, indexRel, sortmem, false);
+
+ /* Report WAL/buffer usage during parallel execution */
+ bufferusage = shm_toc_lookup(toc, PARALLEL_KEY_BUFFER_USAGE, false);
+ walusage = shm_toc_lookup(toc, PARALLEL_KEY_WAL_USAGE, false);
+ InstrEndParallelQuery(&bufferusage[ParallelWorkerNumber],
+ &walusage[ParallelWorkerNumber]);
+
+ index_close(indexRel, indexLockmode);
+ table_close(heapRel, heapLockmode);
+}
+
+/*
+ * Used to keep track of compressed TID lists when building a GIN tuple.
+ */
+typedef struct
+{
+ dlist_node node; /* linked list pointers */
+ GinPostingList *seg;
+} GinSegmentInfo;
+
+/*
+ * _gin_build_tuple
+ * Serialize the state for an index key into a tuple for tuplesort.
+ *
+ * The tuple has a number of scalar fields (mostly matching the build state),
+ * and then a data array that stores the key first, and then the TID list.
+ *
+ * For by-reference data types, we store the actual data. For by-val types
+ * we simply copy the whole Datum, so that we don't have to care about stuff
+ * like endianess etc. We could make it a little bit smaller, but it's not
+ * worth it - it's a tiny fraction of the data, and we need to MAXALIGN the
+ * start of the TID list anyway. So we wouldn't save anything. (This would
+ * not be a good idea for the permanent in-index data, since we'd prefer
+ * that that not depend on sizeof(Datum). But this is just a transient
+ * representation to use while sorting the data.)
+ *
+ * The TID list is serialized as compressed - it's highly compressible, and
+ * we already have ginCompressPostingList for this purpose. The list may be
+ * pretty long, so we compress it into multiple segments and then copy all
+ * of that into the GIN tuple.
+ */
+static GinTuple *
+_gin_build_tuple(OffsetNumber attrnum, unsigned char category,
+ Datum key, int16 typlen, bool typbyval,
+ ItemPointerData *items, uint32 nitems,
+ Size *len)
+{
+ GinTuple *tuple;
+ char *ptr;
+
+ Size tuplen;
+ int keylen;
+
+ dlist_mutable_iter iter;
+ dlist_head segments;
+ int ncompressed;
+ Size compresslen;
+
+ /*
+ * Calculate how long is the key value. Only keys with GIN_CAT_NORM_KEY
+ * have actual non-empty key. We include varlena headers and \0 bytes for
+ * strings, to make it easier to access the data in-line.
+ *
+ * For byval types we simply copy the whole Datum. We could store just the
+ * necessary bytes, but this is simpler to work with and not worth the
+ * extra complexity. Moreover we still need to do the MAXALIGN to allow
+ * direct access to items pointers.
+ *
+ * XXX Note that for byval types we store the whole datum, no matter what
+ * the typlen value is.
+ */
+ if (category != GIN_CAT_NORM_KEY)
+ keylen = 0;
+ else if (typbyval)
+ keylen = sizeof(Datum);
+ else if (typlen > 0)
+ keylen = typlen;
+ else if (typlen == -1)
+ keylen = VARSIZE_ANY(DatumGetPointer(key));
+ else if (typlen == -2)
+ keylen = strlen(DatumGetPointer(key)) + 1;
+ else
+ elog(ERROR, "unexpected typlen value (%d)", typlen);
+
+ /* compress the item pointers */
+ ncompressed = 0;
+ compresslen = 0;
+ dlist_init(&segments);
+
+ /* generate compressed segments of TID list chunks */
+ while (ncompressed < nitems)
+ {
+ int cnt;
+ GinSegmentInfo *seginfo = palloc(sizeof(GinSegmentInfo));
+
+ seginfo->seg = ginCompressPostingList(&items[ncompressed],
+ (nitems - ncompressed),
+ UINT16_MAX,
+ &cnt);
+
+ ncompressed += cnt;
+ compresslen += SizeOfGinPostingList(seginfo->seg);
+
+ dlist_push_tail(&segments, &seginfo->node);
+ }
+
+ /*
+ * Determine GIN tuple length with all the data included. Be careful about
+ * alignment, to allow direct access to compressed segments (those require
+ * only SHORTALIGN).
+ */
+ tuplen = SHORTALIGN(offsetof(GinTuple, data) + keylen) + compresslen;
+
+ *len = tuplen;
+
+ /*
+ * Allocate space for the whole GIN tuple.
+ *
+ * The palloc0 is needed - writetup_index_gin will write the whole tuple
+ * to disk, so we need to make sure the padding bytes are defined
+ * (otherwise valgrind would report this).
+ */
+ tuple = palloc0(tuplen);
+
+ tuple->tuplen = tuplen;
+ tuple->attrnum = attrnum;
+ tuple->category = category;
+ tuple->keylen = keylen;
+ tuple->nitems = nitems;
+
+ /* key type info */
+ tuple->typlen = typlen;
+ tuple->typbyval = typbyval;
+
+ /*
+ * Copy the key and items into the tuple. First the key value, which we
+ * can simply copy right at the beginning of the data array.
+ */
+ if (category == GIN_CAT_NORM_KEY)
+ {
+ if (typbyval)
+ {
+ memcpy(tuple->data, &key, sizeof(Datum));
+ }
+ else if (typlen > 0) /* byref, fixed length */
+ {
+ memcpy(tuple->data, DatumGetPointer(key), typlen);
+ }
+ else if (typlen == -1)
+ {
+ memcpy(tuple->data, DatumGetPointer(key), keylen);
+ }
+ else if (typlen == -2)
+ {
+ memcpy(tuple->data, DatumGetPointer(key), keylen);
+ }
+ }
+
+ /* finally, copy the TIDs into the array */
+ ptr = (char *) tuple + SHORTALIGN(offsetof(GinTuple, data) + keylen);
+
+ /* copy in the compressed data, and free the segments */
+ dlist_foreach_modify(iter, &segments)
+ {
+ GinSegmentInfo *seginfo = dlist_container(GinSegmentInfo, node, iter.cur);
+
+ memcpy(ptr, seginfo->seg, SizeOfGinPostingList(seginfo->seg));
+
+ ptr += SizeOfGinPostingList(seginfo->seg);
+
+ dlist_delete(&seginfo->node);
+
+ pfree(seginfo->seg);
+ pfree(seginfo);
+ }
+
+ return tuple;
+}
+
+/*
+ * _gin_parse_tuple_key
+ * Return a Datum representing the key stored in the tuple.
+ *
+ * Most of the tuple fields are directly accessible, the only thing that
+ * needs more care is the key and the TID list.
+ *
+ * For the key, this returns a regular Datum representing it. It's either the
+ * actual key value, or a pointer to the beginning of the data array (which is
+ * where the data was copied by _gin_build_tuple).
+ */
+static Datum
+_gin_parse_tuple_key(GinTuple *a)
+{
+ Datum key;
+
+ if (a->category != GIN_CAT_NORM_KEY)
+ return (Datum) 0;
+
+ if (a->typbyval)
+ {
+ memcpy(&key, a->data, a->keylen);
+ return key;
+ }
+
+ return PointerGetDatum(a->data);
+}
+
+/*
+* _gin_parse_tuple_items
+ * Return a pointer to a palloc'd array of decompressed TID array.
+ */
+static ItemPointer
+_gin_parse_tuple_items(GinTuple *a)
+{
+ int len;
+ char *ptr;
+ int ndecoded;
+ ItemPointer items;
+
+ len = a->tuplen - SHORTALIGN(offsetof(GinTuple, data) + a->keylen);
+ ptr = (char *) a + SHORTALIGN(offsetof(GinTuple, data) + a->keylen);
+
+ items = ginPostingListDecodeAllSegments((GinPostingList *) ptr, len, &ndecoded);
+
+ Assert(ndecoded == a->nitems);
+
+ return (ItemPointer) items;
+}
+
+/*
+ * _gin_compare_tuples
+ * Compare GIN tuples, used by tuplesort during parallel index build.
+ *
+ * The scalar fields (attrnum, category) are compared first, the key value is
+ * compared last. The comparisons are done using type-specific sort support
+ * functions.
+ *
+ * If the key value matches, we compare the first TID value in the TID list,
+ * which means the tuples are merged in an order in which they are most
+ * likely to be simply concatenated. (This "first" TID will also allow us
+ * to determine a point up to which the list is fully determined and can be
+ * written into the index to enforce a memory limit etc.)
+ */
+int
+_gin_compare_tuples(GinTuple *a, GinTuple *b, SortSupport ssup)
+{
+ int r;
+ Datum keya,
+ keyb;
+
+ if (a->attrnum < b->attrnum)
+ return -1;
+
+ if (a->attrnum > b->attrnum)
+ return 1;
+
+ if (a->category < b->category)
+ return -1;
+
+ if (a->category > b->category)
+ return 1;
+
+ if (a->category == GIN_CAT_NORM_KEY)
+ {
+ keya = _gin_parse_tuple_key(a);
+ keyb = _gin_parse_tuple_key(b);
+
+ r = ApplySortComparator(keya, false,
+ keyb, false,
+ &ssup[a->attrnum - 1]);
+
+ /* if the key is the same, consider the first TID in the array */
+ return (r != 0) ? r : ItemPointerCompare(GinTupleGetFirst(a),
+ GinTupleGetFirst(b));
+ }
+
+ return ItemPointerCompare(GinTupleGetFirst(a),
+ GinTupleGetFirst(b));
+}
diff --git a/src/backend/access/gin/ginlogic.c b/src/backend/access/gin/ginlogic.c
index 28caf91f85736..ff456247cefac 100644
--- a/src/backend/access/gin/ginlogic.c
+++ b/src/backend/access/gin/ginlogic.c
@@ -24,7 +24,7 @@
* is used for.)
*
*
- * Portions Copyright (c) 1996-2024, PostgreSQL Global Development Group
+ * Portions Copyright (c) 1996-2025, PostgreSQL Global Development Group
* Portions Copyright (c) 1994, Regents of the University of California
*
* IDENTIFICATION
@@ -140,7 +140,9 @@ shimBoolConsistentFn(GinScanKey key)
* every combination is O(n^2), so this is only feasible for a small number of
* MAYBE inputs.
*
- * NB: This function modifies the key->entryRes array!
+ * NB: This function modifies the key->entryRes array. For now that's okay
+ * so long as we restore the entry-time contents before returning. This may
+ * need revisiting if we ever invent multithreaded GIN scans, though.
*/
static GinTernaryValue
shimTriConsistentFn(GinScanKey key)
@@ -149,7 +151,7 @@ shimTriConsistentFn(GinScanKey key)
int maybeEntries[MAX_MAYBE_ENTRIES];
int i;
bool boolResult;
- bool recheck = false;
+ bool recheck;
GinTernaryValue curResult;
/*
@@ -169,8 +171,8 @@ shimTriConsistentFn(GinScanKey key)
}
/*
- * If none of the inputs were MAYBE, so we can just call consistent
- * function as is.
+ * If none of the inputs were MAYBE, we can just call the consistent
+ * function as-is.
*/
if (nmaybe == 0)
return directBoolConsistentFn(key);
@@ -179,6 +181,7 @@ shimTriConsistentFn(GinScanKey key)
for (i = 0; i < nmaybe; i++)
key->entryRes[maybeEntries[i]] = GIN_FALSE;
curResult = directBoolConsistentFn(key);
+ recheck = key->recheckCurItem;
for (;;)
{
@@ -200,13 +203,20 @@ shimTriConsistentFn(GinScanKey key)
recheck |= key->recheckCurItem;
if (curResult != boolResult)
- return GIN_MAYBE;
+ {
+ curResult = GIN_MAYBE;
+ break;
+ }
}
/* TRUE with recheck is taken to mean MAYBE */
if (curResult == GIN_TRUE && recheck)
curResult = GIN_MAYBE;
+ /* We must restore the original state of the entryRes array */
+ for (i = 0; i < nmaybe; i++)
+ key->entryRes[maybeEntries[i]] = GIN_MAYBE;
+
return curResult;
}
diff --git a/src/backend/access/gin/ginpostinglist.c b/src/backend/access/gin/ginpostinglist.c
index 708f9f49ec162..48eadec87b0b1 100644
--- a/src/backend/access/gin/ginpostinglist.c
+++ b/src/backend/access/gin/ginpostinglist.c
@@ -4,7 +4,7 @@
* routines for dealing with posting lists.
*
*
- * Portions Copyright (c) 1996-2024, PostgreSQL Global Development Group
+ * Portions Copyright (c) 1996-2025, PostgreSQL Global Development Group
* Portions Copyright (c) 1994, Regents of the University of California
*
* IDENTIFICATION
diff --git a/src/backend/access/gin/ginscan.c b/src/backend/access/gin/ginscan.c
index af24d38544eb9..26081693383c7 100644
--- a/src/backend/access/gin/ginscan.c
+++ b/src/backend/access/gin/ginscan.c
@@ -4,7 +4,7 @@
* routines to manage scans of inverted index relations
*
*
- * Portions Copyright (c) 1996-2024, PostgreSQL Global Development Group
+ * Portions Copyright (c) 1996-2025, PostgreSQL Global Development Group
* Portions Copyright (c) 1994, Regents of the University of California
*
* IDENTIFICATION
@@ -68,8 +68,13 @@ ginFillScanEntry(GinScanOpaque so, OffsetNumber attnum,
*
* Entries with non-null extra_data are never considered identical, since
* we can't know exactly what the opclass might be doing with that.
+ *
+ * Also, give up de-duplication once we have 100 entries. That avoids
+ * spending O(N^2) time on probably-fruitless de-duplication of large
+ * search-key sets. The threshold of 100 is arbitrary but matches
+ * predtest.c's threshold for what's a large array.
*/
- if (extra_data == NULL)
+ if (extra_data == NULL && so->totalentries < 100)
{
for (i = 0; i < so->totalentries; i++)
{
@@ -106,7 +111,8 @@ ginFillScanEntry(GinScanOpaque so, OffsetNumber attnum,
ItemPointerSetMin(&scanEntry->curItem);
scanEntry->matchBitmap = NULL;
scanEntry->matchIterator = NULL;
- scanEntry->matchResult = NULL;
+ scanEntry->matchResult.blockno = InvalidBlockNumber;
+ scanEntry->matchNtuples = -1;
scanEntry->list = NULL;
scanEntry->nlist = 0;
scanEntry->offset = InvalidOffsetNumber;
@@ -246,7 +252,7 @@ ginFreeScanKeys(GinScanOpaque so)
if (entry->list)
pfree(entry->list);
if (entry->matchIterator)
- tbm_end_iterate(entry->matchIterator);
+ tbm_end_private_iterate(entry->matchIterator);
if (entry->matchBitmap)
tbm_free(entry->matchBitmap);
}
@@ -265,6 +271,7 @@ ginNewScanKey(IndexScanDesc scan)
ScanKey scankey = scan->keyData;
GinScanOpaque so = (GinScanOpaque) scan->opaque;
int i;
+ int numExcludeOnly;
bool hasNullQuery = false;
bool attrHasNormalScan[INDEX_MAX_KEYS] = {false};
MemoryContext oldCtx;
@@ -387,6 +394,7 @@ ginNewScanKey(IndexScanDesc scan)
* excludeOnly scan key must receive a GIN_CAT_EMPTY_QUERY hidden entry
* and be set to normal (excludeOnly = false).
*/
+ numExcludeOnly = 0;
for (i = 0; i < so->nkeys; i++)
{
GinScanKey key = &so->keys[i];
@@ -400,6 +408,47 @@ ginNewScanKey(IndexScanDesc scan)
ginScanKeyAddHiddenEntry(so, key, GIN_CAT_EMPTY_QUERY);
attrHasNormalScan[key->attnum - 1] = true;
}
+ else
+ numExcludeOnly++;
+ }
+
+ /*
+ * If we left any excludeOnly scan keys as-is, move them to the end of the
+ * scan key array: they must appear after normal key(s).
+ */
+ if (numExcludeOnly > 0)
+ {
+ GinScanKey tmpkeys;
+ int iNormalKey;
+ int iExcludeOnly;
+
+ /* We'd better have made at least one normal key */
+ Assert(numExcludeOnly < so->nkeys);
+ /* Make a temporary array to hold the re-ordered scan keys */
+ tmpkeys = (GinScanKey) palloc(so->nkeys * sizeof(GinScanKeyData));
+ /* Re-order the keys ... */
+ iNormalKey = 0;
+ iExcludeOnly = so->nkeys - numExcludeOnly;
+ for (i = 0; i < so->nkeys; i++)
+ {
+ GinScanKey key = &so->keys[i];
+
+ if (key->excludeOnly)
+ {
+ memcpy(tmpkeys + iExcludeOnly, key, sizeof(GinScanKeyData));
+ iExcludeOnly++;
+ }
+ else
+ {
+ memcpy(tmpkeys + iNormalKey, key, sizeof(GinScanKeyData));
+ iNormalKey++;
+ }
+ }
+ Assert(iNormalKey == so->nkeys - numExcludeOnly);
+ Assert(iExcludeOnly == so->nkeys);
+ /* ... and copy them back to so->keys[] */
+ memcpy(so->keys, tmpkeys, so->nkeys * sizeof(GinScanKeyData));
+ pfree(tmpkeys);
}
/*
@@ -436,6 +485,8 @@ ginNewScanKey(IndexScanDesc scan)
MemoryContextSwitchTo(oldCtx);
pgstat_count_index_scan(scan->indexRelation);
+ if (scan->instrument)
+ scan->instrument->nsearches++;
}
void
@@ -447,10 +498,7 @@ ginrescan(IndexScanDesc scan, ScanKey scankey, int nscankeys,
ginFreeScanKeys(so);
if (scankey && scan->numberOfKeys > 0)
- {
- memmove(scan->keyData, scankey,
- scan->numberOfKeys * sizeof(ScanKeyData));
- }
+ memcpy(scan->keyData, scankey, scan->numberOfKeys * sizeof(ScanKeyData));
}
diff --git a/src/backend/access/gin/ginutil.c b/src/backend/access/gin/ginutil.c
index 5747ae6a4cabe..78f7b7a2495cf 100644
--- a/src/backend/access/gin/ginutil.c
+++ b/src/backend/access/gin/ginutil.c
@@ -4,7 +4,7 @@
* Utility routines for the Postgres inverted index access method.
*
*
- * Portions Copyright (c) 1996-2024, PostgreSQL Global Development Group
+ * Portions Copyright (c) 1996-2025, PostgreSQL Global Development Group
* Portions Copyright (c) 1994, Regents of the University of California
*
* IDENTIFICATION
@@ -20,6 +20,7 @@
#include "access/xloginsert.h"
#include "catalog/pg_collation.h"
#include "catalog/pg_type.h"
+#include "commands/progress.h"
#include "commands/vacuum.h"
#include "miscadmin.h"
#include "storage/indexfsm.h"
@@ -43,6 +44,9 @@ ginhandler(PG_FUNCTION_ARGS)
amroutine->amoptsprocnum = GIN_OPTIONS_PROC;
amroutine->amcanorder = false;
amroutine->amcanorderbyop = false;
+ amroutine->amcanhash = false;
+ amroutine->amconsistentequality = false;
+ amroutine->amconsistentordering = false;
amroutine->amcanbackward = false;
amroutine->amcanunique = false;
amroutine->amcanmulticol = true;
@@ -53,7 +57,7 @@ ginhandler(PG_FUNCTION_ARGS)
amroutine->amclusterable = false;
amroutine->ampredlocks = true;
amroutine->amcanparallel = false;
- amroutine->amcanbuildparallel = false;
+ amroutine->amcanbuildparallel = true;
amroutine->amcaninclude = false;
amroutine->amusemaintenanceworkmem = true;
amroutine->amsummarizing = false;
@@ -69,9 +73,10 @@ ginhandler(PG_FUNCTION_ARGS)
amroutine->amvacuumcleanup = ginvacuumcleanup;
amroutine->amcanreturn = NULL;
amroutine->amcostestimate = gincostestimate;
+ amroutine->amgettreeheight = NULL;
amroutine->amoptions = ginoptions;
amroutine->amproperty = NULL;
- amroutine->ambuildphasename = NULL;
+ amroutine->ambuildphasename = ginbuildphasename;
amroutine->amvalidate = ginvalidate;
amroutine->amadjustmembers = ginadjustmembers;
amroutine->ambeginscan = ginbeginscan;
@@ -688,7 +693,7 @@ ginUpdateStats(Relation index, const GinStatsData *stats, bool is_build)
memcpy(&data.metadata, metadata, sizeof(GinMetaPageData));
XLogBeginInsert();
- XLogRegisterData((char *) &data, sizeof(ginxlogUpdateMeta));
+ XLogRegisterData(&data, sizeof(ginxlogUpdateMeta));
XLogRegisterBuffer(0, metabuffer, REGBUF_WILL_INIT | REGBUF_STANDARD);
recptr = XLogInsert(RM_GIN_ID, XLOG_GIN_UPDATE_META_PAGE);
@@ -699,3 +704,28 @@ ginUpdateStats(Relation index, const GinStatsData *stats, bool is_build)
END_CRIT_SECTION();
}
+
+/*
+ * ginbuildphasename() -- Return name of index build phase.
+ */
+char *
+ginbuildphasename(int64 phasenum)
+{
+ switch (phasenum)
+ {
+ case PROGRESS_CREATEIDX_SUBPHASE_INITIALIZE:
+ return "initializing";
+ case PROGRESS_GIN_PHASE_INDEXBUILD_TABLESCAN:
+ return "scanning table";
+ case PROGRESS_GIN_PHASE_PERFORMSORT_1:
+ return "sorting tuples (workers)";
+ case PROGRESS_GIN_PHASE_MERGE_1:
+ return "merging tuples (workers)";
+ case PROGRESS_GIN_PHASE_PERFORMSORT_2:
+ return "sorting tuples";
+ case PROGRESS_GIN_PHASE_MERGE_2:
+ return "merging tuples";
+ default:
+ return NULL;
+ }
+}
diff --git a/src/backend/access/gin/ginvacuum.c b/src/backend/access/gin/ginvacuum.c
index b3f415e2849a0..2d833d6d61875 100644
--- a/src/backend/access/gin/ginvacuum.c
+++ b/src/backend/access/gin/ginvacuum.c
@@ -4,7 +4,7 @@
* delete & vacuum routines for the postgres GIN
*
*
- * Portions Copyright (c) 1996-2024, PostgreSQL Global Development Group
+ * Portions Copyright (c) 1996-2025, PostgreSQL Global Development Group
* Portions Copyright (c) 1994, Regents of the University of California
*
* IDENTIFICATION
@@ -19,7 +19,6 @@
#include "access/xloginsert.h"
#include "commands/vacuum.h"
#include "miscadmin.h"
-#include "postmaster/autovacuum.h"
#include "storage/indexfsm.h"
#include "storage/lmgr.h"
#include "storage/predicate.h"
@@ -217,7 +216,7 @@ ginDeletePage(GinVacuumState *gvs, BlockNumber deleteBlkno, BlockNumber leftBlkn
data.rightLink = GinPageGetOpaque(page)->rightlink;
data.deleteXid = GinPageGetDeleteXid(page);
- XLogRegisterData((char *) &data, sizeof(ginxlogDeletePage));
+ XLogRegisterData(&data, sizeof(ginxlogDeletePage));
recptr = XLogInsert(RM_GIN_ID, XLOG_GIN_DELETE_PAGE);
PageSetLSN(page, recptr);
@@ -663,12 +662,12 @@ ginbulkdelete(IndexVacuumInfo *info, IndexBulkDeleteResult *stats,
UnlockReleaseBuffer(buffer);
}
- vacuum_delay_point();
+ vacuum_delay_point(false);
for (i = 0; i < nRoot; i++)
{
ginVacuumPostingTree(&gvs, rootOfPostingTree[i]);
- vacuum_delay_point();
+ vacuum_delay_point(false);
}
if (blkno == InvalidBlockNumber) /* rightmost page */
@@ -749,12 +748,12 @@ ginvacuumcleanup(IndexVacuumInfo *info, IndexBulkDeleteResult *stats)
Buffer buffer;
Page page;
- vacuum_delay_point();
+ vacuum_delay_point(false);
buffer = ReadBufferExtended(index, MAIN_FORKNUM, blkno,
RBM_NORMAL, info->strategy);
LockBuffer(buffer, GIN_SHARE);
- page = (Page) BufferGetPage(buffer);
+ page = BufferGetPage(buffer);
if (GinPageIsRecyclable(page))
{
diff --git a/src/backend/access/gin/ginvalidate.c b/src/backend/access/gin/ginvalidate.c
index 74420a129aa48..5b0bfe8cc1dbc 100644
--- a/src/backend/access/gin/ginvalidate.c
+++ b/src/backend/access/gin/ginvalidate.c
@@ -3,7 +3,7 @@
* ginvalidate.c
* Opclass validator for GIN.
*
- * Portions Copyright (c) 1996-2024, PostgreSQL Global Development Group
+ * Portions Copyright (c) 1996-2025, PostgreSQL Global Development Group
* Portions Copyright (c) 1994, Regents of the University of California
*
* IDENTIFICATION
@@ -19,8 +19,8 @@
#include "catalog/pg_amop.h"
#include "catalog/pg_amproc.h"
#include "catalog/pg_opclass.h"
-#include "catalog/pg_opfamily.h"
#include "catalog/pg_type.h"
+#include "utils/lsyscache.h"
#include "utils/regproc.h"
#include "utils/syscache.h"
@@ -37,8 +37,6 @@ ginvalidate(Oid opclassoid)
Oid opcintype;
Oid opckeytype;
char *opclassname;
- HeapTuple familytup;
- Form_pg_opfamily familyform;
char *opfamilyname;
CatCList *proclist,
*oprlist;
@@ -61,12 +59,7 @@ ginvalidate(Oid opclassoid)
opclassname = NameStr(classform->opcname);
/* Fetch opfamily information */
- familytup = SearchSysCache1(OPFAMILYOID, ObjectIdGetDatum(opfamilyoid));
- if (!HeapTupleIsValid(familytup))
- elog(ERROR, "cache lookup failed for operator family %u", opfamilyoid);
- familyform = (Form_pg_opfamily) GETSTRUCT(familytup);
-
- opfamilyname = NameStr(familyform->opfname);
+ opfamilyname = get_opfamily_name(opfamilyoid, false);
/* Fetch all operators and support functions of the opfamily */
oprlist = SearchSysCacheList1(AMOPSTRATEGY, ObjectIdGetDatum(opfamilyoid));
@@ -264,7 +257,6 @@ ginvalidate(Oid opclassoid)
ReleaseCatCacheList(proclist);
ReleaseCatCacheList(oprlist);
- ReleaseSysCache(familytup);
ReleaseSysCache(classtup);
return result;
diff --git a/src/backend/access/gin/ginxlog.c b/src/backend/access/gin/ginxlog.c
index 07ba0b559eaea..4478e92820494 100644
--- a/src/backend/access/gin/ginxlog.c
+++ b/src/backend/access/gin/ginxlog.c
@@ -4,7 +4,7 @@
* WAL replay logic for inverted index.
*
*
- * Portions Copyright (c) 1996-2024, PostgreSQL Global Development Group
+ * Portions Copyright (c) 1996-2025, PostgreSQL Global Development Group
* Portions Copyright (c) 1994, Regents of the University of California
*
* IDENTIFICATION
@@ -30,7 +30,7 @@ ginRedoClearIncompleteSplit(XLogReaderState *record, uint8 block_id)
if (XLogReadBufferForRedo(record, block_id, &buffer) == BLK_NEEDS_REDO)
{
- page = (Page) BufferGetPage(buffer);
+ page = BufferGetPage(buffer);
GinPageGetOpaque(page)->flags &= ~GIN_INCOMPLETE_SPLIT;
PageSetLSN(page, lsn);
@@ -50,7 +50,7 @@ ginRedoCreatePTree(XLogReaderState *record)
Page page;
buffer = XLogInitBufferForRedo(record, 0);
- page = (Page) BufferGetPage(buffer);
+ page = BufferGetPage(buffer);
GinInitBuffer(buffer, GIN_DATA | GIN_LEAF | GIN_COMPRESSED);
diff --git a/src/backend/access/gin/meson.build b/src/backend/access/gin/meson.build
index bd52c98f14f56..6472831476d64 100644
--- a/src/backend/access/gin/meson.build
+++ b/src/backend/access/gin/meson.build
@@ -1,4 +1,4 @@
-# Copyright (c) 2022-2024, PostgreSQL Global Development Group
+# Copyright (c) 2022-2025, PostgreSQL Global Development Group
backend_sources += files(
'ginarrayproc.c',
diff --git a/src/backend/access/gist/gist.c b/src/backend/access/gist/gist.c
index ed4ffa63a7720..a96796d5c7da9 100644
--- a/src/backend/access/gist/gist.c
+++ b/src/backend/access/gist/gist.c
@@ -4,7 +4,7 @@
* interface routines for the postgres GiST index access method.
*
*
- * Portions Copyright (c) 1996-2024, PostgreSQL Global Development Group
+ * Portions Copyright (c) 1996-2025, PostgreSQL Global Development Group
* Portions Copyright (c) 1994, Regents of the University of California
*
* IDENTIFICATION
@@ -43,7 +43,7 @@ static void gistprunepage(Relation rel, Page page, Buffer buffer,
#define ROTATEDIST(d) do { \
- SplitPageLayout *tmp=(SplitPageLayout*)palloc0(sizeof(SplitPageLayout)); \
+ SplitPageLayout *tmp = (SplitPageLayout *) palloc0(sizeof(SplitPageLayout)); \
tmp->block.blkno = InvalidBlockNumber; \
tmp->buffer = InvalidBuffer; \
tmp->next = (d); \
@@ -65,6 +65,9 @@ gisthandler(PG_FUNCTION_ARGS)
amroutine->amoptsprocnum = GIST_OPTIONS_PROC;
amroutine->amcanorder = false;
amroutine->amcanorderbyop = true;
+ amroutine->amcanhash = false;
+ amroutine->amconsistentequality = false;
+ amroutine->amconsistentordering = false;
amroutine->amcanbackward = false;
amroutine->amcanunique = false;
amroutine->amcanmulticol = true;
@@ -91,6 +94,7 @@ gisthandler(PG_FUNCTION_ARGS)
amroutine->amvacuumcleanup = gistvacuumcleanup;
amroutine->amcanreturn = gistcanreturn;
amroutine->amcostestimate = gistcostestimate;
+ amroutine->amgettreeheight = NULL;
amroutine->amoptions = gistoptions;
amroutine->amproperty = gistproperty;
amroutine->ambuildphasename = NULL;
@@ -106,6 +110,8 @@ gisthandler(PG_FUNCTION_ARGS)
amroutine->amestimateparallelscan = NULL;
amroutine->aminitparallelscan = NULL;
amroutine->amparallelrescan = NULL;
+ amroutine->amtranslatestrategy = NULL;
+ amroutine->amtranslatecmptype = gisttranslatecmptype;
PG_RETURN_POINTER(amroutine);
}
@@ -172,14 +178,13 @@ gistinsert(Relation r, Datum *values, bool *isnull,
oldCxt = MemoryContextSwitchTo(indexInfo->ii_Context);
giststate = initGISTstate(r);
giststate->tempCxt = createTempGistContext();
- indexInfo->ii_AmCache = (void *) giststate;
+ indexInfo->ii_AmCache = giststate;
MemoryContextSwitchTo(oldCxt);
}
oldCxt = MemoryContextSwitchTo(giststate->tempCxt);
- itup = gistFormTuple(giststate, r,
- values, isnull, true /* size is currently bogus */ );
+ itup = gistFormTuple(giststate, r, values, isnull, true);
itup->t_tid = *ht_ctid;
gistdoinsert(r, itup, 0, giststate, heapRel, false);
@@ -626,7 +631,7 @@ gistplacetopage(Relation rel, Size freespace, GISTSTATE *giststate,
}
/*
- * Workhouse routine for doing insertion into a GiST index. Note that
+ * Workhorse routine for doing insertion into a GiST index. Note that
* this routine assumes it is invoked in a short-lived memory context,
* so it does not bother releasing palloc'd allocations.
*/
@@ -691,7 +696,7 @@ gistdoinsert(Relation r, IndexTuple itup, Size freespace,
gistcheckpage(state.r, stack->buffer);
}
- stack->page = (Page) BufferGetPage(stack->buffer);
+ stack->page = BufferGetPage(stack->buffer);
stack->lsn = xlocked ?
PageGetLSN(stack->page) : BufferGetLSNAtomic(stack->buffer);
Assert(!RelationNeedsWAL(state.r) || !XLogRecPtrIsInvalid(stack->lsn));
@@ -778,7 +783,7 @@ gistdoinsert(Relation r, IndexTuple itup, Size freespace,
LockBuffer(stack->buffer, GIST_UNLOCK);
LockBuffer(stack->buffer, GIST_EXCLUSIVE);
xlocked = true;
- stack->page = (Page) BufferGetPage(stack->buffer);
+ stack->page = BufferGetPage(stack->buffer);
if (PageGetLSN(stack->page) != stack->lsn)
{
@@ -842,7 +847,7 @@ gistdoinsert(Relation r, IndexTuple itup, Size freespace,
LockBuffer(stack->buffer, GIST_UNLOCK);
LockBuffer(stack->buffer, GIST_EXCLUSIVE);
xlocked = true;
- stack->page = (Page) BufferGetPage(stack->buffer);
+ stack->page = BufferGetPage(stack->buffer);
stack->lsn = PageGetLSN(stack->page);
if (stack->blkno == GIST_ROOT_BLKNO)
@@ -933,7 +938,7 @@ gistFindPath(Relation r, BlockNumber child, OffsetNumber *downlinkoffnum)
buffer = ReadBuffer(r, top->blkno);
LockBuffer(buffer, GIST_SHARE);
gistcheckpage(r, buffer);
- page = (Page) BufferGetPage(buffer);
+ page = BufferGetPage(buffer);
if (GistPageIsLeaf(page))
{
@@ -1028,7 +1033,7 @@ gistFindCorrectParent(Relation r, GISTInsertStack *child, bool is_build)
GISTInsertStack *ptr;
gistcheckpage(r, parent->buffer);
- parent->page = (Page) BufferGetPage(parent->buffer);
+ parent->page = BufferGetPage(parent->buffer);
maxoff = PageGetMaxOffsetNumber(parent->page);
/* Check if the downlink is still where it was before */
@@ -1043,12 +1048,19 @@ gistFindCorrectParent(Relation r, GISTInsertStack *child, bool is_build)
/*
* The page has changed since we looked. During normal operation, every
* update of a page changes its LSN, so the LSN we memorized should have
- * changed too. During index build, however, we don't WAL-log the changes
- * until we have built the index, so the LSN doesn't change. There is no
- * concurrent activity during index build, but we might have changed the
- * parent ourselves.
+ * changed too.
+ *
+ * During index build, however, we don't WAL-log the changes until we have
+ * built the index, so the LSN doesn't change. There is no concurrent
+ * activity during index build, but we might have changed the parent
+ * ourselves.
+ *
+ * We will also get here if child->downlinkoffnum is invalid. That happens
+ * if 'parent' had been updated by an earlier call to this function on its
+ * grandchild, which had to move right.
*/
- Assert(parent->lsn != PageGetLSN(parent->page) || is_build);
+ Assert(parent->lsn != PageGetLSN(parent->page) || is_build ||
+ child->downlinkoffnum == InvalidOffsetNumber);
/*
* Scan the page to re-find the downlink. If the page was split, it might
@@ -1086,7 +1098,7 @@ gistFindCorrectParent(Relation r, GISTInsertStack *child, bool is_build)
parent->buffer = ReadBuffer(r, parent->blkno);
LockBuffer(parent->buffer, GIST_EXCLUSIVE);
gistcheckpage(r, parent->buffer);
- parent->page = (Page) BufferGetPage(parent->buffer);
+ parent->page = BufferGetPage(parent->buffer);
}
/*
@@ -1109,7 +1121,7 @@ gistFindCorrectParent(Relation r, GISTInsertStack *child, bool is_build)
while (ptr)
{
ptr->buffer = ReadBuffer(r, ptr->blkno);
- ptr->page = (Page) BufferGetPage(ptr->buffer);
+ ptr->page = BufferGetPage(ptr->buffer);
ptr = ptr->parent;
}
@@ -1557,9 +1569,8 @@ initGISTstate(Relation index)
* tuples during page split. Also, B-tree is not adjusting tuples on
* internal pages the way GiST does.
*/
- giststate->nonLeafTupdesc = CreateTupleDescCopyConstr(index->rd_att);
- giststate->nonLeafTupdesc->natts =
- IndexRelationGetNumberOfKeyAttributes(index);
+ giststate->nonLeafTupdesc = CreateTupleDescTruncatedCopy(index->rd_att,
+ IndexRelationGetNumberOfKeyAttributes(index));
for (i = 0; i < IndexRelationGetNumberOfKeyAttributes(index); i++)
{
diff --git a/src/backend/access/gist/gistbuild.c b/src/backend/access/gist/gistbuild.c
index ba06df30fafeb..9b2ec9815f17e 100644
--- a/src/backend/access/gist/gistbuild.c
+++ b/src/backend/access/gist/gistbuild.c
@@ -22,7 +22,7 @@
* tuples (unless buffering mode is disabled).
*
*
- * Portions Copyright (c) 1996-2024, PostgreSQL Global Development Group
+ * Portions Copyright (c) 1996-2025, PostgreSQL Global Development Group
* Portions Copyright (c) 1994, Regents of the University of California
*
* IDENTIFICATION
@@ -273,7 +273,7 @@ gistbuild(Relation heap, Relation index, IndexInfo *indexInfo)
/* Scan the table, adding all tuples to the tuplesort */
reltuples = table_index_build_scan(heap, index, indexInfo, true, true,
gistSortedBuildCallback,
- (void *) &buildstate, NULL);
+ &buildstate, NULL);
/*
* Perform the sort and build index pages.
@@ -312,7 +312,7 @@ gistbuild(Relation heap, Relation index, IndexInfo *indexInfo)
/* Scan the table, inserting all the tuples to the index. */
reltuples = table_index_build_scan(heap, index, indexInfo, true, true,
gistBuildCallback,
- (void *) &buildstate, NULL);
+ &buildstate, NULL);
/*
* If buffering was used, flush out all the tuples that are still in
@@ -657,10 +657,12 @@ gistInitBuffering(GISTBuildState *buildstate)
itupMinSize = (Size) MAXALIGN(sizeof(IndexTupleData));
for (i = 0; i < index->rd_att->natts; i++)
{
- if (TupleDescAttr(index->rd_att, i)->attlen < 0)
+ CompactAttribute *attr = TupleDescCompactAttr(index->rd_att, i);
+
+ if (attr->attlen < 0)
itupMinSize += VARHDRSZ;
else
- itupMinSize += TupleDescAttr(index->rd_att, i)->attlen;
+ itupMinSize += attr->attlen;
}
/* Calculate average and maximal number of index tuples which fit to page */
@@ -967,7 +969,7 @@ gistProcessItup(GISTBuildState *buildstate, IndexTuple itup,
buffer = ReadBuffer(indexrel, blkno);
LockBuffer(buffer, GIST_EXCLUSIVE);
- page = (Page) BufferGetPage(buffer);
+ page = BufferGetPage(buffer);
childoffnum = gistchoose(indexrel, page, itup, giststate);
iid = PageGetItemId(page, childoffnum);
idxtuple = (IndexTuple) PageGetItem(page, iid);
@@ -1446,7 +1448,7 @@ gistGetMaxLevel(Relation index)
* pro forma.
*/
LockBuffer(buffer, GIST_SHARE);
- page = (Page) BufferGetPage(buffer);
+ page = BufferGetPage(buffer);
if (GistPageIsLeaf(page))
{
diff --git a/src/backend/access/gist/gistbuildbuffers.c b/src/backend/access/gist/gistbuildbuffers.c
index 4c2301da00500..0707254d18ea1 100644
--- a/src/backend/access/gist/gistbuildbuffers.c
+++ b/src/backend/access/gist/gistbuildbuffers.c
@@ -4,7 +4,7 @@
* node buffer management functions for GiST buffering build algorithm.
*
*
- * Portions Copyright (c) 1996-2024, PostgreSQL Global Development Group
+ * Portions Copyright (c) 1996-2025, PostgreSQL Global Development Group
* Portions Copyright (c) 1994, Regents of the University of California
*
* IDENTIFICATION
diff --git a/src/backend/access/gist/gistget.c b/src/backend/access/gist/gistget.c
index b35b8a9757752..387d997234537 100644
--- a/src/backend/access/gist/gistget.c
+++ b/src/backend/access/gist/gistget.c
@@ -4,7 +4,7 @@
* fetch tuples from a GiST scan.
*
*
- * Portions Copyright (c) 1996-2024, PostgreSQL Global Development Group
+ * Portions Copyright (c) 1996-2025, PostgreSQL Global Development Group
* Portions Copyright (c) 1994, Regents of the University of California
*
* IDENTIFICATION
@@ -625,6 +625,8 @@ gistgettuple(IndexScanDesc scan, ScanDirection dir)
GISTSearchItem fakeItem;
pgstat_count_index_scan(scan->indexRelation);
+ if (scan->instrument)
+ scan->instrument->nsearches++;
so->firstCall = false;
so->curPageData = so->nPageData = 0;
@@ -750,6 +752,8 @@ gistgetbitmap(IndexScanDesc scan, TIDBitmap *tbm)
return 0;
pgstat_count_index_scan(scan->indexRelation);
+ if (scan->instrument)
+ scan->instrument->nsearches++;
/* Begin the scan by processing the root page */
so->curPageData = so->nPageData = 0;
diff --git a/src/backend/access/gist/gistproc.c b/src/backend/access/gist/gistproc.c
index 781c2f7358814..f2ec6cbe2e524 100644
--- a/src/backend/access/gist/gistproc.c
+++ b/src/backend/access/gist/gistproc.c
@@ -7,7 +7,7 @@
* This gives R-tree behavior, with Guttman's poly-time split algorithm.
*
*
- * Portions Copyright (c) 1996-2024, PostgreSQL Global Development Group
+ * Portions Copyright (c) 1996-2025, PostgreSQL Global Development Group
* Portions Copyright (c) 1994, Regents of the University of California
*
* IDENTIFICATION
@@ -1707,8 +1707,8 @@ gist_bbox_zorder_cmp(Datum a, Datum b, SortSupport ssup)
* Abbreviated version of Z-order comparison
*
* The abbreviated format is a Z-order value computed from the two 32-bit
- * floats. If SIZEOF_DATUM == 8, the 64-bit Z-order value fits fully in the
- * abbreviated Datum, otherwise use its most significant bits.
+ * floats. Now that sizeof(Datum) is always 8, the 64-bit Z-order value
+ * always fits fully in the abbreviated Datum.
*/
static Datum
gist_bbox_zorder_abbrev_convert(Datum original, SortSupport ssup)
@@ -1718,11 +1718,7 @@ gist_bbox_zorder_abbrev_convert(Datum original, SortSupport ssup)
z = point_zorder_internal(p->x, p->y);
-#if SIZEOF_DATUM == 8
- return (Datum) z;
-#else
- return (Datum) (z >> 32);
-#endif
+ return UInt64GetDatum(z);
}
/*
diff --git a/src/backend/access/gist/gistscan.c b/src/backend/access/gist/gistscan.c
index e05801e2f5bf1..700fa959d03d8 100644
--- a/src/backend/access/gist/gistscan.c
+++ b/src/backend/access/gist/gistscan.c
@@ -4,7 +4,7 @@
* routines to manage scans on GiST index relations
*
*
- * Portions Copyright (c) 1996-2024, PostgreSQL Global Development Group
+ * Portions Copyright (c) 1996-2025, PostgreSQL Global Development Group
* Portions Copyright (c) 1994, Regents of the University of California
*
* IDENTIFICATION
@@ -233,8 +233,7 @@ gistrescan(IndexScanDesc scan, ScanKey key, int nkeys,
fn_extras[i] = scan->keyData[i].sk_func.fn_extra;
}
- memmove(scan->keyData, key,
- scan->numberOfKeys * sizeof(ScanKeyData));
+ memcpy(scan->keyData, key, scan->numberOfKeys * sizeof(ScanKeyData));
/*
* Modify the scan key so that the Consistent method is called for all
@@ -289,8 +288,7 @@ gistrescan(IndexScanDesc scan, ScanKey key, int nkeys,
fn_extras[i] = scan->orderByData[i].sk_func.fn_extra;
}
- memmove(scan->orderByData, orderbys,
- scan->numberOfOrderBys * sizeof(ScanKeyData));
+ memcpy(scan->orderByData, orderbys, scan->numberOfOrderBys * sizeof(ScanKeyData));
so->orderByTypes = (Oid *) palloc(scan->numberOfOrderBys * sizeof(Oid));
diff --git a/src/backend/access/gist/gistsplit.c b/src/backend/access/gist/gistsplit.c
index f56b92c31361b..49838ceb07b19 100644
--- a/src/backend/access/gist/gistsplit.c
+++ b/src/backend/access/gist/gistsplit.c
@@ -15,7 +15,7 @@
* gistSplitByKey() is the entry point to this file.
*
*
- * Portions Copyright (c) 1996-2024, PostgreSQL Global Development Group
+ * Portions Copyright (c) 1996-2025, PostgreSQL Global Development Group
* Portions Copyright (c) 1994, Regents of the University of California
*
* IDENTIFICATION
diff --git a/src/backend/access/gist/gistutil.c b/src/backend/access/gist/gistutil.c
index 78e98d68b1518..c0aa7d0222f39 100644
--- a/src/backend/access/gist/gistutil.c
+++ b/src/backend/access/gist/gistutil.c
@@ -4,7 +4,7 @@
* utilities routines for the postgres GiST index access method.
*
*
- * Portions Copyright (c) 1996-2024, PostgreSQL Global Development Group
+ * Portions Copyright (c) 1996-2025, PostgreSQL Global Development Group
* Portions Copyright (c) 1994, Regents of the University of California
*
* IDENTIFICATION
@@ -21,6 +21,7 @@
#include "common/pg_prng.h"
#include "storage/indexfsm.h"
#include "utils/float.h"
+#include "utils/fmgrprotos.h"
#include "utils/lsyscache.h"
#include "utils/rel.h"
#include "utils/snapmgr.h"
@@ -1055,3 +1056,56 @@ gistGetFakeLSN(Relation rel)
return GetFakeLSNForUnloggedRel();
}
}
+
+/*
+ * This is a stratnum translation support function for GiST opclasses that use
+ * the RT*StrategyNumber constants.
+ */
+Datum
+gist_translate_cmptype_common(PG_FUNCTION_ARGS)
+{
+ CompareType cmptype = PG_GETARG_INT32(0);
+
+ switch (cmptype)
+ {
+ case COMPARE_EQ:
+ PG_RETURN_UINT16(RTEqualStrategyNumber);
+ case COMPARE_LT:
+ PG_RETURN_UINT16(RTLessStrategyNumber);
+ case COMPARE_LE:
+ PG_RETURN_UINT16(RTLessEqualStrategyNumber);
+ case COMPARE_GT:
+ PG_RETURN_UINT16(RTGreaterStrategyNumber);
+ case COMPARE_GE:
+ PG_RETURN_UINT16(RTGreaterEqualStrategyNumber);
+ case COMPARE_OVERLAP:
+ PG_RETURN_UINT16(RTOverlapStrategyNumber);
+ case COMPARE_CONTAINED_BY:
+ PG_RETURN_UINT16(RTContainedByStrategyNumber);
+ default:
+ PG_RETURN_UINT16(InvalidStrategy);
+ }
+}
+
+/*
+ * Returns the opclass's private stratnum used for the given compare type.
+ *
+ * Calls the opclass's GIST_TRANSLATE_CMPTYPE_PROC support function, if any,
+ * and returns the result. Returns InvalidStrategy if the function is not
+ * defined.
+ */
+StrategyNumber
+gisttranslatecmptype(CompareType cmptype, Oid opfamily)
+{
+ Oid funcid;
+ Datum result;
+
+ /* Check whether the function is provided. */
+ funcid = get_opfamily_proc(opfamily, ANYOID, ANYOID, GIST_TRANSLATE_CMPTYPE_PROC);
+ if (!OidIsValid(funcid))
+ return InvalidStrategy;
+
+ /* Ask the translation function */
+ result = OidFunctionCall1Coll(funcid, InvalidOid, Int32GetDatum(cmptype));
+ return DatumGetUInt16(result);
+}
diff --git a/src/backend/access/gist/gistvacuum.c b/src/backend/access/gist/gistvacuum.c
index 24fb94f473ecb..b925eda2b9b42 100644
--- a/src/backend/access/gist/gistvacuum.c
+++ b/src/backend/access/gist/gistvacuum.c
@@ -4,7 +4,7 @@
* vacuuming routines for the postgres GiST index access method.
*
*
- * Portions Copyright (c) 1996-2024, PostgreSQL Global Development Group
+ * Portions Copyright (c) 1996-2025, PostgreSQL Global Development Group
* Portions Copyright (c) 1994, Regents of the University of California
*
* IDENTIFICATION
@@ -22,6 +22,7 @@
#include "miscadmin.h"
#include "storage/indexfsm.h"
#include "storage/lmgr.h"
+#include "storage/read_stream.h"
#include "utils/memutils.h"
/* Working state needed by gistbulkdelete */
@@ -44,8 +45,7 @@ typedef struct
static void gistvacuumscan(IndexVacuumInfo *info, IndexBulkDeleteResult *stats,
IndexBulkDeleteCallback callback, void *callback_state);
-static void gistvacuumpage(GistVacState *vstate, BlockNumber blkno,
- BlockNumber orig_blkno);
+static void gistvacuumpage(GistVacState *vstate, Buffer buffer);
static void gistvacuum_delete_empty_pages(IndexVacuumInfo *info,
GistVacState *vstate);
static bool gistdeletepage(IndexVacuumInfo *info, IndexBulkDeleteResult *stats,
@@ -129,8 +129,9 @@ gistvacuumscan(IndexVacuumInfo *info, IndexBulkDeleteResult *stats,
GistVacState vstate;
BlockNumber num_pages;
bool needLock;
- BlockNumber blkno;
MemoryContext oldctx;
+ BlockRangeReadStreamPrivate p;
+ ReadStream *stream = NULL;
/*
* Reset fields that track information about the entire index now. This
@@ -208,7 +209,21 @@ gistvacuumscan(IndexVacuumInfo *info, IndexBulkDeleteResult *stats,
*/
needLock = !RELATION_IS_LOCAL(rel);
- blkno = GIST_ROOT_BLKNO;
+ p.current_blocknum = GIST_ROOT_BLKNO;
+
+ /*
+ * It is safe to use batchmode as block_range_read_stream_cb takes no
+ * locks.
+ */
+ stream = read_stream_begin_relation(READ_STREAM_MAINTENANCE |
+ READ_STREAM_FULL |
+ READ_STREAM_USE_BATCHING,
+ info->strategy,
+ rel,
+ MAIN_FORKNUM,
+ block_range_read_stream_cb,
+ &p,
+ 0);
for (;;)
{
/* Get the current relation length */
@@ -219,13 +234,37 @@ gistvacuumscan(IndexVacuumInfo *info, IndexBulkDeleteResult *stats,
UnlockRelationForExtension(rel, ExclusiveLock);
/* Quit if we've scanned the whole relation */
- if (blkno >= num_pages)
+ if (p.current_blocknum >= num_pages)
break;
- /* Iterate over pages, then loop back to recheck length */
- for (; blkno < num_pages; blkno++)
- gistvacuumpage(&vstate, blkno, blkno);
+
+ p.last_exclusive = num_pages;
+
+ /* Iterate over pages, then loop back to recheck relation length */
+ while (true)
+ {
+ Buffer buf;
+
+ /* call vacuum_delay_point while not holding any buffer lock */
+ vacuum_delay_point(false);
+
+ buf = read_stream_next_buffer(stream, NULL);
+
+ if (!BufferIsValid(buf))
+ break;
+
+ gistvacuumpage(&vstate, buf);
+ }
+
+ /*
+ * We have to reset the read stream to use it again. After returning
+ * InvalidBuffer, the read stream API won't invoke our callback again
+ * until the stream has been reset.
+ */
+ read_stream_reset(stream);
}
+ read_stream_end(stream);
+
/*
* If we found any recyclable pages (and recorded them in the FSM), then
* forcibly update the upper-level FSM pages to ensure that searchers can
@@ -260,40 +299,38 @@ gistvacuumscan(IndexVacuumInfo *info, IndexBulkDeleteResult *stats,
/*
* gistvacuumpage --- VACUUM one page
*
- * This processes a single page for gistbulkdelete(). In some cases we
- * must go back and re-examine previously-scanned pages; this routine
- * recurses when necessary to handle that case.
- *
- * blkno is the page to process. orig_blkno is the highest block number
- * reached by the outer gistvacuumscan loop (the same as blkno, unless we
- * are recursing to re-examine a previous page).
+ * This processes a single page for gistbulkdelete(). `buffer` contains the
+ * page to process. In some cases we must go back and reexamine
+ * previously-scanned pages; this routine recurses when necessary to handle
+ * that case.
*/
static void
-gistvacuumpage(GistVacState *vstate, BlockNumber blkno, BlockNumber orig_blkno)
+gistvacuumpage(GistVacState *vstate, Buffer buffer)
{
IndexVacuumInfo *info = vstate->info;
IndexBulkDeleteCallback callback = vstate->callback;
void *callback_state = vstate->callback_state;
Relation rel = info->index;
- Buffer buffer;
+ BlockNumber orig_blkno = BufferGetBlockNumber(buffer);
Page page;
BlockNumber recurse_to;
+ /*
+ * orig_blkno is the highest block number reached by the outer
+ * gistvacuumscan() loop. This will be the same as blkno unless we are
+ * recursing to reexamine a previous page.
+ */
+ BlockNumber blkno = orig_blkno;
+
restart:
recurse_to = InvalidBlockNumber;
- /* call vacuum_delay_point while not holding any buffer lock */
- vacuum_delay_point();
-
- buffer = ReadBufferExtended(rel, MAIN_FORKNUM, blkno, RBM_NORMAL,
- info->strategy);
-
/*
* We are not going to stay here for a long time, aggressively grab an
* exclusive lock.
*/
LockBuffer(buffer, GIST_EXCLUSIVE);
- page = (Page) BufferGetPage(buffer);
+ page = BufferGetPage(buffer);
if (gistPageRecyclable(page))
{
@@ -450,6 +487,12 @@ gistvacuumpage(GistVacState *vstate, BlockNumber blkno, BlockNumber orig_blkno)
if (recurse_to != InvalidBlockNumber)
{
blkno = recurse_to;
+
+ /* check for vacuum delay while not holding any buffer lock */
+ vacuum_delay_point(false);
+
+ buffer = ReadBufferExtended(rel, MAIN_FORKNUM, blkno, RBM_NORMAL,
+ info->strategy);
goto restart;
}
}
@@ -485,7 +528,7 @@ gistvacuum_delete_empty_pages(IndexVacuumInfo *info, GistVacState *vstate)
RBM_NORMAL, info->strategy);
LockBuffer(buffer, GIST_SHARE);
- page = (Page) BufferGetPage(buffer);
+ page = BufferGetPage(buffer);
if (PageIsNew(page) || GistPageIsDeleted(page) || GistPageIsLeaf(page))
{
diff --git a/src/backend/access/gist/gistvalidate.c b/src/backend/access/gist/gistvalidate.c
index 36b5a85cf31a7..2ed6f74fce97b 100644
--- a/src/backend/access/gist/gistvalidate.c
+++ b/src/backend/access/gist/gistvalidate.c
@@ -3,7 +3,7 @@
* gistvalidate.c
* Opclass validator for GiST.
*
- * Portions Copyright (c) 1996-2024, PostgreSQL Global Development Group
+ * Portions Copyright (c) 1996-2025, PostgreSQL Global Development Group
* Portions Copyright (c) 1994, Regents of the University of California
*
* IDENTIFICATION
@@ -19,7 +19,6 @@
#include "catalog/pg_amop.h"
#include "catalog/pg_amproc.h"
#include "catalog/pg_opclass.h"
-#include "catalog/pg_opfamily.h"
#include "catalog/pg_type.h"
#include "utils/lsyscache.h"
#include "utils/regproc.h"
@@ -39,8 +38,6 @@ gistvalidate(Oid opclassoid)
Oid opcintype;
Oid opckeytype;
char *opclassname;
- HeapTuple familytup;
- Form_pg_opfamily familyform;
char *opfamilyname;
CatCList *proclist,
*oprlist;
@@ -63,12 +60,7 @@ gistvalidate(Oid opclassoid)
opclassname = NameStr(classform->opcname);
/* Fetch opfamily information */
- familytup = SearchSysCache1(OPFAMILYOID, ObjectIdGetDatum(opfamilyoid));
- if (!HeapTupleIsValid(familytup))
- elog(ERROR, "cache lookup failed for operator family %u", opfamilyoid);
- familyform = (Form_pg_opfamily) GETSTRUCT(familytup);
-
- opfamilyname = NameStr(familyform->opfname);
+ opfamilyname = get_opfamily_name(opfamilyoid, false);
/* Fetch all operators and support functions of the opfamily */
oprlist = SearchSysCacheList1(AMOPSTRATEGY, ObjectIdGetDatum(opfamilyoid));
@@ -146,6 +138,12 @@ gistvalidate(Oid opclassoid)
ok = check_amproc_signature(procform->amproc, VOIDOID, true,
1, 1, INTERNALOID);
break;
+ case GIST_TRANSLATE_CMPTYPE_PROC:
+ ok = check_amproc_signature(procform->amproc, INT2OID, true,
+ 1, 1, INT4OID) &&
+ procform->amproclefttype == ANYOID &&
+ procform->amprocrighttype == ANYOID;
+ break;
default:
ereport(INFO,
(errcode(ERRCODE_INVALID_OBJECT_DEFINITION),
@@ -266,7 +264,8 @@ gistvalidate(Oid opclassoid)
continue; /* got it */
if (i == GIST_DISTANCE_PROC || i == GIST_FETCH_PROC ||
i == GIST_COMPRESS_PROC || i == GIST_DECOMPRESS_PROC ||
- i == GIST_OPTIONS_PROC || i == GIST_SORTSUPPORT_PROC)
+ i == GIST_OPTIONS_PROC || i == GIST_SORTSUPPORT_PROC ||
+ i == GIST_TRANSLATE_CMPTYPE_PROC)
continue; /* optional methods */
ereport(INFO,
(errcode(ERRCODE_INVALID_OBJECT_DEFINITION),
@@ -277,7 +276,6 @@ gistvalidate(Oid opclassoid)
ReleaseCatCacheList(proclist);
ReleaseCatCacheList(oprlist);
- ReleaseSysCache(familytup);
ReleaseSysCache(classtup);
return result;
@@ -338,6 +336,7 @@ gistadjustmembers(Oid opfamilyoid,
case GIST_FETCH_PROC:
case GIST_OPTIONS_PROC:
case GIST_SORTSUPPORT_PROC:
+ case GIST_TRANSLATE_CMPTYPE_PROC:
/* Optional, so force it to be a soft family dependency */
op->ref_is_hard = false;
op->ref_is_family = true;
diff --git a/src/backend/access/gist/gistxlog.c b/src/backend/access/gist/gistxlog.c
index 451e8d8d98e63..42fee1f0764fa 100644
--- a/src/backend/access/gist/gistxlog.c
+++ b/src/backend/access/gist/gistxlog.c
@@ -4,7 +4,7 @@
* WAL replay logic for GiST.
*
*
- * Portions Copyright (c) 1996-2024, PostgreSQL Global Development Group
+ * Portions Copyright (c) 1996-2025, PostgreSQL Global Development Group
* Portions Copyright (c) 1994, Regents of the University of California
*
* IDENTIFICATION
@@ -83,7 +83,7 @@ gistRedoPageUpdateRecord(XLogReaderState *record)
data = begin = XLogRecGetBlockData(record, 0, &datalen);
- page = (Page) BufferGetPage(buffer);
+ page = BufferGetPage(buffer);
if (xldata->ntodelete == 1 && xldata->ntoinsert == 1)
{
@@ -201,7 +201,7 @@ gistRedoDeleteRecord(XLogReaderState *record)
if (XLogReadBufferForRedo(record, 0, &buffer) == BLK_NEEDS_REDO)
{
- page = (Page) BufferGetPage(buffer);
+ page = BufferGetPage(buffer);
PageIndexMultiDelete(page, toDelete, xldata->ntodelete);
@@ -280,7 +280,7 @@ gistRedoPageSplitRecord(XLogReaderState *record)
}
buffer = XLogInitBufferForRedo(record, i + 1);
- page = (Page) BufferGetPage(buffer);
+ page = BufferGetPage(buffer);
data = XLogRecGetBlockData(record, i + 1, &datalen);
tuples = decodePageSplitRecord(data, datalen, &num);
@@ -348,7 +348,7 @@ gistRedoPageDelete(XLogReaderState *record)
if (XLogReadBufferForRedo(record, 0, &leafBuffer) == BLK_NEEDS_REDO)
{
- Page page = (Page) BufferGetPage(leafBuffer);
+ Page page = BufferGetPage(leafBuffer);
GistPageSetDeleted(page, xldata->deleteXid);
@@ -358,7 +358,7 @@ gistRedoPageDelete(XLogReaderState *record)
if (XLogReadBufferForRedo(record, 1, &parentBuffer) == BLK_NEEDS_REDO)
{
- Page page = (Page) BufferGetPage(parentBuffer);
+ Page page = BufferGetPage(parentBuffer);
PageIndexTupleDelete(page, xldata->downlinkOffset);
@@ -528,14 +528,14 @@ gistXLogSplit(bool page_is_leaf,
* of buffer or data registrations here, make sure you modify the
* XLogEnsureRecordSpace() calls accordingly!
*/
- XLogRegisterData((char *) &xlrec, sizeof(gistxlogPageSplit));
+ XLogRegisterData(&xlrec, sizeof(gistxlogPageSplit));
i = 1;
for (ptr = dist; ptr; ptr = ptr->next)
{
XLogRegisterBuffer(i, ptr->buffer, REGBUF_WILL_INIT);
- XLogRegisterBufData(i, (char *) &(ptr->block.num), sizeof(int));
- XLogRegisterBufData(i, (char *) ptr->list, ptr->lenlist);
+ XLogRegisterBufData(i, &(ptr->block.num), sizeof(int));
+ XLogRegisterBufData(i, ptr->list, ptr->lenlist);
i++;
}
@@ -559,7 +559,7 @@ gistXLogPageDelete(Buffer buffer, FullTransactionId xid,
xlrec.downlinkOffset = downlinkOffset;
XLogBeginInsert();
- XLogRegisterData((char *) &xlrec, SizeOfGistxlogPageDelete);
+ XLogRegisterData(&xlrec, SizeOfGistxlogPageDelete);
XLogRegisterBuffer(0, buffer, REGBUF_STANDARD);
XLogRegisterBuffer(1, parentBuffer, REGBUF_STANDARD);
@@ -583,7 +583,7 @@ gistXLogAssignLSN(void)
*/
XLogBeginInsert();
XLogSetRecordFlags(XLOG_MARK_UNIMPORTANT);
- XLogRegisterData((char *) &dummy, sizeof(dummy));
+ XLogRegisterData(&dummy, sizeof(dummy));
return XLogInsert(RM_GIST_ID, XLOG_GIST_ASSIGN_LSN);
}
@@ -609,7 +609,7 @@ gistXLogPageReuse(Relation rel, Relation heaprel,
xlrec_reuse.snapshotConflictHorizon = deleteXid;
XLogBeginInsert();
- XLogRegisterData((char *) &xlrec_reuse, SizeOfGistxlogPageReuse);
+ XLogRegisterData(&xlrec_reuse, SizeOfGistxlogPageReuse);
XLogInsert(RM_GIST_ID, XLOG_GIST_PAGE_REUSE);
}
@@ -639,14 +639,14 @@ gistXLogUpdate(Buffer buffer,
xlrec.ntoinsert = ituplen;
XLogBeginInsert();
- XLogRegisterData((char *) &xlrec, sizeof(gistxlogPageUpdate));
+ XLogRegisterData(&xlrec, sizeof(gistxlogPageUpdate));
XLogRegisterBuffer(0, buffer, REGBUF_STANDARD);
- XLogRegisterBufData(0, (char *) todelete, sizeof(OffsetNumber) * ntodelete);
+ XLogRegisterBufData(0, todelete, sizeof(OffsetNumber) * ntodelete);
/* new tuples */
for (i = 0; i < ituplen; i++)
- XLogRegisterBufData(0, (char *) (itup[i]), IndexTupleSize(itup[i]));
+ XLogRegisterBufData(0, itup[i], IndexTupleSize(itup[i]));
/*
* Include a full page image of the child buf. (only necessary if a
@@ -678,14 +678,14 @@ gistXLogDelete(Buffer buffer, OffsetNumber *todelete, int ntodelete,
xlrec.ntodelete = ntodelete;
XLogBeginInsert();
- XLogRegisterData((char *) &xlrec, SizeOfGistxlogDelete);
+ XLogRegisterData(&xlrec, SizeOfGistxlogDelete);
/*
* We need the target-offsets array whether or not we store the whole
* buffer, to allow us to find the snapshotConflictHorizon on a standby
* server.
*/
- XLogRegisterData((char *) todelete, ntodelete * sizeof(OffsetNumber));
+ XLogRegisterData(todelete, ntodelete * sizeof(OffsetNumber));
XLogRegisterBuffer(0, buffer, REGBUF_STANDARD);
diff --git a/src/backend/access/gist/meson.build b/src/backend/access/gist/meson.build
index 1f67512192484..14c37c5eb1b9b 100644
--- a/src/backend/access/gist/meson.build
+++ b/src/backend/access/gist/meson.build
@@ -1,4 +1,4 @@
-# Copyright (c) 2022-2024, PostgreSQL Global Development Group
+# Copyright (c) 2022-2025, PostgreSQL Global Development Group
backend_sources += files(
'gist.c',
diff --git a/src/backend/access/hash/hash.c b/src/backend/access/hash/hash.c
index 01d06b7c3289e..53061c819fbf0 100644
--- a/src/backend/access/hash/hash.c
+++ b/src/backend/access/hash/hash.c
@@ -3,7 +3,7 @@
* hash.c
* Implementation of Margo Seltzer's Hashing package for postgres.
*
- * Portions Copyright (c) 1996-2024, PostgreSQL Global Development Group
+ * Portions Copyright (c) 1996-2025, PostgreSQL Global Development Group
* Portions Copyright (c) 1994, Regents of the University of California
*
*
@@ -21,6 +21,7 @@
#include "access/hash.h"
#include "access/hash_xlog.h"
#include "access/relscan.h"
+#include "access/stratnum.h"
#include "access/tableam.h"
#include "access/xloginsert.h"
#include "commands/progress.h"
@@ -63,6 +64,9 @@ hashhandler(PG_FUNCTION_ARGS)
amroutine->amoptsprocnum = HASHOPTIONS_PROC;
amroutine->amcanorder = false;
amroutine->amcanorderbyop = false;
+ amroutine->amcanhash = true;
+ amroutine->amconsistentequality = true;
+ amroutine->amconsistentordering = false;
amroutine->amcanbackward = true;
amroutine->amcanunique = false;
amroutine->amcanmulticol = false;
@@ -89,6 +93,7 @@ hashhandler(PG_FUNCTION_ARGS)
amroutine->amvacuumcleanup = hashvacuumcleanup;
amroutine->amcanreturn = NULL;
amroutine->amcostestimate = hashcostestimate;
+ amroutine->amgettreeheight = NULL;
amroutine->amoptions = hashoptions;
amroutine->amproperty = NULL;
amroutine->ambuildphasename = NULL;
@@ -104,6 +109,8 @@ hashhandler(PG_FUNCTION_ARGS)
amroutine->amestimateparallelscan = NULL;
amroutine->aminitparallelscan = NULL;
amroutine->amparallelrescan = NULL;
+ amroutine->amtranslatestrategy = hashtranslatestrategy;
+ amroutine->amtranslatecmptype = hashtranslatecmptype;
PG_RETURN_POINTER(amroutine);
}
@@ -119,7 +126,7 @@ hashbuild(Relation heap, Relation index, IndexInfo *indexInfo)
double reltuples;
double allvisfrac;
uint32 num_buckets;
- long sort_threshold;
+ Size sort_threshold;
HashBuildState buildstate;
/*
@@ -154,13 +161,13 @@ hashbuild(Relation heap, Relation index, IndexInfo *indexInfo)
* one page. Also, "initial index size" accounting does not include the
* metapage, nor the first bitmap page.
*/
- sort_threshold = (maintenance_work_mem * 1024L) / BLCKSZ;
+ sort_threshold = (maintenance_work_mem * (Size) 1024) / BLCKSZ;
if (index->rd_rel->relpersistence != RELPERSISTENCE_TEMP)
sort_threshold = Min(sort_threshold, NBuffers);
else
sort_threshold = Min(sort_threshold, NLocBuffer);
- if (num_buckets >= (uint32) sort_threshold)
+ if (num_buckets >= sort_threshold)
buildstate.spool = _h_spoolinit(heap, index, num_buckets);
else
buildstate.spool = NULL;
@@ -172,7 +179,7 @@ hashbuild(Relation heap, Relation index, IndexInfo *indexInfo)
/* do the heap scan */
reltuples = table_index_build_scan(heap, index, indexInfo, true, true,
hashbuildCallback,
- (void *) &buildstate, NULL);
+ &buildstate, NULL);
pgstat_progress_update_param(PROGRESS_CREATEIDX_TUPLES_TOTAL,
buildstate.indtuples);
@@ -414,11 +421,7 @@ hashrescan(IndexScanDesc scan, ScanKey scankey, int nscankeys,
/* Update scan key, if a new one is given */
if (scankey && scan->numberOfKeys > 0)
- {
- memmove(scan->keyData,
- scankey,
- scan->numberOfKeys * sizeof(ScanKeyData));
- }
+ memcpy(scan->keyData, scankey, scan->numberOfKeys * sizeof(ScanKeyData));
so->hashso_buc_populated = false;
so->hashso_buc_split = false;
@@ -616,7 +619,7 @@ hashbulkdelete(IndexVacuumInfo *info, IndexBulkDeleteResult *stats,
xlrec.ntuples = metap->hashm_ntuples;
XLogBeginInsert();
- XLogRegisterData((char *) &xlrec, SizeOfHashUpdateMetaPage);
+ XLogRegisterData(&xlrec, SizeOfHashUpdateMetaPage);
XLogRegisterBuffer(0, metabuf, REGBUF_STANDARD);
@@ -716,7 +719,7 @@ hashbucketcleanup(Relation rel, Bucket cur_bucket, Buffer bucket_buf,
bool retain_pin = false;
bool clear_dead_marking = false;
- vacuum_delay_point();
+ vacuum_delay_point(false);
page = BufferGetPage(buf);
opaque = HashPageGetOpaque(page);
@@ -823,7 +826,7 @@ hashbucketcleanup(Relation rel, Bucket cur_bucket, Buffer bucket_buf,
xlrec.is_primary_bucket_page = (buf == bucket_buf);
XLogBeginInsert();
- XLogRegisterData((char *) &xlrec, SizeOfHashDelete);
+ XLogRegisterData(&xlrec, SizeOfHashDelete);
/*
* bucket buffer was not changed, but still needs to be
@@ -838,7 +841,7 @@ hashbucketcleanup(Relation rel, Bucket cur_bucket, Buffer bucket_buf,
}
XLogRegisterBuffer(1, buf, REGBUF_STANDARD);
- XLogRegisterBufData(1, (char *) deletable,
+ XLogRegisterBufData(1, deletable,
ndeletable * sizeof(OffsetNumber));
recptr = XLogInsert(RM_HASH_ID, XLOG_HASH_DELETE);
@@ -925,3 +928,19 @@ hashbucketcleanup(Relation rel, Bucket cur_bucket, Buffer bucket_buf,
else
LockBuffer(bucket_buf, BUFFER_LOCK_UNLOCK);
}
+
+CompareType
+hashtranslatestrategy(StrategyNumber strategy, Oid opfamily)
+{
+ if (strategy == HTEqualStrategyNumber)
+ return COMPARE_EQ;
+ return COMPARE_INVALID;
+}
+
+StrategyNumber
+hashtranslatecmptype(CompareType cmptype, Oid opfamily)
+{
+ if (cmptype == COMPARE_EQ)
+ return HTEqualStrategyNumber;
+ return InvalidStrategy;
+}
diff --git a/src/backend/access/hash/hash_xlog.c b/src/backend/access/hash/hash_xlog.c
index 4e1ec468569e1..d963a0c370292 100644
--- a/src/backend/access/hash/hash_xlog.c
+++ b/src/backend/access/hash/hash_xlog.c
@@ -4,7 +4,7 @@
* WAL replay logic for hash index.
*
*
- * Portions Copyright (c) 1996-2024, PostgreSQL Global Development Group
+ * Portions Copyright (c) 1996-2025, PostgreSQL Global Development Group
* Portions Copyright (c) 1994, Regents of the University of California
*
* IDENTIFICATION
@@ -38,7 +38,7 @@ hash_xlog_init_meta_page(XLogReaderState *record)
Assert(BufferIsValid(metabuf));
_hash_init_metabuffer(metabuf, xlrec->num_tuples, xlrec->procid,
xlrec->ffactor, true);
- page = (Page) BufferGetPage(metabuf);
+ page = BufferGetPage(metabuf);
PageSetLSN(page, lsn);
MarkBufferDirty(metabuf);
@@ -235,7 +235,7 @@ hash_xlog_add_ovfl_page(XLogReaderState *record)
if (XLogReadBufferForRedo(record, 2, &mapbuffer) == BLK_NEEDS_REDO)
{
- Page mappage = (Page) BufferGetPage(mapbuffer);
+ Page mappage = BufferGetPage(mapbuffer);
uint32 *freep = NULL;
uint32 *bitmap_page_bit;
@@ -538,7 +538,7 @@ hash_xlog_move_page_contents(XLogReaderState *record)
data = begin = XLogRecGetBlockData(record, 1, &datalen);
- writepage = (Page) BufferGetPage(writebuf);
+ writepage = BufferGetPage(writebuf);
if (xldata->ntups > 0)
{
@@ -584,7 +584,7 @@ hash_xlog_move_page_contents(XLogReaderState *record)
ptr = XLogRecGetBlockData(record, 2, &len);
- page = (Page) BufferGetPage(deletebuf);
+ page = BufferGetPage(deletebuf);
if (len > 0)
{
@@ -670,7 +670,7 @@ hash_xlog_squeeze_page(XLogReaderState *record)
data = begin = XLogRecGetBlockData(record, 1, &datalen);
- writepage = (Page) BufferGetPage(writebuf);
+ writepage = BufferGetPage(writebuf);
if (xldata->ntups > 0)
{
@@ -807,7 +807,7 @@ hash_xlog_squeeze_page(XLogReaderState *record)
/* replay the record for bitmap page */
if (XLogReadBufferForRedo(record, 5, &mapbuf) == BLK_NEEDS_REDO)
{
- Page mappage = (Page) BufferGetPage(mapbuf);
+ Page mappage = BufferGetPage(mapbuf);
uint32 *freep = NULL;
char *data;
uint32 *bitmap_page_bit;
@@ -895,7 +895,7 @@ hash_xlog_delete(XLogReaderState *record)
ptr = XLogRecGetBlockData(record, 1, &len);
- page = (Page) BufferGetPage(deletebuf);
+ page = BufferGetPage(deletebuf);
if (len > 0)
{
@@ -946,7 +946,7 @@ hash_xlog_split_cleanup(XLogReaderState *record)
{
HashPageOpaque bucket_opaque;
- page = (Page) BufferGetPage(buffer);
+ page = BufferGetPage(buffer);
bucket_opaque = HashPageGetOpaque(page);
bucket_opaque->hasho_flag &= ~LH_BUCKET_NEEDS_SPLIT_CLEANUP;
@@ -1029,7 +1029,7 @@ hash_xlog_vacuum_one_page(XLogReaderState *record)
if (action == BLK_NEEDS_REDO)
{
- page = (Page) BufferGetPage(buffer);
+ page = BufferGetPage(buffer);
PageIndexMultiDelete(page, toDelete, xldata->ntuples);
diff --git a/src/backend/access/hash/hashfunc.c b/src/backend/access/hash/hashfunc.c
index ce8ee0ea2efdb..ec96348942ee7 100644
--- a/src/backend/access/hash/hashfunc.c
+++ b/src/backend/access/hash/hashfunc.c
@@ -3,7 +3,7 @@
* hashfunc.c
* Support functions for hash access method.
*
- * Portions Copyright (c) 1996-2024, PostgreSQL Global Development Group
+ * Portions Copyright (c) 1996-2025, PostgreSQL Global Development Group
* Portions Copyright (c) 1994, Regents of the University of California
*
*
@@ -268,7 +268,7 @@ hashtext(PG_FUNCTION_ARGS)
{
text *key = PG_GETARG_TEXT_PP(0);
Oid collid = PG_GET_COLLATION();
- pg_locale_t mylocale = 0;
+ pg_locale_t mylocale;
Datum result;
if (!collid)
@@ -277,10 +277,9 @@ hashtext(PG_FUNCTION_ARGS)
errmsg("could not determine which collation to use for string hashing"),
errhint("Use the COLLATE clause to set the collation explicitly.")));
- if (!lc_collate_is_c(collid))
- mylocale = pg_newlocale_from_collation(collid);
+ mylocale = pg_newlocale_from_collation(collid);
- if (pg_locale_deterministic(mylocale))
+ if (mylocale->deterministic)
{
result = hash_any((unsigned char *) VARDATA_ANY(key),
VARSIZE_ANY_EXHDR(key));
@@ -298,7 +297,9 @@ hashtext(PG_FUNCTION_ARGS)
buf = palloc(bsize + 1);
rsize = pg_strnxfrm(buf, bsize + 1, keydata, keylen, mylocale);
- if (rsize != bsize)
+
+ /* the second call may return a smaller value than the first */
+ if (rsize > bsize)
elog(ERROR, "pg_strnxfrm() returned unexpected result");
/*
@@ -322,7 +323,7 @@ hashtextextended(PG_FUNCTION_ARGS)
{
text *key = PG_GETARG_TEXT_PP(0);
Oid collid = PG_GET_COLLATION();
- pg_locale_t mylocale = 0;
+ pg_locale_t mylocale;
Datum result;
if (!collid)
@@ -331,10 +332,9 @@ hashtextextended(PG_FUNCTION_ARGS)
errmsg("could not determine which collation to use for string hashing"),
errhint("Use the COLLATE clause to set the collation explicitly.")));
- if (!lc_collate_is_c(collid))
- mylocale = pg_newlocale_from_collation(collid);
+ mylocale = pg_newlocale_from_collation(collid);
- if (pg_locale_deterministic(mylocale))
+ if (mylocale->deterministic)
{
result = hash_any_extended((unsigned char *) VARDATA_ANY(key),
VARSIZE_ANY_EXHDR(key),
@@ -352,7 +352,9 @@ hashtextextended(PG_FUNCTION_ARGS)
buf = palloc(bsize + 1);
rsize = pg_strnxfrm(buf, bsize + 1, keydata, keylen, mylocale);
- if (rsize != bsize)
+
+ /* the second call may return a smaller value than the first */
+ if (rsize > bsize)
elog(ERROR, "pg_strnxfrm() returned unexpected result");
/*
@@ -374,6 +376,11 @@ hashtextextended(PG_FUNCTION_ARGS)
/*
* hashvarlena() can be used for any varlena datatype in which there are
* no non-significant bits, ie, distinct bitpatterns never compare as equal.
+ *
+ * (However, you need to define an SQL-level wrapper function around it with
+ * the concrete input data type; otherwise hashvalidate() won't accept it.
+ * Moreover, at least for built-in types, a C-level wrapper function is also
+ * recommended; otherwise, the opr_sanity test will get upset.)
*/
Datum
hashvarlena(PG_FUNCTION_ARGS)
@@ -404,3 +411,15 @@ hashvarlenaextended(PG_FUNCTION_ARGS)
return result;
}
+
+Datum
+hashbytea(PG_FUNCTION_ARGS)
+{
+ return hashvarlena(fcinfo);
+}
+
+Datum
+hashbyteaextended(PG_FUNCTION_ARGS)
+{
+ return hashvarlenaextended(fcinfo);
+}
diff --git a/src/backend/access/hash/hashinsert.c b/src/backend/access/hash/hashinsert.c
index 9ac162041183e..10de1580dc211 100644
--- a/src/backend/access/hash/hashinsert.c
+++ b/src/backend/access/hash/hashinsert.c
@@ -3,7 +3,7 @@
* hashinsert.c
* Item insertion in hash tables for Postgres.
*
- * Portions Copyright (c) 1996-2024, PostgreSQL Global Development Group
+ * Portions Copyright (c) 1996-2025, PostgreSQL Global Development Group
* Portions Copyright (c) 1994, Regents of the University of California
*
*
@@ -221,12 +221,12 @@ _hash_doinsert(Relation rel, IndexTuple itup, Relation heapRel, bool sorted)
xlrec.offnum = itup_off;
XLogBeginInsert();
- XLogRegisterData((char *) &xlrec, SizeOfHashInsert);
+ XLogRegisterData(&xlrec, SizeOfHashInsert);
XLogRegisterBuffer(1, metabuf, REGBUF_STANDARD);
XLogRegisterBuffer(0, buf, REGBUF_STANDARD);
- XLogRegisterBufData(0, (char *) itup, IndexTupleSize(itup));
+ XLogRegisterBufData(0, itup, IndexTupleSize(itup));
recptr = XLogInsert(RM_HASH_ID, XLOG_HASH_INSERT);
@@ -436,14 +436,14 @@ _hash_vacuum_one_page(Relation rel, Relation hrel, Buffer metabuf, Buffer buf)
XLogBeginInsert();
XLogRegisterBuffer(0, buf, REGBUF_STANDARD);
- XLogRegisterData((char *) &xlrec, SizeOfHashVacuumOnePage);
+ XLogRegisterData(&xlrec, SizeOfHashVacuumOnePage);
/*
* We need the target-offsets array whether or not we store the
* whole buffer, to allow us to find the snapshotConflictHorizon
* on a standby server.
*/
- XLogRegisterData((char *) deletable,
+ XLogRegisterData(deletable,
ndeletable * sizeof(OffsetNumber));
XLogRegisterBuffer(1, metabuf, REGBUF_STANDARD);
diff --git a/src/backend/access/hash/hashovfl.c b/src/backend/access/hash/hashovfl.c
index c280ae885e37a..4f5fd3b28372a 100644
--- a/src/backend/access/hash/hashovfl.c
+++ b/src/backend/access/hash/hashovfl.c
@@ -3,7 +3,7 @@
* hashovfl.c
* Overflow page management code for the Postgres hash access method
*
- * Portions Copyright (c) 1996-2024, PostgreSQL Global Development Group
+ * Portions Copyright (c) 1996-2025, PostgreSQL Global Development Group
* Portions Copyright (c) 1994, Regents of the University of California
*
*
@@ -388,24 +388,24 @@ _hash_addovflpage(Relation rel, Buffer metabuf, Buffer buf, bool retain_pin)
xlrec.bmsize = metap->hashm_bmsize;
XLogBeginInsert();
- XLogRegisterData((char *) &xlrec, SizeOfHashAddOvflPage);
+ XLogRegisterData(&xlrec, SizeOfHashAddOvflPage);
XLogRegisterBuffer(0, ovflbuf, REGBUF_WILL_INIT);
- XLogRegisterBufData(0, (char *) &pageopaque->hasho_bucket, sizeof(Bucket));
+ XLogRegisterBufData(0, &pageopaque->hasho_bucket, sizeof(Bucket));
XLogRegisterBuffer(1, buf, REGBUF_STANDARD);
if (BufferIsValid(mapbuf))
{
XLogRegisterBuffer(2, mapbuf, REGBUF_STANDARD);
- XLogRegisterBufData(2, (char *) &bitmap_page_bit, sizeof(uint32));
+ XLogRegisterBufData(2, &bitmap_page_bit, sizeof(uint32));
}
if (BufferIsValid(newmapbuf))
XLogRegisterBuffer(3, newmapbuf, REGBUF_WILL_INIT);
XLogRegisterBuffer(4, metabuf, REGBUF_STANDARD);
- XLogRegisterBufData(4, (char *) &metap->hashm_firstfree, sizeof(uint32));
+ XLogRegisterBufData(4, &metap->hashm_firstfree, sizeof(uint32));
recptr = XLogInsert(RM_HASH_ID, XLOG_HASH_ADD_OVFL_PAGE);
@@ -656,7 +656,7 @@ _hash_freeovflpage(Relation rel, Buffer bucketbuf, Buffer ovflbuf,
xlrec.is_prev_bucket_same_wrt = (wbuf == prevbuf);
XLogBeginInsert();
- XLogRegisterData((char *) &xlrec, SizeOfHashSqueezePage);
+ XLogRegisterData(&xlrec, SizeOfHashSqueezePage);
/*
* bucket buffer was not changed, but still needs to be registered to
@@ -676,10 +676,10 @@ _hash_freeovflpage(Relation rel, Buffer bucketbuf, Buffer ovflbuf,
/* Remember that wbuf is modified. */
mod_wbuf = true;
- XLogRegisterBufData(1, (char *) itup_offsets,
+ XLogRegisterBufData(1, itup_offsets,
nitups * sizeof(OffsetNumber));
for (i = 0; i < nitups; i++)
- XLogRegisterBufData(1, (char *) itups[i], tups_size[i]);
+ XLogRegisterBufData(1, itups[i], tups_size[i]);
}
else if (xlrec.is_prim_bucket_same_wrt || xlrec.is_prev_bucket_same_wrt)
{
@@ -721,12 +721,12 @@ _hash_freeovflpage(Relation rel, Buffer bucketbuf, Buffer ovflbuf,
XLogRegisterBuffer(4, nextbuf, REGBUF_STANDARD);
XLogRegisterBuffer(5, mapbuf, REGBUF_STANDARD);
- XLogRegisterBufData(5, (char *) &bitmapbit, sizeof(uint32));
+ XLogRegisterBufData(5, &bitmapbit, sizeof(uint32));
if (update_metap)
{
XLogRegisterBuffer(6, metabuf, REGBUF_STANDARD);
- XLogRegisterBufData(6, (char *) &metap->hashm_firstfree, sizeof(uint32));
+ XLogRegisterBufData(6, &metap->hashm_firstfree, sizeof(uint32));
}
recptr = XLogInsert(RM_HASH_ID, XLOG_HASH_SQUEEZE_PAGE);
@@ -993,7 +993,7 @@ _hash_squeezebucket(Relation rel,
xlrec.is_prim_bucket_same_wrt = (wbuf == bucket_buf);
XLogBeginInsert();
- XLogRegisterData((char *) &xlrec, SizeOfHashMovePageContents);
+ XLogRegisterData(&xlrec, SizeOfHashMovePageContents);
/*
* bucket buffer was not changed, but still needs to
@@ -1008,13 +1008,13 @@ _hash_squeezebucket(Relation rel,
}
XLogRegisterBuffer(1, wbuf, REGBUF_STANDARD);
- XLogRegisterBufData(1, (char *) itup_offsets,
+ XLogRegisterBufData(1, itup_offsets,
nitups * sizeof(OffsetNumber));
for (i = 0; i < nitups; i++)
- XLogRegisterBufData(1, (char *) itups[i], tups_size[i]);
+ XLogRegisterBufData(1, itups[i], tups_size[i]);
XLogRegisterBuffer(2, rbuf, REGBUF_STANDARD);
- XLogRegisterBufData(2, (char *) deletable,
+ XLogRegisterBufData(2, deletable,
ndeletable * sizeof(OffsetNumber));
recptr = XLogInsert(RM_HASH_ID, XLOG_HASH_MOVE_PAGE_CONTENTS);
diff --git a/src/backend/access/hash/hashpage.c b/src/backend/access/hash/hashpage.c
index d09c349e28f99..b8e5bd005e59a 100644
--- a/src/backend/access/hash/hashpage.c
+++ b/src/backend/access/hash/hashpage.c
@@ -3,7 +3,7 @@
* hashpage.c
* Hash table page management code for the Postgres hash access method
*
- * Portions Copyright (c) 1996-2024, PostgreSQL Global Development Group
+ * Portions Copyright (c) 1996-2025, PostgreSQL Global Development Group
* Portions Copyright (c) 1994, Regents of the University of California
*
*
@@ -394,7 +394,7 @@ _hash_init(Relation rel, double num_tuples, ForkNumber forkNum)
xlrec.ffactor = metap->hashm_ffactor;
XLogBeginInsert();
- XLogRegisterData((char *) &xlrec, SizeOfHashInitMetaPage);
+ XLogRegisterData(&xlrec, SizeOfHashInitMetaPage);
XLogRegisterBuffer(0, metabuf, REGBUF_WILL_INIT | REGBUF_STANDARD);
recptr = XLogInsert(RM_HASH_ID, XLOG_HASH_INIT_META_PAGE);
@@ -468,7 +468,7 @@ _hash_init(Relation rel, double num_tuples, ForkNumber forkNum)
xlrec.bmsize = metap->hashm_bmsize;
XLogBeginInsert();
- XLogRegisterData((char *) &xlrec, SizeOfHashInitBitmapPage);
+ XLogRegisterData(&xlrec, SizeOfHashInitBitmapPage);
XLogRegisterBuffer(0, bitmapbuf, REGBUF_WILL_INIT);
/*
@@ -916,21 +916,21 @@ _hash_expandtable(Relation rel, Buffer metabuf)
if (metap_update_masks)
{
xlrec.flags |= XLH_SPLIT_META_UPDATE_MASKS;
- XLogRegisterBufData(2, (char *) &metap->hashm_lowmask, sizeof(uint32));
- XLogRegisterBufData(2, (char *) &metap->hashm_highmask, sizeof(uint32));
+ XLogRegisterBufData(2, &metap->hashm_lowmask, sizeof(uint32));
+ XLogRegisterBufData(2, &metap->hashm_highmask, sizeof(uint32));
}
if (metap_update_splitpoint)
{
xlrec.flags |= XLH_SPLIT_META_UPDATE_SPLITPOINT;
- XLogRegisterBufData(2, (char *) &metap->hashm_ovflpoint,
+ XLogRegisterBufData(2, &metap->hashm_ovflpoint,
sizeof(uint32));
XLogRegisterBufData(2,
- (char *) &metap->hashm_spares[metap->hashm_ovflpoint],
+ &metap->hashm_spares[metap->hashm_ovflpoint],
sizeof(uint32));
}
- XLogRegisterData((char *) &xlrec, SizeOfHashSplitAllocPage);
+ XLogRegisterData(&xlrec, SizeOfHashSplitAllocPage);
recptr = XLogInsert(RM_HASH_ID, XLOG_HASH_SPLIT_ALLOCATE_PAGE);
@@ -1304,7 +1304,7 @@ _hash_splitbucket(Relation rel,
XLogBeginInsert();
- XLogRegisterData((char *) &xlrec, SizeOfHashSplitComplete);
+ XLogRegisterData(&xlrec, SizeOfHashSplitComplete);
XLogRegisterBuffer(0, bucket_obuf, REGBUF_STANDARD);
XLogRegisterBuffer(1, bucket_nbuf, REGBUF_STANDARD);
diff --git a/src/backend/access/hash/hashsearch.c b/src/backend/access/hash/hashsearch.c
index 0d99d6abc8669..92c15a65be29a 100644
--- a/src/backend/access/hash/hashsearch.c
+++ b/src/backend/access/hash/hashsearch.c
@@ -3,7 +3,7 @@
* hashsearch.c
* search code for postgres hash tables
*
- * Portions Copyright (c) 1996-2024, PostgreSQL Global Development Group
+ * Portions Copyright (c) 1996-2025, PostgreSQL Global Development Group
* Portions Copyright (c) 1994, Regents of the University of California
*
*
@@ -298,6 +298,8 @@ _hash_first(IndexScanDesc scan, ScanDirection dir)
HashScanPosItem *currItem;
pgstat_count_index_scan(rel);
+ if (scan->instrument)
+ scan->instrument->nsearches++;
/*
* We do not support hash scans with no index qualification, because we
diff --git a/src/backend/access/hash/hashsort.c b/src/backend/access/hash/hashsort.c
index 149cd9fc05628..6e8c0e68a92c8 100644
--- a/src/backend/access/hash/hashsort.c
+++ b/src/backend/access/hash/hashsort.c
@@ -14,7 +14,7 @@
* plenty of locality of access.
*
*
- * Portions Copyright (c) 1996-2024, PostgreSQL Global Development Group
+ * Portions Copyright (c) 1996-2025, PostgreSQL Global Development Group
* Portions Copyright (c) 1994, Regents of the University of California
*
* IDENTIFICATION
@@ -148,6 +148,9 @@ _h_indexbuild(HSpool *hspool, Relation heapRel)
/* the tuples are sorted by hashkey, so pass 'sorted' as true */
_hash_doinsert(hspool->index, itup, heapRel, true);
+ /* allow insertion phase to be interrupted, and track progress */
+ CHECK_FOR_INTERRUPTS();
+
pgstat_progress_update_param(PROGRESS_CREATEIDX_TUPLES_DONE,
++tups_done);
}
diff --git a/src/backend/access/hash/hashutil.c b/src/backend/access/hash/hashutil.c
index 20028f5cd14e1..66c39f606540b 100644
--- a/src/backend/access/hash/hashutil.c
+++ b/src/backend/access/hash/hashutil.c
@@ -3,7 +3,7 @@
* hashutil.c
* Utility code for Postgres hash implementation.
*
- * Portions Copyright (c) 1996-2024, PostgreSQL Global Development Group
+ * Portions Copyright (c) 1996-2025, PostgreSQL Global Development Group
* Portions Copyright (c) 1994, Regents of the University of California
*
*
diff --git a/src/backend/access/hash/hashvalidate.c b/src/backend/access/hash/hashvalidate.c
index 40164e2ea2bb8..06ac832ba10f8 100644
--- a/src/backend/access/hash/hashvalidate.c
+++ b/src/backend/access/hash/hashvalidate.c
@@ -3,7 +3,7 @@
* hashvalidate.c
* Opclass validator for hash.
*
- * Portions Copyright (c) 1996-2024, PostgreSQL Global Development Group
+ * Portions Copyright (c) 1996-2025, PostgreSQL Global Development Group
* Portions Copyright (c) 1994, Regents of the University of California
*
* IDENTIFICATION
@@ -21,20 +21,13 @@
#include "catalog/pg_amop.h"
#include "catalog/pg_amproc.h"
#include "catalog/pg_opclass.h"
-#include "catalog/pg_opfamily.h"
-#include "catalog/pg_proc.h"
#include "catalog/pg_type.h"
-#include "parser/parse_coerce.h"
#include "utils/builtins.h"
-#include "utils/fmgroids.h"
#include "utils/lsyscache.h"
#include "utils/regproc.h"
#include "utils/syscache.h"
-static bool check_hash_func_signature(Oid funcid, int16 amprocnum, Oid argtype);
-
-
/*
* Validator for a hash opclass.
*
@@ -52,8 +45,6 @@ hashvalidate(Oid opclassoid)
Oid opfamilyoid;
Oid opcintype;
char *opclassname;
- HeapTuple familytup;
- Form_pg_opfamily familyform;
char *opfamilyname;
CatCList *proclist,
*oprlist;
@@ -74,12 +65,7 @@ hashvalidate(Oid opclassoid)
opclassname = NameStr(classform->opcname);
/* Fetch opfamily information */
- familytup = SearchSysCache1(OPFAMILYOID, ObjectIdGetDatum(opfamilyoid));
- if (!HeapTupleIsValid(familytup))
- elog(ERROR, "cache lookup failed for operator family %u", opfamilyoid);
- familyform = (Form_pg_opfamily) GETSTRUCT(familytup);
-
- opfamilyname = NameStr(familyform->opfname);
+ opfamilyname = get_opfamily_name(opfamilyoid, false);
/* Fetch all operators and support functions of the opfamily */
oprlist = SearchSysCacheList1(AMOPSTRATEGY, ObjectIdGetDatum(opfamilyoid));
@@ -90,6 +76,7 @@ hashvalidate(Oid opclassoid)
{
HeapTuple proctup = &proclist->members[i]->tuple;
Form_pg_amproc procform = (Form_pg_amproc) GETSTRUCT(proctup);
+ bool ok;
/*
* All hash functions should be registered with matching left/right
@@ -109,29 +96,15 @@ hashvalidate(Oid opclassoid)
switch (procform->amprocnum)
{
case HASHSTANDARD_PROC:
+ ok = check_amproc_signature(procform->amproc, INT4OID, true,
+ 1, 1, procform->amproclefttype);
+ break;
case HASHEXTENDED_PROC:
- if (!check_hash_func_signature(procform->amproc, procform->amprocnum,
- procform->amproclefttype))
- {
- ereport(INFO,
- (errcode(ERRCODE_INVALID_OBJECT_DEFINITION),
- errmsg("operator family \"%s\" of access method %s contains function %s with wrong signature for support number %d",
- opfamilyname, "hash",
- format_procedure(procform->amproc),
- procform->amprocnum)));
- result = false;
- }
- else
- {
- /* Remember which types we can hash */
- hashabletypes =
- list_append_unique_oid(hashabletypes,
- procform->amproclefttype);
- }
+ ok = check_amproc_signature(procform->amproc, INT8OID, true,
+ 2, 2, procform->amproclefttype, INT8OID);
break;
case HASHOPTIONS_PROC:
- if (!check_amoptsproc_signature(procform->amproc))
- result = false;
+ ok = check_amoptsproc_signature(procform->amproc);
break;
default:
ereport(INFO,
@@ -141,7 +114,24 @@ hashvalidate(Oid opclassoid)
format_procedure(procform->amproc),
procform->amprocnum)));
result = false;
- break;
+ continue; /* don't want additional message */
+ }
+
+ if (!ok)
+ {
+ ereport(INFO,
+ (errcode(ERRCODE_INVALID_OBJECT_DEFINITION),
+ errmsg("operator family \"%s\" of access method %s contains function %s with wrong signature for support number %d",
+ opfamilyname, "hash",
+ format_procedure(procform->amproc),
+ procform->amprocnum)));
+ result = false;
+ }
+
+ /* Remember which types we can hash */
+ if (ok && (procform->amprocnum == HASHSTANDARD_PROC || procform->amprocnum == HASHEXTENDED_PROC))
+ {
+ hashabletypes = list_append_unique_oid(hashabletypes, procform->amproclefttype);
}
}
@@ -260,91 +250,12 @@ hashvalidate(Oid opclassoid)
ReleaseCatCacheList(proclist);
ReleaseCatCacheList(oprlist);
- ReleaseSysCache(familytup);
ReleaseSysCache(classtup);
return result;
}
-/*
- * We need a custom version of check_amproc_signature because of assorted
- * hacks in the core hash opclass definitions.
- */
-static bool
-check_hash_func_signature(Oid funcid, int16 amprocnum, Oid argtype)
-{
- bool result = true;
- Oid restype;
- int16 nargs;
- HeapTuple tp;
- Form_pg_proc procform;
-
- switch (amprocnum)
- {
- case HASHSTANDARD_PROC:
- restype = INT4OID;
- nargs = 1;
- break;
-
- case HASHEXTENDED_PROC:
- restype = INT8OID;
- nargs = 2;
- break;
-
- default:
- elog(ERROR, "invalid amprocnum");
- }
-
- tp = SearchSysCache1(PROCOID, ObjectIdGetDatum(funcid));
- if (!HeapTupleIsValid(tp))
- elog(ERROR, "cache lookup failed for function %u", funcid);
- procform = (Form_pg_proc) GETSTRUCT(tp);
-
- if (procform->prorettype != restype || procform->proretset ||
- procform->pronargs != nargs)
- result = false;
-
- if (!IsBinaryCoercible(argtype, procform->proargtypes.values[0]))
- {
- /*
- * Some of the built-in hash opclasses cheat by using hash functions
- * that are different from but physically compatible with the opclass
- * datatype. In some of these cases, even a "binary coercible" check
- * fails because there's no relevant cast. For the moment, fix it by
- * having a list of allowed cases. Test the specific function
- * identity, not just its input type, because hashvarlena() takes
- * INTERNAL and allowing any such function seems too scary.
- */
- if ((funcid == F_HASHINT4 || funcid == F_HASHINT4EXTENDED) &&
- (argtype == DATEOID ||
- argtype == XIDOID || argtype == CIDOID))
- /* okay, allowed use of hashint4() */ ;
- else if ((funcid == F_HASHINT8 || funcid == F_HASHINT8EXTENDED) &&
- (argtype == XID8OID))
- /* okay, allowed use of hashint8() */ ;
- else if ((funcid == F_TIMESTAMP_HASH ||
- funcid == F_TIMESTAMP_HASH_EXTENDED) &&
- argtype == TIMESTAMPTZOID)
- /* okay, allowed use of timestamp_hash() */ ;
- else if ((funcid == F_HASHCHAR || funcid == F_HASHCHAREXTENDED) &&
- argtype == BOOLOID)
- /* okay, allowed use of hashchar() */ ;
- else if ((funcid == F_HASHVARLENA || funcid == F_HASHVARLENAEXTENDED) &&
- argtype == BYTEAOID)
- /* okay, allowed use of hashvarlena() */ ;
- else
- result = false;
- }
-
- /* If function takes a second argument, it must be for a 64-bit salt. */
- if (nargs == 2 && procform->proargtypes.values[1] != INT8OID)
- result = false;
-
- ReleaseSysCache(tp);
- return result;
-}
-
/*
* Prechecking function for adding operators/functions to a hash opfamily.
*/
diff --git a/src/backend/access/hash/meson.build b/src/backend/access/hash/meson.build
index 390e2795e784a..5f933faa6c9fe 100644
--- a/src/backend/access/hash/meson.build
+++ b/src/backend/access/hash/meson.build
@@ -1,4 +1,4 @@
-# Copyright (c) 2022-2024, PostgreSQL Global Development Group
+# Copyright (c) 2022-2025, PostgreSQL Global Development Group
backend_sources += files(
'hash.c',
diff --git a/src/backend/access/heap/Makefile b/src/backend/access/heap/Makefile
index af0bd1888e53f..394534172fa1a 100644
--- a/src/backend/access/heap/Makefile
+++ b/src/backend/access/heap/Makefile
@@ -16,6 +16,7 @@ OBJS = \
heapam.o \
heapam_handler.o \
heapam_visibility.o \
+ heapam_xlog.o \
heaptoast.o \
hio.o \
pruneheap.o \
diff --git a/src/backend/access/heap/README.tuplock b/src/backend/access/heap/README.tuplock
index 6441e8baf0e4a..843c2e58f929d 100644
--- a/src/backend/access/heap/README.tuplock
+++ b/src/backend/access/heap/README.tuplock
@@ -70,13 +70,8 @@ KEY SHARE conflict
When there is a single locker in a tuple, we can just store the locking info
in the tuple itself. We do this by storing the locker's Xid in XMAX, and
-setting infomask bits specifying the locking strength. There is one exception
-here: since infomask space is limited, we do not provide a separate bit
-for SELECT FOR SHARE, so we have to use the extended info in a MultiXact in
-that case. (The other cases, SELECT FOR UPDATE and SELECT FOR KEY SHARE, are
-presumably more commonly used due to being the standards-mandated locking
-mechanism, or heavily used by the RI code, so we want to provide fast paths
-for those.)
+setting infomask bits specifying the locking strength. See "Infomask Bits"
+below for details on the bit patterns we use.
MultiXacts
----------
@@ -153,3 +148,54 @@ The following infomask bits are applicable:
We currently never set the HEAP_XMAX_COMMITTED when the HEAP_XMAX_IS_MULTI bit
is set.
+
+Locking to write inplace-updated tables
+---------------------------------------
+
+If IsInplaceUpdateRelation() returns true for a table, the table is a system
+catalog that receives systable_inplace_update_begin() calls. Preparing a
+heap_update() of these tables follows additional locking rules, to ensure we
+don't lose the effects of an inplace update. In particular, consider a moment
+when a backend has fetched the old tuple to modify, not yet having called
+heap_update(). Another backend's inplace update starting then can't conclude
+until the heap_update() places its new tuple in a buffer. We enforce that
+using locktags as follows. While DDL code is the main audience, the executor
+follows these rules to make e.g. "MERGE INTO pg_class" safer. Locking rules
+are per-catalog:
+
+ pg_class systable_inplace_update_begin() callers: before the call, acquire a
+ lock on the relation in mode ShareUpdateExclusiveLock or stricter. If the
+ update targets a row of RELKIND_INDEX (but not RELKIND_PARTITIONED_INDEX),
+ that lock must be on the table. Locking the index rel is not necessary.
+ (This allows VACUUM to overwrite per-index pg_class while holding a lock on
+ the table alone.) systable_inplace_update_begin() acquires and releases
+ LOCKTAG_TUPLE in InplaceUpdateTupleLock, an alias for ExclusiveLock, on each
+ tuple it overwrites.
+
+ pg_class heap_update() callers: before copying the tuple to modify, take a
+ lock on the tuple, a ShareUpdateExclusiveLock on the relation, or a
+ ShareRowExclusiveLock or stricter on the relation.
+
+ SearchSysCacheLocked1() is one convenient way to acquire the tuple lock.
+ Most heap_update() callers already hold a suitable lock on the relation for
+ other reasons and can skip the tuple lock. If you do acquire the tuple
+ lock, release it immediately after the update.
+
+
+ pg_database: before copying the tuple to modify, all updaters of pg_database
+ rows acquire LOCKTAG_TUPLE. (Few updaters acquire LOCKTAG_OBJECT on the
+ database OID, so it wasn't worth extending that as a second option.)
+
+Ideally, DDL might want to perform permissions checks before LockTuple(), as
+we do with RangeVarGetRelidExtended() callbacks. We typically don't bother.
+LOCKTAG_TUPLE acquirers release it after each row, so the potential
+inconvenience is lower.
+
+Reading inplace-updated columns
+-------------------------------
+
+Inplace updates create an exception to the rule that tuple data won't change
+under a reader holding a pin. A reader of a heap_fetch() result tuple may
+witness a torn read. Current inplace-updated fields are aligned and are no
+wider than four bytes, and current readers don't need consistency across
+fields. Hence, they get by with just fetching each field once.
diff --git a/src/backend/access/heap/heapam.c b/src/backend/access/heap/heapam.c
index 82bb9cb33b6f0..4c5ae205a7a60 100644
--- a/src/backend/access/heap/heapam.c
+++ b/src/backend/access/heap/heapam.c
@@ -3,7 +3,7 @@
* heapam.c
* heap access method code
*
- * Portions Copyright (c) 1996-2024, PostgreSQL Global Development Group
+ * Portions Copyright (c) 1996-2025, PostgreSQL Global Development Group
* Portions Copyright (c) 1994, Regents of the University of California
*
*
@@ -31,42 +31,28 @@
*/
#include "postgres.h"
-#include "access/bufmask.h"
#include "access/heapam.h"
-#include "access/heapam_xlog.h"
#include "access/heaptoast.h"
#include "access/hio.h"
#include "access/multixact.h"
-#include "access/parallel.h"
-#include "access/relscan.h"
#include "access/subtrans.h"
#include "access/syncscan.h"
-#include "access/sysattr.h"
-#include "access/tableam.h"
-#include "access/transam.h"
#include "access/valid.h"
#include "access/visibilitymap.h"
-#include "access/xact.h"
-#include "access/xlog.h"
#include "access/xloginsert.h"
-#include "access/xlogutils.h"
-#include "catalog/catalog.h"
+#include "catalog/pg_database.h"
+#include "catalog/pg_database_d.h"
#include "commands/vacuum.h"
-#include "miscadmin.h"
#include "pgstat.h"
-#include "port/atomics.h"
#include "port/pg_bitutils.h"
-#include "storage/bufmgr.h"
-#include "storage/freespace.h"
#include "storage/lmgr.h"
#include "storage/predicate.h"
#include "storage/procarray.h"
-#include "storage/standby.h"
#include "utils/datum.h"
+#include "utils/injection_point.h"
#include "utils/inval.h"
-#include "utils/relcache.h"
-#include "utils/snapmgr.h"
#include "utils/spccache.h"
+#include "utils/syscache.h"
static HeapTuple heap_prepare_insert(Relation relation, HeapTuple tup,
@@ -75,6 +61,12 @@ static XLogRecPtr log_heap_update(Relation reln, Buffer oldbuf,
Buffer newbuf, HeapTuple oldtup,
HeapTuple newtup, HeapTuple old_key_tuple,
bool all_visible_cleared, bool new_all_visible_cleared);
+#ifdef USE_ASSERT_CHECKING
+static void check_lock_if_inplace_updateable_rel(Relation relation,
+ ItemPointer otid,
+ HeapTuple newtup);
+static void check_inplace_rel_lock(HeapTuple oldtup);
+#endif
static Bitmapset *HeapDetermineColumnsInfo(Relation relation,
Bitmapset *interesting_cols,
Bitmapset *external_cols,
@@ -106,7 +98,8 @@ static void MultiXactIdWait(MultiXactId multi, MultiXactStatus status, uint16 in
Relation rel, ItemPointer ctid, XLTW_Oper oper,
int *remaining);
static bool ConditionalMultiXactIdWait(MultiXactId multi, MultiXactStatus status,
- uint16 infomask, Relation rel, int *remaining);
+ uint16 infomask, Relation rel, int *remaining,
+ bool logLockFailure);
static void index_delete_sort(TM_IndexDeleteOp *delstate);
static int bottomup_sort_and_shrink(TM_IndexDeleteOp *delstate);
static XLogRecPtr log_heap_new_cid(Relation relation, HeapTuple tup);
@@ -121,6 +114,8 @@ static HeapTuple ExtractReplicaIdentity(Relation relation, HeapTuple tp, bool ke
* heavyweight lock mode and MultiXactStatus values to use for any particular
* tuple lock strength.
*
+ * These interact with InplaceUpdateTupleLock, an alias for ExclusiveLock.
+ *
* Don't look at lockstatus/updstatus directly! Use get_mxact_status_for_lock
* instead.
*/
@@ -168,8 +163,8 @@ static const struct
LockTuple((rel), (tup), tupleLockExtraInfo[mode].hwlock)
#define UnlockTupleTuplock(rel, tup, mode) \
UnlockTuple((rel), (tup), tupleLockExtraInfo[mode].hwlock)
-#define ConditionalLockTupleTuplock(rel, tup, mode) \
- ConditionalLockTuple((rel), (tup), tupleLockExtraInfo[mode].hwlock)
+#define ConditionalLockTupleTuplock(rel, tup, mode, log) \
+ ConditionalLockTuple((rel), (tup), tupleLockExtraInfo[mode].hwlock, (log))
#ifdef USE_PREFETCH
/*
@@ -218,6 +213,27 @@ static const int MultiXactStatusLock[MaxMultiXactStatus + 1] =
#define TUPLOCK_from_mxstatus(status) \
(MultiXactStatusLock[(status)])
+/*
+ * Check that we have a valid snapshot if we might need TOAST access.
+ */
+static inline void
+AssertHasSnapshotForToast(Relation rel)
+{
+#ifdef USE_ASSERT_CHECKING
+
+ /* bootstrap mode in particular breaks this rule */
+ if (!IsNormalProcessingMode())
+ return;
+
+ /* if the relation doesn't have a TOAST table, we are good */
+ if (!OidIsValid(rel->rd_rel->reltoastrelid))
+ return;
+
+ Assert(HaveRegisteredOrActiveSnapshot());
+
+#endif /* USE_ASSERT_CHECKING */
+}
+
/* ----------------------------------------------------------------
* heap support routines
* ----------------------------------------------------------------
@@ -285,6 +301,47 @@ heap_scan_stream_read_next_serial(ReadStream *stream,
return scan->rs_prefetch_block;
}
+/*
+ * Read stream API callback for bitmap heap scans.
+ * Returns the next block the caller wants from the read stream or
+ * InvalidBlockNumber when done.
+ */
+static BlockNumber
+bitmapheap_stream_read_next(ReadStream *pgsr, void *private_data,
+ void *per_buffer_data)
+{
+ TBMIterateResult *tbmres = per_buffer_data;
+ BitmapHeapScanDesc bscan = (BitmapHeapScanDesc) private_data;
+ HeapScanDesc hscan = (HeapScanDesc) bscan;
+ TableScanDesc sscan = &hscan->rs_base;
+
+ for (;;)
+ {
+ CHECK_FOR_INTERRUPTS();
+
+ /* no more entries in the bitmap */
+ if (!tbm_iterate(&sscan->st.rs_tbmiterator, tbmres))
+ return InvalidBlockNumber;
+
+ /*
+ * Ignore any claimed entries past what we think is the end of the
+ * relation. It may have been extended after the start of our scan (we
+ * only hold an AccessShareLock, and it could be inserts from this
+ * backend). We don't take this optimization in SERIALIZABLE
+ * isolation though, as we need to examine all invisible tuples
+ * reachable by the index.
+ */
+ if (!IsolationIsSerializable() &&
+ tbmres->blockno >= hscan->rs_nblocks)
+ continue;
+
+ return tbmres->blockno;
+ }
+
+ /* not reachable */
+ Assert(false);
+}
+
/* ----------------
* initscan - scan code common to heap_beginscan and heap_rescan
* ----------------
@@ -386,6 +443,8 @@ initscan(HeapScanDesc scan, ScanKey key, bool keep_startblock)
ItemPointerSetInvalid(&scan->rs_ctup.t_self);
scan->rs_cbuf = InvalidBuffer;
scan->rs_cblock = InvalidBlockNumber;
+ scan->rs_ntuples = 0;
+ scan->rs_cindex = 0;
/*
* Initialize to ForwardScanDirection because it is most common and
@@ -951,8 +1010,8 @@ heapgettup_pagemode(HeapScanDesc scan,
{
HeapTuple tuple = &(scan->rs_ctup);
Page page;
- int lineindex;
- int linesleft;
+ uint32 lineindex;
+ uint32 linesleft;
if (likely(scan->rs_inited))
{
@@ -989,6 +1048,9 @@ heapgettup_pagemode(HeapScanDesc scan,
linesleft = scan->rs_ntuples;
lineindex = ScanDirectionIsForward(dir) ? 0 : linesleft - 1;
+ /* block is the same for all tuples, set it once outside the loop */
+ ItemPointerSetBlockNumber(&tuple->t_self, scan->rs_cblock);
+
/* lineindex now references the next or previous visible tid */
continue_page:
@@ -997,13 +1059,14 @@ heapgettup_pagemode(HeapScanDesc scan,
ItemId lpp;
OffsetNumber lineoff;
+ Assert(lineindex <= scan->rs_ntuples);
lineoff = scan->rs_vistuples[lineindex];
lpp = PageGetItemId(page, lineoff);
Assert(ItemIdIsNormal(lpp));
tuple->t_data = (HeapTupleHeader) PageGetItem(page, lpp);
tuple->t_len = ItemIdGetLength(lpp);
- ItemPointerSet(&(tuple->t_self), scan->rs_cblock, lineoff);
+ ItemPointerSetOffsetNumber(&tuple->t_self, lineoff);
/* skip any tuples that don't match the scan key */
if (key != NULL &&
@@ -1053,7 +1116,18 @@ heap_beginscan(Relation relation, Snapshot snapshot,
/*
* allocate and initialize scan descriptor
*/
- scan = (HeapScanDesc) palloc(sizeof(HeapScanDescData));
+ if (flags & SO_TYPE_BITMAPSCAN)
+ {
+ BitmapHeapScanDesc bscan = palloc(sizeof(BitmapHeapScanDescData));
+
+ /*
+ * Bitmap Heap scans do not have any fields that a normal Heap Scan
+ * does not have, so no special initializations required here.
+ */
+ scan = (HeapScanDesc) bscan;
+ }
+ else
+ scan = (HeapScanDesc) palloc(sizeof(HeapScanDescData));
scan->rs_base.rs_rd = relation;
scan->rs_base.rs_snapshot = snapshot;
@@ -1061,8 +1135,7 @@ heap_beginscan(Relation relation, Snapshot snapshot,
scan->rs_base.rs_flags = flags;
scan->rs_base.rs_parallel = parallel_scan;
scan->rs_strategy = NULL; /* set in initscan */
- scan->rs_vmbuffer = InvalidBuffer;
- scan->rs_empty_tuples_pending = 0;
+ scan->rs_cbuf = InvalidBuffer;
/*
* Disable page-at-a-time mode if it's not a MVCC-safe snapshot.
@@ -1070,6 +1143,17 @@ heap_beginscan(Relation relation, Snapshot snapshot,
if (!(snapshot && IsMVCCSnapshot(snapshot)))
scan->rs_base.rs_flags &= ~SO_ALLOW_PAGEMODE;
+ /* Check that a historic snapshot is not used for non-catalog tables */
+ if (snapshot &&
+ IsHistoricMVCCSnapshot(snapshot) &&
+ !RelationIsAccessibleInLogicalDecoding(relation))
+ {
+ ereport(ERROR,
+ (errcode(ERRCODE_INVALID_TRANSACTION_STATE),
+ errmsg("cannot query non-catalog table \"%s\" during logical decoding",
+ RelationGetRelationName(relation))));
+ }
+
/*
* For seqscan and sample scans in a serializable transaction, acquire a
* predicate lock on the entire relation. This is required not only to
@@ -1134,7 +1218,15 @@ heap_beginscan(Relation relation, Snapshot snapshot,
else
cb = heap_scan_stream_read_next_serial;
- scan->rs_read_stream = read_stream_begin_relation(READ_STREAM_SEQUENTIAL,
+ /* ---
+ * It is safe to use batchmode as the only locks taken by `cb`
+ * are never taken while waiting for IO:
+ * - SyncScanLock is used in the non-parallel case
+ * - in the parallel case, only spinlocks and atomics are used
+ * ---
+ */
+ scan->rs_read_stream = read_stream_begin_relation(READ_STREAM_SEQUENTIAL |
+ READ_STREAM_USE_BATCHING,
scan->rs_strategy,
scan->rs_base.rs_rd,
MAIN_FORKNUM,
@@ -1142,6 +1234,17 @@ heap_beginscan(Relation relation, Snapshot snapshot,
scan,
0);
}
+ else if (scan->rs_base.rs_flags & SO_TYPE_BITMAPSCAN)
+ {
+ scan->rs_read_stream = read_stream_begin_relation(READ_STREAM_DEFAULT |
+ READ_STREAM_USE_BATCHING,
+ scan->rs_strategy,
+ scan->rs_base.rs_rd,
+ MAIN_FORKNUM,
+ bitmapheap_stream_read_next,
+ scan,
+ sizeof(TBMIterateResult));
+ }
return (TableScanDesc) scan;
@@ -1176,20 +1279,15 @@ heap_rescan(TableScanDesc sscan, ScanKey key, bool set_params,
* unpin scan buffers
*/
if (BufferIsValid(scan->rs_cbuf))
- ReleaseBuffer(scan->rs_cbuf);
-
- if (BufferIsValid(scan->rs_vmbuffer))
{
- ReleaseBuffer(scan->rs_vmbuffer);
- scan->rs_vmbuffer = InvalidBuffer;
+ ReleaseBuffer(scan->rs_cbuf);
+ scan->rs_cbuf = InvalidBuffer;
}
/*
- * Reset rs_empty_tuples_pending, a field only used by bitmap heap scan,
- * to avoid incorrectly emitting NULL-filled tuples from a previous scan
- * on rescan.
+ * SO_TYPE_BITMAPSCAN would be cleaned up here, but it does not hold any
+ * additional data vs a normal HeapScan
*/
- scan->rs_empty_tuples_pending = 0;
/*
* The read stream is reset on rescan. This must be done before
@@ -1218,9 +1316,6 @@ heap_endscan(TableScanDesc sscan)
if (BufferIsValid(scan->rs_cbuf))
ReleaseBuffer(scan->rs_cbuf);
- if (BufferIsValid(scan->rs_vmbuffer))
- ReleaseBuffer(scan->rs_vmbuffer);
-
/*
* Must free the read stream before freeing the BufferAccessStrategy.
*/
@@ -1395,8 +1490,8 @@ heap_set_tidrange(TableScanDesc sscan, ItemPointer mintid,
heap_setscanlimits(sscan, startBlk, numBlks);
/* Finally, set the TID range in sscan */
- ItemPointerCopy(&lowestItem, &sscan->rs_mintid);
- ItemPointerCopy(&highestItem, &sscan->rs_maxtid);
+ ItemPointerCopy(&lowestItem, &sscan->st.tidrange.rs_mintid);
+ ItemPointerCopy(&highestItem, &sscan->st.tidrange.rs_maxtid);
}
bool
@@ -1404,8 +1499,8 @@ heap_getnextslot_tidrange(TableScanDesc sscan, ScanDirection direction,
TupleTableSlot *slot)
{
HeapScanDesc scan = (HeapScanDesc) sscan;
- ItemPointer mintid = &sscan->rs_mintid;
- ItemPointer maxtid = &sscan->rs_maxtid;
+ ItemPointer mintid = &sscan->st.tidrange.rs_mintid;
+ ItemPointer maxtid = &sscan->st.tidrange.rs_maxtid;
/* Note: no locking manipulations needed */
for (;;)
@@ -2003,6 +2098,8 @@ heap_insert(Relation relation, HeapTuple tup, CommandId cid,
Assert(HeapTupleHeaderGetNatts(tup->t_data) <=
RelationGetNumberOfAttributes(relation));
+ AssertHasSnapshotForToast(relation);
+
/*
* Fill in tuple header fields and toast the tuple if necessary.
*
@@ -2118,7 +2215,7 @@ heap_insert(Relation relation, HeapTuple tup, CommandId cid,
}
XLogBeginInsert();
- XLogRegisterData((char *) &xlrec, SizeOfHeapInsert);
+ XLogRegisterData(&xlrec, SizeOfHeapInsert);
xlhdr.t_infomask2 = heaptup->t_data->t_infomask2;
xlhdr.t_infomask = heaptup->t_data->t_infomask;
@@ -2130,7 +2227,7 @@ heap_insert(Relation relation, HeapTuple tup, CommandId cid,
* xl_heap_header in the xlog.
*/
XLogRegisterBuffer(0, buffer, REGBUF_STANDARD | bufflags);
- XLogRegisterBufData(0, (char *) &xlhdr, SizeOfHeapHeader);
+ XLogRegisterBufData(0, &xlhdr, SizeOfHeapHeader);
/* PG73FORMAT: write bitmap [+ padding] [+ oid] + data */
XLogRegisterBufData(0,
(char *) heaptup->t_data + SizeofHeapTupleHeader,
@@ -2280,6 +2377,8 @@ heap_multi_insert(Relation relation, TupleTableSlot **slots, int ntuples,
/* currently not needed (thus unsupported) for heap_multi_insert() */
Assert(!(options & HEAP_INSERT_NO_LOGICAL));
+ AssertHasSnapshotForToast(relation);
+
needwal = RelationNeedsWAL(relation);
saveFreeSpace = RelationGetTargetPageFreeSpace(relation,
HEAP_DEFAULT_FILLFACTOR);
@@ -2527,7 +2626,7 @@ heap_multi_insert(Relation relation, TupleTableSlot **slots, int ntuples,
bufflags |= REGBUF_KEEP_DATA;
XLogBeginInsert();
- XLogRegisterData((char *) xlrec, tupledata - scratch.data);
+ XLogRegisterData(xlrec, tupledata - scratch.data);
XLogRegisterBuffer(0, buffer, REGBUF_STANDARD | bufflags);
XLogRegisterBufData(0, tupledata, totaldatalen);
@@ -2548,9 +2647,6 @@ heap_multi_insert(Relation relation, TupleTableSlot **slots, int ntuples,
*/
if (all_frozen_set)
{
- Assert(PageIsAllVisible(page));
- Assert(visibilitymap_pin_ok(BufferGetBlockNumber(buffer), vmbuffer));
-
/*
* It's fine to use InvalidTransactionId here - this is only used
* when HEAP_INSERT_FROZEN is specified, which intentionally
@@ -2702,6 +2798,8 @@ heap_delete(Relation relation, ItemPointer tid,
Assert(ItemPointerIsValid(tid));
+ AssertHasSnapshotForToast(relation);
+
/*
* Forbid this during a parallel operation, lest it allocate a combo CID.
* Other workers might need that combo CID for visibility checks, and we
@@ -3017,7 +3115,7 @@ heap_delete(Relation relation, ItemPointer tid,
}
XLogBeginInsert();
- XLogRegisterData((char *) &xlrec, SizeOfHeapDelete);
+ XLogRegisterData(&xlrec, SizeOfHeapDelete);
XLogRegisterBuffer(0, buffer, REGBUF_STANDARD);
@@ -3030,7 +3128,7 @@ heap_delete(Relation relation, ItemPointer tid,
xlhdr.t_infomask = old_key_tuple->t_data->t_infomask;
xlhdr.t_hoff = old_key_tuple->t_data->t_hoff;
- XLogRegisterData((char *) &xlhdr, SizeOfHeapHeader);
+ XLogRegisterData(&xlhdr, SizeOfHeapHeader);
XLogRegisterData((char *) old_key_tuple->t_data
+ SizeofHeapTupleHeader,
old_key_tuple->t_len
@@ -3197,6 +3295,8 @@ heap_update(Relation relation, ItemPointer otid, HeapTuple newtup,
Assert(HeapTupleHeaderGetNatts(newtup->t_data) <=
RelationGetNumberOfAttributes(relation));
+ AssertHasSnapshotForToast(relation);
+
/*
* Forbid this during a parallel operation, lest it allocate a combo CID.
* Other workers might need that combo CID for visibility checks, and we
@@ -3207,6 +3307,10 @@ heap_update(Relation relation, ItemPointer otid, HeapTuple newtup,
(errcode(ERRCODE_INVALID_TRANSACTION_STATE),
errmsg("cannot update tuples during a parallel operation")));
+#ifdef USE_ASSERT_CHECKING
+ check_lock_if_inplace_updateable_rel(relation, otid, newtup);
+#endif
+
/*
* Fetch the list of attributes to be checked for various operations.
*
@@ -3237,6 +3341,7 @@ heap_update(Relation relation, ItemPointer otid, HeapTuple newtup,
interesting_attrs = bms_add_members(interesting_attrs, id_attrs);
block = ItemPointerGetBlockNumber(otid);
+ INJECTION_POINT("heap_update-before-pin", NULL);
buffer = ReadBuffer(relation, block);
page = BufferGetPage(buffer);
@@ -3252,7 +3357,51 @@ heap_update(Relation relation, ItemPointer otid, HeapTuple newtup,
LockBuffer(buffer, BUFFER_LOCK_EXCLUSIVE);
lp = PageGetItemId(page, ItemPointerGetOffsetNumber(otid));
- Assert(ItemIdIsNormal(lp));
+
+ /*
+ * Usually, a buffer pin and/or snapshot blocks pruning of otid, ensuring
+ * we see LP_NORMAL here. When the otid origin is a syscache, we may have
+ * neither a pin nor a snapshot. Hence, we may see other LP_ states, each
+ * of which indicates concurrent pruning.
+ *
+ * Failing with TM_Updated would be most accurate. However, unlike other
+ * TM_Updated scenarios, we don't know the successor ctid in LP_UNUSED and
+ * LP_DEAD cases. While the distinction between TM_Updated and TM_Deleted
+ * does matter to SQL statements UPDATE and MERGE, those SQL statements
+ * hold a snapshot that ensures LP_NORMAL. Hence, the choice between
+ * TM_Updated and TM_Deleted affects only the wording of error messages.
+ * Settle on TM_Deleted, for two reasons. First, it avoids complicating
+ * the specification of when tmfd->ctid is valid. Second, it creates
+ * error log evidence that we took this branch.
+ *
+ * Since it's possible to see LP_UNUSED at otid, it's also possible to see
+ * LP_NORMAL for a tuple that replaced LP_UNUSED. If it's a tuple for an
+ * unrelated row, we'll fail with "duplicate key value violates unique".
+ * XXX if otid is the live, newer version of the newtup row, we'll discard
+ * changes originating in versions of this catalog row after the version
+ * the caller got from syscache. See syscache-update-pruned.spec.
+ */
+ if (!ItemIdIsNormal(lp))
+ {
+ Assert(RelationSupportsSysCache(RelationGetRelid(relation)));
+
+ UnlockReleaseBuffer(buffer);
+ Assert(!have_tuple_lock);
+ if (vmbuffer != InvalidBuffer)
+ ReleaseBuffer(vmbuffer);
+ tmfd->ctid = *otid;
+ tmfd->xmax = InvalidTransactionId;
+ tmfd->cmax = InvalidCommandId;
+ *update_indexes = TU_None;
+
+ bms_free(hot_attrs);
+ bms_free(sum_attrs);
+ bms_free(key_attrs);
+ bms_free(id_attrs);
+ /* modified_attrs not yet initialized */
+ bms_free(interesting_attrs);
+ return TM_Deleted;
+ }
/*
* Fill in enough data in oldtup for HeapDetermineColumnsInfo to work
@@ -3747,7 +3896,7 @@ heap_update(Relation relation, ItemPointer otid, HeapTuple newtup,
oldtup.t_data->t_infomask2);
xlrec.flags =
cleared_all_frozen ? XLH_LOCK_ALL_FROZEN_CLEARED : 0;
- XLogRegisterData((char *) &xlrec, SizeOfHeapLock);
+ XLogRegisterData(&xlrec, SizeOfHeapLock);
recptr = XLogInsert(RM_HEAP_ID, XLOG_HEAP_LOCK);
PageSetLSN(page, recptr);
}
@@ -4071,6 +4220,128 @@ heap_update(Relation relation, ItemPointer otid, HeapTuple newtup,
return TM_Ok;
}
+#ifdef USE_ASSERT_CHECKING
+/*
+ * Confirm adequate lock held during heap_update(), per rules from
+ * README.tuplock section "Locking to write inplace-updated tables".
+ */
+static void
+check_lock_if_inplace_updateable_rel(Relation relation,
+ ItemPointer otid,
+ HeapTuple newtup)
+{
+ /* LOCKTAG_TUPLE acceptable for any catalog */
+ switch (RelationGetRelid(relation))
+ {
+ case RelationRelationId:
+ case DatabaseRelationId:
+ {
+ LOCKTAG tuptag;
+
+ SET_LOCKTAG_TUPLE(tuptag,
+ relation->rd_lockInfo.lockRelId.dbId,
+ relation->rd_lockInfo.lockRelId.relId,
+ ItemPointerGetBlockNumber(otid),
+ ItemPointerGetOffsetNumber(otid));
+ if (LockHeldByMe(&tuptag, InplaceUpdateTupleLock, false))
+ return;
+ }
+ break;
+ default:
+ Assert(!IsInplaceUpdateRelation(relation));
+ return;
+ }
+
+ switch (RelationGetRelid(relation))
+ {
+ case RelationRelationId:
+ {
+ /* LOCKTAG_TUPLE or LOCKTAG_RELATION ok */
+ Form_pg_class classForm = (Form_pg_class) GETSTRUCT(newtup);
+ Oid relid = classForm->oid;
+ Oid dbid;
+ LOCKTAG tag;
+
+ if (IsSharedRelation(relid))
+ dbid = InvalidOid;
+ else
+ dbid = MyDatabaseId;
+
+ if (classForm->relkind == RELKIND_INDEX)
+ {
+ Relation irel = index_open(relid, AccessShareLock);
+
+ SET_LOCKTAG_RELATION(tag, dbid, irel->rd_index->indrelid);
+ index_close(irel, AccessShareLock);
+ }
+ else
+ SET_LOCKTAG_RELATION(tag, dbid, relid);
+
+ if (!LockHeldByMe(&tag, ShareUpdateExclusiveLock, false) &&
+ !LockHeldByMe(&tag, ShareRowExclusiveLock, true))
+ elog(WARNING,
+ "missing lock for relation \"%s\" (OID %u, relkind %c) @ TID (%u,%u)",
+ NameStr(classForm->relname),
+ relid,
+ classForm->relkind,
+ ItemPointerGetBlockNumber(otid),
+ ItemPointerGetOffsetNumber(otid));
+ }
+ break;
+ case DatabaseRelationId:
+ {
+ /* LOCKTAG_TUPLE required */
+ Form_pg_database dbForm = (Form_pg_database) GETSTRUCT(newtup);
+
+ elog(WARNING,
+ "missing lock on database \"%s\" (OID %u) @ TID (%u,%u)",
+ NameStr(dbForm->datname),
+ dbForm->oid,
+ ItemPointerGetBlockNumber(otid),
+ ItemPointerGetOffsetNumber(otid));
+ }
+ break;
+ }
+}
+
+/*
+ * Confirm adequate relation lock held, per rules from README.tuplock section
+ * "Locking to write inplace-updated tables".
+ */
+static void
+check_inplace_rel_lock(HeapTuple oldtup)
+{
+ Form_pg_class classForm = (Form_pg_class) GETSTRUCT(oldtup);
+ Oid relid = classForm->oid;
+ Oid dbid;
+ LOCKTAG tag;
+
+ if (IsSharedRelation(relid))
+ dbid = InvalidOid;
+ else
+ dbid = MyDatabaseId;
+
+ if (classForm->relkind == RELKIND_INDEX)
+ {
+ Relation irel = index_open(relid, AccessShareLock);
+
+ SET_LOCKTAG_RELATION(tag, dbid, irel->rd_index->indrelid);
+ index_close(irel, AccessShareLock);
+ }
+ else
+ SET_LOCKTAG_RELATION(tag, dbid, relid);
+
+ if (!LockHeldByMe(&tag, ShareUpdateExclusiveLock, true))
+ elog(WARNING,
+ "missing lock for relation \"%s\" (OID %u, relkind %c) @ TID (%u,%u)",
+ NameStr(classForm->relname),
+ relid,
+ classForm->relkind,
+ ItemPointerGetBlockNumber(&oldtup->t_self),
+ ItemPointerGetOffsetNumber(&oldtup->t_self));
+}
+#endif
+
/*
* Check if the specified attribute's values are the same. Subroutine for
* HeapDetermineColumnsInfo.
@@ -4079,8 +4350,6 @@ static bool
heap_attr_equals(TupleDesc tupdesc, int attrnum, Datum value1, Datum value2,
bool isnull1, bool isnull2)
{
- Form_pg_attribute att;
-
/*
* If one value is NULL and other is not, then they are certainly not
* equal
@@ -4110,8 +4379,10 @@ heap_attr_equals(TupleDesc tupdesc, int attrnum, Datum value1, Datum value2,
}
else
{
+ CompactAttribute *att;
+
Assert(attrnum <= tupdesc->natts);
- att = TupleDescAttr(tupdesc, attrnum - 1);
+ att = TupleDescCompactAttr(tupdesc, attrnum - 1);
return datumIsEqual(value1, value2, att->attbyval, att->attlen);
}
}
@@ -4193,7 +4464,7 @@ HeapDetermineColumnsInfo(Relation relation,
* that system attributes can't be stored externally.
*/
if (attrnum < 0 || isnull1 ||
- TupleDescAttr(tupdesc, attrnum - 1)->attlen != -1)
+ TupleDescCompactAttr(tupdesc, attrnum - 1)->attlen != -1)
continue;
/*
@@ -4708,7 +4979,7 @@ heap_lock_tuple(Relation relation, HeapTuple tuple,
case LockWaitSkip:
if (!ConditionalMultiXactIdWait((MultiXactId) xwait,
status, infomask, relation,
- NULL))
+ NULL, false))
{
result = TM_WouldBlock;
/* recovery code expects to have buffer lock held */
@@ -4719,7 +4990,7 @@ heap_lock_tuple(Relation relation, HeapTuple tuple,
case LockWaitError:
if (!ConditionalMultiXactIdWait((MultiXactId) xwait,
status, infomask, relation,
- NULL))
+ NULL, log_lock_failures))
ereport(ERROR,
(errcode(ERRCODE_LOCK_NOT_AVAILABLE),
errmsg("could not obtain lock on row in relation \"%s\"",
@@ -4748,7 +5019,7 @@ heap_lock_tuple(Relation relation, HeapTuple tuple,
XLTW_Lock);
break;
case LockWaitSkip:
- if (!ConditionalXactLockTableWait(xwait))
+ if (!ConditionalXactLockTableWait(xwait, false))
{
result = TM_WouldBlock;
/* recovery code expects to have buffer lock held */
@@ -4757,7 +5028,7 @@ heap_lock_tuple(Relation relation, HeapTuple tuple,
}
break;
case LockWaitError:
- if (!ConditionalXactLockTableWait(xwait))
+ if (!ConditionalXactLockTableWait(xwait, log_lock_failures))
ereport(ERROR,
(errcode(ERRCODE_LOCK_NOT_AVAILABLE),
errmsg("could not obtain lock on row in relation \"%s\"",
@@ -4956,7 +5227,7 @@ heap_lock_tuple(Relation relation, HeapTuple tuple,
xlrec.infobits_set = compute_infobits(new_infomask,
tuple->t_data->t_infomask2);
xlrec.flags = cleared_all_frozen ? XLH_LOCK_ALL_FROZEN_CLEARED : 0;
- XLogRegisterData((char *) &xlrec, SizeOfHeapLock);
+ XLogRegisterData(&xlrec, SizeOfHeapLock);
/* we don't decode row locks atm, so no need to log the origin */
@@ -5017,12 +5288,12 @@ heap_acquire_tuplock(Relation relation, ItemPointer tid, LockTupleMode mode,
break;
case LockWaitSkip:
- if (!ConditionalLockTupleTuplock(relation, tid, mode))
+ if (!ConditionalLockTupleTuplock(relation, tid, mode, false))
return false;
break;
case LockWaitError:
- if (!ConditionalLockTupleTuplock(relation, tid, mode))
+ if (!ConditionalLockTupleTuplock(relation, tid, mode, log_lock_failures))
ereport(ERROR,
(errcode(ERRCODE_LOCK_NOT_AVAILABLE),
errmsg("could not obtain lock on row in relation \"%s\"",
@@ -5709,7 +5980,7 @@ heap_lock_updated_tuple_rec(Relation rel, ItemPointer tid, TransactionId xid,
xlrec.flags =
cleared_all_frozen ? XLH_LOCK_ALL_FROZEN_CLEARED : 0;
- XLogRegisterData((char *) &xlrec, SizeOfHeapLockUpdated);
+ XLogRegisterData(&xlrec, SizeOfHeapLockUpdated);
recptr = XLogInsert(RM_HEAP2_ID, XLOG_HEAP2_LOCK_UPDATED);
@@ -5825,7 +6096,7 @@ heap_finish_speculative(Relation relation, ItemPointer tid)
buffer = ReadBuffer(relation, ItemPointerGetBlockNumber(tid));
LockBuffer(buffer, BUFFER_LOCK_EXCLUSIVE);
- page = (Page) BufferGetPage(buffer);
+ page = BufferGetPage(buffer);
offnum = ItemPointerGetOffsetNumber(tid);
if (PageGetMaxOffsetNumber(page) >= offnum)
@@ -5862,7 +6133,7 @@ heap_finish_speculative(Relation relation, ItemPointer tid)
/* We want the same filtering on this as on a plain insert */
XLogSetRecordFlags(XLOG_INCLUDE_ORIGIN);
- XLogRegisterData((char *) &xlrec, SizeOfHeapConfirm);
+ XLogRegisterData(&xlrec, SizeOfHeapConfirm);
XLogRegisterBuffer(0, buffer, REGBUF_STANDARD);
recptr = XLogInsert(RM_HEAP_ID, XLOG_HEAP_CONFIRM);
@@ -6007,7 +6278,7 @@ heap_abort_speculative(Relation relation, ItemPointer tid)
xlrec.xmax = xid;
XLogBeginInsert();
- XLogRegisterData((char *) &xlrec, SizeOfHeapDelete);
+ XLogRegisterData(&xlrec, SizeOfHeapDelete);
XLogRegisterBuffer(0, buffer, REGBUF_STANDARD);
/* No replica identity & replication origin logged */
@@ -6040,86 +6311,292 @@ heap_abort_speculative(Relation relation, ItemPointer tid)
}
/*
- * heap_inplace_update - update a tuple "in place" (ie, overwrite it)
- *
- * Overwriting violates both MVCC and transactional safety, so the uses
- * of this function in Postgres are extremely limited. Nonetheless we
- * find some places to use it.
- *
- * The tuple cannot change size, and therefore it's reasonable to assume
- * that its null bitmap (if any) doesn't change either. So we just
- * overwrite the data portion of the tuple without touching the null
- * bitmap or any of the header fields.
- *
- * tuple is an in-memory tuple structure containing the data to be written
- * over the target tuple. Also, tuple->t_self identifies the target tuple.
- *
- * Note that the tuple updated here had better not come directly from the
- * syscache if the relation has a toast relation as this tuple could
- * include toast values that have been expanded, causing a failure here.
+ * heap_inplace_lock - protect inplace update from concurrent heap_update()
+ *
+ * Evaluate whether the tuple's state is compatible with a no-key update.
+ * Current transaction rowmarks are fine, as is KEY SHARE from any
+ * transaction. If compatible, return true with the buffer exclusive-locked,
+ * and the caller must release that by calling
+ * heap_inplace_update_and_unlock(), calling heap_inplace_unlock(), or raising
+ * an error. Otherwise, call release_callback(arg), wait for blocking
+ * transactions to end, and return false.
+ *
+ * Since this is intended for system catalogs and SERIALIZABLE doesn't cover
+ * DDL, this doesn't guarantee any particular predicate locking.
+ *
+ * One could modify this to return true for tuples with delete in progress,
+ * All inplace updaters take a lock that conflicts with DROP. If explicit
+ * "DELETE FROM pg_class" is in progress, we'll wait for it like we would an
+ * update.
+ *
+ * Readers of inplace-updated fields expect changes to those fields are
+ * durable. For example, vac_truncate_clog() reads datfrozenxid from
+ * pg_database tuples via catalog snapshots. A future snapshot must not
+ * return a lower datfrozenxid for the same database OID (lower in the
+ * FullTransactionIdPrecedes() sense). We achieve that since no update of a
+ * tuple can start while we hold a lock on its buffer. In cases like
+ * BEGIN;GRANT;CREATE INDEX;COMMIT we're inplace-updating a tuple visible only
+ * to this transaction. ROLLBACK then is one case where it's okay to lose
+ * inplace updates. (Restoring relhasindex=false on ROLLBACK is fine, since
+ * any concurrent CREATE INDEX would have blocked, then inplace-updated the
+ * committed tuple.)
+ *
+ * In principle, we could avoid waiting by overwriting every tuple in the
+ * updated tuple chain. Reader expectations permit updating a tuple only if
+ * it's aborted, is the tail of the chain, or we already updated the tuple
+ * referenced in its t_ctid. Hence, we would need to overwrite the tuples in
+ * order from tail to head. That would imply either (a) mutating all tuples
+ * in one critical section or (b) accepting a chance of partial completion.
+ * Partial completion of a relfrozenxid update would have the weird
+ * consequence that the table's next VACUUM could see the table's relfrozenxid
+ * move forward between vacuum_get_cutoffs() and finishing.
*/
-void
-heap_inplace_update(Relation relation, HeapTuple tuple)
+bool
+heap_inplace_lock(Relation relation,
+ HeapTuple oldtup_ptr, Buffer buffer,
+ void (*release_callback) (void *), void *arg)
{
- Buffer buffer;
- Page page;
- OffsetNumber offnum;
- ItemId lp = NULL;
- HeapTupleHeader htup;
- uint32 oldlen;
- uint32 newlen;
+ HeapTupleData oldtup = *oldtup_ptr; /* minimize diff vs. heap_update() */
+ TM_Result result;
+ bool ret;
+
+#ifdef USE_ASSERT_CHECKING
+ if (RelationGetRelid(relation) == RelationRelationId)
+ check_inplace_rel_lock(oldtup_ptr);
+#endif
+
+ Assert(BufferIsValid(buffer));
/*
- * For now, we don't allow parallel updates. Unlike a regular update,
- * this should never create a combo CID, so it might be possible to relax
- * this restriction, but not without more thought and testing. It's not
- * clear that it would be useful, anyway.
+ * Construct shared cache inval if necessary. Because we pass a tuple
+ * version without our own inplace changes or inplace changes other
+ * sessions complete while we wait for locks, inplace update mustn't
+ * change catcache lookup keys. But we aren't bothering with index
+ * updates either, so that's true a fortiori. After LockBuffer(), it
+ * would be too late, because this might reach a
+ * CatalogCacheInitializeCache() that locks "buffer".
*/
- if (IsInParallelMode())
- ereport(ERROR,
- (errcode(ERRCODE_INVALID_TRANSACTION_STATE),
- errmsg("cannot update tuples during a parallel operation")));
+ CacheInvalidateHeapTupleInplace(relation, oldtup_ptr, NULL);
- buffer = ReadBuffer(relation, ItemPointerGetBlockNumber(&(tuple->t_self)));
+ LockTuple(relation, &oldtup.t_self, InplaceUpdateTupleLock);
LockBuffer(buffer, BUFFER_LOCK_EXCLUSIVE);
- page = (Page) BufferGetPage(buffer);
- offnum = ItemPointerGetOffsetNumber(&(tuple->t_self));
- if (PageGetMaxOffsetNumber(page) >= offnum)
- lp = PageGetItemId(page, offnum);
+ /*----------
+ * Interpret HeapTupleSatisfiesUpdate() like heap_update() does, except:
+ *
+ * - wait unconditionally
+ * - already locked tuple above, since inplace needs that unconditionally
+ * - don't recheck header after wait: simpler to defer to next iteration
+ * - don't try to continue even if the updater aborts: likewise
+ * - no crosscheck
+ */
+ result = HeapTupleSatisfiesUpdate(&oldtup, GetCurrentCommandId(false),
+ buffer);
- if (PageGetMaxOffsetNumber(page) < offnum || !ItemIdIsNormal(lp))
- elog(ERROR, "invalid lp");
+ if (result == TM_Invisible)
+ {
+ /* no known way this can happen */
+ ereport(ERROR,
+ (errcode(ERRCODE_OBJECT_NOT_IN_PREREQUISITE_STATE),
+ errmsg_internal("attempted to overwrite invisible tuple")));
+ }
+ else if (result == TM_SelfModified)
+ {
+ /*
+ * CREATE INDEX might reach this if an expression is silly enough to
+ * call e.g. SELECT ... FROM pg_class FOR SHARE. C code of other SQL
+ * statements might get here after a heap_update() of the same row, in
+ * the absence of an intervening CommandCounterIncrement().
+ */
+ ereport(ERROR,
+ (errcode(ERRCODE_OBJECT_NOT_IN_PREREQUISITE_STATE),
+ errmsg("tuple to be updated was already modified by an operation triggered by the current command")));
+ }
+ else if (result == TM_BeingModified)
+ {
+ TransactionId xwait;
+ uint16 infomask;
- htup = (HeapTupleHeader) PageGetItem(page, lp);
+ xwait = HeapTupleHeaderGetRawXmax(oldtup.t_data);
+ infomask = oldtup.t_data->t_infomask;
+
+ if (infomask & HEAP_XMAX_IS_MULTI)
+ {
+ LockTupleMode lockmode = LockTupleNoKeyExclusive;
+ MultiXactStatus mxact_status = MultiXactStatusNoKeyUpdate;
+ int remain;
+
+ if (DoesMultiXactIdConflict((MultiXactId) xwait, infomask,
+ lockmode, NULL))
+ {
+ LockBuffer(buffer, BUFFER_LOCK_UNLOCK);
+ release_callback(arg);
+ ret = false;
+ MultiXactIdWait((MultiXactId) xwait, mxact_status, infomask,
+ relation, &oldtup.t_self, XLTW_Update,
+ &remain);
+ }
+ else
+ ret = true;
+ }
+ else if (TransactionIdIsCurrentTransactionId(xwait))
+ ret = true;
+ else if (HEAP_XMAX_IS_KEYSHR_LOCKED(infomask))
+ ret = true;
+ else
+ {
+ LockBuffer(buffer, BUFFER_LOCK_UNLOCK);
+ release_callback(arg);
+ ret = false;
+ XactLockTableWait(xwait, relation, &oldtup.t_self,
+ XLTW_Update);
+ }
+ }
+ else
+ {
+ ret = (result == TM_Ok);
+ if (!ret)
+ {
+ LockBuffer(buffer, BUFFER_LOCK_UNLOCK);
+ release_callback(arg);
+ }
+ }
+
+ /*
+ * GetCatalogSnapshot() relies on invalidation messages to know when to
+ * take a new snapshot. COMMIT of xwait is responsible for sending the
+ * invalidation. We're not acquiring heavyweight locks sufficient to
+ * block if not yet sent, so we must take a new snapshot to ensure a later
+ * attempt has a fair chance. While we don't need this if xwait aborted,
+ * don't bother optimizing that.
+ */
+ if (!ret)
+ {
+ UnlockTuple(relation, &oldtup.t_self, InplaceUpdateTupleLock);
+ ForgetInplace_Inval();
+ InvalidateCatalogSnapshot();
+ }
+ return ret;
+}
- oldlen = ItemIdGetLength(lp) - htup->t_hoff;
+/*
+ * heap_inplace_update_and_unlock - core of systable_inplace_update_finish
+ *
+ * The tuple cannot change size, and therefore its header fields and null
+ * bitmap (if any) don't change either.
+ *
+ * Since we hold LOCKTAG_TUPLE, no updater has a local copy of this tuple.
+ */
+void
+heap_inplace_update_and_unlock(Relation relation,
+ HeapTuple oldtup, HeapTuple tuple,
+ Buffer buffer)
+{
+ HeapTupleHeader htup = oldtup->t_data;
+ uint32 oldlen;
+ uint32 newlen;
+ char *dst;
+ char *src;
+ int nmsgs = 0;
+ SharedInvalidationMessage *invalMessages = NULL;
+ bool RelcacheInitFileInval = false;
+
+ Assert(ItemPointerEquals(&oldtup->t_self, &tuple->t_self));
+ oldlen = oldtup->t_len - htup->t_hoff;
newlen = tuple->t_len - tuple->t_data->t_hoff;
if (oldlen != newlen || htup->t_hoff != tuple->t_data->t_hoff)
elog(ERROR, "wrong tuple length");
- /* NO EREPORT(ERROR) from here till changes are logged */
- START_CRIT_SECTION();
+ dst = (char *) htup + htup->t_hoff;
+ src = (char *) tuple->t_data + tuple->t_data->t_hoff;
- memcpy((char *) htup + htup->t_hoff,
- (char *) tuple->t_data + tuple->t_data->t_hoff,
- newlen);
+ /* Like RecordTransactionCommit(), log only if needed */
+ if (XLogStandbyInfoActive())
+ nmsgs = inplaceGetInvalidationMessages(&invalMessages,
+ &RelcacheInitFileInval);
- MarkBufferDirty(buffer);
+ /*
+ * Unlink relcache init files as needed. If unlinking, acquire
+ * RelCacheInitLock until after associated invalidations. By doing this
+ * in advance, if we checkpoint and then crash between inplace
+ * XLogInsert() and inval, we don't rely on StartupXLOG() ->
+ * RelationCacheInitFileRemove(). That uses elevel==LOG, so replay would
+ * neglect to PANIC on EIO.
+ */
+ PreInplace_Inval();
+
+ /*----------
+ * NO EREPORT(ERROR) from here till changes are complete
+ *
+ * Our buffer lock won't stop a reader having already pinned and checked
+ * visibility for this tuple. Hence, we write WAL first, then mutate the
+ * buffer. Like in MarkBufferDirtyHint() or RecordTransactionCommit(),
+ * checkpoint delay makes that acceptable. With the usual order of
+ * changes, a crash after memcpy() and before XLogInsert() could allow
+ * datfrozenxid to overtake relfrozenxid:
+ *
+ * ["D" is a VACUUM (ONLY_DATABASE_STATS)]
+ * ["R" is a VACUUM tbl]
+ * D: vac_update_datfrozenxid() -> systable_beginscan(pg_class)
+ * D: systable_getnext() returns pg_class tuple of tbl
+ * R: memcpy() into pg_class tuple of tbl
+ * D: raise pg_database.datfrozenxid, XLogInsert(), finish
+ * [crash]
+ * [recovery restores datfrozenxid w/o relfrozenxid]
+ *
+ * Mimic MarkBufferDirtyHint() subroutine XLogSaveBufferForHint().
+ * Specifically, use DELAY_CHKPT_START, and copy the buffer to the stack.
+ * The stack copy facilitates a FPI of the post-mutation block before we
+ * accept other sessions seeing it. DELAY_CHKPT_START allows us to
+ * XLogInsert() before MarkBufferDirty(). Since XLogSaveBufferForHint()
+ * can operate under BUFFER_LOCK_SHARED, it can't avoid DELAY_CHKPT_START.
+ * This function, however, likely could avoid it with the following order
+ * of operations: MarkBufferDirty(), XLogInsert(), memcpy(). Opt to use
+ * DELAY_CHKPT_START here, too, as a way to have fewer distinct code
+ * patterns to analyze. Inplace update isn't so frequent that it should
+ * pursue the small optimization of skipping DELAY_CHKPT_START.
+ */
+ Assert((MyProc->delayChkptFlags & DELAY_CHKPT_START) == 0);
+ START_CRIT_SECTION();
+ MyProc->delayChkptFlags |= DELAY_CHKPT_START;
/* XLOG stuff */
if (RelationNeedsWAL(relation))
{
xl_heap_inplace xlrec;
+ PGAlignedBlock copied_buffer;
+ char *origdata = (char *) BufferGetBlock(buffer);
+ Page page = BufferGetPage(buffer);
+ uint16 lower = ((PageHeader) page)->pd_lower;
+ uint16 upper = ((PageHeader) page)->pd_upper;
+ uintptr_t dst_offset_in_block;
+ RelFileLocator rlocator;
+ ForkNumber forkno;
+ BlockNumber blkno;
XLogRecPtr recptr;
xlrec.offnum = ItemPointerGetOffsetNumber(&tuple->t_self);
+ xlrec.dbId = MyDatabaseId;
+ xlrec.tsId = MyDatabaseTableSpace;
+ xlrec.relcacheInitFileInval = RelcacheInitFileInval;
+ xlrec.nmsgs = nmsgs;
XLogBeginInsert();
- XLogRegisterData((char *) &xlrec, SizeOfHeapInplace);
-
- XLogRegisterBuffer(0, buffer, REGBUF_STANDARD);
- XLogRegisterBufData(0, (char *) htup + htup->t_hoff, newlen);
+ XLogRegisterData(&xlrec, MinSizeOfHeapInplace);
+ if (nmsgs != 0)
+ XLogRegisterData(invalMessages,
+ nmsgs * sizeof(SharedInvalidationMessage));
+
+ /* register block matching what buffer will look like after changes */
+ memcpy(copied_buffer.data, origdata, lower);
+ memcpy(copied_buffer.data + upper, origdata + upper, BLCKSZ - upper);
+ dst_offset_in_block = dst - origdata;
+ memcpy(copied_buffer.data + dst_offset_in_block, src, newlen);
+ BufferGetTag(buffer, &rlocator, &forkno, &blkno);
+ Assert(forkno == MAIN_FORKNUM);
+ XLogRegisterBlock(0, &rlocator, forkno, blkno, copied_buffer.data,
+ REGBUF_STANDARD);
+ XLogRegisterBufData(0, src, newlen);
/* inplace updates aren't decoded atm, don't log the origin */
@@ -6128,20 +6605,50 @@ heap_inplace_update(Relation relation, HeapTuple tuple)
PageSetLSN(page, recptr);
}
+ memcpy(dst, src, newlen);
+
+ MarkBufferDirty(buffer);
+
+ LockBuffer(buffer, BUFFER_LOCK_UNLOCK);
+
+ /*
+ * Send invalidations to shared queue. SearchSysCacheLocked1() assumes we
+ * do this before UnlockTuple().
+ *
+ * If we're mutating a tuple visible only to this transaction, there's an
+ * equivalent transactional inval from the action that created the tuple,
+ * and this inval is superfluous.
+ */
+ AtInplace_Inval();
+
+ MyProc->delayChkptFlags &= ~DELAY_CHKPT_START;
END_CRIT_SECTION();
+ UnlockTuple(relation, &tuple->t_self, InplaceUpdateTupleLock);
- UnlockReleaseBuffer(buffer);
+ AcceptInvalidationMessages(); /* local processing of just-sent inval */
/*
- * Send out shared cache inval if necessary. Note that because we only
- * pass the new version of the tuple, this mustn't be used for any
- * operations that could change catcache lookup keys. But we aren't
- * bothering with index updates either, so that's true a fortiori.
+ * Queue a transactional inval. The immediate invalidation we just sent
+ * is the only one known to be necessary. To reduce risk from the
+ * transition to immediate invalidation, continue sending a transactional
+ * invalidation like we've long done. Third-party code might rely on it.
*/
if (!IsBootstrapProcessingMode())
CacheInvalidateHeapTuple(relation, tuple, NULL);
}
+/*
+ * heap_inplace_unlock - reverse of heap_inplace_lock
+ */
+void
+heap_inplace_unlock(Relation relation,
+ HeapTuple oldtup, Buffer buffer)
+{
+ LockBuffer(buffer, BUFFER_LOCK_UNLOCK);
+ UnlockTuple(relation, &oldtup->t_self, InplaceUpdateTupleLock);
+ ForgetInplace_Inval();
+}
+
#define FRM_NOOP 0x0001
#define FRM_INVALIDATE_XMAX 0x0002
#define FRM_RETURN_IS_XID 0x0004
@@ -6810,32 +7317,8 @@ heap_prepare_freeze_tuple(HeapTupleHeader tuple,
}
/*
- * heap_execute_freeze_tuple
- * Execute the prepared freezing of a tuple with caller's freeze plan.
- *
- * Caller is responsible for ensuring that no other backend can access the
- * storage underlying this tuple, either by holding an exclusive lock on the
- * buffer containing it (which is what lazy VACUUM does), or by having it be
- * in private storage (which is what CLUSTER and friends do).
- */
-static inline void
-heap_execute_freeze_tuple(HeapTupleHeader tuple, HeapTupleFreeze *frz)
-{
- HeapTupleHeaderSetXmax(tuple, frz->xmax);
-
- if (frz->frzflags & XLH_FREEZE_XVAC)
- HeapTupleHeaderSetXvac(tuple, FrozenTransactionId);
-
- if (frz->frzflags & XLH_INVALID_XVAC)
- HeapTupleHeaderSetXvac(tuple, InvalidTransactionId);
-
- tuple->t_infomask = frz->t_infomask;
- tuple->t_infomask2 = frz->t_infomask2;
-}
-
-/*
- * Perform xmin/xmax XID status sanity checks before actually executing freeze
- * plans.
+ * Perform xmin/xmax XID status sanity checks before actually executing freeze
+ * plans.
*
* heap_prepare_freeze_tuple doesn't perform these checks directly because
* pg_xact lookups are relatively expensive. They shouldn't be repeated by
@@ -7094,10 +7577,10 @@ MultiXactIdGetUpdateXid(TransactionId xmax, uint16 t_infomask)
* checking the hint bits.
*/
TransactionId
-HeapTupleGetUpdateXid(HeapTupleHeader tuple)
+HeapTupleGetUpdateXid(const HeapTupleHeaderData *tup)
{
- return MultiXactIdGetUpdateXid(HeapTupleHeaderGetRawXmax(tuple),
- tuple->t_infomask);
+ return MultiXactIdGetUpdateXid(HeapTupleHeaderGetRawXmax(tup),
+ tup->t_infomask);
}
/*
@@ -7191,7 +7674,8 @@ DoesMultiXactIdConflict(MultiXactId multi, uint16 infomask,
* fail if lock is unavailable. 'rel', 'ctid' and 'oper' are used to set up
* context information for error messages. 'remaining', if not NULL, receives
* the number of members that are still running, including any (non-aborted)
- * subtransactions of our own transaction.
+ * subtransactions of our own transaction. 'logLockFailure' indicates whether
+ * to log details when a lock acquisition fails with 'nowait' enabled.
*
* We do this by sleeping on each member using XactLockTableWait. Any
* members that belong to the current backend are *not* waited for, however;
@@ -7212,7 +7696,7 @@ static bool
Do_MultiXactIdWait(MultiXactId multi, MultiXactStatus status,
uint16 infomask, bool nowait,
Relation rel, ItemPointer ctid, XLTW_Oper oper,
- int *remaining)
+ int *remaining, bool logLockFailure)
{
bool result = true;
MultiXactMember *members;
@@ -7259,7 +7743,7 @@ Do_MultiXactIdWait(MultiXactId multi, MultiXactStatus status,
*/
if (nowait)
{
- result = ConditionalXactLockTableWait(memxid);
+ result = ConditionalXactLockTableWait(memxid, logLockFailure);
if (!result)
break;
}
@@ -7292,7 +7776,7 @@ MultiXactIdWait(MultiXactId multi, MultiXactStatus status, uint16 infomask,
int *remaining)
{
(void) Do_MultiXactIdWait(multi, status, infomask, false,
- rel, ctid, oper, remaining);
+ rel, ctid, oper, remaining, false);
}
/*
@@ -7310,10 +7794,11 @@ MultiXactIdWait(MultiXactId multi, MultiXactStatus status, uint16 infomask,
*/
static bool
ConditionalMultiXactIdWait(MultiXactId multi, MultiXactStatus status,
- uint16 infomask, Relation rel, int *remaining)
+ uint16 infomask, Relation rel, int *remaining,
+ bool logLockFailure)
{
return Do_MultiXactIdWait(multi, status, infomask, true,
- rel, NULL, XLTW_None, remaining);
+ rel, NULL, XLTW_None, remaining, logLockFailure);
}
/*
@@ -7980,7 +8465,6 @@ index_delete_sort(TM_IndexDeleteOp *delstate)
{
TM_IndexDelete *deltids = delstate->deltids;
int ndeltids = delstate->ndeltids;
- int low = 0;
/*
* Shellsort gap sequence (taken from Sedgewick-Incerpi paper).
@@ -7996,7 +8480,7 @@ index_delete_sort(TM_IndexDeleteOp *delstate)
for (int g = 0; g < lengthof(gaps); g++)
{
- for (int hi = gaps[g], i = low + hi; i < ndeltids; i++)
+ for (int hi = gaps[g], i = hi; i < ndeltids; i++)
{
TM_IndexDelete d = deltids[i];
int j = i;
@@ -8333,7 +8817,7 @@ log_heap_visible(Relation rel, Buffer heap_buffer, Buffer vm_buffer,
if (RelationIsAccessibleInLogicalDecoding(rel))
xlrec.flags |= VISIBILITYMAP_XLOG_CATALOG_REL;
XLogBeginInsert();
- XLogRegisterData((char *) &xlrec, SizeOfHeapVisible);
+ XLogRegisterData(&xlrec, SizeOfHeapVisible);
XLogRegisterBuffer(0, vm_buffer, 0);
@@ -8484,7 +8968,7 @@ log_heap_update(Relation reln, Buffer oldbuf,
if (oldbuf != newbuf)
XLogRegisterBuffer(1, oldbuf, REGBUF_STANDARD);
- XLogRegisterData((char *) &xlrec, SizeOfHeapUpdate);
+ XLogRegisterData(&xlrec, SizeOfHeapUpdate);
/*
* Prepare WAL data for the new tuple.
@@ -8495,15 +8979,15 @@ log_heap_update(Relation reln, Buffer oldbuf,
{
prefix_suffix[0] = prefixlen;
prefix_suffix[1] = suffixlen;
- XLogRegisterBufData(0, (char *) &prefix_suffix, sizeof(uint16) * 2);
+ XLogRegisterBufData(0, &prefix_suffix, sizeof(uint16) * 2);
}
else if (prefixlen > 0)
{
- XLogRegisterBufData(0, (char *) &prefixlen, sizeof(uint16));
+ XLogRegisterBufData(0, &prefixlen, sizeof(uint16));
}
else
{
- XLogRegisterBufData(0, (char *) &suffixlen, sizeof(uint16));
+ XLogRegisterBufData(0, &suffixlen, sizeof(uint16));
}
}
@@ -8517,11 +9001,11 @@ log_heap_update(Relation reln, Buffer oldbuf,
*
* The 'data' doesn't include the common prefix or suffix.
*/
- XLogRegisterBufData(0, (char *) &xlhdr, SizeOfHeapHeader);
+ XLogRegisterBufData(0, &xlhdr, SizeOfHeapHeader);
if (prefixlen == 0)
{
XLogRegisterBufData(0,
- ((char *) newtup->t_data) + SizeofHeapTupleHeader,
+ (char *) newtup->t_data + SizeofHeapTupleHeader,
newtup->t_len - SizeofHeapTupleHeader - suffixlen);
}
else
@@ -8534,13 +9018,13 @@ log_heap_update(Relation reln, Buffer oldbuf,
if (newtup->t_data->t_hoff - SizeofHeapTupleHeader > 0)
{
XLogRegisterBufData(0,
- ((char *) newtup->t_data) + SizeofHeapTupleHeader,
+ (char *) newtup->t_data + SizeofHeapTupleHeader,
newtup->t_data->t_hoff - SizeofHeapTupleHeader);
}
/* data after common prefix */
XLogRegisterBufData(0,
- ((char *) newtup->t_data) + newtup->t_data->t_hoff + prefixlen,
+ (char *) newtup->t_data + newtup->t_data->t_hoff + prefixlen,
newtup->t_len - newtup->t_data->t_hoff - prefixlen - suffixlen);
}
@@ -8552,7 +9036,7 @@ log_heap_update(Relation reln, Buffer oldbuf,
xlhdr_idx.t_infomask = old_key_tuple->t_data->t_infomask;
xlhdr_idx.t_hoff = old_key_tuple->t_data->t_hoff;
- XLogRegisterData((char *) &xlhdr_idx, SizeOfHeapHeader);
+ XLogRegisterData(&xlhdr_idx, SizeOfHeapHeader);
/* PG73FORMAT: write bitmap [+ padding] [+ oid] + data */
XLogRegisterData((char *) old_key_tuple->t_data + SizeofHeapTupleHeader,
@@ -8632,7 +9116,7 @@ log_heap_new_cid(Relation relation, HeapTuple tup)
* called us certainly did, but that's WAL-logged separately.
*/
XLogBeginInsert();
- XLogRegisterData((char *) &xlrec, SizeOfHeapNewCid);
+ XLogRegisterData(&xlrec, SizeOfHeapNewCid);
/* will be looked at irrespective of origin */
@@ -8743,1303 +9227,6 @@ ExtractReplicaIdentity(Relation relation, HeapTuple tp, bool key_required,
return key_tuple;
}
-/*
- * Replay XLOG_HEAP2_PRUNE_* records.
- */
-static void
-heap_xlog_prune_freeze(XLogReaderState *record)
-{
- XLogRecPtr lsn = record->EndRecPtr;
- char *maindataptr = XLogRecGetData(record);
- xl_heap_prune xlrec;
- Buffer buffer;
- RelFileLocator rlocator;
- BlockNumber blkno;
- XLogRedoAction action;
-
- XLogRecGetBlockTag(record, 0, &rlocator, NULL, &blkno);
- memcpy(&xlrec, maindataptr, SizeOfHeapPrune);
- maindataptr += SizeOfHeapPrune;
-
- /*
- * We will take an ordinary exclusive lock or a cleanup lock depending on
- * whether the XLHP_CLEANUP_LOCK flag is set. With an ordinary exclusive
- * lock, we better not be doing anything that requires moving existing
- * tuple data.
- */
- Assert((xlrec.flags & XLHP_CLEANUP_LOCK) != 0 ||
- (xlrec.flags & (XLHP_HAS_REDIRECTIONS | XLHP_HAS_DEAD_ITEMS)) == 0);
-
- /*
- * We are about to remove and/or freeze tuples. In Hot Standby mode,
- * ensure that there are no queries running for which the removed tuples
- * are still visible or which still consider the frozen xids as running.
- * The conflict horizon XID comes after xl_heap_prune.
- */
- if ((xlrec.flags & XLHP_HAS_CONFLICT_HORIZON) != 0)
- {
- TransactionId snapshot_conflict_horizon;
-
- /* memcpy() because snapshot_conflict_horizon is stored unaligned */
- memcpy(&snapshot_conflict_horizon, maindataptr, sizeof(TransactionId));
- maindataptr += sizeof(TransactionId);
-
- if (InHotStandby)
- ResolveRecoveryConflictWithSnapshot(snapshot_conflict_horizon,
- (xlrec.flags & XLHP_IS_CATALOG_REL) != 0,
- rlocator);
- }
-
- /*
- * If we have a full-page image, restore it and we're done.
- */
- action = XLogReadBufferForRedoExtended(record, 0, RBM_NORMAL,
- (xlrec.flags & XLHP_CLEANUP_LOCK) != 0,
- &buffer);
- if (action == BLK_NEEDS_REDO)
- {
- Page page = (Page) BufferGetPage(buffer);
- OffsetNumber *redirected;
- OffsetNumber *nowdead;
- OffsetNumber *nowunused;
- int nredirected;
- int ndead;
- int nunused;
- int nplans;
- Size datalen;
- xlhp_freeze_plan *plans;
- OffsetNumber *frz_offsets;
- char *dataptr = XLogRecGetBlockData(record, 0, &datalen);
-
- heap_xlog_deserialize_prune_and_freeze(dataptr, xlrec.flags,
- &nplans, &plans, &frz_offsets,
- &nredirected, &redirected,
- &ndead, &nowdead,
- &nunused, &nowunused);
-
- /*
- * Update all line pointers per the record, and repair fragmentation
- * if needed.
- */
- if (nredirected > 0 || ndead > 0 || nunused > 0)
- heap_page_prune_execute(buffer,
- (xlrec.flags & XLHP_CLEANUP_LOCK) == 0,
- redirected, nredirected,
- nowdead, ndead,
- nowunused, nunused);
-
- /* Freeze tuples */
- for (int p = 0; p < nplans; p++)
- {
- HeapTupleFreeze frz;
-
- /*
- * Convert freeze plan representation from WAL record into
- * per-tuple format used by heap_execute_freeze_tuple
- */
- frz.xmax = plans[p].xmax;
- frz.t_infomask2 = plans[p].t_infomask2;
- frz.t_infomask = plans[p].t_infomask;
- frz.frzflags = plans[p].frzflags;
- frz.offset = InvalidOffsetNumber; /* unused, but be tidy */
-
- for (int i = 0; i < plans[p].ntuples; i++)
- {
- OffsetNumber offset = *(frz_offsets++);
- ItemId lp;
- HeapTupleHeader tuple;
-
- lp = PageGetItemId(page, offset);
- tuple = (HeapTupleHeader) PageGetItem(page, lp);
- heap_execute_freeze_tuple(tuple, &frz);
- }
- }
-
- /* There should be no more data */
- Assert((char *) frz_offsets == dataptr + datalen);
-
- /*
- * Note: we don't worry about updating the page's prunability hints.
- * At worst this will cause an extra prune cycle to occur soon.
- */
-
- PageSetLSN(page, lsn);
- MarkBufferDirty(buffer);
- }
-
- /*
- * If we released any space or line pointers, update the free space map.
- *
- * Do this regardless of a full-page image being applied, since the FSM
- * data is not in the page anyway.
- */
- if (BufferIsValid(buffer))
- {
- if (xlrec.flags & (XLHP_HAS_REDIRECTIONS |
- XLHP_HAS_DEAD_ITEMS |
- XLHP_HAS_NOW_UNUSED_ITEMS))
- {
- Size freespace = PageGetHeapFreeSpace(BufferGetPage(buffer));
-
- UnlockReleaseBuffer(buffer);
-
- XLogRecordPageWithFreeSpace(rlocator, blkno, freespace);
- }
- else
- UnlockReleaseBuffer(buffer);
- }
-}
-
-/*
- * Replay XLOG_HEAP2_VISIBLE record.
- *
- * The critical integrity requirement here is that we must never end up with
- * a situation where the visibility map bit is set, and the page-level
- * PD_ALL_VISIBLE bit is clear. If that were to occur, then a subsequent
- * page modification would fail to clear the visibility map bit.
- */
-static void
-heap_xlog_visible(XLogReaderState *record)
-{
- XLogRecPtr lsn = record->EndRecPtr;
- xl_heap_visible *xlrec = (xl_heap_visible *) XLogRecGetData(record);
- Buffer vmbuffer = InvalidBuffer;
- Buffer buffer;
- Page page;
- RelFileLocator rlocator;
- BlockNumber blkno;
- XLogRedoAction action;
-
- Assert((xlrec->flags & VISIBILITYMAP_XLOG_VALID_BITS) == xlrec->flags);
-
- XLogRecGetBlockTag(record, 1, &rlocator, NULL, &blkno);
-
- /*
- * If there are any Hot Standby transactions running that have an xmin
- * horizon old enough that this page isn't all-visible for them, they
- * might incorrectly decide that an index-only scan can skip a heap fetch.
- *
- * NB: It might be better to throw some kind of "soft" conflict here that
- * forces any index-only scan that is in flight to perform heap fetches,
- * rather than killing the transaction outright.
- */
- if (InHotStandby)
- ResolveRecoveryConflictWithSnapshot(xlrec->snapshotConflictHorizon,
- xlrec->flags & VISIBILITYMAP_XLOG_CATALOG_REL,
- rlocator);
-
- /*
- * Read the heap page, if it still exists. If the heap file has dropped or
- * truncated later in recovery, we don't need to update the page, but we'd
- * better still update the visibility map.
- */
- action = XLogReadBufferForRedo(record, 1, &buffer);
- if (action == BLK_NEEDS_REDO)
- {
- /*
- * We don't bump the LSN of the heap page when setting the visibility
- * map bit (unless checksums or wal_hint_bits is enabled, in which
- * case we must). This exposes us to torn page hazards, but since
- * we're not inspecting the existing page contents in any way, we
- * don't care.
- */
- page = BufferGetPage(buffer);
-
- PageSetAllVisible(page);
-
- if (XLogHintBitIsNeeded())
- PageSetLSN(page, lsn);
-
- MarkBufferDirty(buffer);
- }
- else if (action == BLK_RESTORED)
- {
- /*
- * If heap block was backed up, we already restored it and there's
- * nothing more to do. (This can only happen with checksums or
- * wal_log_hints enabled.)
- */
- }
-
- if (BufferIsValid(buffer))
- {
- Size space = PageGetFreeSpace(BufferGetPage(buffer));
-
- UnlockReleaseBuffer(buffer);
-
- /*
- * Since FSM is not WAL-logged and only updated heuristically, it
- * easily becomes stale in standbys. If the standby is later promoted
- * and runs VACUUM, it will skip updating individual free space
- * figures for pages that became all-visible (or all-frozen, depending
- * on the vacuum mode,) which is troublesome when FreeSpaceMapVacuum
- * propagates too optimistic free space values to upper FSM layers;
- * later inserters try to use such pages only to find out that they
- * are unusable. This can cause long stalls when there are many such
- * pages.
- *
- * Forestall those problems by updating FSM's idea about a page that
- * is becoming all-visible or all-frozen.
- *
- * Do this regardless of a full-page image being applied, since the
- * FSM data is not in the page anyway.
- */
- if (xlrec->flags & VISIBILITYMAP_VALID_BITS)
- XLogRecordPageWithFreeSpace(rlocator, blkno, space);
- }
-
- /*
- * Even if we skipped the heap page update due to the LSN interlock, it's
- * still safe to update the visibility map. Any WAL record that clears
- * the visibility map bit does so before checking the page LSN, so any
- * bits that need to be cleared will still be cleared.
- */
- if (XLogReadBufferForRedoExtended(record, 0, RBM_ZERO_ON_ERROR, false,
- &vmbuffer) == BLK_NEEDS_REDO)
- {
- Page vmpage = BufferGetPage(vmbuffer);
- Relation reln;
- uint8 vmbits;
-
- /* initialize the page if it was read as zeros */
- if (PageIsNew(vmpage))
- PageInit(vmpage, BLCKSZ, 0);
-
- /* remove VISIBILITYMAP_XLOG_* */
- vmbits = xlrec->flags & VISIBILITYMAP_VALID_BITS;
-
- /*
- * XLogReadBufferForRedoExtended locked the buffer. But
- * visibilitymap_set will handle locking itself.
- */
- LockBuffer(vmbuffer, BUFFER_LOCK_UNLOCK);
-
- reln = CreateFakeRelcacheEntry(rlocator);
- visibilitymap_pin(reln, blkno, &vmbuffer);
-
- visibilitymap_set(reln, blkno, InvalidBuffer, lsn, vmbuffer,
- xlrec->snapshotConflictHorizon, vmbits);
-
- ReleaseBuffer(vmbuffer);
- FreeFakeRelcacheEntry(reln);
- }
- else if (BufferIsValid(vmbuffer))
- UnlockReleaseBuffer(vmbuffer);
-}
-
-/*
- * Given an "infobits" field from an XLog record, set the correct bits in the
- * given infomask and infomask2 for the tuple touched by the record.
- *
- * (This is the reverse of compute_infobits).
- */
-static void
-fix_infomask_from_infobits(uint8 infobits, uint16 *infomask, uint16 *infomask2)
-{
- *infomask &= ~(HEAP_XMAX_IS_MULTI | HEAP_XMAX_LOCK_ONLY |
- HEAP_XMAX_KEYSHR_LOCK | HEAP_XMAX_EXCL_LOCK);
- *infomask2 &= ~HEAP_KEYS_UPDATED;
-
- if (infobits & XLHL_XMAX_IS_MULTI)
- *infomask |= HEAP_XMAX_IS_MULTI;
- if (infobits & XLHL_XMAX_LOCK_ONLY)
- *infomask |= HEAP_XMAX_LOCK_ONLY;
- if (infobits & XLHL_XMAX_EXCL_LOCK)
- *infomask |= HEAP_XMAX_EXCL_LOCK;
- /* note HEAP_XMAX_SHR_LOCK isn't considered here */
- if (infobits & XLHL_XMAX_KEYSHR_LOCK)
- *infomask |= HEAP_XMAX_KEYSHR_LOCK;
-
- if (infobits & XLHL_KEYS_UPDATED)
- *infomask2 |= HEAP_KEYS_UPDATED;
-}
-
-static void
-heap_xlog_delete(XLogReaderState *record)
-{
- XLogRecPtr lsn = record->EndRecPtr;
- xl_heap_delete *xlrec = (xl_heap_delete *) XLogRecGetData(record);
- Buffer buffer;
- Page page;
- ItemId lp = NULL;
- HeapTupleHeader htup;
- BlockNumber blkno;
- RelFileLocator target_locator;
- ItemPointerData target_tid;
-
- XLogRecGetBlockTag(record, 0, &target_locator, NULL, &blkno);
- ItemPointerSetBlockNumber(&target_tid, blkno);
- ItemPointerSetOffsetNumber(&target_tid, xlrec->offnum);
-
- /*
- * The visibility map may need to be fixed even if the heap page is
- * already up-to-date.
- */
- if (xlrec->flags & XLH_DELETE_ALL_VISIBLE_CLEARED)
- {
- Relation reln = CreateFakeRelcacheEntry(target_locator);
- Buffer vmbuffer = InvalidBuffer;
-
- visibilitymap_pin(reln, blkno, &vmbuffer);
- visibilitymap_clear(reln, blkno, vmbuffer, VISIBILITYMAP_VALID_BITS);
- ReleaseBuffer(vmbuffer);
- FreeFakeRelcacheEntry(reln);
- }
-
- if (XLogReadBufferForRedo(record, 0, &buffer) == BLK_NEEDS_REDO)
- {
- page = BufferGetPage(buffer);
-
- if (PageGetMaxOffsetNumber(page) >= xlrec->offnum)
- lp = PageGetItemId(page, xlrec->offnum);
-
- if (PageGetMaxOffsetNumber(page) < xlrec->offnum || !ItemIdIsNormal(lp))
- elog(PANIC, "invalid lp");
-
- htup = (HeapTupleHeader) PageGetItem(page, lp);
-
- htup->t_infomask &= ~(HEAP_XMAX_BITS | HEAP_MOVED);
- htup->t_infomask2 &= ~HEAP_KEYS_UPDATED;
- HeapTupleHeaderClearHotUpdated(htup);
- fix_infomask_from_infobits(xlrec->infobits_set,
- &htup->t_infomask, &htup->t_infomask2);
- if (!(xlrec->flags & XLH_DELETE_IS_SUPER))
- HeapTupleHeaderSetXmax(htup, xlrec->xmax);
- else
- HeapTupleHeaderSetXmin(htup, InvalidTransactionId);
- HeapTupleHeaderSetCmax(htup, FirstCommandId, false);
-
- /* Mark the page as a candidate for pruning */
- PageSetPrunable(page, XLogRecGetXid(record));
-
- if (xlrec->flags & XLH_DELETE_ALL_VISIBLE_CLEARED)
- PageClearAllVisible(page);
-
- /* Make sure t_ctid is set correctly */
- if (xlrec->flags & XLH_DELETE_IS_PARTITION_MOVE)
- HeapTupleHeaderSetMovedPartitions(htup);
- else
- htup->t_ctid = target_tid;
- PageSetLSN(page, lsn);
- MarkBufferDirty(buffer);
- }
- if (BufferIsValid(buffer))
- UnlockReleaseBuffer(buffer);
-}
-
-static void
-heap_xlog_insert(XLogReaderState *record)
-{
- XLogRecPtr lsn = record->EndRecPtr;
- xl_heap_insert *xlrec = (xl_heap_insert *) XLogRecGetData(record);
- Buffer buffer;
- Page page;
- union
- {
- HeapTupleHeaderData hdr;
- char data[MaxHeapTupleSize];
- } tbuf;
- HeapTupleHeader htup;
- xl_heap_header xlhdr;
- uint32 newlen;
- Size freespace = 0;
- RelFileLocator target_locator;
- BlockNumber blkno;
- ItemPointerData target_tid;
- XLogRedoAction action;
-
- XLogRecGetBlockTag(record, 0, &target_locator, NULL, &blkno);
- ItemPointerSetBlockNumber(&target_tid, blkno);
- ItemPointerSetOffsetNumber(&target_tid, xlrec->offnum);
-
- /*
- * The visibility map may need to be fixed even if the heap page is
- * already up-to-date.
- */
- if (xlrec->flags & XLH_INSERT_ALL_VISIBLE_CLEARED)
- {
- Relation reln = CreateFakeRelcacheEntry(target_locator);
- Buffer vmbuffer = InvalidBuffer;
-
- visibilitymap_pin(reln, blkno, &vmbuffer);
- visibilitymap_clear(reln, blkno, vmbuffer, VISIBILITYMAP_VALID_BITS);
- ReleaseBuffer(vmbuffer);
- FreeFakeRelcacheEntry(reln);
- }
-
- /*
- * If we inserted the first and only tuple on the page, re-initialize the
- * page from scratch.
- */
- if (XLogRecGetInfo(record) & XLOG_HEAP_INIT_PAGE)
- {
- buffer = XLogInitBufferForRedo(record, 0);
- page = BufferGetPage(buffer);
- PageInit(page, BufferGetPageSize(buffer), 0);
- action = BLK_NEEDS_REDO;
- }
- else
- action = XLogReadBufferForRedo(record, 0, &buffer);
- if (action == BLK_NEEDS_REDO)
- {
- Size datalen;
- char *data;
-
- page = BufferGetPage(buffer);
-
- if (PageGetMaxOffsetNumber(page) + 1 < xlrec->offnum)
- elog(PANIC, "invalid max offset number");
-
- data = XLogRecGetBlockData(record, 0, &datalen);
-
- newlen = datalen - SizeOfHeapHeader;
- Assert(datalen > SizeOfHeapHeader && newlen <= MaxHeapTupleSize);
- memcpy((char *) &xlhdr, data, SizeOfHeapHeader);
- data += SizeOfHeapHeader;
-
- htup = &tbuf.hdr;
- MemSet((char *) htup, 0, SizeofHeapTupleHeader);
- /* PG73FORMAT: get bitmap [+ padding] [+ oid] + data */
- memcpy((char *) htup + SizeofHeapTupleHeader,
- data,
- newlen);
- newlen += SizeofHeapTupleHeader;
- htup->t_infomask2 = xlhdr.t_infomask2;
- htup->t_infomask = xlhdr.t_infomask;
- htup->t_hoff = xlhdr.t_hoff;
- HeapTupleHeaderSetXmin(htup, XLogRecGetXid(record));
- HeapTupleHeaderSetCmin(htup, FirstCommandId);
- htup->t_ctid = target_tid;
-
- if (PageAddItem(page, (Item) htup, newlen, xlrec->offnum,
- true, true) == InvalidOffsetNumber)
- elog(PANIC, "failed to add tuple");
-
- freespace = PageGetHeapFreeSpace(page); /* needed to update FSM below */
-
- PageSetLSN(page, lsn);
-
- if (xlrec->flags & XLH_INSERT_ALL_VISIBLE_CLEARED)
- PageClearAllVisible(page);
-
- /* XLH_INSERT_ALL_FROZEN_SET implies that all tuples are visible */
- if (xlrec->flags & XLH_INSERT_ALL_FROZEN_SET)
- PageSetAllVisible(page);
-
- MarkBufferDirty(buffer);
- }
- if (BufferIsValid(buffer))
- UnlockReleaseBuffer(buffer);
-
- /*
- * If the page is running low on free space, update the FSM as well.
- * Arbitrarily, our definition of "low" is less than 20%. We can't do much
- * better than that without knowing the fill-factor for the table.
- *
- * XXX: Don't do this if the page was restored from full page image. We
- * don't bother to update the FSM in that case, it doesn't need to be
- * totally accurate anyway.
- */
- if (action == BLK_NEEDS_REDO && freespace < BLCKSZ / 5)
- XLogRecordPageWithFreeSpace(target_locator, blkno, freespace);
-}
-
-/*
- * Handles MULTI_INSERT record type.
- */
-static void
-heap_xlog_multi_insert(XLogReaderState *record)
-{
- XLogRecPtr lsn = record->EndRecPtr;
- xl_heap_multi_insert *xlrec;
- RelFileLocator rlocator;
- BlockNumber blkno;
- Buffer buffer;
- Page page;
- union
- {
- HeapTupleHeaderData hdr;
- char data[MaxHeapTupleSize];
- } tbuf;
- HeapTupleHeader htup;
- uint32 newlen;
- Size freespace = 0;
- int i;
- bool isinit = (XLogRecGetInfo(record) & XLOG_HEAP_INIT_PAGE) != 0;
- XLogRedoAction action;
-
- /*
- * Insertion doesn't overwrite MVCC data, so no conflict processing is
- * required.
- */
- xlrec = (xl_heap_multi_insert *) XLogRecGetData(record);
-
- XLogRecGetBlockTag(record, 0, &rlocator, NULL, &blkno);
-
- /* check that the mutually exclusive flags are not both set */
- Assert(!((xlrec->flags & XLH_INSERT_ALL_VISIBLE_CLEARED) &&
- (xlrec->flags & XLH_INSERT_ALL_FROZEN_SET)));
-
- /*
- * The visibility map may need to be fixed even if the heap page is
- * already up-to-date.
- */
- if (xlrec->flags & XLH_INSERT_ALL_VISIBLE_CLEARED)
- {
- Relation reln = CreateFakeRelcacheEntry(rlocator);
- Buffer vmbuffer = InvalidBuffer;
-
- visibilitymap_pin(reln, blkno, &vmbuffer);
- visibilitymap_clear(reln, blkno, vmbuffer, VISIBILITYMAP_VALID_BITS);
- ReleaseBuffer(vmbuffer);
- FreeFakeRelcacheEntry(reln);
- }
-
- if (isinit)
- {
- buffer = XLogInitBufferForRedo(record, 0);
- page = BufferGetPage(buffer);
- PageInit(page, BufferGetPageSize(buffer), 0);
- action = BLK_NEEDS_REDO;
- }
- else
- action = XLogReadBufferForRedo(record, 0, &buffer);
- if (action == BLK_NEEDS_REDO)
- {
- char *tupdata;
- char *endptr;
- Size len;
-
- /* Tuples are stored as block data */
- tupdata = XLogRecGetBlockData(record, 0, &len);
- endptr = tupdata + len;
-
- page = (Page) BufferGetPage(buffer);
-
- for (i = 0; i < xlrec->ntuples; i++)
- {
- OffsetNumber offnum;
- xl_multi_insert_tuple *xlhdr;
-
- /*
- * If we're reinitializing the page, the tuples are stored in
- * order from FirstOffsetNumber. Otherwise there's an array of
- * offsets in the WAL record, and the tuples come after that.
- */
- if (isinit)
- offnum = FirstOffsetNumber + i;
- else
- offnum = xlrec->offsets[i];
- if (PageGetMaxOffsetNumber(page) + 1 < offnum)
- elog(PANIC, "invalid max offset number");
-
- xlhdr = (xl_multi_insert_tuple *) SHORTALIGN(tupdata);
- tupdata = ((char *) xlhdr) + SizeOfMultiInsertTuple;
-
- newlen = xlhdr->datalen;
- Assert(newlen <= MaxHeapTupleSize);
- htup = &tbuf.hdr;
- MemSet((char *) htup, 0, SizeofHeapTupleHeader);
- /* PG73FORMAT: get bitmap [+ padding] [+ oid] + data */
- memcpy((char *) htup + SizeofHeapTupleHeader,
- (char *) tupdata,
- newlen);
- tupdata += newlen;
-
- newlen += SizeofHeapTupleHeader;
- htup->t_infomask2 = xlhdr->t_infomask2;
- htup->t_infomask = xlhdr->t_infomask;
- htup->t_hoff = xlhdr->t_hoff;
- HeapTupleHeaderSetXmin(htup, XLogRecGetXid(record));
- HeapTupleHeaderSetCmin(htup, FirstCommandId);
- ItemPointerSetBlockNumber(&htup->t_ctid, blkno);
- ItemPointerSetOffsetNumber(&htup->t_ctid, offnum);
-
- offnum = PageAddItem(page, (Item) htup, newlen, offnum, true, true);
- if (offnum == InvalidOffsetNumber)
- elog(PANIC, "failed to add tuple");
- }
- if (tupdata != endptr)
- elog(PANIC, "total tuple length mismatch");
-
- freespace = PageGetHeapFreeSpace(page); /* needed to update FSM below */
-
- PageSetLSN(page, lsn);
-
- if (xlrec->flags & XLH_INSERT_ALL_VISIBLE_CLEARED)
- PageClearAllVisible(page);
-
- /* XLH_INSERT_ALL_FROZEN_SET implies that all tuples are visible */
- if (xlrec->flags & XLH_INSERT_ALL_FROZEN_SET)
- PageSetAllVisible(page);
-
- MarkBufferDirty(buffer);
- }
- if (BufferIsValid(buffer))
- UnlockReleaseBuffer(buffer);
-
- /*
- * If the page is running low on free space, update the FSM as well.
- * Arbitrarily, our definition of "low" is less than 20%. We can't do much
- * better than that without knowing the fill-factor for the table.
- *
- * XXX: Don't do this if the page was restored from full page image. We
- * don't bother to update the FSM in that case, it doesn't need to be
- * totally accurate anyway.
- */
- if (action == BLK_NEEDS_REDO && freespace < BLCKSZ / 5)
- XLogRecordPageWithFreeSpace(rlocator, blkno, freespace);
-}
-
-/*
- * Handles UPDATE and HOT_UPDATE
- */
-static void
-heap_xlog_update(XLogReaderState *record, bool hot_update)
-{
- XLogRecPtr lsn = record->EndRecPtr;
- xl_heap_update *xlrec = (xl_heap_update *) XLogRecGetData(record);
- RelFileLocator rlocator;
- BlockNumber oldblk;
- BlockNumber newblk;
- ItemPointerData newtid;
- Buffer obuffer,
- nbuffer;
- Page page;
- OffsetNumber offnum;
- ItemId lp = NULL;
- HeapTupleData oldtup;
- HeapTupleHeader htup;
- uint16 prefixlen = 0,
- suffixlen = 0;
- char *newp;
- union
- {
- HeapTupleHeaderData hdr;
- char data[MaxHeapTupleSize];
- } tbuf;
- xl_heap_header xlhdr;
- uint32 newlen;
- Size freespace = 0;
- XLogRedoAction oldaction;
- XLogRedoAction newaction;
-
- /* initialize to keep the compiler quiet */
- oldtup.t_data = NULL;
- oldtup.t_len = 0;
-
- XLogRecGetBlockTag(record, 0, &rlocator, NULL, &newblk);
- if (XLogRecGetBlockTagExtended(record, 1, NULL, NULL, &oldblk, NULL))
- {
- /* HOT updates are never done across pages */
- Assert(!hot_update);
- }
- else
- oldblk = newblk;
-
- ItemPointerSet(&newtid, newblk, xlrec->new_offnum);
-
- /*
- * The visibility map may need to be fixed even if the heap page is
- * already up-to-date.
- */
- if (xlrec->flags & XLH_UPDATE_OLD_ALL_VISIBLE_CLEARED)
- {
- Relation reln = CreateFakeRelcacheEntry(rlocator);
- Buffer vmbuffer = InvalidBuffer;
-
- visibilitymap_pin(reln, oldblk, &vmbuffer);
- visibilitymap_clear(reln, oldblk, vmbuffer, VISIBILITYMAP_VALID_BITS);
- ReleaseBuffer(vmbuffer);
- FreeFakeRelcacheEntry(reln);
- }
-
- /*
- * In normal operation, it is important to lock the two pages in
- * page-number order, to avoid possible deadlocks against other update
- * operations going the other way. However, during WAL replay there can
- * be no other update happening, so we don't need to worry about that. But
- * we *do* need to worry that we don't expose an inconsistent state to Hot
- * Standby queries --- so the original page can't be unlocked before we've
- * added the new tuple to the new page.
- */
-
- /* Deal with old tuple version */
- oldaction = XLogReadBufferForRedo(record, (oldblk == newblk) ? 0 : 1,
- &obuffer);
- if (oldaction == BLK_NEEDS_REDO)
- {
- page = BufferGetPage(obuffer);
- offnum = xlrec->old_offnum;
- if (PageGetMaxOffsetNumber(page) >= offnum)
- lp = PageGetItemId(page, offnum);
-
- if (PageGetMaxOffsetNumber(page) < offnum || !ItemIdIsNormal(lp))
- elog(PANIC, "invalid lp");
-
- htup = (HeapTupleHeader) PageGetItem(page, lp);
-
- oldtup.t_data = htup;
- oldtup.t_len = ItemIdGetLength(lp);
-
- htup->t_infomask &= ~(HEAP_XMAX_BITS | HEAP_MOVED);
- htup->t_infomask2 &= ~HEAP_KEYS_UPDATED;
- if (hot_update)
- HeapTupleHeaderSetHotUpdated(htup);
- else
- HeapTupleHeaderClearHotUpdated(htup);
- fix_infomask_from_infobits(xlrec->old_infobits_set, &htup->t_infomask,
- &htup->t_infomask2);
- HeapTupleHeaderSetXmax(htup, xlrec->old_xmax);
- HeapTupleHeaderSetCmax(htup, FirstCommandId, false);
- /* Set forward chain link in t_ctid */
- htup->t_ctid = newtid;
-
- /* Mark the page as a candidate for pruning */
- PageSetPrunable(page, XLogRecGetXid(record));
-
- if (xlrec->flags & XLH_UPDATE_OLD_ALL_VISIBLE_CLEARED)
- PageClearAllVisible(page);
-
- PageSetLSN(page, lsn);
- MarkBufferDirty(obuffer);
- }
-
- /*
- * Read the page the new tuple goes into, if different from old.
- */
- if (oldblk == newblk)
- {
- nbuffer = obuffer;
- newaction = oldaction;
- }
- else if (XLogRecGetInfo(record) & XLOG_HEAP_INIT_PAGE)
- {
- nbuffer = XLogInitBufferForRedo(record, 0);
- page = (Page) BufferGetPage(nbuffer);
- PageInit(page, BufferGetPageSize(nbuffer), 0);
- newaction = BLK_NEEDS_REDO;
- }
- else
- newaction = XLogReadBufferForRedo(record, 0, &nbuffer);
-
- /*
- * The visibility map may need to be fixed even if the heap page is
- * already up-to-date.
- */
- if (xlrec->flags & XLH_UPDATE_NEW_ALL_VISIBLE_CLEARED)
- {
- Relation reln = CreateFakeRelcacheEntry(rlocator);
- Buffer vmbuffer = InvalidBuffer;
-
- visibilitymap_pin(reln, newblk, &vmbuffer);
- visibilitymap_clear(reln, newblk, vmbuffer, VISIBILITYMAP_VALID_BITS);
- ReleaseBuffer(vmbuffer);
- FreeFakeRelcacheEntry(reln);
- }
-
- /* Deal with new tuple */
- if (newaction == BLK_NEEDS_REDO)
- {
- char *recdata;
- char *recdata_end;
- Size datalen;
- Size tuplen;
-
- recdata = XLogRecGetBlockData(record, 0, &datalen);
- recdata_end = recdata + datalen;
-
- page = BufferGetPage(nbuffer);
-
- offnum = xlrec->new_offnum;
- if (PageGetMaxOffsetNumber(page) + 1 < offnum)
- elog(PANIC, "invalid max offset number");
-
- if (xlrec->flags & XLH_UPDATE_PREFIX_FROM_OLD)
- {
- Assert(newblk == oldblk);
- memcpy(&prefixlen, recdata, sizeof(uint16));
- recdata += sizeof(uint16);
- }
- if (xlrec->flags & XLH_UPDATE_SUFFIX_FROM_OLD)
- {
- Assert(newblk == oldblk);
- memcpy(&suffixlen, recdata, sizeof(uint16));
- recdata += sizeof(uint16);
- }
-
- memcpy((char *) &xlhdr, recdata, SizeOfHeapHeader);
- recdata += SizeOfHeapHeader;
-
- tuplen = recdata_end - recdata;
- Assert(tuplen <= MaxHeapTupleSize);
-
- htup = &tbuf.hdr;
- MemSet((char *) htup, 0, SizeofHeapTupleHeader);
-
- /*
- * Reconstruct the new tuple using the prefix and/or suffix from the
- * old tuple, and the data stored in the WAL record.
- */
- newp = (char *) htup + SizeofHeapTupleHeader;
- if (prefixlen > 0)
- {
- int len;
-
- /* copy bitmap [+ padding] [+ oid] from WAL record */
- len = xlhdr.t_hoff - SizeofHeapTupleHeader;
- memcpy(newp, recdata, len);
- recdata += len;
- newp += len;
-
- /* copy prefix from old tuple */
- memcpy(newp, (char *) oldtup.t_data + oldtup.t_data->t_hoff, prefixlen);
- newp += prefixlen;
-
- /* copy new tuple data from WAL record */
- len = tuplen - (xlhdr.t_hoff - SizeofHeapTupleHeader);
- memcpy(newp, recdata, len);
- recdata += len;
- newp += len;
- }
- else
- {
- /*
- * copy bitmap [+ padding] [+ oid] + data from record, all in one
- * go
- */
- memcpy(newp, recdata, tuplen);
- recdata += tuplen;
- newp += tuplen;
- }
- Assert(recdata == recdata_end);
-
- /* copy suffix from old tuple */
- if (suffixlen > 0)
- memcpy(newp, (char *) oldtup.t_data + oldtup.t_len - suffixlen, suffixlen);
-
- newlen = SizeofHeapTupleHeader + tuplen + prefixlen + suffixlen;
- htup->t_infomask2 = xlhdr.t_infomask2;
- htup->t_infomask = xlhdr.t_infomask;
- htup->t_hoff = xlhdr.t_hoff;
-
- HeapTupleHeaderSetXmin(htup, XLogRecGetXid(record));
- HeapTupleHeaderSetCmin(htup, FirstCommandId);
- HeapTupleHeaderSetXmax(htup, xlrec->new_xmax);
- /* Make sure there is no forward chain link in t_ctid */
- htup->t_ctid = newtid;
-
- offnum = PageAddItem(page, (Item) htup, newlen, offnum, true, true);
- if (offnum == InvalidOffsetNumber)
- elog(PANIC, "failed to add tuple");
-
- if (xlrec->flags & XLH_UPDATE_NEW_ALL_VISIBLE_CLEARED)
- PageClearAllVisible(page);
-
- freespace = PageGetHeapFreeSpace(page); /* needed to update FSM below */
-
- PageSetLSN(page, lsn);
- MarkBufferDirty(nbuffer);
- }
-
- if (BufferIsValid(nbuffer) && nbuffer != obuffer)
- UnlockReleaseBuffer(nbuffer);
- if (BufferIsValid(obuffer))
- UnlockReleaseBuffer(obuffer);
-
- /*
- * If the new page is running low on free space, update the FSM as well.
- * Arbitrarily, our definition of "low" is less than 20%. We can't do much
- * better than that without knowing the fill-factor for the table.
- *
- * However, don't update the FSM on HOT updates, because after crash
- * recovery, either the old or the new tuple will certainly be dead and
- * prunable. After pruning, the page will have roughly as much free space
- * as it did before the update, assuming the new tuple is about the same
- * size as the old one.
- *
- * XXX: Don't do this if the page was restored from full page image. We
- * don't bother to update the FSM in that case, it doesn't need to be
- * totally accurate anyway.
- */
- if (newaction == BLK_NEEDS_REDO && !hot_update && freespace < BLCKSZ / 5)
- XLogRecordPageWithFreeSpace(rlocator, newblk, freespace);
-}
-
-static void
-heap_xlog_confirm(XLogReaderState *record)
-{
- XLogRecPtr lsn = record->EndRecPtr;
- xl_heap_confirm *xlrec = (xl_heap_confirm *) XLogRecGetData(record);
- Buffer buffer;
- Page page;
- OffsetNumber offnum;
- ItemId lp = NULL;
- HeapTupleHeader htup;
-
- if (XLogReadBufferForRedo(record, 0, &buffer) == BLK_NEEDS_REDO)
- {
- page = BufferGetPage(buffer);
-
- offnum = xlrec->offnum;
- if (PageGetMaxOffsetNumber(page) >= offnum)
- lp = PageGetItemId(page, offnum);
-
- if (PageGetMaxOffsetNumber(page) < offnum || !ItemIdIsNormal(lp))
- elog(PANIC, "invalid lp");
-
- htup = (HeapTupleHeader) PageGetItem(page, lp);
-
- /*
- * Confirm tuple as actually inserted
- */
- ItemPointerSet(&htup->t_ctid, BufferGetBlockNumber(buffer), offnum);
-
- PageSetLSN(page, lsn);
- MarkBufferDirty(buffer);
- }
- if (BufferIsValid(buffer))
- UnlockReleaseBuffer(buffer);
-}
-
-static void
-heap_xlog_lock(XLogReaderState *record)
-{
- XLogRecPtr lsn = record->EndRecPtr;
- xl_heap_lock *xlrec = (xl_heap_lock *) XLogRecGetData(record);
- Buffer buffer;
- Page page;
- OffsetNumber offnum;
- ItemId lp = NULL;
- HeapTupleHeader htup;
-
- /*
- * The visibility map may need to be fixed even if the heap page is
- * already up-to-date.
- */
- if (xlrec->flags & XLH_LOCK_ALL_FROZEN_CLEARED)
- {
- RelFileLocator rlocator;
- Buffer vmbuffer = InvalidBuffer;
- BlockNumber block;
- Relation reln;
-
- XLogRecGetBlockTag(record, 0, &rlocator, NULL, &block);
- reln = CreateFakeRelcacheEntry(rlocator);
-
- visibilitymap_pin(reln, block, &vmbuffer);
- visibilitymap_clear(reln, block, vmbuffer, VISIBILITYMAP_ALL_FROZEN);
-
- ReleaseBuffer(vmbuffer);
- FreeFakeRelcacheEntry(reln);
- }
-
- if (XLogReadBufferForRedo(record, 0, &buffer) == BLK_NEEDS_REDO)
- {
- page = (Page) BufferGetPage(buffer);
-
- offnum = xlrec->offnum;
- if (PageGetMaxOffsetNumber(page) >= offnum)
- lp = PageGetItemId(page, offnum);
-
- if (PageGetMaxOffsetNumber(page) < offnum || !ItemIdIsNormal(lp))
- elog(PANIC, "invalid lp");
-
- htup = (HeapTupleHeader) PageGetItem(page, lp);
-
- htup->t_infomask &= ~(HEAP_XMAX_BITS | HEAP_MOVED);
- htup->t_infomask2 &= ~HEAP_KEYS_UPDATED;
- fix_infomask_from_infobits(xlrec->infobits_set, &htup->t_infomask,
- &htup->t_infomask2);
-
- /*
- * Clear relevant update flags, but only if the modified infomask says
- * there's no update.
- */
- if (HEAP_XMAX_IS_LOCKED_ONLY(htup->t_infomask))
- {
- HeapTupleHeaderClearHotUpdated(htup);
- /* Make sure there is no forward chain link in t_ctid */
- ItemPointerSet(&htup->t_ctid,
- BufferGetBlockNumber(buffer),
- offnum);
- }
- HeapTupleHeaderSetXmax(htup, xlrec->xmax);
- HeapTupleHeaderSetCmax(htup, FirstCommandId, false);
- PageSetLSN(page, lsn);
- MarkBufferDirty(buffer);
- }
- if (BufferIsValid(buffer))
- UnlockReleaseBuffer(buffer);
-}
-
-static void
-heap_xlog_lock_updated(XLogReaderState *record)
-{
- XLogRecPtr lsn = record->EndRecPtr;
- xl_heap_lock_updated *xlrec;
- Buffer buffer;
- Page page;
- OffsetNumber offnum;
- ItemId lp = NULL;
- HeapTupleHeader htup;
-
- xlrec = (xl_heap_lock_updated *) XLogRecGetData(record);
-
- /*
- * The visibility map may need to be fixed even if the heap page is
- * already up-to-date.
- */
- if (xlrec->flags & XLH_LOCK_ALL_FROZEN_CLEARED)
- {
- RelFileLocator rlocator;
- Buffer vmbuffer = InvalidBuffer;
- BlockNumber block;
- Relation reln;
-
- XLogRecGetBlockTag(record, 0, &rlocator, NULL, &block);
- reln = CreateFakeRelcacheEntry(rlocator);
-
- visibilitymap_pin(reln, block, &vmbuffer);
- visibilitymap_clear(reln, block, vmbuffer, VISIBILITYMAP_ALL_FROZEN);
-
- ReleaseBuffer(vmbuffer);
- FreeFakeRelcacheEntry(reln);
- }
-
- if (XLogReadBufferForRedo(record, 0, &buffer) == BLK_NEEDS_REDO)
- {
- page = BufferGetPage(buffer);
-
- offnum = xlrec->offnum;
- if (PageGetMaxOffsetNumber(page) >= offnum)
- lp = PageGetItemId(page, offnum);
-
- if (PageGetMaxOffsetNumber(page) < offnum || !ItemIdIsNormal(lp))
- elog(PANIC, "invalid lp");
-
- htup = (HeapTupleHeader) PageGetItem(page, lp);
-
- htup->t_infomask &= ~(HEAP_XMAX_BITS | HEAP_MOVED);
- htup->t_infomask2 &= ~HEAP_KEYS_UPDATED;
- fix_infomask_from_infobits(xlrec->infobits_set, &htup->t_infomask,
- &htup->t_infomask2);
- HeapTupleHeaderSetXmax(htup, xlrec->xmax);
-
- PageSetLSN(page, lsn);
- MarkBufferDirty(buffer);
- }
- if (BufferIsValid(buffer))
- UnlockReleaseBuffer(buffer);
-}
-
-static void
-heap_xlog_inplace(XLogReaderState *record)
-{
- XLogRecPtr lsn = record->EndRecPtr;
- xl_heap_inplace *xlrec = (xl_heap_inplace *) XLogRecGetData(record);
- Buffer buffer;
- Page page;
- OffsetNumber offnum;
- ItemId lp = NULL;
- HeapTupleHeader htup;
- uint32 oldlen;
- Size newlen;
-
- if (XLogReadBufferForRedo(record, 0, &buffer) == BLK_NEEDS_REDO)
- {
- char *newtup = XLogRecGetBlockData(record, 0, &newlen);
-
- page = BufferGetPage(buffer);
-
- offnum = xlrec->offnum;
- if (PageGetMaxOffsetNumber(page) >= offnum)
- lp = PageGetItemId(page, offnum);
-
- if (PageGetMaxOffsetNumber(page) < offnum || !ItemIdIsNormal(lp))
- elog(PANIC, "invalid lp");
-
- htup = (HeapTupleHeader) PageGetItem(page, lp);
-
- oldlen = ItemIdGetLength(lp) - htup->t_hoff;
- if (oldlen != newlen)
- elog(PANIC, "wrong tuple length");
-
- memcpy((char *) htup + htup->t_hoff, newtup, newlen);
-
- PageSetLSN(page, lsn);
- MarkBufferDirty(buffer);
- }
- if (BufferIsValid(buffer))
- UnlockReleaseBuffer(buffer);
-}
-
-void
-heap_redo(XLogReaderState *record)
-{
- uint8 info = XLogRecGetInfo(record) & ~XLR_INFO_MASK;
-
- /*
- * These operations don't overwrite MVCC data so no conflict processing is
- * required. The ones in heap2 rmgr do.
- */
-
- switch (info & XLOG_HEAP_OPMASK)
- {
- case XLOG_HEAP_INSERT:
- heap_xlog_insert(record);
- break;
- case XLOG_HEAP_DELETE:
- heap_xlog_delete(record);
- break;
- case XLOG_HEAP_UPDATE:
- heap_xlog_update(record, false);
- break;
- case XLOG_HEAP_TRUNCATE:
-
- /*
- * TRUNCATE is a no-op because the actions are already logged as
- * SMGR WAL records. TRUNCATE WAL record only exists for logical
- * decoding.
- */
- break;
- case XLOG_HEAP_HOT_UPDATE:
- heap_xlog_update(record, true);
- break;
- case XLOG_HEAP_CONFIRM:
- heap_xlog_confirm(record);
- break;
- case XLOG_HEAP_LOCK:
- heap_xlog_lock(record);
- break;
- case XLOG_HEAP_INPLACE:
- heap_xlog_inplace(record);
- break;
- default:
- elog(PANIC, "heap_redo: unknown op code %u", info);
- }
-}
-
-void
-heap2_redo(XLogReaderState *record)
-{
- uint8 info = XLogRecGetInfo(record) & ~XLR_INFO_MASK;
-
- switch (info & XLOG_HEAP_OPMASK)
- {
- case XLOG_HEAP2_PRUNE_ON_ACCESS:
- case XLOG_HEAP2_PRUNE_VACUUM_SCAN:
- case XLOG_HEAP2_PRUNE_VACUUM_CLEANUP:
- heap_xlog_prune_freeze(record);
- break;
- case XLOG_HEAP2_VISIBLE:
- heap_xlog_visible(record);
- break;
- case XLOG_HEAP2_MULTI_INSERT:
- heap_xlog_multi_insert(record);
- break;
- case XLOG_HEAP2_LOCK_UPDATED:
- heap_xlog_lock_updated(record);
- break;
- case XLOG_HEAP2_NEW_CID:
-
- /*
- * Nothing to do on a real replay, only used during logical
- * decoding.
- */
- break;
- case XLOG_HEAP2_REWRITE:
- heap_xlog_logical_rewrite(record);
- break;
- default:
- elog(PANIC, "heap2_redo: unknown op code %u", info);
- }
-}
-
-/*
- * Mask a heap page before performing consistency checks on it.
- */
-void
-heap_mask(char *pagedata, BlockNumber blkno)
-{
- Page page = (Page) pagedata;
- OffsetNumber off;
-
- mask_page_lsn_and_checksum(page);
-
- mask_page_hint_bits(page);
- mask_unused_space(page);
-
- for (off = 1; off <= PageGetMaxOffsetNumber(page); off++)
- {
- ItemId iid = PageGetItemId(page, off);
- char *page_item;
-
- page_item = (char *) (page + ItemIdGetOffset(iid));
-
- if (ItemIdIsNormal(iid))
- {
- HeapTupleHeader page_htup = (HeapTupleHeader) page_item;
-
- /*
- * If xmin of a tuple is not yet frozen, we should ignore
- * differences in hint bits, since they can be set without
- * emitting WAL.
- */
- if (!HeapTupleHeaderXminFrozen(page_htup))
- page_htup->t_infomask &= ~HEAP_XACT_MASK;
- else
- {
- /* Still we need to mask xmax hint bits. */
- page_htup->t_infomask &= ~HEAP_XMAX_INVALID;
- page_htup->t_infomask &= ~HEAP_XMAX_COMMITTED;
- }
-
- /*
- * During replay, we set Command Id to FirstCommandId. Hence, mask
- * it. See heap_xlog_insert() for details.
- */
- page_htup->t_choice.t_heap.t_field3.t_cid = MASK_MARKER;
-
- /*
- * For a speculative tuple, heap_insert() does not set ctid in the
- * caller-passed heap tuple itself, leaving the ctid field to
- * contain a speculative token value - a per-backend monotonically
- * increasing identifier. Besides, it does not WAL-log ctid under
- * any circumstances.
- *
- * During redo, heap_xlog_insert() sets t_ctid to current block
- * number and self offset number. It doesn't care about any
- * speculative insertions on the primary. Hence, we set t_ctid to
- * current block number and self offset number to ignore any
- * inconsistency.
- */
- if (HeapTupleHeaderIsSpeculative(page_htup))
- ItemPointerSet(&page_htup->t_ctid, blkno, off);
-
- /*
- * NB: Not ignoring ctid changes due to the tuple having moved
- * (i.e. HeapTupleHeaderIndicatesMovedPartitions), because that's
- * important information that needs to be in-sync between primary
- * and standby, and thus is WAL logged.
- */
- }
-
- /*
- * Ignore any padding bytes after the tuple, when the length of the
- * item is not MAXALIGNed.
- */
- if (ItemIdHasStorage(iid))
- {
- int len = ItemIdGetLength(iid);
- int padlen = MAXALIGN(len) - len;
-
- if (padlen > 0)
- memset(page_item + len, MASK_MARKER, padlen);
- }
- }
-}
-
/*
* HeapCheckForSerializableConflictOut
* We are reading a tuple. If it's not visible, there may be a
diff --git a/src/backend/access/heap/heapam_handler.c b/src/backend/access/heap/heapam_handler.c
index 6f8b1b79298f3..bcbac844bb669 100644
--- a/src/backend/access/heap/heapam_handler.c
+++ b/src/backend/access/heap/heapam_handler.c
@@ -3,7 +3,7 @@
* heapam_handler.c
* heap table access method code
*
- * Portions Copyright (c) 1996-2024, PostgreSQL Global Development Group
+ * Portions Copyright (c) 1996-2025, PostgreSQL Global Development Group
* Portions Copyright (c) 1994, Regents of the University of California
*
*
@@ -56,7 +56,9 @@ static bool SampleHeapTupleVisible(TableScanDesc scan, Buffer buffer,
static BlockNumber heapam_scan_get_blocks_done(HeapScanDesc hscan);
-static const TableAmRoutine heapam_methods;
+static bool BitmapHeapScanNextBlock(TableScanDesc scan,
+ bool *recheck,
+ uint64 *lossy_pages, uint64 *exact_pages);
/* ------------------------------------------------------------------------
@@ -457,12 +459,12 @@ heapam_tuple_lock(Relation relation, ItemPointer tid, Snapshot snapshot,
XLTW_FetchUpdated);
break;
case LockWaitSkip:
- if (!ConditionalXactLockTableWait(SnapshotDirty.xmax))
+ if (!ConditionalXactLockTableWait(SnapshotDirty.xmax, false))
/* skip instead of waiting */
return TM_WouldBlock;
break;
case LockWaitError:
- if (!ConditionalXactLockTableWait(SnapshotDirty.xmax))
+ if (!ConditionalXactLockTableWait(SnapshotDirty.xmax, log_lock_failures))
ereport(ERROR,
(errcode(ERRCODE_LOCK_NOT_AVAILABLE),
errmsg("could not obtain lock on row in relation \"%s\"",
@@ -607,14 +609,11 @@ heapam_relation_set_new_filelocator(Relation rel,
/*
* If required, set up an init fork for an unlogged table so that it can
- * be correctly reinitialized on restart. Recovery may remove it while
- * replaying, for example, an XLOG_DBASE_CREATE* or XLOG_TBLSPC_CREATE
- * record. Therefore, logging is necessary even if wal_level=minimal.
+ * be correctly reinitialized on restart.
*/
if (persistence == RELPERSISTENCE_UNLOGGED)
{
Assert(rel->rd_rel->relkind == RELKIND_RELATION ||
- rel->rd_rel->relkind == RELKIND_MATVIEW ||
rel->rd_rel->relkind == RELKIND_TOASTVALUE);
smgrcreate(srel, INIT_FORKNUM, false);
log_smgrcreate(newrlocator, INIT_FORKNUM);
@@ -754,7 +753,7 @@ heapam_relation_copy_for_cluster(Relation OldHeap, Relation NewHeap,
tableScan = NULL;
heapScan = NULL;
- indexScan = index_beginscan(OldHeap, OldIndex, SnapshotAny, 0, 0);
+ indexScan = index_beginscan(OldHeap, OldIndex, SnapshotAny, NULL, 0, 0);
index_rescan(indexScan, NULL, 0, NULL, 0);
}
else
@@ -2052,6 +2051,8 @@ heapam_relation_needs_toast_table(Relation rel)
if (att->attisdropped)
continue;
+ if (att->attgenerated == ATTRIBUTE_GENERATED_VIRTUAL)
+ continue;
data_length = att_align_nominal(data_length, att->attalign);
if (att->attlen > 0)
{
@@ -2118,165 +2119,32 @@ heapam_estimate_rel_size(Relation rel, int32 *attr_widths,
* ------------------------------------------------------------------------
*/
-static bool
-heapam_scan_bitmap_next_block(TableScanDesc scan,
- TBMIterateResult *tbmres)
-{
- HeapScanDesc hscan = (HeapScanDesc) scan;
- BlockNumber block = tbmres->blockno;
- Buffer buffer;
- Snapshot snapshot;
- int ntup;
-
- hscan->rs_cindex = 0;
- hscan->rs_ntuples = 0;
-
- /*
- * We can skip fetching the heap page if we don't need any fields from the
- * heap, the bitmap entries don't need rechecking, and all tuples on the
- * page are visible to our transaction.
- */
- if (!(scan->rs_flags & SO_NEED_TUPLES) &&
- !tbmres->recheck &&
- VM_ALL_VISIBLE(scan->rs_rd, tbmres->blockno, &hscan->rs_vmbuffer))
- {
- /* can't be lossy in the skip_fetch case */
- Assert(tbmres->ntuples >= 0);
- Assert(hscan->rs_empty_tuples_pending >= 0);
-
- hscan->rs_empty_tuples_pending += tbmres->ntuples;
-
- return true;
- }
-
- /*
- * Ignore any claimed entries past what we think is the end of the
- * relation. It may have been extended after the start of our scan (we
- * only hold an AccessShareLock, and it could be inserts from this
- * backend). We don't take this optimization in SERIALIZABLE isolation
- * though, as we need to examine all invisible tuples reachable by the
- * index.
- */
- if (!IsolationIsSerializable() && block >= hscan->rs_nblocks)
- return false;
-
- /*
- * Acquire pin on the target heap page, trading in any pin we held before.
- */
- hscan->rs_cbuf = ReleaseAndReadBuffer(hscan->rs_cbuf,
- scan->rs_rd,
- block);
- hscan->rs_cblock = block;
- buffer = hscan->rs_cbuf;
- snapshot = scan->rs_snapshot;
-
- ntup = 0;
-
- /*
- * Prune and repair fragmentation for the whole page, if possible.
- */
- heap_page_prune_opt(scan->rs_rd, buffer);
-
- /*
- * We must hold share lock on the buffer content while examining tuple
- * visibility. Afterwards, however, the tuples we have found to be
- * visible are guaranteed good as long as we hold the buffer pin.
- */
- LockBuffer(buffer, BUFFER_LOCK_SHARE);
-
- /*
- * We need two separate strategies for lossy and non-lossy cases.
- */
- if (tbmres->ntuples >= 0)
- {
- /*
- * Bitmap is non-lossy, so we just look through the offsets listed in
- * tbmres; but we have to follow any HOT chain starting at each such
- * offset.
- */
- int curslot;
-
- for (curslot = 0; curslot < tbmres->ntuples; curslot++)
- {
- OffsetNumber offnum = tbmres->offsets[curslot];
- ItemPointerData tid;
- HeapTupleData heapTuple;
-
- ItemPointerSet(&tid, block, offnum);
- if (heap_hot_search_buffer(&tid, scan->rs_rd, buffer, snapshot,
- &heapTuple, NULL, true))
- hscan->rs_vistuples[ntup++] = ItemPointerGetOffsetNumber(&tid);
- }
- }
- else
- {
- /*
- * Bitmap is lossy, so we must examine each line pointer on the page.
- * But we can ignore HOT chains, since we'll check each tuple anyway.
- */
- Page page = BufferGetPage(buffer);
- OffsetNumber maxoff = PageGetMaxOffsetNumber(page);
- OffsetNumber offnum;
-
- for (offnum = FirstOffsetNumber; offnum <= maxoff; offnum = OffsetNumberNext(offnum))
- {
- ItemId lp;
- HeapTupleData loctup;
- bool valid;
-
- lp = PageGetItemId(page, offnum);
- if (!ItemIdIsNormal(lp))
- continue;
- loctup.t_data = (HeapTupleHeader) PageGetItem(page, lp);
- loctup.t_len = ItemIdGetLength(lp);
- loctup.t_tableOid = scan->rs_rd->rd_id;
- ItemPointerSet(&loctup.t_self, block, offnum);
- valid = HeapTupleSatisfiesVisibility(&loctup, snapshot, buffer);
- if (valid)
- {
- hscan->rs_vistuples[ntup++] = offnum;
- PredicateLockTID(scan->rs_rd, &loctup.t_self, snapshot,
- HeapTupleHeaderGetXmin(loctup.t_data));
- }
- HeapCheckForSerializableConflictOut(valid, scan->rs_rd, &loctup,
- buffer, snapshot);
- }
- }
-
- LockBuffer(buffer, BUFFER_LOCK_UNLOCK);
-
- Assert(ntup <= MaxHeapTuplesPerPage);
- hscan->rs_ntuples = ntup;
-
- return ntup > 0;
-}
-
static bool
heapam_scan_bitmap_next_tuple(TableScanDesc scan,
- TBMIterateResult *tbmres,
- TupleTableSlot *slot)
+ TupleTableSlot *slot,
+ bool *recheck,
+ uint64 *lossy_pages,
+ uint64 *exact_pages)
{
- HeapScanDesc hscan = (HeapScanDesc) scan;
+ BitmapHeapScanDesc bscan = (BitmapHeapScanDesc) scan;
+ HeapScanDesc hscan = (HeapScanDesc) bscan;
OffsetNumber targoffset;
Page page;
ItemId lp;
- if (hscan->rs_empty_tuples_pending > 0)
+ /*
+ * Out of range? If so, nothing more to look at on this page
+ */
+ while (hscan->rs_cindex >= hscan->rs_ntuples)
{
/*
- * If we don't have to fetch the tuple, just return nulls.
+ * Returns false if the bitmap is exhausted and there are no further
+ * blocks we need to scan.
*/
- ExecStoreAllNullTuple(slot);
- hscan->rs_empty_tuples_pending--;
- return true;
+ if (!BitmapHeapScanNextBlock(scan, recheck, lossy_pages, exact_pages))
+ return false;
}
- /*
- * Out of range? If so, nothing more to look at on this page
- */
- if (hscan->rs_cindex < 0 || hscan->rs_cindex >= hscan->rs_ntuples)
- return false;
-
targoffset = hscan->rs_vistuples[hscan->rs_cindex];
page = BufferGetPage(hscan->rs_cbuf);
lp = PageGetItemId(page, targoffset);
@@ -2412,7 +2280,7 @@ heapam_scan_sample_next_tuple(TableScanDesc scan, SampleScanState *scanstate,
if (!pagemode)
LockBuffer(hscan->rs_cbuf, BUFFER_LOCK_SHARE);
- page = (Page) BufferGetPage(hscan->rs_cbuf);
+ page = BufferGetPage(hscan->rs_cbuf);
all_visible = PageIsAllVisible(page) &&
!scan->rs_snapshot->takenDuringRecovery;
maxoffset = PageGetMaxOffsetNumber(page);
@@ -2524,7 +2392,7 @@ reform_and_rewrite_tuple(HeapTuple tuple,
/* Be sure to null out any dropped columns */
for (i = 0; i < newTupDesc->natts; i++)
{
- if (TupleDescAttr(newTupDesc, i)->attisdropped)
+ if (TupleDescCompactAttr(newTupDesc, i)->attisdropped)
isnull[i] = true;
}
@@ -2548,6 +2416,9 @@ SampleHeapTupleVisible(TableScanDesc scan, Buffer buffer,
if (scan->rs_flags & SO_ALLOW_PAGEMODE)
{
+ uint32 start = 0,
+ end = hscan->rs_ntuples;
+
/*
* In pageatatime mode, heap_prepare_pagescan() already did visibility
* checks, so just look at the info it left in rs_vistuples[].
@@ -2557,18 +2428,15 @@ SampleHeapTupleVisible(TableScanDesc scan, Buffer buffer,
* in increasing order, but it's not clear that there would be enough
* gain to justify the restriction.
*/
- int start = 0,
- end = hscan->rs_ntuples - 1;
-
- while (start <= end)
+ while (start < end)
{
- int mid = (start + end) / 2;
+ uint32 mid = start + (end - start) / 2;
OffsetNumber curoffset = hscan->rs_vistuples[mid];
if (tupoffset == curoffset)
return true;
else if (tupoffset < curoffset)
- end = mid - 1;
+ end = mid;
else
start = mid + 1;
}
@@ -2583,6 +2451,162 @@ SampleHeapTupleVisible(TableScanDesc scan, Buffer buffer,
}
}
+/*
+ * Helper function get the next block of a bitmap heap scan. Returns true when
+ * it got the next block and saved it in the scan descriptor and false when
+ * the bitmap and or relation are exhausted.
+ */
+static bool
+BitmapHeapScanNextBlock(TableScanDesc scan,
+ bool *recheck,
+ uint64 *lossy_pages, uint64 *exact_pages)
+{
+ BitmapHeapScanDesc bscan = (BitmapHeapScanDesc) scan;
+ HeapScanDesc hscan = (HeapScanDesc) bscan;
+ BlockNumber block;
+ void *per_buffer_data;
+ Buffer buffer;
+ Snapshot snapshot;
+ int ntup;
+ TBMIterateResult *tbmres;
+ OffsetNumber offsets[TBM_MAX_TUPLES_PER_PAGE];
+ int noffsets = -1;
+
+ Assert(scan->rs_flags & SO_TYPE_BITMAPSCAN);
+ Assert(hscan->rs_read_stream);
+
+ hscan->rs_cindex = 0;
+ hscan->rs_ntuples = 0;
+
+ /* Release buffer containing previous block. */
+ if (BufferIsValid(hscan->rs_cbuf))
+ {
+ ReleaseBuffer(hscan->rs_cbuf);
+ hscan->rs_cbuf = InvalidBuffer;
+ }
+
+ hscan->rs_cbuf = read_stream_next_buffer(hscan->rs_read_stream,
+ &per_buffer_data);
+
+ if (BufferIsInvalid(hscan->rs_cbuf))
+ {
+ /* the bitmap is exhausted */
+ return false;
+ }
+
+ Assert(per_buffer_data);
+
+ tbmres = per_buffer_data;
+
+ Assert(BlockNumberIsValid(tbmres->blockno));
+ Assert(BufferGetBlockNumber(hscan->rs_cbuf) == tbmres->blockno);
+
+ /* Exact pages need their tuple offsets extracted. */
+ if (!tbmres->lossy)
+ noffsets = tbm_extract_page_tuple(tbmres, offsets,
+ TBM_MAX_TUPLES_PER_PAGE);
+
+ *recheck = tbmres->recheck;
+
+ block = hscan->rs_cblock = tbmres->blockno;
+ buffer = hscan->rs_cbuf;
+ snapshot = scan->rs_snapshot;
+
+ ntup = 0;
+
+ /*
+ * Prune and repair fragmentation for the whole page, if possible.
+ */
+ heap_page_prune_opt(scan->rs_rd, buffer);
+
+ /*
+ * We must hold share lock on the buffer content while examining tuple
+ * visibility. Afterwards, however, the tuples we have found to be
+ * visible are guaranteed good as long as we hold the buffer pin.
+ */
+ LockBuffer(buffer, BUFFER_LOCK_SHARE);
+
+ /*
+ * We need two separate strategies for lossy and non-lossy cases.
+ */
+ if (!tbmres->lossy)
+ {
+ /*
+ * Bitmap is non-lossy, so we just look through the offsets listed in
+ * tbmres; but we have to follow any HOT chain starting at each such
+ * offset.
+ */
+ int curslot;
+
+ /* We must have extracted the tuple offsets by now */
+ Assert(noffsets > -1);
+
+ for (curslot = 0; curslot < noffsets; curslot++)
+ {
+ OffsetNumber offnum = offsets[curslot];
+ ItemPointerData tid;
+ HeapTupleData heapTuple;
+
+ ItemPointerSet(&tid, block, offnum);
+ if (heap_hot_search_buffer(&tid, scan->rs_rd, buffer, snapshot,
+ &heapTuple, NULL, true))
+ hscan->rs_vistuples[ntup++] = ItemPointerGetOffsetNumber(&tid);
+ }
+ }
+ else
+ {
+ /*
+ * Bitmap is lossy, so we must examine each line pointer on the page.
+ * But we can ignore HOT chains, since we'll check each tuple anyway.
+ */
+ Page page = BufferGetPage(buffer);
+ OffsetNumber maxoff = PageGetMaxOffsetNumber(page);
+ OffsetNumber offnum;
+
+ for (offnum = FirstOffsetNumber; offnum <= maxoff; offnum = OffsetNumberNext(offnum))
+ {
+ ItemId lp;
+ HeapTupleData loctup;
+ bool valid;
+
+ lp = PageGetItemId(page, offnum);
+ if (!ItemIdIsNormal(lp))
+ continue;
+ loctup.t_data = (HeapTupleHeader) PageGetItem(page, lp);
+ loctup.t_len = ItemIdGetLength(lp);
+ loctup.t_tableOid = scan->rs_rd->rd_id;
+ ItemPointerSet(&loctup.t_self, block, offnum);
+ valid = HeapTupleSatisfiesVisibility(&loctup, snapshot, buffer);
+ if (valid)
+ {
+ hscan->rs_vistuples[ntup++] = offnum;
+ PredicateLockTID(scan->rs_rd, &loctup.t_self, snapshot,
+ HeapTupleHeaderGetXmin(loctup.t_data));
+ }
+ HeapCheckForSerializableConflictOut(valid, scan->rs_rd, &loctup,
+ buffer, snapshot);
+ }
+ }
+
+ LockBuffer(buffer, BUFFER_LOCK_UNLOCK);
+
+ Assert(ntup <= MaxHeapTuplesPerPage);
+ hscan->rs_ntuples = ntup;
+
+ if (tbmres->lossy)
+ (*lossy_pages)++;
+ else
+ (*exact_pages)++;
+
+ /*
+ * Return true to indicate that a valid block was found and the bitmap is
+ * not exhausted. If there are no visible tuples on this page,
+ * hscan->rs_ntuples will be 0 and heapam_scan_bitmap_next_tuple() will
+ * return false returning control to this function to advance to the next
+ * block in the bitmap.
+ */
+ return true;
+}
/* ------------------------------------------------------------------------
* Definition of the heap table access method.
@@ -2642,7 +2666,6 @@ static const TableAmRoutine heapam_methods = {
.relation_estimate_size = heapam_estimate_rel_size,
- .scan_bitmap_next_block = heapam_scan_bitmap_next_block,
.scan_bitmap_next_tuple = heapam_scan_bitmap_next_tuple,
.scan_sample_next_block = heapam_scan_sample_next_block,
.scan_sample_next_tuple = heapam_scan_sample_next_tuple
diff --git a/src/backend/access/heap/heapam_visibility.c b/src/backend/access/heap/heapam_visibility.c
index 9243feed01f9b..05f6946fe60d2 100644
--- a/src/backend/access/heap/heapam_visibility.c
+++ b/src/backend/access/heap/heapam_visibility.c
@@ -55,7 +55,7 @@
* HeapTupleSatisfiesAny()
* all tuples are visible
*
- * Portions Copyright (c) 1996-2024, PostgreSQL Global Development Group
+ * Portions Copyright (c) 1996-2025, PostgreSQL Global Development Group
* Portions Copyright (c) 1994, Regents of the University of California
*
* IDENTIFICATION
@@ -962,6 +962,15 @@ HeapTupleSatisfiesMVCC(HeapTuple htup, Snapshot snapshot,
{
HeapTupleHeader tuple = htup->t_data;
+ /*
+ * Assert that the caller has registered the snapshot. This function
+ * doesn't care about the registration as such, but in general you
+ * shouldn't try to use a snapshot without registration because it might
+ * get invalidated while it's still in use, and this is a convenient place
+ * to check for that.
+ */
+ Assert(snapshot->regd_count > 0 || snapshot->active_count > 0);
+
Assert(ItemPointerIsValid(&htup->t_self));
Assert(htup->t_tableOid != InvalidOid);
diff --git a/src/backend/access/heap/heapam_xlog.c b/src/backend/access/heap/heapam_xlog.c
new file mode 100644
index 0000000000000..cf843277938de
--- /dev/null
+++ b/src/backend/access/heap/heapam_xlog.c
@@ -0,0 +1,1343 @@
+/*-------------------------------------------------------------------------
+ *
+ * heapam_xlog.c
+ * WAL replay logic for heap access method.
+ *
+ * Portions Copyright (c) 1996-2025, PostgreSQL Global Development Group
+ * Portions Copyright (c) 1994, Regents of the University of California
+ *
+ *
+ * IDENTIFICATION
+ * src/backend/access/heap/heapam_xlog.c
+ *
+ *-------------------------------------------------------------------------
+ */
+#include "postgres.h"
+
+#include "access/bufmask.h"
+#include "access/heapam.h"
+#include "access/visibilitymap.h"
+#include "access/xlog.h"
+#include "access/xlogutils.h"
+#include "storage/freespace.h"
+#include "storage/standby.h"
+
+
+/*
+ * Replay XLOG_HEAP2_PRUNE_* records.
+ */
+static void
+heap_xlog_prune_freeze(XLogReaderState *record)
+{
+ XLogRecPtr lsn = record->EndRecPtr;
+ char *maindataptr = XLogRecGetData(record);
+ xl_heap_prune xlrec;
+ Buffer buffer;
+ RelFileLocator rlocator;
+ BlockNumber blkno;
+ XLogRedoAction action;
+
+ XLogRecGetBlockTag(record, 0, &rlocator, NULL, &blkno);
+ memcpy(&xlrec, maindataptr, SizeOfHeapPrune);
+ maindataptr += SizeOfHeapPrune;
+
+ /*
+ * We will take an ordinary exclusive lock or a cleanup lock depending on
+ * whether the XLHP_CLEANUP_LOCK flag is set. With an ordinary exclusive
+ * lock, we better not be doing anything that requires moving existing
+ * tuple data.
+ */
+ Assert((xlrec.flags & XLHP_CLEANUP_LOCK) != 0 ||
+ (xlrec.flags & (XLHP_HAS_REDIRECTIONS | XLHP_HAS_DEAD_ITEMS)) == 0);
+
+ /*
+ * We are about to remove and/or freeze tuples. In Hot Standby mode,
+ * ensure that there are no queries running for which the removed tuples
+ * are still visible or which still consider the frozen xids as running.
+ * The conflict horizon XID comes after xl_heap_prune.
+ */
+ if ((xlrec.flags & XLHP_HAS_CONFLICT_HORIZON) != 0)
+ {
+ TransactionId snapshot_conflict_horizon;
+
+ /* memcpy() because snapshot_conflict_horizon is stored unaligned */
+ memcpy(&snapshot_conflict_horizon, maindataptr, sizeof(TransactionId));
+ maindataptr += sizeof(TransactionId);
+
+ if (InHotStandby)
+ ResolveRecoveryConflictWithSnapshot(snapshot_conflict_horizon,
+ (xlrec.flags & XLHP_IS_CATALOG_REL) != 0,
+ rlocator);
+ }
+
+ /*
+ * If we have a full-page image, restore it and we're done.
+ */
+ action = XLogReadBufferForRedoExtended(record, 0, RBM_NORMAL,
+ (xlrec.flags & XLHP_CLEANUP_LOCK) != 0,
+ &buffer);
+ if (action == BLK_NEEDS_REDO)
+ {
+ Page page = BufferGetPage(buffer);
+ OffsetNumber *redirected;
+ OffsetNumber *nowdead;
+ OffsetNumber *nowunused;
+ int nredirected;
+ int ndead;
+ int nunused;
+ int nplans;
+ Size datalen;
+ xlhp_freeze_plan *plans;
+ OffsetNumber *frz_offsets;
+ char *dataptr = XLogRecGetBlockData(record, 0, &datalen);
+
+ heap_xlog_deserialize_prune_and_freeze(dataptr, xlrec.flags,
+ &nplans, &plans, &frz_offsets,
+ &nredirected, &redirected,
+ &ndead, &nowdead,
+ &nunused, &nowunused);
+
+ /*
+ * Update all line pointers per the record, and repair fragmentation
+ * if needed.
+ */
+ if (nredirected > 0 || ndead > 0 || nunused > 0)
+ heap_page_prune_execute(buffer,
+ (xlrec.flags & XLHP_CLEANUP_LOCK) == 0,
+ redirected, nredirected,
+ nowdead, ndead,
+ nowunused, nunused);
+
+ /* Freeze tuples */
+ for (int p = 0; p < nplans; p++)
+ {
+ HeapTupleFreeze frz;
+
+ /*
+ * Convert freeze plan representation from WAL record into
+ * per-tuple format used by heap_execute_freeze_tuple
+ */
+ frz.xmax = plans[p].xmax;
+ frz.t_infomask2 = plans[p].t_infomask2;
+ frz.t_infomask = plans[p].t_infomask;
+ frz.frzflags = plans[p].frzflags;
+ frz.offset = InvalidOffsetNumber; /* unused, but be tidy */
+
+ for (int i = 0; i < plans[p].ntuples; i++)
+ {
+ OffsetNumber offset = *(frz_offsets++);
+ ItemId lp;
+ HeapTupleHeader tuple;
+
+ lp = PageGetItemId(page, offset);
+ tuple = (HeapTupleHeader) PageGetItem(page, lp);
+ heap_execute_freeze_tuple(tuple, &frz);
+ }
+ }
+
+ /* There should be no more data */
+ Assert((char *) frz_offsets == dataptr + datalen);
+
+ /*
+ * Note: we don't worry about updating the page's prunability hints.
+ * At worst this will cause an extra prune cycle to occur soon.
+ */
+
+ PageSetLSN(page, lsn);
+ MarkBufferDirty(buffer);
+ }
+
+ /*
+ * If we released any space or line pointers, update the free space map.
+ *
+ * Do this regardless of a full-page image being applied, since the FSM
+ * data is not in the page anyway.
+ */
+ if (BufferIsValid(buffer))
+ {
+ if (xlrec.flags & (XLHP_HAS_REDIRECTIONS |
+ XLHP_HAS_DEAD_ITEMS |
+ XLHP_HAS_NOW_UNUSED_ITEMS))
+ {
+ Size freespace = PageGetHeapFreeSpace(BufferGetPage(buffer));
+
+ UnlockReleaseBuffer(buffer);
+
+ XLogRecordPageWithFreeSpace(rlocator, blkno, freespace);
+ }
+ else
+ UnlockReleaseBuffer(buffer);
+ }
+}
+
+/*
+ * Replay XLOG_HEAP2_VISIBLE records.
+ *
+ * The critical integrity requirement here is that we must never end up with
+ * a situation where the visibility map bit is set, and the page-level
+ * PD_ALL_VISIBLE bit is clear. If that were to occur, then a subsequent
+ * page modification would fail to clear the visibility map bit.
+ */
+static void
+heap_xlog_visible(XLogReaderState *record)
+{
+ XLogRecPtr lsn = record->EndRecPtr;
+ xl_heap_visible *xlrec = (xl_heap_visible *) XLogRecGetData(record);
+ Buffer vmbuffer = InvalidBuffer;
+ Buffer buffer;
+ Page page;
+ RelFileLocator rlocator;
+ BlockNumber blkno;
+ XLogRedoAction action;
+
+ Assert((xlrec->flags & VISIBILITYMAP_XLOG_VALID_BITS) == xlrec->flags);
+
+ XLogRecGetBlockTag(record, 1, &rlocator, NULL, &blkno);
+
+ /*
+ * If there are any Hot Standby transactions running that have an xmin
+ * horizon old enough that this page isn't all-visible for them, they
+ * might incorrectly decide that an index-only scan can skip a heap fetch.
+ *
+ * NB: It might be better to throw some kind of "soft" conflict here that
+ * forces any index-only scan that is in flight to perform heap fetches,
+ * rather than killing the transaction outright.
+ */
+ if (InHotStandby)
+ ResolveRecoveryConflictWithSnapshot(xlrec->snapshotConflictHorizon,
+ xlrec->flags & VISIBILITYMAP_XLOG_CATALOG_REL,
+ rlocator);
+
+ /*
+ * Read the heap page, if it still exists. If the heap file has dropped or
+ * truncated later in recovery, we don't need to update the page, but we'd
+ * better still update the visibility map.
+ */
+ action = XLogReadBufferForRedo(record, 1, &buffer);
+ if (action == BLK_NEEDS_REDO)
+ {
+ /*
+ * We don't bump the LSN of the heap page when setting the visibility
+ * map bit (unless checksums or wal_hint_bits is enabled, in which
+ * case we must). This exposes us to torn page hazards, but since
+ * we're not inspecting the existing page contents in any way, we
+ * don't care.
+ */
+ page = BufferGetPage(buffer);
+
+ PageSetAllVisible(page);
+
+ if (XLogHintBitIsNeeded())
+ PageSetLSN(page, lsn);
+
+ MarkBufferDirty(buffer);
+ }
+ else if (action == BLK_RESTORED)
+ {
+ /*
+ * If heap block was backed up, we already restored it and there's
+ * nothing more to do. (This can only happen with checksums or
+ * wal_log_hints enabled.)
+ */
+ }
+
+ if (BufferIsValid(buffer))
+ {
+ Size space = PageGetFreeSpace(BufferGetPage(buffer));
+
+ UnlockReleaseBuffer(buffer);
+
+ /*
+ * Since FSM is not WAL-logged and only updated heuristically, it
+ * easily becomes stale in standbys. If the standby is later promoted
+ * and runs VACUUM, it will skip updating individual free space
+ * figures for pages that became all-visible (or all-frozen, depending
+ * on the vacuum mode,) which is troublesome when FreeSpaceMapVacuum
+ * propagates too optimistic free space values to upper FSM layers;
+ * later inserters try to use such pages only to find out that they
+ * are unusable. This can cause long stalls when there are many such
+ * pages.
+ *
+ * Forestall those problems by updating FSM's idea about a page that
+ * is becoming all-visible or all-frozen.
+ *
+ * Do this regardless of a full-page image being applied, since the
+ * FSM data is not in the page anyway.
+ */
+ if (xlrec->flags & VISIBILITYMAP_VALID_BITS)
+ XLogRecordPageWithFreeSpace(rlocator, blkno, space);
+ }
+
+ /*
+ * Even if we skipped the heap page update due to the LSN interlock, it's
+ * still safe to update the visibility map. Any WAL record that clears
+ * the visibility map bit does so before checking the page LSN, so any
+ * bits that need to be cleared will still be cleared.
+ */
+ if (XLogReadBufferForRedoExtended(record, 0, RBM_ZERO_ON_ERROR, false,
+ &vmbuffer) == BLK_NEEDS_REDO)
+ {
+ Page vmpage = BufferGetPage(vmbuffer);
+ Relation reln;
+ uint8 vmbits;
+
+ /* initialize the page if it was read as zeros */
+ if (PageIsNew(vmpage))
+ PageInit(vmpage, BLCKSZ, 0);
+
+ /* remove VISIBILITYMAP_XLOG_* */
+ vmbits = xlrec->flags & VISIBILITYMAP_VALID_BITS;
+
+ /*
+ * XLogReadBufferForRedoExtended locked the buffer. But
+ * visibilitymap_set will handle locking itself.
+ */
+ LockBuffer(vmbuffer, BUFFER_LOCK_UNLOCK);
+
+ reln = CreateFakeRelcacheEntry(rlocator);
+
+ visibilitymap_set(reln, blkno, InvalidBuffer, lsn, vmbuffer,
+ xlrec->snapshotConflictHorizon, vmbits);
+
+ ReleaseBuffer(vmbuffer);
+ FreeFakeRelcacheEntry(reln);
+ }
+ else if (BufferIsValid(vmbuffer))
+ UnlockReleaseBuffer(vmbuffer);
+}
+
+/*
+ * Given an "infobits" field from an XLog record, set the correct bits in the
+ * given infomask and infomask2 for the tuple touched by the record.
+ *
+ * (This is the reverse of compute_infobits).
+ */
+static void
+fix_infomask_from_infobits(uint8 infobits, uint16 *infomask, uint16 *infomask2)
+{
+ *infomask &= ~(HEAP_XMAX_IS_MULTI | HEAP_XMAX_LOCK_ONLY |
+ HEAP_XMAX_KEYSHR_LOCK | HEAP_XMAX_EXCL_LOCK);
+ *infomask2 &= ~HEAP_KEYS_UPDATED;
+
+ if (infobits & XLHL_XMAX_IS_MULTI)
+ *infomask |= HEAP_XMAX_IS_MULTI;
+ if (infobits & XLHL_XMAX_LOCK_ONLY)
+ *infomask |= HEAP_XMAX_LOCK_ONLY;
+ if (infobits & XLHL_XMAX_EXCL_LOCK)
+ *infomask |= HEAP_XMAX_EXCL_LOCK;
+ /* note HEAP_XMAX_SHR_LOCK isn't considered here */
+ if (infobits & XLHL_XMAX_KEYSHR_LOCK)
+ *infomask |= HEAP_XMAX_KEYSHR_LOCK;
+
+ if (infobits & XLHL_KEYS_UPDATED)
+ *infomask2 |= HEAP_KEYS_UPDATED;
+}
+
+/*
+ * Replay XLOG_HEAP_DELETE records.
+ */
+static void
+heap_xlog_delete(XLogReaderState *record)
+{
+ XLogRecPtr lsn = record->EndRecPtr;
+ xl_heap_delete *xlrec = (xl_heap_delete *) XLogRecGetData(record);
+ Buffer buffer;
+ Page page;
+ ItemId lp = NULL;
+ HeapTupleHeader htup;
+ BlockNumber blkno;
+ RelFileLocator target_locator;
+ ItemPointerData target_tid;
+
+ XLogRecGetBlockTag(record, 0, &target_locator, NULL, &blkno);
+ ItemPointerSetBlockNumber(&target_tid, blkno);
+ ItemPointerSetOffsetNumber(&target_tid, xlrec->offnum);
+
+ /*
+ * The visibility map may need to be fixed even if the heap page is
+ * already up-to-date.
+ */
+ if (xlrec->flags & XLH_DELETE_ALL_VISIBLE_CLEARED)
+ {
+ Relation reln = CreateFakeRelcacheEntry(target_locator);
+ Buffer vmbuffer = InvalidBuffer;
+
+ visibilitymap_pin(reln, blkno, &vmbuffer);
+ visibilitymap_clear(reln, blkno, vmbuffer, VISIBILITYMAP_VALID_BITS);
+ ReleaseBuffer(vmbuffer);
+ FreeFakeRelcacheEntry(reln);
+ }
+
+ if (XLogReadBufferForRedo(record, 0, &buffer) == BLK_NEEDS_REDO)
+ {
+ page = BufferGetPage(buffer);
+
+ if (PageGetMaxOffsetNumber(page) >= xlrec->offnum)
+ lp = PageGetItemId(page, xlrec->offnum);
+
+ if (PageGetMaxOffsetNumber(page) < xlrec->offnum || !ItemIdIsNormal(lp))
+ elog(PANIC, "invalid lp");
+
+ htup = (HeapTupleHeader) PageGetItem(page, lp);
+
+ htup->t_infomask &= ~(HEAP_XMAX_BITS | HEAP_MOVED);
+ htup->t_infomask2 &= ~HEAP_KEYS_UPDATED;
+ HeapTupleHeaderClearHotUpdated(htup);
+ fix_infomask_from_infobits(xlrec->infobits_set,
+ &htup->t_infomask, &htup->t_infomask2);
+ if (!(xlrec->flags & XLH_DELETE_IS_SUPER))
+ HeapTupleHeaderSetXmax(htup, xlrec->xmax);
+ else
+ HeapTupleHeaderSetXmin(htup, InvalidTransactionId);
+ HeapTupleHeaderSetCmax(htup, FirstCommandId, false);
+
+ /* Mark the page as a candidate for pruning */
+ PageSetPrunable(page, XLogRecGetXid(record));
+
+ if (xlrec->flags & XLH_DELETE_ALL_VISIBLE_CLEARED)
+ PageClearAllVisible(page);
+
+ /* Make sure t_ctid is set correctly */
+ if (xlrec->flags & XLH_DELETE_IS_PARTITION_MOVE)
+ HeapTupleHeaderSetMovedPartitions(htup);
+ else
+ htup->t_ctid = target_tid;
+ PageSetLSN(page, lsn);
+ MarkBufferDirty(buffer);
+ }
+ if (BufferIsValid(buffer))
+ UnlockReleaseBuffer(buffer);
+}
+
+/*
+ * Replay XLOG_HEAP_INSERT records.
+ */
+static void
+heap_xlog_insert(XLogReaderState *record)
+{
+ XLogRecPtr lsn = record->EndRecPtr;
+ xl_heap_insert *xlrec = (xl_heap_insert *) XLogRecGetData(record);
+ Buffer buffer;
+ Page page;
+ union
+ {
+ HeapTupleHeaderData hdr;
+ char data[MaxHeapTupleSize];
+ } tbuf;
+ HeapTupleHeader htup;
+ xl_heap_header xlhdr;
+ uint32 newlen;
+ Size freespace = 0;
+ RelFileLocator target_locator;
+ BlockNumber blkno;
+ ItemPointerData target_tid;
+ XLogRedoAction action;
+
+ XLogRecGetBlockTag(record, 0, &target_locator, NULL, &blkno);
+ ItemPointerSetBlockNumber(&target_tid, blkno);
+ ItemPointerSetOffsetNumber(&target_tid, xlrec->offnum);
+
+ /* No freezing in the heap_insert() code path */
+ Assert(!(xlrec->flags & XLH_INSERT_ALL_FROZEN_SET));
+
+ /*
+ * The visibility map may need to be fixed even if the heap page is
+ * already up-to-date.
+ */
+ if (xlrec->flags & XLH_INSERT_ALL_VISIBLE_CLEARED)
+ {
+ Relation reln = CreateFakeRelcacheEntry(target_locator);
+ Buffer vmbuffer = InvalidBuffer;
+
+ visibilitymap_pin(reln, blkno, &vmbuffer);
+ visibilitymap_clear(reln, blkno, vmbuffer, VISIBILITYMAP_VALID_BITS);
+ ReleaseBuffer(vmbuffer);
+ FreeFakeRelcacheEntry(reln);
+ }
+
+ /*
+ * If we inserted the first and only tuple on the page, re-initialize the
+ * page from scratch.
+ */
+ if (XLogRecGetInfo(record) & XLOG_HEAP_INIT_PAGE)
+ {
+ buffer = XLogInitBufferForRedo(record, 0);
+ page = BufferGetPage(buffer);
+ PageInit(page, BufferGetPageSize(buffer), 0);
+ action = BLK_NEEDS_REDO;
+ }
+ else
+ action = XLogReadBufferForRedo(record, 0, &buffer);
+ if (action == BLK_NEEDS_REDO)
+ {
+ Size datalen;
+ char *data;
+
+ page = BufferGetPage(buffer);
+
+ if (PageGetMaxOffsetNumber(page) + 1 < xlrec->offnum)
+ elog(PANIC, "invalid max offset number");
+
+ data = XLogRecGetBlockData(record, 0, &datalen);
+
+ newlen = datalen - SizeOfHeapHeader;
+ Assert(datalen > SizeOfHeapHeader && newlen <= MaxHeapTupleSize);
+ memcpy(&xlhdr, data, SizeOfHeapHeader);
+ data += SizeOfHeapHeader;
+
+ htup = &tbuf.hdr;
+ MemSet(htup, 0, SizeofHeapTupleHeader);
+ /* PG73FORMAT: get bitmap [+ padding] [+ oid] + data */
+ memcpy((char *) htup + SizeofHeapTupleHeader,
+ data,
+ newlen);
+ newlen += SizeofHeapTupleHeader;
+ htup->t_infomask2 = xlhdr.t_infomask2;
+ htup->t_infomask = xlhdr.t_infomask;
+ htup->t_hoff = xlhdr.t_hoff;
+ HeapTupleHeaderSetXmin(htup, XLogRecGetXid(record));
+ HeapTupleHeaderSetCmin(htup, FirstCommandId);
+ htup->t_ctid = target_tid;
+
+ if (PageAddItem(page, (Item) htup, newlen, xlrec->offnum,
+ true, true) == InvalidOffsetNumber)
+ elog(PANIC, "failed to add tuple");
+
+ freespace = PageGetHeapFreeSpace(page); /* needed to update FSM below */
+
+ PageSetLSN(page, lsn);
+
+ if (xlrec->flags & XLH_INSERT_ALL_VISIBLE_CLEARED)
+ PageClearAllVisible(page);
+
+ MarkBufferDirty(buffer);
+ }
+ if (BufferIsValid(buffer))
+ UnlockReleaseBuffer(buffer);
+
+ /*
+ * If the page is running low on free space, update the FSM as well.
+ * Arbitrarily, our definition of "low" is less than 20%. We can't do much
+ * better than that without knowing the fill-factor for the table.
+ *
+ * XXX: Don't do this if the page was restored from full page image. We
+ * don't bother to update the FSM in that case, it doesn't need to be
+ * totally accurate anyway.
+ */
+ if (action == BLK_NEEDS_REDO && freespace < BLCKSZ / 5)
+ XLogRecordPageWithFreeSpace(target_locator, blkno, freespace);
+}
+
+/*
+ * Replay XLOG_HEAP2_MULTI_INSERT records.
+ */
+static void
+heap_xlog_multi_insert(XLogReaderState *record)
+{
+ XLogRecPtr lsn = record->EndRecPtr;
+ xl_heap_multi_insert *xlrec;
+ RelFileLocator rlocator;
+ BlockNumber blkno;
+ Buffer buffer;
+ Page page;
+ union
+ {
+ HeapTupleHeaderData hdr;
+ char data[MaxHeapTupleSize];
+ } tbuf;
+ HeapTupleHeader htup;
+ uint32 newlen;
+ Size freespace = 0;
+ int i;
+ bool isinit = (XLogRecGetInfo(record) & XLOG_HEAP_INIT_PAGE) != 0;
+ XLogRedoAction action;
+
+ /*
+ * Insertion doesn't overwrite MVCC data, so no conflict processing is
+ * required.
+ */
+ xlrec = (xl_heap_multi_insert *) XLogRecGetData(record);
+
+ XLogRecGetBlockTag(record, 0, &rlocator, NULL, &blkno);
+
+ /* check that the mutually exclusive flags are not both set */
+ Assert(!((xlrec->flags & XLH_INSERT_ALL_VISIBLE_CLEARED) &&
+ (xlrec->flags & XLH_INSERT_ALL_FROZEN_SET)));
+
+ /*
+ * The visibility map may need to be fixed even if the heap page is
+ * already up-to-date.
+ */
+ if (xlrec->flags & XLH_INSERT_ALL_VISIBLE_CLEARED)
+ {
+ Relation reln = CreateFakeRelcacheEntry(rlocator);
+ Buffer vmbuffer = InvalidBuffer;
+
+ visibilitymap_pin(reln, blkno, &vmbuffer);
+ visibilitymap_clear(reln, blkno, vmbuffer, VISIBILITYMAP_VALID_BITS);
+ ReleaseBuffer(vmbuffer);
+ FreeFakeRelcacheEntry(reln);
+ }
+
+ if (isinit)
+ {
+ buffer = XLogInitBufferForRedo(record, 0);
+ page = BufferGetPage(buffer);
+ PageInit(page, BufferGetPageSize(buffer), 0);
+ action = BLK_NEEDS_REDO;
+ }
+ else
+ action = XLogReadBufferForRedo(record, 0, &buffer);
+ if (action == BLK_NEEDS_REDO)
+ {
+ char *tupdata;
+ char *endptr;
+ Size len;
+
+ /* Tuples are stored as block data */
+ tupdata = XLogRecGetBlockData(record, 0, &len);
+ endptr = tupdata + len;
+
+ page = BufferGetPage(buffer);
+
+ for (i = 0; i < xlrec->ntuples; i++)
+ {
+ OffsetNumber offnum;
+ xl_multi_insert_tuple *xlhdr;
+
+ /*
+ * If we're reinitializing the page, the tuples are stored in
+ * order from FirstOffsetNumber. Otherwise there's an array of
+ * offsets in the WAL record, and the tuples come after that.
+ */
+ if (isinit)
+ offnum = FirstOffsetNumber + i;
+ else
+ offnum = xlrec->offsets[i];
+ if (PageGetMaxOffsetNumber(page) + 1 < offnum)
+ elog(PANIC, "invalid max offset number");
+
+ xlhdr = (xl_multi_insert_tuple *) SHORTALIGN(tupdata);
+ tupdata = ((char *) xlhdr) + SizeOfMultiInsertTuple;
+
+ newlen = xlhdr->datalen;
+ Assert(newlen <= MaxHeapTupleSize);
+ htup = &tbuf.hdr;
+ MemSet(htup, 0, SizeofHeapTupleHeader);
+ /* PG73FORMAT: get bitmap [+ padding] [+ oid] + data */
+ memcpy((char *) htup + SizeofHeapTupleHeader,
+ tupdata,
+ newlen);
+ tupdata += newlen;
+
+ newlen += SizeofHeapTupleHeader;
+ htup->t_infomask2 = xlhdr->t_infomask2;
+ htup->t_infomask = xlhdr->t_infomask;
+ htup->t_hoff = xlhdr->t_hoff;
+ HeapTupleHeaderSetXmin(htup, XLogRecGetXid(record));
+ HeapTupleHeaderSetCmin(htup, FirstCommandId);
+ ItemPointerSetBlockNumber(&htup->t_ctid, blkno);
+ ItemPointerSetOffsetNumber(&htup->t_ctid, offnum);
+
+ offnum = PageAddItem(page, (Item) htup, newlen, offnum, true, true);
+ if (offnum == InvalidOffsetNumber)
+ elog(PANIC, "failed to add tuple");
+ }
+ if (tupdata != endptr)
+ elog(PANIC, "total tuple length mismatch");
+
+ freespace = PageGetHeapFreeSpace(page); /* needed to update FSM below */
+
+ PageSetLSN(page, lsn);
+
+ if (xlrec->flags & XLH_INSERT_ALL_VISIBLE_CLEARED)
+ PageClearAllVisible(page);
+
+ /* XLH_INSERT_ALL_FROZEN_SET implies that all tuples are visible */
+ if (xlrec->flags & XLH_INSERT_ALL_FROZEN_SET)
+ PageSetAllVisible(page);
+
+ MarkBufferDirty(buffer);
+ }
+ if (BufferIsValid(buffer))
+ UnlockReleaseBuffer(buffer);
+
+ /*
+ * If the page is running low on free space, update the FSM as well.
+ * Arbitrarily, our definition of "low" is less than 20%. We can't do much
+ * better than that without knowing the fill-factor for the table.
+ *
+ * XXX: Don't do this if the page was restored from full page image. We
+ * don't bother to update the FSM in that case, it doesn't need to be
+ * totally accurate anyway.
+ */
+ if (action == BLK_NEEDS_REDO && freespace < BLCKSZ / 5)
+ XLogRecordPageWithFreeSpace(rlocator, blkno, freespace);
+}
+
+/*
+ * Replay XLOG_HEAP_UPDATE and XLOG_HEAP_HOT_UPDATE records.
+ */
+static void
+heap_xlog_update(XLogReaderState *record, bool hot_update)
+{
+ XLogRecPtr lsn = record->EndRecPtr;
+ xl_heap_update *xlrec = (xl_heap_update *) XLogRecGetData(record);
+ RelFileLocator rlocator;
+ BlockNumber oldblk;
+ BlockNumber newblk;
+ ItemPointerData newtid;
+ Buffer obuffer,
+ nbuffer;
+ Page page;
+ OffsetNumber offnum;
+ ItemId lp = NULL;
+ HeapTupleData oldtup;
+ HeapTupleHeader htup;
+ uint16 prefixlen = 0,
+ suffixlen = 0;
+ char *newp;
+ union
+ {
+ HeapTupleHeaderData hdr;
+ char data[MaxHeapTupleSize];
+ } tbuf;
+ xl_heap_header xlhdr;
+ uint32 newlen;
+ Size freespace = 0;
+ XLogRedoAction oldaction;
+ XLogRedoAction newaction;
+
+ /* initialize to keep the compiler quiet */
+ oldtup.t_data = NULL;
+ oldtup.t_len = 0;
+
+ XLogRecGetBlockTag(record, 0, &rlocator, NULL, &newblk);
+ if (XLogRecGetBlockTagExtended(record, 1, NULL, NULL, &oldblk, NULL))
+ {
+ /* HOT updates are never done across pages */
+ Assert(!hot_update);
+ }
+ else
+ oldblk = newblk;
+
+ ItemPointerSet(&newtid, newblk, xlrec->new_offnum);
+
+ /*
+ * The visibility map may need to be fixed even if the heap page is
+ * already up-to-date.
+ */
+ if (xlrec->flags & XLH_UPDATE_OLD_ALL_VISIBLE_CLEARED)
+ {
+ Relation reln = CreateFakeRelcacheEntry(rlocator);
+ Buffer vmbuffer = InvalidBuffer;
+
+ visibilitymap_pin(reln, oldblk, &vmbuffer);
+ visibilitymap_clear(reln, oldblk, vmbuffer, VISIBILITYMAP_VALID_BITS);
+ ReleaseBuffer(vmbuffer);
+ FreeFakeRelcacheEntry(reln);
+ }
+
+ /*
+ * In normal operation, it is important to lock the two pages in
+ * page-number order, to avoid possible deadlocks against other update
+ * operations going the other way. However, during WAL replay there can
+ * be no other update happening, so we don't need to worry about that. But
+ * we *do* need to worry that we don't expose an inconsistent state to Hot
+ * Standby queries --- so the original page can't be unlocked before we've
+ * added the new tuple to the new page.
+ */
+
+ /* Deal with old tuple version */
+ oldaction = XLogReadBufferForRedo(record, (oldblk == newblk) ? 0 : 1,
+ &obuffer);
+ if (oldaction == BLK_NEEDS_REDO)
+ {
+ page = BufferGetPage(obuffer);
+ offnum = xlrec->old_offnum;
+ if (PageGetMaxOffsetNumber(page) >= offnum)
+ lp = PageGetItemId(page, offnum);
+
+ if (PageGetMaxOffsetNumber(page) < offnum || !ItemIdIsNormal(lp))
+ elog(PANIC, "invalid lp");
+
+ htup = (HeapTupleHeader) PageGetItem(page, lp);
+
+ oldtup.t_data = htup;
+ oldtup.t_len = ItemIdGetLength(lp);
+
+ htup->t_infomask &= ~(HEAP_XMAX_BITS | HEAP_MOVED);
+ htup->t_infomask2 &= ~HEAP_KEYS_UPDATED;
+ if (hot_update)
+ HeapTupleHeaderSetHotUpdated(htup);
+ else
+ HeapTupleHeaderClearHotUpdated(htup);
+ fix_infomask_from_infobits(xlrec->old_infobits_set, &htup->t_infomask,
+ &htup->t_infomask2);
+ HeapTupleHeaderSetXmax(htup, xlrec->old_xmax);
+ HeapTupleHeaderSetCmax(htup, FirstCommandId, false);
+ /* Set forward chain link in t_ctid */
+ htup->t_ctid = newtid;
+
+ /* Mark the page as a candidate for pruning */
+ PageSetPrunable(page, XLogRecGetXid(record));
+
+ if (xlrec->flags & XLH_UPDATE_OLD_ALL_VISIBLE_CLEARED)
+ PageClearAllVisible(page);
+
+ PageSetLSN(page, lsn);
+ MarkBufferDirty(obuffer);
+ }
+
+ /*
+ * Read the page the new tuple goes into, if different from old.
+ */
+ if (oldblk == newblk)
+ {
+ nbuffer = obuffer;
+ newaction = oldaction;
+ }
+ else if (XLogRecGetInfo(record) & XLOG_HEAP_INIT_PAGE)
+ {
+ nbuffer = XLogInitBufferForRedo(record, 0);
+ page = BufferGetPage(nbuffer);
+ PageInit(page, BufferGetPageSize(nbuffer), 0);
+ newaction = BLK_NEEDS_REDO;
+ }
+ else
+ newaction = XLogReadBufferForRedo(record, 0, &nbuffer);
+
+ /*
+ * The visibility map may need to be fixed even if the heap page is
+ * already up-to-date.
+ */
+ if (xlrec->flags & XLH_UPDATE_NEW_ALL_VISIBLE_CLEARED)
+ {
+ Relation reln = CreateFakeRelcacheEntry(rlocator);
+ Buffer vmbuffer = InvalidBuffer;
+
+ visibilitymap_pin(reln, newblk, &vmbuffer);
+ visibilitymap_clear(reln, newblk, vmbuffer, VISIBILITYMAP_VALID_BITS);
+ ReleaseBuffer(vmbuffer);
+ FreeFakeRelcacheEntry(reln);
+ }
+
+ /* Deal with new tuple */
+ if (newaction == BLK_NEEDS_REDO)
+ {
+ char *recdata;
+ char *recdata_end;
+ Size datalen;
+ Size tuplen;
+
+ recdata = XLogRecGetBlockData(record, 0, &datalen);
+ recdata_end = recdata + datalen;
+
+ page = BufferGetPage(nbuffer);
+
+ offnum = xlrec->new_offnum;
+ if (PageGetMaxOffsetNumber(page) + 1 < offnum)
+ elog(PANIC, "invalid max offset number");
+
+ if (xlrec->flags & XLH_UPDATE_PREFIX_FROM_OLD)
+ {
+ Assert(newblk == oldblk);
+ memcpy(&prefixlen, recdata, sizeof(uint16));
+ recdata += sizeof(uint16);
+ }
+ if (xlrec->flags & XLH_UPDATE_SUFFIX_FROM_OLD)
+ {
+ Assert(newblk == oldblk);
+ memcpy(&suffixlen, recdata, sizeof(uint16));
+ recdata += sizeof(uint16);
+ }
+
+ memcpy(&xlhdr, recdata, SizeOfHeapHeader);
+ recdata += SizeOfHeapHeader;
+
+ tuplen = recdata_end - recdata;
+ Assert(tuplen <= MaxHeapTupleSize);
+
+ htup = &tbuf.hdr;
+ MemSet(htup, 0, SizeofHeapTupleHeader);
+
+ /*
+ * Reconstruct the new tuple using the prefix and/or suffix from the
+ * old tuple, and the data stored in the WAL record.
+ */
+ newp = (char *) htup + SizeofHeapTupleHeader;
+ if (prefixlen > 0)
+ {
+ int len;
+
+ /* copy bitmap [+ padding] [+ oid] from WAL record */
+ len = xlhdr.t_hoff - SizeofHeapTupleHeader;
+ memcpy(newp, recdata, len);
+ recdata += len;
+ newp += len;
+
+ /* copy prefix from old tuple */
+ memcpy(newp, (char *) oldtup.t_data + oldtup.t_data->t_hoff, prefixlen);
+ newp += prefixlen;
+
+ /* copy new tuple data from WAL record */
+ len = tuplen - (xlhdr.t_hoff - SizeofHeapTupleHeader);
+ memcpy(newp, recdata, len);
+ recdata += len;
+ newp += len;
+ }
+ else
+ {
+ /*
+ * copy bitmap [+ padding] [+ oid] + data from record, all in one
+ * go
+ */
+ memcpy(newp, recdata, tuplen);
+ recdata += tuplen;
+ newp += tuplen;
+ }
+ Assert(recdata == recdata_end);
+
+ /* copy suffix from old tuple */
+ if (suffixlen > 0)
+ memcpy(newp, (char *) oldtup.t_data + oldtup.t_len - suffixlen, suffixlen);
+
+ newlen = SizeofHeapTupleHeader + tuplen + prefixlen + suffixlen;
+ htup->t_infomask2 = xlhdr.t_infomask2;
+ htup->t_infomask = xlhdr.t_infomask;
+ htup->t_hoff = xlhdr.t_hoff;
+
+ HeapTupleHeaderSetXmin(htup, XLogRecGetXid(record));
+ HeapTupleHeaderSetCmin(htup, FirstCommandId);
+ HeapTupleHeaderSetXmax(htup, xlrec->new_xmax);
+ /* Make sure there is no forward chain link in t_ctid */
+ htup->t_ctid = newtid;
+
+ offnum = PageAddItem(page, (Item) htup, newlen, offnum, true, true);
+ if (offnum == InvalidOffsetNumber)
+ elog(PANIC, "failed to add tuple");
+
+ if (xlrec->flags & XLH_UPDATE_NEW_ALL_VISIBLE_CLEARED)
+ PageClearAllVisible(page);
+
+ freespace = PageGetHeapFreeSpace(page); /* needed to update FSM below */
+
+ PageSetLSN(page, lsn);
+ MarkBufferDirty(nbuffer);
+ }
+
+ if (BufferIsValid(nbuffer) && nbuffer != obuffer)
+ UnlockReleaseBuffer(nbuffer);
+ if (BufferIsValid(obuffer))
+ UnlockReleaseBuffer(obuffer);
+
+ /*
+ * If the new page is running low on free space, update the FSM as well.
+ * Arbitrarily, our definition of "low" is less than 20%. We can't do much
+ * better than that without knowing the fill-factor for the table.
+ *
+ * However, don't update the FSM on HOT updates, because after crash
+ * recovery, either the old or the new tuple will certainly be dead and
+ * prunable. After pruning, the page will have roughly as much free space
+ * as it did before the update, assuming the new tuple is about the same
+ * size as the old one.
+ *
+ * XXX: Don't do this if the page was restored from full page image. We
+ * don't bother to update the FSM in that case, it doesn't need to be
+ * totally accurate anyway.
+ */
+ if (newaction == BLK_NEEDS_REDO && !hot_update && freespace < BLCKSZ / 5)
+ XLogRecordPageWithFreeSpace(rlocator, newblk, freespace);
+}
+
+/*
+ * Replay XLOG_HEAP_CONFIRM records.
+ */
+static void
+heap_xlog_confirm(XLogReaderState *record)
+{
+ XLogRecPtr lsn = record->EndRecPtr;
+ xl_heap_confirm *xlrec = (xl_heap_confirm *) XLogRecGetData(record);
+ Buffer buffer;
+ Page page;
+ OffsetNumber offnum;
+ ItemId lp = NULL;
+ HeapTupleHeader htup;
+
+ if (XLogReadBufferForRedo(record, 0, &buffer) == BLK_NEEDS_REDO)
+ {
+ page = BufferGetPage(buffer);
+
+ offnum = xlrec->offnum;
+ if (PageGetMaxOffsetNumber(page) >= offnum)
+ lp = PageGetItemId(page, offnum);
+
+ if (PageGetMaxOffsetNumber(page) < offnum || !ItemIdIsNormal(lp))
+ elog(PANIC, "invalid lp");
+
+ htup = (HeapTupleHeader) PageGetItem(page, lp);
+
+ /*
+ * Confirm tuple as actually inserted
+ */
+ ItemPointerSet(&htup->t_ctid, BufferGetBlockNumber(buffer), offnum);
+
+ PageSetLSN(page, lsn);
+ MarkBufferDirty(buffer);
+ }
+ if (BufferIsValid(buffer))
+ UnlockReleaseBuffer(buffer);
+}
+
+/*
+ * Replay XLOG_HEAP_LOCK records.
+ */
+static void
+heap_xlog_lock(XLogReaderState *record)
+{
+ XLogRecPtr lsn = record->EndRecPtr;
+ xl_heap_lock *xlrec = (xl_heap_lock *) XLogRecGetData(record);
+ Buffer buffer;
+ Page page;
+ OffsetNumber offnum;
+ ItemId lp = NULL;
+ HeapTupleHeader htup;
+
+ /*
+ * The visibility map may need to be fixed even if the heap page is
+ * already up-to-date.
+ */
+ if (xlrec->flags & XLH_LOCK_ALL_FROZEN_CLEARED)
+ {
+ RelFileLocator rlocator;
+ Buffer vmbuffer = InvalidBuffer;
+ BlockNumber block;
+ Relation reln;
+
+ XLogRecGetBlockTag(record, 0, &rlocator, NULL, &block);
+ reln = CreateFakeRelcacheEntry(rlocator);
+
+ visibilitymap_pin(reln, block, &vmbuffer);
+ visibilitymap_clear(reln, block, vmbuffer, VISIBILITYMAP_ALL_FROZEN);
+
+ ReleaseBuffer(vmbuffer);
+ FreeFakeRelcacheEntry(reln);
+ }
+
+ if (XLogReadBufferForRedo(record, 0, &buffer) == BLK_NEEDS_REDO)
+ {
+ page = BufferGetPage(buffer);
+
+ offnum = xlrec->offnum;
+ if (PageGetMaxOffsetNumber(page) >= offnum)
+ lp = PageGetItemId(page, offnum);
+
+ if (PageGetMaxOffsetNumber(page) < offnum || !ItemIdIsNormal(lp))
+ elog(PANIC, "invalid lp");
+
+ htup = (HeapTupleHeader) PageGetItem(page, lp);
+
+ htup->t_infomask &= ~(HEAP_XMAX_BITS | HEAP_MOVED);
+ htup->t_infomask2 &= ~HEAP_KEYS_UPDATED;
+ fix_infomask_from_infobits(xlrec->infobits_set, &htup->t_infomask,
+ &htup->t_infomask2);
+
+ /*
+ * Clear relevant update flags, but only if the modified infomask says
+ * there's no update.
+ */
+ if (HEAP_XMAX_IS_LOCKED_ONLY(htup->t_infomask))
+ {
+ HeapTupleHeaderClearHotUpdated(htup);
+ /* Make sure there is no forward chain link in t_ctid */
+ ItemPointerSet(&htup->t_ctid,
+ BufferGetBlockNumber(buffer),
+ offnum);
+ }
+ HeapTupleHeaderSetXmax(htup, xlrec->xmax);
+ HeapTupleHeaderSetCmax(htup, FirstCommandId, false);
+ PageSetLSN(page, lsn);
+ MarkBufferDirty(buffer);
+ }
+ if (BufferIsValid(buffer))
+ UnlockReleaseBuffer(buffer);
+}
+
+/*
+ * Replay XLOG_HEAP2_LOCK_UPDATED records.
+ */
+static void
+heap_xlog_lock_updated(XLogReaderState *record)
+{
+ XLogRecPtr lsn = record->EndRecPtr;
+ xl_heap_lock_updated *xlrec;
+ Buffer buffer;
+ Page page;
+ OffsetNumber offnum;
+ ItemId lp = NULL;
+ HeapTupleHeader htup;
+
+ xlrec = (xl_heap_lock_updated *) XLogRecGetData(record);
+
+ /*
+ * The visibility map may need to be fixed even if the heap page is
+ * already up-to-date.
+ */
+ if (xlrec->flags & XLH_LOCK_ALL_FROZEN_CLEARED)
+ {
+ RelFileLocator rlocator;
+ Buffer vmbuffer = InvalidBuffer;
+ BlockNumber block;
+ Relation reln;
+
+ XLogRecGetBlockTag(record, 0, &rlocator, NULL, &block);
+ reln = CreateFakeRelcacheEntry(rlocator);
+
+ visibilitymap_pin(reln, block, &vmbuffer);
+ visibilitymap_clear(reln, block, vmbuffer, VISIBILITYMAP_ALL_FROZEN);
+
+ ReleaseBuffer(vmbuffer);
+ FreeFakeRelcacheEntry(reln);
+ }
+
+ if (XLogReadBufferForRedo(record, 0, &buffer) == BLK_NEEDS_REDO)
+ {
+ page = BufferGetPage(buffer);
+
+ offnum = xlrec->offnum;
+ if (PageGetMaxOffsetNumber(page) >= offnum)
+ lp = PageGetItemId(page, offnum);
+
+ if (PageGetMaxOffsetNumber(page) < offnum || !ItemIdIsNormal(lp))
+ elog(PANIC, "invalid lp");
+
+ htup = (HeapTupleHeader) PageGetItem(page, lp);
+
+ htup->t_infomask &= ~(HEAP_XMAX_BITS | HEAP_MOVED);
+ htup->t_infomask2 &= ~HEAP_KEYS_UPDATED;
+ fix_infomask_from_infobits(xlrec->infobits_set, &htup->t_infomask,
+ &htup->t_infomask2);
+ HeapTupleHeaderSetXmax(htup, xlrec->xmax);
+
+ PageSetLSN(page, lsn);
+ MarkBufferDirty(buffer);
+ }
+ if (BufferIsValid(buffer))
+ UnlockReleaseBuffer(buffer);
+}
+
+/*
+ * Replay XLOG_HEAP_INPLACE records.
+ */
+static void
+heap_xlog_inplace(XLogReaderState *record)
+{
+ XLogRecPtr lsn = record->EndRecPtr;
+ xl_heap_inplace *xlrec = (xl_heap_inplace *) XLogRecGetData(record);
+ Buffer buffer;
+ Page page;
+ OffsetNumber offnum;
+ ItemId lp = NULL;
+ HeapTupleHeader htup;
+ uint32 oldlen;
+ Size newlen;
+
+ if (XLogReadBufferForRedo(record, 0, &buffer) == BLK_NEEDS_REDO)
+ {
+ char *newtup = XLogRecGetBlockData(record, 0, &newlen);
+
+ page = BufferGetPage(buffer);
+
+ offnum = xlrec->offnum;
+ if (PageGetMaxOffsetNumber(page) >= offnum)
+ lp = PageGetItemId(page, offnum);
+
+ if (PageGetMaxOffsetNumber(page) < offnum || !ItemIdIsNormal(lp))
+ elog(PANIC, "invalid lp");
+
+ htup = (HeapTupleHeader) PageGetItem(page, lp);
+
+ oldlen = ItemIdGetLength(lp) - htup->t_hoff;
+ if (oldlen != newlen)
+ elog(PANIC, "wrong tuple length");
+
+ memcpy((char *) htup + htup->t_hoff, newtup, newlen);
+
+ PageSetLSN(page, lsn);
+ MarkBufferDirty(buffer);
+ }
+ if (BufferIsValid(buffer))
+ UnlockReleaseBuffer(buffer);
+
+ ProcessCommittedInvalidationMessages(xlrec->msgs,
+ xlrec->nmsgs,
+ xlrec->relcacheInitFileInval,
+ xlrec->dbId,
+ xlrec->tsId);
+}
+
+void
+heap_redo(XLogReaderState *record)
+{
+ uint8 info = XLogRecGetInfo(record) & ~XLR_INFO_MASK;
+
+ /*
+ * These operations don't overwrite MVCC data so no conflict processing is
+ * required. The ones in heap2 rmgr do.
+ */
+
+ switch (info & XLOG_HEAP_OPMASK)
+ {
+ case XLOG_HEAP_INSERT:
+ heap_xlog_insert(record);
+ break;
+ case XLOG_HEAP_DELETE:
+ heap_xlog_delete(record);
+ break;
+ case XLOG_HEAP_UPDATE:
+ heap_xlog_update(record, false);
+ break;
+ case XLOG_HEAP_TRUNCATE:
+
+ /*
+ * TRUNCATE is a no-op because the actions are already logged as
+ * SMGR WAL records. TRUNCATE WAL record only exists for logical
+ * decoding.
+ */
+ break;
+ case XLOG_HEAP_HOT_UPDATE:
+ heap_xlog_update(record, true);
+ break;
+ case XLOG_HEAP_CONFIRM:
+ heap_xlog_confirm(record);
+ break;
+ case XLOG_HEAP_LOCK:
+ heap_xlog_lock(record);
+ break;
+ case XLOG_HEAP_INPLACE:
+ heap_xlog_inplace(record);
+ break;
+ default:
+ elog(PANIC, "heap_redo: unknown op code %u", info);
+ }
+}
+
+void
+heap2_redo(XLogReaderState *record)
+{
+ uint8 info = XLogRecGetInfo(record) & ~XLR_INFO_MASK;
+
+ switch (info & XLOG_HEAP_OPMASK)
+ {
+ case XLOG_HEAP2_PRUNE_ON_ACCESS:
+ case XLOG_HEAP2_PRUNE_VACUUM_SCAN:
+ case XLOG_HEAP2_PRUNE_VACUUM_CLEANUP:
+ heap_xlog_prune_freeze(record);
+ break;
+ case XLOG_HEAP2_VISIBLE:
+ heap_xlog_visible(record);
+ break;
+ case XLOG_HEAP2_MULTI_INSERT:
+ heap_xlog_multi_insert(record);
+ break;
+ case XLOG_HEAP2_LOCK_UPDATED:
+ heap_xlog_lock_updated(record);
+ break;
+ case XLOG_HEAP2_NEW_CID:
+
+ /*
+ * Nothing to do on a real replay, only used during logical
+ * decoding.
+ */
+ break;
+ case XLOG_HEAP2_REWRITE:
+ heap_xlog_logical_rewrite(record);
+ break;
+ default:
+ elog(PANIC, "heap2_redo: unknown op code %u", info);
+ }
+}
+
+/*
+ * Mask a heap page before performing consistency checks on it.
+ */
+void
+heap_mask(char *pagedata, BlockNumber blkno)
+{
+ Page page = (Page) pagedata;
+ OffsetNumber off;
+
+ mask_page_lsn_and_checksum(page);
+
+ mask_page_hint_bits(page);
+ mask_unused_space(page);
+
+ for (off = 1; off <= PageGetMaxOffsetNumber(page); off++)
+ {
+ ItemId iid = PageGetItemId(page, off);
+ char *page_item;
+
+ page_item = (char *) (page + ItemIdGetOffset(iid));
+
+ if (ItemIdIsNormal(iid))
+ {
+ HeapTupleHeader page_htup = (HeapTupleHeader) page_item;
+
+ /*
+ * If xmin of a tuple is not yet frozen, we should ignore
+ * differences in hint bits, since they can be set without
+ * emitting WAL.
+ */
+ if (!HeapTupleHeaderXminFrozen(page_htup))
+ page_htup->t_infomask &= ~HEAP_XACT_MASK;
+ else
+ {
+ /* Still we need to mask xmax hint bits. */
+ page_htup->t_infomask &= ~HEAP_XMAX_INVALID;
+ page_htup->t_infomask &= ~HEAP_XMAX_COMMITTED;
+ }
+
+ /*
+ * During replay, we set Command Id to FirstCommandId. Hence, mask
+ * it. See heap_xlog_insert() for details.
+ */
+ page_htup->t_choice.t_heap.t_field3.t_cid = MASK_MARKER;
+
+ /*
+ * For a speculative tuple, heap_insert() does not set ctid in the
+ * caller-passed heap tuple itself, leaving the ctid field to
+ * contain a speculative token value - a per-backend monotonically
+ * increasing identifier. Besides, it does not WAL-log ctid under
+ * any circumstances.
+ *
+ * During redo, heap_xlog_insert() sets t_ctid to current block
+ * number and self offset number. It doesn't care about any
+ * speculative insertions on the primary. Hence, we set t_ctid to
+ * current block number and self offset number to ignore any
+ * inconsistency.
+ */
+ if (HeapTupleHeaderIsSpeculative(page_htup))
+ ItemPointerSet(&page_htup->t_ctid, blkno, off);
+
+ /*
+ * NB: Not ignoring ctid changes due to the tuple having moved
+ * (i.e. HeapTupleHeaderIndicatesMovedPartitions), because that's
+ * important information that needs to be in-sync between primary
+ * and standby, and thus is WAL logged.
+ */
+ }
+
+ /*
+ * Ignore any padding bytes after the tuple, when the length of the
+ * item is not MAXALIGNed.
+ */
+ if (ItemIdHasStorage(iid))
+ {
+ int len = ItemIdGetLength(iid);
+ int padlen = MAXALIGN(len) - len;
+
+ if (padlen > 0)
+ memset(page_item + len, MASK_MARKER, padlen);
+ }
+ }
+}
diff --git a/src/backend/access/heap/heaptoast.c b/src/backend/access/heap/heaptoast.c
index a420e1653046c..cb1e57030f64c 100644
--- a/src/backend/access/heap/heaptoast.c
+++ b/src/backend/access/heap/heaptoast.c
@@ -4,7 +4,7 @@
* Heap-specific definitions for external and compressed storage
* of variable size attributes.
*
- * Copyright (c) 2000-2024, PostgreSQL Global Development Group
+ * Copyright (c) 2000-2025, PostgreSQL Global Development Group
*
*
* IDENTIFICATION
@@ -369,7 +369,7 @@ toast_flatten_tuple(HeapTuple tup, TupleDesc tupleDesc)
/*
* Look at non-null varlena attributes
*/
- if (!toast_isnull[i] && TupleDescAttr(tupleDesc, i)->attlen == -1)
+ if (!toast_isnull[i] && TupleDescCompactAttr(tupleDesc, i)->attlen == -1)
{
struct varlena *new_value;
@@ -483,7 +483,7 @@ toast_flatten_tuple_to_datum(HeapTupleHeader tup,
*/
if (toast_isnull[i])
has_nulls = true;
- else if (TupleDescAttr(tupleDesc, i)->attlen == -1)
+ else if (TupleDescCompactAttr(tupleDesc, i)->attlen == -1)
{
struct varlena *new_value;
@@ -584,7 +584,7 @@ toast_build_flattened_tuple(TupleDesc tupleDesc,
/*
* Look at non-null varlena attributes
*/
- if (!isnull[i] && TupleDescAttr(tupleDesc, i)->attlen == -1)
+ if (!isnull[i] && TupleDescCompactAttr(tupleDesc, i)->attlen == -1)
{
struct varlena *new_value;
@@ -639,7 +639,6 @@ heap_fetch_toast_slice(Relation toastrel, Oid valueid, int32 attrsize,
int endchunk;
int num_indexes;
int validIndex;
- SnapshotData SnapshotToast;
/* Look for the valid index of toast relation */
validIndex = toast_open_indexes(toastrel,
@@ -685,9 +684,8 @@ heap_fetch_toast_slice(Relation toastrel, Oid valueid, int32 attrsize,
}
/* Prepare for scan */
- init_toast_snapshot(&SnapshotToast);
toastscan = systable_beginscan_ordered(toastrel, toastidxs[validIndex],
- &SnapshotToast, nscankeys, toastkey);
+ get_toast_snapshot(), nscankeys, toastkey);
/*
* Read the chunks by index
diff --git a/src/backend/access/heap/hio.c b/src/backend/access/heap/hio.c
index 7c662cdf46ecf..c482c9d61b265 100644
--- a/src/backend/access/heap/hio.c
+++ b/src/backend/access/heap/hio.c
@@ -3,7 +3,7 @@
* hio.c
* POSTGRES heap access method input/output code.
*
- * Portions Copyright (c) 1996-2024, PostgreSQL Global Development Group
+ * Portions Copyright (c) 1996-2025, PostgreSQL Global Development Group
* Portions Copyright (c) 1994, Regents of the University of California
*
*
diff --git a/src/backend/access/heap/meson.build b/src/backend/access/heap/meson.build
index e00d5b4f0de2d..2637b24112fba 100644
--- a/src/backend/access/heap/meson.build
+++ b/src/backend/access/heap/meson.build
@@ -1,9 +1,10 @@
-# Copyright (c) 2022-2024, PostgreSQL Global Development Group
+# Copyright (c) 2022-2025, PostgreSQL Global Development Group
backend_sources += files(
'heapam.c',
'heapam_handler.c',
'heapam_visibility.c',
+ 'heapam_xlog.c',
'heaptoast.c',
'hio.c',
'pruneheap.c',
diff --git a/src/backend/access/heap/pruneheap.c b/src/backend/access/heap/pruneheap.c
index 3cdfc5b7f1bfa..7ebd22f00a370 100644
--- a/src/backend/access/heap/pruneheap.c
+++ b/src/backend/access/heap/pruneheap.c
@@ -3,7 +3,7 @@
* pruneheap.c
* heap page pruning and HOT-chain management code
*
- * Portions Copyright (c) 1996-2024, PostgreSQL Global Development Group
+ * Portions Copyright (c) 1996-2025, PostgreSQL Global Development Group
* Portions Copyright (c) 1994, Regents of the University of California
*
*
@@ -325,6 +325,8 @@ heap_page_prune_opt(Relation relation, Buffer buffer)
*
* cutoffs contains the freeze cutoffs, established by VACUUM at the beginning
* of vacuuming the relation. Required if HEAP_PRUNE_FREEZE option is set.
+ * cutoffs->OldestXmin is also used to determine if dead tuples are
+ * HEAPTUPLE_RECENTLY_DEAD or HEAPTUPLE_DEAD.
*
* presult contains output parameters needed by callers, such as the number of
* tuples removed and the offsets of dead items on the page after pruning.
@@ -922,8 +924,27 @@ heap_prune_satisfies_vacuum(PruneState *prstate, HeapTuple tup, Buffer buffer)
if (res != HEAPTUPLE_RECENTLY_DEAD)
return res;
+ /*
+ * For VACUUM, we must be sure to prune tuples with xmax older than
+ * OldestXmin -- a visibility cutoff determined at the beginning of
+ * vacuuming the relation. OldestXmin is used for freezing determination
+ * and we cannot freeze dead tuples' xmaxes.
+ */
+ if (prstate->cutoffs &&
+ TransactionIdIsValid(prstate->cutoffs->OldestXmin) &&
+ NormalTransactionIdPrecedes(dead_after, prstate->cutoffs->OldestXmin))
+ return HEAPTUPLE_DEAD;
+
+ /*
+ * Determine whether or not the tuple is considered dead when compared
+ * with the provided GlobalVisState. On-access pruning does not provide
+ * VacuumCutoffs. And for vacuum, even if the tuple's xmax is not older
+ * than OldestXmin, GlobalVisTestIsRemovableXid() could find the row dead
+ * if the GlobalVisState has been updated since the beginning of vacuuming
+ * the relation.
+ */
if (GlobalVisTestIsRemovableXid(prstate->vistest, dead_after))
- res = HEAPTUPLE_DEAD;
+ return HEAPTUPLE_DEAD;
return res;
}
@@ -1542,7 +1563,7 @@ heap_page_prune_execute(Buffer buffer, bool lp_truncate_only,
OffsetNumber *nowdead, int ndead,
OffsetNumber *nowunused, int nunused)
{
- Page page = (Page) BufferGetPage(buffer);
+ Page page = BufferGetPage(buffer);
OffsetNumber *offnum;
HeapTupleHeader htup PG_USED_FOR_ASSERTS_ONLY;
@@ -1885,7 +1906,7 @@ heap_log_freeze_eq(xlhp_freeze_plan *plan, HeapTupleFreeze *frz)
}
/*
- * Comparator used to deduplicate XLOG_HEAP2_FREEZE_PAGE freeze plans
+ * Comparator used to deduplicate the freeze plans used in WAL records.
*/
static int
heap_log_freeze_cmp(const void *arg1, const void *arg2)
@@ -1945,7 +1966,7 @@ heap_log_freeze_new_plan(xlhp_freeze_plan *plan, HeapTupleFreeze *frz)
/*
* Deduplicate tuple-based freeze plans so that each distinct set of
- * processing steps is only stored once in XLOG_HEAP2_FREEZE_PAGE records.
+ * processing steps is only stored once in the WAL record.
* Called during original execution of freezing (for logged relations).
*
* Return value is number of plans set in *plans_out for caller. Also writes
@@ -2072,9 +2093,9 @@ log_heap_prune_and_freeze(Relation relation, Buffer buffer,
nplans = heap_log_freeze_plan(frozen, nfrozen, plans, frz_offsets);
freeze_plans.nplans = nplans;
- XLogRegisterBufData(0, (char *) &freeze_plans,
+ XLogRegisterBufData(0, &freeze_plans,
offsetof(xlhp_freeze_plans, plans));
- XLogRegisterBufData(0, (char *) plans,
+ XLogRegisterBufData(0, plans,
sizeof(xlhp_freeze_plan) * nplans);
}
if (nredirected > 0)
@@ -2082,9 +2103,9 @@ log_heap_prune_and_freeze(Relation relation, Buffer buffer,
xlrec.flags |= XLHP_HAS_REDIRECTIONS;
redirect_items.ntargets = nredirected;
- XLogRegisterBufData(0, (char *) &redirect_items,
+ XLogRegisterBufData(0, &redirect_items,
offsetof(xlhp_prune_items, data));
- XLogRegisterBufData(0, (char *) redirected,
+ XLogRegisterBufData(0, redirected,
sizeof(OffsetNumber[2]) * nredirected);
}
if (ndead > 0)
@@ -2092,9 +2113,9 @@ log_heap_prune_and_freeze(Relation relation, Buffer buffer,
xlrec.flags |= XLHP_HAS_DEAD_ITEMS;
dead_items.ntargets = ndead;
- XLogRegisterBufData(0, (char *) &dead_items,
+ XLogRegisterBufData(0, &dead_items,
offsetof(xlhp_prune_items, data));
- XLogRegisterBufData(0, (char *) dead,
+ XLogRegisterBufData(0, dead,
sizeof(OffsetNumber) * ndead);
}
if (nunused > 0)
@@ -2102,17 +2123,17 @@ log_heap_prune_and_freeze(Relation relation, Buffer buffer,
xlrec.flags |= XLHP_HAS_NOW_UNUSED_ITEMS;
unused_items.ntargets = nunused;
- XLogRegisterBufData(0, (char *) &unused_items,
+ XLogRegisterBufData(0, &unused_items,
offsetof(xlhp_prune_items, data));
- XLogRegisterBufData(0, (char *) unused,
+ XLogRegisterBufData(0, unused,
sizeof(OffsetNumber) * nunused);
}
if (nfrozen > 0)
- XLogRegisterBufData(0, (char *) frz_offsets,
+ XLogRegisterBufData(0, frz_offsets,
sizeof(OffsetNumber) * nfrozen);
/*
- * Prepare the main xl_heap_prune record. We already set the XLPH_HAS_*
+ * Prepare the main xl_heap_prune record. We already set the XLHP_HAS_*
* flag above.
*/
if (RelationIsAccessibleInLogicalDecoding(relation))
@@ -2126,9 +2147,9 @@ log_heap_prune_and_freeze(Relation relation, Buffer buffer,
Assert(nredirected == 0 && ndead == 0);
/* also, any items in 'unused' must've been LP_DEAD previously */
}
- XLogRegisterData((char *) &xlrec, SizeOfHeapPrune);
+ XLogRegisterData(&xlrec, SizeOfHeapPrune);
if (TransactionIdIsValid(conflict_xid))
- XLogRegisterData((char *) &conflict_xid, sizeof(TransactionId));
+ XLogRegisterData(&conflict_xid, sizeof(TransactionId));
switch (reason)
{
diff --git a/src/backend/access/heap/rewriteheap.c b/src/backend/access/heap/rewriteheap.c
index 473f3aa9bef9e..e6d2b5fced198 100644
--- a/src/backend/access/heap/rewriteheap.c
+++ b/src/backend/access/heap/rewriteheap.c
@@ -92,7 +92,7 @@
* heap's TOAST table will go through the normal bufmgr.
*
*
- * Portions Copyright (c) 1996-2024, PostgreSQL Global Development Group
+ * Portions Copyright (c) 1996-2025, PostgreSQL Global Development Group
* Portions Copyright (c) 1994-5, Regents of the University of California
*
* IDENTIFICATION
@@ -887,7 +887,7 @@ logical_heap_rewrite_flush_mappings(RewriteState state)
src->off += len;
XLogBeginInsert();
- XLogRegisterData((char *) (&xlrec), sizeof(xlrec));
+ XLogRegisterData(&xlrec, sizeof(xlrec));
XLogRegisterData(waldata_start, len);
/* write xlog record */
@@ -961,8 +961,8 @@ logical_rewrite_log_mapping(RewriteState state, TransactionId xid,
dboid = MyDatabaseId;
snprintf(path, MAXPGPATH,
- "pg_logical/mappings/" LOGICAL_REWRITE_FORMAT,
- dboid, relid,
+ "%s/" LOGICAL_REWRITE_FORMAT,
+ PG_LOGICAL_MAPPINGS_DIR, dboid, relid,
LSN_FORMAT_ARGS(state->rs_begin_lsn),
xid, GetCurrentTransactionId());
@@ -1081,8 +1081,8 @@ heap_xlog_logical_rewrite(XLogReaderState *r)
xlrec = (xl_heap_rewrite_mapping *) XLogRecGetData(r);
snprintf(path, MAXPGPATH,
- "pg_logical/mappings/" LOGICAL_REWRITE_FORMAT,
- xlrec->mapped_db, xlrec->mapped_rel,
+ "%s/" LOGICAL_REWRITE_FORMAT,
+ PG_LOGICAL_MAPPINGS_DIR, xlrec->mapped_db, xlrec->mapped_rel,
LSN_FORMAT_ARGS(xlrec->start_lsn),
xlrec->mapped_xid, XLogRecGetXid(r));
@@ -1158,7 +1158,7 @@ CheckPointLogicalRewriteHeap(void)
XLogRecPtr redo;
DIR *mappings_dir;
struct dirent *mapping_de;
- char path[MAXPGPATH + 20];
+ char path[MAXPGPATH + sizeof(PG_LOGICAL_MAPPINGS_DIR)];
/*
* We start of with a minimum of the last redo pointer. No new decoding
@@ -1173,8 +1173,8 @@ CheckPointLogicalRewriteHeap(void)
if (cutoff != InvalidXLogRecPtr && redo < cutoff)
cutoff = redo;
- mappings_dir = AllocateDir("pg_logical/mappings");
- while ((mapping_de = ReadDir(mappings_dir, "pg_logical/mappings")) != NULL)
+ mappings_dir = AllocateDir(PG_LOGICAL_MAPPINGS_DIR);
+ while ((mapping_de = ReadDir(mappings_dir, PG_LOGICAL_MAPPINGS_DIR)) != NULL)
{
Oid dboid;
Oid relid;
@@ -1189,7 +1189,7 @@ CheckPointLogicalRewriteHeap(void)
strcmp(mapping_de->d_name, "..") == 0)
continue;
- snprintf(path, sizeof(path), "pg_logical/mappings/%s", mapping_de->d_name);
+ snprintf(path, sizeof(path), "%s/%s", PG_LOGICAL_MAPPINGS_DIR, mapping_de->d_name);
de_type = get_dirent_type(path, mapping_de, false, DEBUG1);
if (de_type != PGFILETYPE_ERROR && de_type != PGFILETYPE_REG)
@@ -1249,5 +1249,5 @@ CheckPointLogicalRewriteHeap(void)
FreeDir(mappings_dir);
/* persist directory entries to disk */
- fsync_fname("pg_logical/mappings", true);
+ fsync_fname(PG_LOGICAL_MAPPINGS_DIR, true);
}
diff --git a/src/backend/access/heap/vacuumlazy.c b/src/backend/access/heap/vacuumlazy.c
index 8145ea8fc3f57..981d9380a925c 100644
--- a/src/backend/access/heap/vacuumlazy.c
+++ b/src/backend/access/heap/vacuumlazy.c
@@ -3,6 +3,104 @@
* vacuumlazy.c
* Concurrent ("lazy") vacuuming.
*
+ * Heap relations are vacuumed in three main phases. In phase I, vacuum scans
+ * relation pages, pruning and freezing tuples and saving dead tuples' TIDs in
+ * a TID store. If that TID store fills up or vacuum finishes scanning the
+ * relation, it progresses to phase II: index vacuuming. Index vacuuming
+ * deletes the dead index entries referenced in the TID store. In phase III,
+ * vacuum scans the blocks of the relation referred to by the TIDs in the TID
+ * store and reaps the corresponding dead items, freeing that space for future
+ * tuples.
+ *
+ * If there are no indexes or index scanning is disabled, phase II may be
+ * skipped. If phase I identified very few dead index entries or if vacuum's
+ * failsafe mechanism has triggered (to avoid transaction ID wraparound),
+ * vacuum may skip phases II and III.
+ *
+ * If the TID store fills up in phase I, vacuum suspends phase I and proceeds
+ * to phases II and III, cleaning up the dead tuples referenced in the current
+ * TID store. This empties the TID store, allowing vacuum to resume phase I.
+ *
+ * In a way, the phases are more like states in a state machine, but they have
+ * been referred to colloquially as phases for so long that they are referred
+ * to as such here.
+ *
+ * Manually invoked VACUUMs may scan indexes during phase II in parallel. For
+ * more information on this, see the comment at the top of vacuumparallel.c.
+ *
+ * In between phases, vacuum updates the freespace map (every
+ * VACUUM_FSM_EVERY_PAGES).
+ *
+ * After completing all three phases, vacuum may truncate the relation if it
+ * has emptied pages at the end. Finally, vacuum updates relation statistics
+ * in pg_class and the cumulative statistics subsystem.
+ *
+ * Relation Scanning:
+ *
+ * Vacuum scans the heap relation, starting at the beginning and progressing
+ * to the end, skipping pages as permitted by their visibility status, vacuum
+ * options, and various other requirements.
+ *
+ * Vacuums are either aggressive or normal. Aggressive vacuums must scan every
+ * unfrozen tuple in order to advance relfrozenxid and avoid transaction ID
+ * wraparound. Normal vacuums may scan otherwise skippable pages for one of
+ * two reasons:
+ *
+ * When page skipping is not disabled, a normal vacuum may scan pages that are
+ * marked all-visible (and even all-frozen) in the visibility map if the range
+ * of skippable pages is below SKIP_PAGES_THRESHOLD. This is primarily for the
+ * benefit of kernel readahead (see comment in heap_vac_scan_next_block()).
+ *
+ * A normal vacuum may also scan skippable pages in an effort to freeze them
+ * and decrease the backlog of all-visible but not all-frozen pages that have
+ * to be processed by the next aggressive vacuum. These are referred to as
+ * eagerly scanned pages. Pages scanned due to SKIP_PAGES_THRESHOLD do not
+ * count as eagerly scanned pages.
+ *
+ * Eagerly scanned pages that are set all-frozen in the VM are successful
+ * eager freezes and those not set all-frozen in the VM are failed eager
+ * freezes.
+ *
+ * Because we want to amortize the overhead of freezing pages over multiple
+ * vacuums, normal vacuums cap the number of successful eager freezes to
+ * MAX_EAGER_FREEZE_SUCCESS_RATE of the number of all-visible but not
+ * all-frozen pages at the beginning of the vacuum. Since eagerly frozen pages
+ * may be unfrozen before the next aggressive vacuum, capping the number of
+ * successful eager freezes also caps the downside of eager freezing:
+ * potentially wasted work.
+ *
+ * Once the success cap has been hit, eager scanning is disabled for the
+ * remainder of the vacuum of the relation.
+ *
+ * Success is capped globally because we don't want to limit our successes if
+ * old data happens to be concentrated in a particular part of the table. This
+ * is especially likely to happen for append-mostly workloads where the oldest
+ * data is at the beginning of the unfrozen portion of the relation.
+ *
+ * On the assumption that different regions of the table are likely to contain
+ * similarly aged data, normal vacuums use a localized eager freeze failure
+ * cap. The failure count is reset for each region of the table -- comprised
+ * of EAGER_SCAN_REGION_SIZE blocks. In each region, we tolerate
+ * vacuum_max_eager_freeze_failure_rate of EAGER_SCAN_REGION_SIZE failures
+ * before suspending eager scanning until the end of the region.
+ * vacuum_max_eager_freeze_failure_rate is configurable both globally and per
+ * table.
+ *
+ * Aggressive vacuums must examine every unfrozen tuple and thus are not
+ * subject to any of the limits imposed by the eager scanning algorithm.
+ *
+ * Once vacuum has decided to scan a given block, it must read the block and
+ * obtain a cleanup lock to prune tuples on the page. A non-aggressive vacuum
+ * may choose to skip pruning and freezing if it cannot acquire a cleanup lock
+ * on the buffer right away. In this case, it may miss cleaning up dead tuples
+ * and their associated index entries (though it is free to reap any existing
+ * dead items on the page).
+ *
+ * After pruning and freezing, pages that are newly all-visible and all-frozen
+ * are marked as such in the visibility map.
+ *
+ * Dead TID Storage:
+ *
* The major space usage for vacuuming is storage for the dead tuple IDs that
* are to be removed from indexes. We want to ensure we can vacuum even the
* very largest relations with finite memory space usage. To do that, we set
@@ -20,7 +118,7 @@
* that there only needs to be one call to lazy_vacuum, after the initial pass
* completes.
*
- * Portions Copyright (c) 1996-2024, PostgreSQL Global Development Group
+ * Portions Copyright (c) 1996-2025, PostgreSQL Global Development Group
* Portions Copyright (c) 1994, Regents of the University of California
*
*
@@ -35,7 +133,6 @@
#include "access/genam.h"
#include "access/heapam.h"
-#include "access/heapam_xlog.h"
#include "access/htup_details.h"
#include "access/multixact.h"
#include "access/tidstore.h"
@@ -43,10 +140,10 @@
#include "access/visibilitymap.h"
#include "access/xloginsert.h"
#include "catalog/storage.h"
-#include "commands/dbcommands.h"
#include "commands/progress.h"
#include "commands/vacuum.h"
#include "common/int.h"
+#include "common/pg_prng.h"
#include "executor/instrument.h"
#include "miscadmin.h"
#include "pgstat.h"
@@ -55,8 +152,8 @@
#include "storage/bufmgr.h"
#include "storage/freespace.h"
#include "storage/lmgr.h"
+#include "storage/read_stream.h"
#include "utils/lsyscache.h"
-#include "utils/memutils.h"
#include "utils/pg_rusage.h"
#include "utils/timestamp.h"
@@ -133,6 +230,31 @@ typedef enum
VACUUM_ERRCB_PHASE_TRUNCATE,
} VacErrPhase;
+/*
+ * An eager scan of a page that is set all-frozen in the VM is considered
+ * "successful". To spread out freezing overhead across multiple normal
+ * vacuums, we limit the number of successful eager page freezes. The maximum
+ * number of eager page freezes is calculated as a ratio of the all-visible
+ * but not all-frozen pages at the beginning of the vacuum.
+ */
+#define MAX_EAGER_FREEZE_SUCCESS_RATE 0.2
+
+/*
+ * On the assumption that different regions of the table tend to have
+ * similarly aged data, once vacuum fails to freeze
+ * vacuum_max_eager_freeze_failure_rate of the blocks in a region of size
+ * EAGER_SCAN_REGION_SIZE, it suspends eager scanning until it has progressed
+ * to another region of the table with potentially older data.
+ */
+#define EAGER_SCAN_REGION_SIZE 4096
+
+/*
+ * heap_vac_scan_next_block() sets these flags to communicate information
+ * about the block it read to the caller.
+ */
+#define VAC_BLK_WAS_EAGER_SCANNED (1 << 0)
+#define VAC_BLK_ALL_VISIBLE_ACCORDING_TO_VM (1 << 1)
+
typedef struct LVRelState
{
/* Target heap relation and its indexes */
@@ -189,8 +311,30 @@ typedef struct LVRelState
BlockNumber rel_pages; /* total number of pages */
BlockNumber scanned_pages; /* # pages examined (not skipped via VM) */
+
+ /*
+ * Count of all-visible blocks eagerly scanned (for logging only). This
+ * does not include skippable blocks scanned due to SKIP_PAGES_THRESHOLD.
+ */
+ BlockNumber eager_scanned_pages;
+
BlockNumber removed_pages; /* # pages removed by relation truncation */
- BlockNumber frozen_pages; /* # pages with newly frozen tuples */
+ BlockNumber new_frozen_tuple_pages; /* # pages with newly frozen tuples */
+
+ /* # pages newly set all-visible in the VM */
+ BlockNumber vm_new_visible_pages;
+
+ /*
+ * # pages newly set all-visible and all-frozen in the VM. This is a
+ * subset of vm_new_visible_pages. That is, vm_new_visible_pages includes
+ * all pages set all-visible, but vm_new_visible_frozen_pages includes
+ * only those which were also set all-frozen.
+ */
+ BlockNumber vm_new_visible_frozen_pages;
+
+ /* # all-visible pages newly set all-frozen in the VM */
+ BlockNumber vm_new_frozen_pages;
+
BlockNumber lpdead_item_pages; /* # pages with LP_DEAD items */
BlockNumber missed_dead_pages; /* # pages with missed dead tuples */
BlockNumber nonempty_pages; /* actually, last nonempty page + 1 */
@@ -215,9 +359,57 @@ typedef struct LVRelState
BlockNumber current_block; /* last block returned */
BlockNumber next_unskippable_block; /* next unskippable block */
bool next_unskippable_allvis; /* its visibility status */
+ bool next_unskippable_eager_scanned; /* if it was eagerly scanned */
Buffer next_unskippable_vmbuffer; /* buffer containing its VM bit */
+
+ /* State related to managing eager scanning of all-visible pages */
+
+ /*
+ * A normal vacuum that has failed to freeze too many eagerly scanned
+ * blocks in a region suspends eager scanning.
+ * next_eager_scan_region_start is the block number of the first block
+ * eligible for resumed eager scanning.
+ *
+ * When eager scanning is permanently disabled, either initially
+ * (including for aggressive vacuum) or due to hitting the success cap,
+ * this is set to InvalidBlockNumber.
+ */
+ BlockNumber next_eager_scan_region_start;
+
+ /*
+ * The remaining number of blocks a normal vacuum will consider eager
+ * scanning when it is successful. When eager scanning is enabled, this is
+ * initialized to MAX_EAGER_FREEZE_SUCCESS_RATE of the total number of
+ * all-visible but not all-frozen pages. For each eager freeze success,
+ * this is decremented. Once it hits 0, eager scanning is permanently
+ * disabled. It is initialized to 0 if eager scanning starts out disabled
+ * (including for aggressive vacuum).
+ */
+ BlockNumber eager_scan_remaining_successes;
+
+ /*
+ * The maximum number of blocks which may be eagerly scanned and not
+ * frozen before eager scanning is temporarily suspended. This is
+ * configurable both globally, via the
+ * vacuum_max_eager_freeze_failure_rate GUC, and per table, with a table
+ * storage parameter of the same name. It is calculated as
+ * vacuum_max_eager_freeze_failure_rate of EAGER_SCAN_REGION_SIZE blocks.
+ * It is 0 when eager scanning is disabled.
+ */
+ BlockNumber eager_scan_max_fails_per_region;
+
+ /*
+ * The number of eagerly scanned blocks vacuum failed to freeze (due to
+ * age) in the current eager scan region. Vacuum resets it to
+ * eager_scan_max_fails_per_region each time it enters a new region of the
+ * relation. If eager_scan_remaining_fails hits 0, eager scanning is
+ * suspended until the next region. It is also 0 if eager scanning has
+ * been permanently disabled.
+ */
+ BlockNumber eager_scan_remaining_fails;
} LVRelState;
+
/* Struct for saving and restoring vacuum error information. */
typedef struct LVSavedErrInfo
{
@@ -229,16 +421,19 @@ typedef struct LVSavedErrInfo
/* non-export function prototypes */
static void lazy_scan_heap(LVRelState *vacrel);
-static bool heap_vac_scan_next_block(LVRelState *vacrel, BlockNumber *blkno,
- bool *all_visible_according_to_vm);
+static void heap_vacuum_eager_scan_setup(LVRelState *vacrel,
+ const VacuumParams params);
+static BlockNumber heap_vac_scan_next_block(ReadStream *stream,
+ void *callback_private_data,
+ void *per_buffer_data);
static void find_next_unskippable_block(LVRelState *vacrel, bool *skipsallvis);
static bool lazy_scan_new_or_empty(LVRelState *vacrel, Buffer buf,
BlockNumber blkno, Page page,
bool sharelock, Buffer vmbuffer);
-static void lazy_scan_prune(LVRelState *vacrel, Buffer buf,
+static int lazy_scan_prune(LVRelState *vacrel, Buffer buf,
BlockNumber blkno, Page page,
Buffer vmbuffer, bool all_visible_according_to_vm,
- bool *has_lpdead_items);
+ bool *has_lpdead_items, bool *vm_page_frozen);
static bool lazy_scan_noprune(LVRelState *vacrel, Buffer buf,
BlockNumber blkno, Page page,
bool *has_lpdead_items);
@@ -246,7 +441,7 @@ static void lazy_vacuum(LVRelState *vacrel);
static bool lazy_vacuum_all_indexes(LVRelState *vacrel);
static void lazy_vacuum_heap_rel(LVRelState *vacrel);
static void lazy_vacuum_heap_page(LVRelState *vacrel, BlockNumber blkno,
- Buffer buffer, OffsetNumber *offsets,
+ Buffer buffer, OffsetNumber *deadoffsets,
int num_offsets, Buffer vmbuffer);
static bool lazy_check_wraparound_failsafe(LVRelState *vacrel);
static void lazy_cleanup_all_indexes(LVRelState *vacrel);
@@ -280,6 +475,130 @@ static void restore_vacuum_error_info(LVRelState *vacrel,
const LVSavedErrInfo *saved_vacrel);
+
+/*
+ * Helper to set up the eager scanning state for vacuuming a single relation.
+ * Initializes the eager scan management related members of the LVRelState.
+ *
+ * Caller provides whether or not an aggressive vacuum is required due to
+ * vacuum options or for relfrozenxid/relminmxid advancement.
+ */
+static void
+heap_vacuum_eager_scan_setup(LVRelState *vacrel, const VacuumParams params)
+{
+ uint32 randseed;
+ BlockNumber allvisible;
+ BlockNumber allfrozen;
+ float first_region_ratio;
+ bool oldest_unfrozen_before_cutoff = false;
+
+ /*
+ * Initialize eager scan management fields to their disabled values.
+ * Aggressive vacuums, normal vacuums of small tables, and normal vacuums
+ * of tables without sufficiently old tuples disable eager scanning.
+ */
+ vacrel->next_eager_scan_region_start = InvalidBlockNumber;
+ vacrel->eager_scan_max_fails_per_region = 0;
+ vacrel->eager_scan_remaining_fails = 0;
+ vacrel->eager_scan_remaining_successes = 0;
+
+ /* If eager scanning is explicitly disabled, just return. */
+ if (params.max_eager_freeze_failure_rate == 0)
+ return;
+
+ /*
+ * The caller will have determined whether or not an aggressive vacuum is
+ * required by either the vacuum parameters or the relative age of the
+ * oldest unfrozen transaction IDs. An aggressive vacuum must scan every
+ * all-visible page to safely advance the relfrozenxid and/or relminmxid,
+ * so scans of all-visible pages are not considered eager.
+ */
+ if (vacrel->aggressive)
+ return;
+
+ /*
+ * Aggressively vacuuming a small relation shouldn't take long, so it
+ * isn't worth amortizing. We use two times the region size as the size
+ * cutoff because the eager scan start block is a random spot somewhere in
+ * the first region, making the second region the first to be eager
+ * scanned normally.
+ */
+ if (vacrel->rel_pages < 2 * EAGER_SCAN_REGION_SIZE)
+ return;
+
+ /*
+ * We only want to enable eager scanning if we are likely to be able to
+ * freeze some of the pages in the relation.
+ *
+ * Tuples with XIDs older than OldestXmin or MXIDs older than OldestMxact
+ * are technically freezable, but we won't freeze them unless the criteria
+ * for opportunistic freezing is met. Only tuples with XIDs/MXIDs older
+ * than the FreezeLimit/MultiXactCutoff are frozen in the common case.
+ *
+ * So, as a heuristic, we wait until the FreezeLimit has advanced past the
+ * relfrozenxid or the MultiXactCutoff has advanced past the relminmxid to
+ * enable eager scanning.
+ */
+ if (TransactionIdIsNormal(vacrel->cutoffs.relfrozenxid) &&
+ TransactionIdPrecedes(vacrel->cutoffs.relfrozenxid,
+ vacrel->cutoffs.FreezeLimit))
+ oldest_unfrozen_before_cutoff = true;
+
+ if (!oldest_unfrozen_before_cutoff &&
+ MultiXactIdIsValid(vacrel->cutoffs.relminmxid) &&
+ MultiXactIdPrecedes(vacrel->cutoffs.relminmxid,
+ vacrel->cutoffs.MultiXactCutoff))
+ oldest_unfrozen_before_cutoff = true;
+
+ if (!oldest_unfrozen_before_cutoff)
+ return;
+
+ /* We have met the criteria to eagerly scan some pages. */
+
+ /*
+ * Our success cap is MAX_EAGER_FREEZE_SUCCESS_RATE of the number of
+ * all-visible but not all-frozen blocks in the relation.
+ */
+ visibilitymap_count(vacrel->rel, &allvisible, &allfrozen);
+
+ vacrel->eager_scan_remaining_successes =
+ (BlockNumber) (MAX_EAGER_FREEZE_SUCCESS_RATE *
+ (allvisible - allfrozen));
+
+ /* If every all-visible page is frozen, eager scanning is disabled. */
+ if (vacrel->eager_scan_remaining_successes == 0)
+ return;
+
+ /*
+ * Now calculate the bounds of the first eager scan region. Its end block
+ * will be a random spot somewhere in the first EAGER_SCAN_REGION_SIZE
+ * blocks. This affects the bounds of all subsequent regions and avoids
+ * eager scanning and failing to freeze the same blocks each vacuum of the
+ * relation.
+ */
+ randseed = pg_prng_uint32(&pg_global_prng_state);
+
+ vacrel->next_eager_scan_region_start = randseed % EAGER_SCAN_REGION_SIZE;
+
+ Assert(params.max_eager_freeze_failure_rate > 0 &&
+ params.max_eager_freeze_failure_rate <= 1);
+
+ vacrel->eager_scan_max_fails_per_region =
+ params.max_eager_freeze_failure_rate *
+ EAGER_SCAN_REGION_SIZE;
+
+ /*
+ * The first region will be smaller than subsequent regions. As such,
+ * adjust the eager freeze failures tolerated for this region.
+ */
+ first_region_ratio = 1 - (float) vacrel->next_eager_scan_region_start /
+ EAGER_SCAN_REGION_SIZE;
+
+ vacrel->eager_scan_remaining_fails =
+ vacrel->eager_scan_max_fails_per_region *
+ first_region_ratio;
+}
+
/*
* heap_vacuum_rel() -- perform VACUUM for one heap relation
*
@@ -292,7 +611,7 @@ static void restore_vacuum_error_info(LVRelState *vacrel,
* and locked the relation.
*/
void
-heap_vacuum_rel(Relation rel, VacuumParams *params,
+heap_vacuum_rel(Relation rel, const VacuumParams params,
BufferAccessStrategy bstrategy)
{
LVRelState *vacrel;
@@ -303,7 +622,8 @@ heap_vacuum_rel(Relation rel, VacuumParams *params,
minmulti_updated;
BlockNumber orig_rel_pages,
new_rel_pages,
- new_rel_allvisible;
+ new_rel_allvisible,
+ new_rel_allfrozen;
PGRUsage ru0;
TimestampTz starttime = 0;
PgStat_Counter startreadtime = 0,
@@ -313,13 +633,12 @@ heap_vacuum_rel(Relation rel, VacuumParams *params,
ErrorContextCallback errcallback;
char **indnames = NULL;
- verbose = (params->options & VACOPT_VERBOSE) != 0;
+ verbose = (params.options & VACOPT_VERBOSE) != 0;
instrument = (verbose || (AmAutoVacuumWorkerProcess() &&
- params->log_min_duration >= 0));
+ params.log_min_duration >= 0));
if (instrument)
{
pg_rusage_init(&ru0);
- starttime = GetCurrentTimestamp();
if (track_io_timing)
{
startreadtime = pgStatBlockReadTime;
@@ -327,6 +646,9 @@ heap_vacuum_rel(Relation rel, VacuumParams *params,
}
}
+ /* Used for instrumentation and stats report */
+ starttime = GetCurrentTimestamp();
+
pgstat_progress_start_command(PROGRESS_COMMAND_VACUUM,
RelationGetRelid(rel));
@@ -376,9 +698,9 @@ heap_vacuum_rel(Relation rel, VacuumParams *params,
* The truncate param allows user to avoid attempting relation truncation,
* though it can't force truncation to happen.
*/
- Assert(params->index_cleanup != VACOPTVALUE_UNSPECIFIED);
- Assert(params->truncate != VACOPTVALUE_UNSPECIFIED &&
- params->truncate != VACOPTVALUE_AUTO);
+ Assert(params.index_cleanup != VACOPTVALUE_UNSPECIFIED);
+ Assert(params.truncate != VACOPTVALUE_UNSPECIFIED &&
+ params.truncate != VACOPTVALUE_AUTO);
/*
* While VacuumFailSafeActive is reset to false before calling this, we
@@ -388,14 +710,14 @@ heap_vacuum_rel(Relation rel, VacuumParams *params,
vacrel->consider_bypass_optimization = true;
vacrel->do_index_vacuuming = true;
vacrel->do_index_cleanup = true;
- vacrel->do_rel_truncate = (params->truncate != VACOPTVALUE_DISABLED);
- if (params->index_cleanup == VACOPTVALUE_DISABLED)
+ vacrel->do_rel_truncate = (params.truncate != VACOPTVALUE_DISABLED);
+ if (params.index_cleanup == VACOPTVALUE_DISABLED)
{
/* Force disable index vacuuming up-front */
vacrel->do_index_vacuuming = false;
vacrel->do_index_cleanup = false;
}
- else if (params->index_cleanup == VACOPTVALUE_ENABLED)
+ else if (params.index_cleanup == VACOPTVALUE_ENABLED)
{
/* Force index vacuuming. Note that failsafe can still bypass. */
vacrel->consider_bypass_optimization = false;
@@ -403,13 +725,14 @@ heap_vacuum_rel(Relation rel, VacuumParams *params,
else
{
/* Default/auto, make all decisions dynamically */
- Assert(params->index_cleanup == VACOPTVALUE_AUTO);
+ Assert(params.index_cleanup == VACOPTVALUE_AUTO);
}
/* Initialize page counters explicitly (be tidy) */
vacrel->scanned_pages = 0;
+ vacrel->eager_scanned_pages = 0;
vacrel->removed_pages = 0;
- vacrel->frozen_pages = 0;
+ vacrel->new_frozen_tuple_pages = 0;
vacrel->lpdead_item_pages = 0;
vacrel->missed_dead_pages = 0;
vacrel->nonempty_pages = 0;
@@ -430,6 +753,10 @@ heap_vacuum_rel(Relation rel, VacuumParams *params,
vacrel->recently_dead_tuples = 0;
vacrel->missed_dead_tuples = 0;
+ vacrel->vm_new_visible_pages = 0;
+ vacrel->vm_new_visible_frozen_pages = 0;
+ vacrel->vm_new_frozen_pages = 0;
+
/*
* Get cutoffs that determine which deleted tuples are considered DEAD,
* not just RECENTLY_DEAD, and which XIDs/MXIDs to freeze. Then determine
@@ -438,23 +765,30 @@ heap_vacuum_rel(Relation rel, VacuumParams *params,
* as an upper bound on the XIDs stored in the pages we'll actually scan
* (NewRelfrozenXid tracking must never be allowed to miss unfrozen XIDs).
*
- * Next acquire vistest, a related cutoff that's used in pruning. We
- * expect vistest will always make heap_page_prune_and_freeze() remove any
- * deleted tuple whose xmax is < OldestXmin. lazy_scan_prune must never
- * become confused about whether a tuple should be frozen or removed. (In
- * the future we might want to teach lazy_scan_prune to recompute vistest
- * from time to time, to increase the number of dead tuples it can prune
- * away.)
+ * Next acquire vistest, a related cutoff that's used in pruning. We use
+ * vistest in combination with OldestXmin to ensure that
+ * heap_page_prune_and_freeze() always removes any deleted tuple whose
+ * xmax is < OldestXmin. lazy_scan_prune must never become confused about
+ * whether a tuple should be frozen or removed. (In the future we might
+ * want to teach lazy_scan_prune to recompute vistest from time to time,
+ * to increase the number of dead tuples it can prune away.)
*/
vacrel->aggressive = vacuum_get_cutoffs(rel, params, &vacrel->cutoffs);
vacrel->rel_pages = orig_rel_pages = RelationGetNumberOfBlocks(rel);
vacrel->vistest = GlobalVisTestFor(rel);
+
/* Initialize state used to track oldest extant XID/MXID */
vacrel->NewRelfrozenXid = vacrel->cutoffs.OldestXmin;
vacrel->NewRelminMxid = vacrel->cutoffs.OldestMxact;
+
+ /*
+ * Initialize state related to tracking all-visible page skipping. This is
+ * very important to determine whether or not it is safe to advance the
+ * relfrozenxid/relminmxid.
+ */
vacrel->skippedallvis = false;
skipwithvm = true;
- if (params->options & VACOPT_DISABLE_PAGE_SKIPPING)
+ if (params.options & VACOPT_DISABLE_PAGE_SKIPPING)
{
/*
* Force aggressive mode, and disable skipping blocks using the
@@ -466,6 +800,13 @@ heap_vacuum_rel(Relation rel, VacuumParams *params,
vacrel->skipwithvm = skipwithvm;
+ /*
+ * Set up eager scan tracking state. This must happen after determining
+ * whether or not the vacuum must be aggressive, because only normal
+ * vacuums use the eager scan algorithm.
+ */
+ heap_vacuum_eager_scan_setup(vacrel, params);
+
if (verbose)
{
if (vacrel->aggressive)
@@ -488,7 +829,7 @@ heap_vacuum_rel(Relation rel, VacuumParams *params,
* is already dangerously old.)
*/
lazy_check_wraparound_failsafe(vacrel);
- dead_items_alloc(vacrel, params->nworkers);
+ dead_items_alloc(vacrel, params.nworkers);
/*
* Call lazy_scan_heap to perform all required heap pruning, index
@@ -558,10 +899,18 @@ heap_vacuum_rel(Relation rel, VacuumParams *params,
* pg_class.relpages to
*/
new_rel_pages = vacrel->rel_pages; /* After possible rel truncation */
- visibilitymap_count(rel, &new_rel_allvisible, NULL);
+ visibilitymap_count(rel, &new_rel_allvisible, &new_rel_allfrozen);
if (new_rel_allvisible > new_rel_pages)
new_rel_allvisible = new_rel_pages;
+ /*
+ * An all-frozen block _must_ be all-visible. As such, clamp the count of
+ * all-frozen blocks to the count of all-visible blocks. This matches the
+ * clamping of relallvisible above.
+ */
+ if (new_rel_allfrozen > new_rel_allvisible)
+ new_rel_allfrozen = new_rel_allvisible;
+
/*
* Now actually update rel's pg_class entry.
*
@@ -570,7 +919,8 @@ heap_vacuum_rel(Relation rel, VacuumParams *params,
* scan every page that isn't skipped using the visibility map.
*/
vac_update_relstats(rel, new_rel_pages, vacrel->new_live_tuples,
- new_rel_allvisible, vacrel->nindexes > 0,
+ new_rel_allvisible, new_rel_allfrozen,
+ vacrel->nindexes > 0,
vacrel->NewRelfrozenXid, vacrel->NewRelminMxid,
&frozenxid_updated, &minmulti_updated, false);
@@ -588,16 +938,17 @@ heap_vacuum_rel(Relation rel, VacuumParams *params,
rel->rd_rel->relisshared,
Max(vacrel->new_live_tuples, 0),
vacrel->recently_dead_tuples +
- vacrel->missed_dead_tuples);
+ vacrel->missed_dead_tuples,
+ starttime);
pgstat_progress_end_command();
if (instrument)
{
TimestampTz endtime = GetCurrentTimestamp();
- if (verbose || params->log_min_duration == 0 ||
+ if (verbose || params.log_min_duration == 0 ||
TimestampDifferenceExceeds(starttime, endtime,
- params->log_min_duration))
+ params.log_min_duration))
{
long secs_dur;
int usecs_dur;
@@ -608,6 +959,9 @@ heap_vacuum_rel(Relation rel, VacuumParams *params,
int32 diff;
double read_rate = 0,
write_rate = 0;
+ int64 total_blks_hit;
+ int64 total_blks_read;
+ int64 total_blks_dirtied;
TimestampDifference(starttime, endtime, &secs_dur, &usecs_dur);
memset(&walusage, 0, sizeof(WalUsage));
@@ -615,6 +969,13 @@ heap_vacuum_rel(Relation rel, VacuumParams *params,
memset(&bufferusage, 0, sizeof(BufferUsage));
BufferUsageAccumDiff(&bufferusage, &pgBufferUsage, &startbufferusage);
+ total_blks_hit = bufferusage.shared_blks_hit +
+ bufferusage.local_blks_hit;
+ total_blks_read = bufferusage.shared_blks_read +
+ bufferusage.local_blks_read;
+ total_blks_dirtied = bufferusage.shared_blks_dirtied +
+ bufferusage.local_blks_dirtied;
+
initStringInfo(&buf);
if (verbose)
{
@@ -622,10 +983,10 @@ heap_vacuum_rel(Relation rel, VacuumParams *params,
* Aggressiveness already reported earlier, in dedicated
* VACUUM VERBOSE ereport
*/
- Assert(!params->is_wraparound);
+ Assert(!params.is_wraparound);
msgfmt = _("finished vacuuming \"%s.%s.%s\": index scans: %d\n");
}
- else if (params->is_wraparound)
+ else if (params.is_wraparound)
{
/*
* While it's possible for a VACUUM to be both is_wraparound
@@ -650,21 +1011,23 @@ heap_vacuum_rel(Relation rel, VacuumParams *params,
vacrel->relnamespace,
vacrel->relname,
vacrel->num_index_scans);
- appendStringInfo(&buf, _("pages: %u removed, %u remain, %u scanned (%.2f%% of total)\n"),
+ appendStringInfo(&buf, _("pages: %u removed, %u remain, %u scanned (%.2f%% of total), %u eagerly scanned\n"),
vacrel->removed_pages,
new_rel_pages,
vacrel->scanned_pages,
orig_rel_pages == 0 ? 100.0 :
- 100.0 * vacrel->scanned_pages / orig_rel_pages);
+ 100.0 * vacrel->scanned_pages /
+ orig_rel_pages,
+ vacrel->eager_scanned_pages);
appendStringInfo(&buf,
- _("tuples: %lld removed, %lld remain, %lld are dead but not yet removable\n"),
- (long long) vacrel->tuples_deleted,
- (long long) vacrel->new_rel_tuples,
- (long long) vacrel->recently_dead_tuples);
+ _("tuples: %" PRId64 " removed, %" PRId64 " remain, %" PRId64 " are dead but not yet removable\n"),
+ vacrel->tuples_deleted,
+ (int64) vacrel->new_rel_tuples,
+ vacrel->recently_dead_tuples);
if (vacrel->missed_dead_tuples > 0)
appendStringInfo(&buf,
- _("tuples missed: %lld dead from %u pages not removed due to cleanup lock contention\n"),
- (long long) vacrel->missed_dead_tuples,
+ _("tuples missed: %" PRId64 " dead from %u pages not removed due to cleanup lock contention\n"),
+ vacrel->missed_dead_tuples,
vacrel->missed_dead_pages);
diff = (int32) (ReadNextTransactionId() -
vacrel->cutoffs.OldestXmin);
@@ -687,11 +1050,19 @@ heap_vacuum_rel(Relation rel, VacuumParams *params,
_("new relminmxid: %u, which is %d MXIDs ahead of previous value\n"),
vacrel->NewRelminMxid, diff);
}
- appendStringInfo(&buf, _("frozen: %u pages from table (%.2f%% of total) had %lld tuples frozen\n"),
- vacrel->frozen_pages,
+ appendStringInfo(&buf, _("frozen: %u pages from table (%.2f%% of total) had %" PRId64 " tuples frozen\n"),
+ vacrel->new_frozen_tuple_pages,
orig_rel_pages == 0 ? 100.0 :
- 100.0 * vacrel->frozen_pages / orig_rel_pages,
- (long long) vacrel->tuples_frozen);
+ 100.0 * vacrel->new_frozen_tuple_pages /
+ orig_rel_pages,
+ vacrel->tuples_frozen);
+
+ appendStringInfo(&buf,
+ _("visibility map: %u pages set all-visible, %u pages set all-frozen (%u were all-visible)\n"),
+ vacrel->vm_new_visible_pages,
+ vacrel->vm_new_visible_frozen_pages +
+ vacrel->vm_new_frozen_pages,
+ vacrel->vm_new_frozen_pages);
if (vacrel->do_index_vacuuming)
{
if (vacrel->nindexes == 0 || vacrel->num_index_scans == 0)
@@ -699,7 +1070,7 @@ heap_vacuum_rel(Relation rel, VacuumParams *params,
else
appendStringInfoString(&buf, _("index scan needed: "));
- msgfmt = _("%u pages from table (%.2f%% of total) had %lld dead item identifiers removed\n");
+ msgfmt = _("%u pages from table (%.2f%% of total) had %" PRId64 " dead item identifiers removed\n");
}
else
{
@@ -708,13 +1079,13 @@ heap_vacuum_rel(Relation rel, VacuumParams *params,
else
appendStringInfoString(&buf, _("index scan bypassed by failsafe: "));
- msgfmt = _("%u pages from table (%.2f%% of total) have %lld dead item identifiers\n");
+ msgfmt = _("%u pages from table (%.2f%% of total) have %" PRId64 " dead item identifiers\n");
}
appendStringInfo(&buf, msgfmt,
vacrel->lpdead_item_pages,
orig_rel_pages == 0 ? 100.0 :
100.0 * vacrel->lpdead_item_pages / orig_rel_pages,
- (long long) vacrel->lpdead_items);
+ vacrel->lpdead_items);
for (int i = 0; i < vacrel->nindexes; i++)
{
IndexBulkDeleteResult *istat = vacrel->indstats[i];
@@ -730,6 +1101,17 @@ heap_vacuum_rel(Relation rel, VacuumParams *params,
istat->pages_deleted,
istat->pages_free);
}
+ if (track_cost_delay_timing)
+ {
+ /*
+ * We bypass the changecount mechanism because this value is
+ * only updated by the calling process. We also rely on the
+ * above call to pgstat_progress_end_command() to not clear
+ * the st_progress_param array.
+ */
+ appendStringInfo(&buf, _("delay time: %.3f ms\n"),
+ (double) MyBEEntry->st_progress_param[PROGRESS_VACUUM_DELAY_TIME] / 1000000.0);
+ }
if (track_io_timing)
{
double read_ms = (double) (pgStatBlockReadTime - startreadtime) / 1000;
@@ -740,23 +1122,24 @@ heap_vacuum_rel(Relation rel, VacuumParams *params,
}
if (secs_dur > 0 || usecs_dur > 0)
{
- read_rate = (double) BLCKSZ * (bufferusage.shared_blks_read + bufferusage.local_blks_read) /
+ read_rate = (double) BLCKSZ * total_blks_read /
(1024 * 1024) / (secs_dur + usecs_dur / 1000000.0);
- write_rate = (double) BLCKSZ * (bufferusage.shared_blks_dirtied + bufferusage.local_blks_dirtied) /
+ write_rate = (double) BLCKSZ * total_blks_dirtied /
(1024 * 1024) / (secs_dur + usecs_dur / 1000000.0);
}
appendStringInfo(&buf, _("avg read rate: %.3f MB/s, avg write rate: %.3f MB/s\n"),
read_rate, write_rate);
appendStringInfo(&buf,
- _("buffer usage: %lld hits, %lld misses, %lld dirtied\n"),
- (long long) (bufferusage.shared_blks_hit + bufferusage.local_blks_hit),
- (long long) (bufferusage.shared_blks_read + bufferusage.local_blks_read),
- (long long) (bufferusage.shared_blks_dirtied + bufferusage.local_blks_dirtied));
+ _("buffer usage: %" PRId64 " hits, %" PRId64 " reads, %" PRId64 " dirtied\n"),
+ total_blks_hit,
+ total_blks_read,
+ total_blks_dirtied);
appendStringInfo(&buf,
- _("WAL usage: %lld records, %lld full page images, %llu bytes\n"),
- (long long) walusage.wal_records,
- (long long) walusage.wal_fpi,
- (unsigned long long) walusage.wal_bytes);
+ _("WAL usage: %" PRId64 " records, %" PRId64 " full page images, %" PRIu64 " bytes, %" PRId64 " buffers full\n"),
+ walusage.wal_records,
+ walusage.wal_fpi,
+ walusage.wal_bytes,
+ walusage.wal_buffers_full);
appendStringInfo(&buf, _("system usage: %s"), pg_rusage_show(&ru0));
ereport(verbose ? INFO : LOG,
@@ -815,13 +1198,12 @@ heap_vacuum_rel(Relation rel, VacuumParams *params,
static void
lazy_scan_heap(LVRelState *vacrel)
{
+ ReadStream *stream;
BlockNumber rel_pages = vacrel->rel_pages,
- blkno,
+ blkno = 0,
next_fsm_block_to_vacuum = 0;
- bool all_visible_according_to_vm;
-
- TidStore *dead_items = vacrel->dead_items;
- VacDeadItemsInfo *dead_items_info = vacrel->dead_items_info;
+ BlockNumber orig_eager_scan_success_limit =
+ vacrel->eager_scan_remaining_successes; /* for logging */
Buffer vmbuffer = InvalidBuffer;
const int initprog_index[] = {
PROGRESS_VACUUM_PHASE,
@@ -833,30 +1215,42 @@ lazy_scan_heap(LVRelState *vacrel)
/* Report that we're scanning the heap, advertising total # of blocks */
initprog_val[0] = PROGRESS_VACUUM_PHASE_SCAN_HEAP;
initprog_val[1] = rel_pages;
- initprog_val[2] = dead_items_info->max_bytes;
+ initprog_val[2] = vacrel->dead_items_info->max_bytes;
pgstat_progress_update_multi_param(3, initprog_index, initprog_val);
/* Initialize for the first heap_vac_scan_next_block() call */
vacrel->current_block = InvalidBlockNumber;
vacrel->next_unskippable_block = InvalidBlockNumber;
vacrel->next_unskippable_allvis = false;
+ vacrel->next_unskippable_eager_scanned = false;
vacrel->next_unskippable_vmbuffer = InvalidBuffer;
- while (heap_vac_scan_next_block(vacrel, &blkno, &all_visible_according_to_vm))
+ /*
+ * Set up the read stream for vacuum's first pass through the heap.
+ *
+ * This could be made safe for READ_STREAM_USE_BATCHING, but only with
+ * explicit work in heap_vac_scan_next_block.
+ */
+ stream = read_stream_begin_relation(READ_STREAM_MAINTENANCE,
+ vacrel->bstrategy,
+ vacrel->rel,
+ MAIN_FORKNUM,
+ heap_vac_scan_next_block,
+ vacrel,
+ sizeof(uint8));
+
+ while (true)
{
Buffer buf;
Page page;
+ uint8 blk_info = 0;
+ int ndeleted = 0;
bool has_lpdead_items;
+ void *per_buffer_data = NULL;
+ bool vm_page_frozen = false;
bool got_cleanup_lock = false;
- vacrel->scanned_pages++;
-
- /* Report as block scanned, update error traceback information */
- pgstat_progress_update_param(PROGRESS_VACUUM_HEAP_BLKS_SCANNED, blkno);
- update_vacuum_error_info(vacrel, NULL, VACUUM_ERRCB_PHASE_SCAN_HEAP,
- blkno, InvalidOffsetNumber);
-
- vacuum_delay_point();
+ vacuum_delay_point(false);
/*
* Regularly check if wraparound failsafe should trigger.
@@ -867,16 +1261,20 @@ lazy_scan_heap(LVRelState *vacrel)
* one-pass strategy, and the two-pass strategy with the index_cleanup
* param set to 'off'.
*/
- if (vacrel->scanned_pages % FAILSAFE_EVERY_PAGES == 0)
+ if (vacrel->scanned_pages > 0 &&
+ vacrel->scanned_pages % FAILSAFE_EVERY_PAGES == 0)
lazy_check_wraparound_failsafe(vacrel);
/*
* Consider if we definitely have enough space to process TIDs on page
* already. If we are close to overrunning the available space for
* dead_items TIDs, pause and do a cycle of vacuuming before we tackle
- * this page.
+ * this page. However, let's force at least one page-worth of tuples
+ * to be stored as to ensure we do at least some work when the memory
+ * configured is so low that we run out before storing anything.
*/
- if (TidStoreMemoryUsage(dead_items) > dead_items_info->max_bytes)
+ if (vacrel->dead_items_info->num_items > 0 &&
+ TidStoreMemoryUsage(vacrel->dead_items) > vacrel->dead_items_info->max_bytes)
{
/*
* Before beginning index vacuuming, we release any pin we may
@@ -896,10 +1294,11 @@ lazy_scan_heap(LVRelState *vacrel)
/*
* Vacuum the Free Space Map to make newly-freed space visible on
- * upper-level FSM pages. Note we have not yet processed blkno.
+ * upper-level FSM pages. Note that blkno is the previously
+ * processed block.
*/
FreeSpaceMapVacuumRange(vacrel->rel, next_fsm_block_to_vacuum,
- blkno);
+ blkno + 1);
next_fsm_block_to_vacuum = blkno;
/* Report that we are once again scanning the heap */
@@ -907,6 +1306,26 @@ lazy_scan_heap(LVRelState *vacrel)
PROGRESS_VACUUM_PHASE_SCAN_HEAP);
}
+ buf = read_stream_next_buffer(stream, &per_buffer_data);
+
+ /* The relation is exhausted. */
+ if (!BufferIsValid(buf))
+ break;
+
+ blk_info = *((uint8 *) per_buffer_data);
+ CheckBufferIsPinnedOnce(buf);
+ page = BufferGetPage(buf);
+ blkno = BufferGetBlockNumber(buf);
+
+ vacrel->scanned_pages++;
+ if (blk_info & VAC_BLK_WAS_EAGER_SCANNED)
+ vacrel->eager_scanned_pages++;
+
+ /* Report as block scanned, update error traceback information */
+ pgstat_progress_update_param(PROGRESS_VACUUM_HEAP_BLKS_SCANNED, blkno);
+ update_vacuum_error_info(vacrel, NULL, VACUUM_ERRCB_PHASE_SCAN_HEAP,
+ blkno, InvalidOffsetNumber);
+
/*
* Pin the visibility map page in case we need to mark the page
* all-visible. In most cases this will be very cheap, because we'll
@@ -914,10 +1333,6 @@ lazy_scan_heap(LVRelState *vacrel)
*/
visibilitymap_pin(vacrel->rel, blkno, &vmbuffer);
- buf = ReadBufferExtended(vacrel->rel, MAIN_FORKNUM, blkno, RBM_NORMAL,
- vacrel->bstrategy);
- page = BufferGetPage(buf);
-
/*
* We need a buffer cleanup lock to prune HOT chains and defragment
* the page in lazy_scan_prune. But when it's not possible to acquire
@@ -972,9 +1387,65 @@ lazy_scan_heap(LVRelState *vacrel)
* line pointers previously marked LP_DEAD.
*/
if (got_cleanup_lock)
- lazy_scan_prune(vacrel, buf, blkno, page,
- vmbuffer, all_visible_according_to_vm,
- &has_lpdead_items);
+ ndeleted = lazy_scan_prune(vacrel, buf, blkno, page,
+ vmbuffer,
+ blk_info & VAC_BLK_ALL_VISIBLE_ACCORDING_TO_VM,
+ &has_lpdead_items, &vm_page_frozen);
+
+ /*
+ * Count an eagerly scanned page as a failure or a success.
+ *
+ * Only lazy_scan_prune() freezes pages, so if we didn't get the
+ * cleanup lock, we won't have frozen the page. However, we only count
+ * pages that were too new to require freezing as eager freeze
+ * failures.
+ *
+ * We could gather more information from lazy_scan_noprune() about
+ * whether or not there were tuples with XIDs or MXIDs older than the
+ * FreezeLimit or MultiXactCutoff. However, for simplicity, we simply
+ * exclude pages skipped due to cleanup lock contention from eager
+ * freeze algorithm caps.
+ */
+ if (got_cleanup_lock &&
+ (blk_info & VAC_BLK_WAS_EAGER_SCANNED))
+ {
+ /* Aggressive vacuums do not eager scan. */
+ Assert(!vacrel->aggressive);
+
+ if (vm_page_frozen)
+ {
+ if (vacrel->eager_scan_remaining_successes > 0)
+ vacrel->eager_scan_remaining_successes--;
+
+ if (vacrel->eager_scan_remaining_successes == 0)
+ {
+ /*
+ * Report only once that we disabled eager scanning. We
+ * may eagerly read ahead blocks in excess of the success
+ * or failure caps before attempting to freeze them, so we
+ * could reach here even after disabling additional eager
+ * scanning.
+ */
+ if (vacrel->eager_scan_max_fails_per_region > 0)
+ ereport(vacrel->verbose ? INFO : DEBUG2,
+ (errmsg("disabling eager scanning after freezing %u eagerly scanned blocks of relation \"%s.%s.%s\"",
+ orig_eager_scan_success_limit,
+ vacrel->dbname, vacrel->relnamespace,
+ vacrel->relname)));
+
+ /*
+ * If we hit our success cap, permanently disable eager
+ * scanning by setting the other eager scan management
+ * fields to their disabled values.
+ */
+ vacrel->eager_scan_remaining_fails = 0;
+ vacrel->next_eager_scan_region_start = InvalidBlockNumber;
+ vacrel->eager_scan_max_fails_per_region = 0;
+ }
+ }
+ else if (vacrel->eager_scan_remaining_fails > 0)
+ vacrel->eager_scan_remaining_fails--;
+ }
/*
* Now drop the buffer lock and, potentially, update the FSM.
@@ -1010,7 +1481,7 @@ lazy_scan_heap(LVRelState *vacrel)
* table has indexes. There will only be newly-freed space if we
* held the cleanup lock and lazy_scan_prune() was called.
*/
- if (got_cleanup_lock && vacrel->nindexes == 0 && has_lpdead_items &&
+ if (got_cleanup_lock && vacrel->nindexes == 0 && ndeleted > 0 &&
blkno - next_fsm_block_to_vacuum >= VACUUM_FSM_EVERY_PAGES)
{
FreeSpaceMapVacuumRange(vacrel->rel, next_fsm_block_to_vacuum,
@@ -1026,8 +1497,12 @@ lazy_scan_heap(LVRelState *vacrel)
if (BufferIsValid(vmbuffer))
ReleaseBuffer(vmbuffer);
- /* report that everything is now scanned */
- pgstat_progress_update_param(PROGRESS_VACUUM_HEAP_BLKS_SCANNED, blkno);
+ /*
+ * Report that everything is now scanned. We never skip scanning the last
+ * block in the relation, so we can pass rel_pages here.
+ */
+ pgstat_progress_update_param(PROGRESS_VACUUM_HEAP_BLKS_SCANNED,
+ rel_pages);
/* now we can compute the new value for pg_class.reltuples */
vacrel->new_live_tuples = vac_estimate_reltuples(vacrel->rel, rel_pages,
@@ -1042,22 +1517,26 @@ lazy_scan_heap(LVRelState *vacrel)
Max(vacrel->new_live_tuples, 0) + vacrel->recently_dead_tuples +
vacrel->missed_dead_tuples;
+ read_stream_end(stream);
+
/*
* Do index vacuuming (call each index's ambulkdelete routine), then do
* related heap vacuuming
*/
- if (dead_items_info->num_items > 0)
+ if (vacrel->dead_items_info->num_items > 0)
lazy_vacuum(vacrel);
/*
* Vacuum the remainder of the Free Space Map. We must do this whether or
* not there were indexes, and whether or not we bypassed index vacuuming.
+ * We can pass rel_pages here because we never skip scanning the last
+ * block of the relation.
*/
- if (blkno > next_fsm_block_to_vacuum)
- FreeSpaceMapVacuumRange(vacrel->rel, next_fsm_block_to_vacuum, blkno);
+ if (rel_pages > next_fsm_block_to_vacuum)
+ FreeSpaceMapVacuumRange(vacrel->rel, next_fsm_block_to_vacuum, rel_pages);
/* report all blocks vacuumed */
- pgstat_progress_update_param(PROGRESS_VACUUM_HEAP_BLKS_VACUUMED, blkno);
+ pgstat_progress_update_param(PROGRESS_VACUUM_HEAP_BLKS_VACUUMED, rel_pages);
/* Do final index cleanup (call each index's amvacuumcleanup routine) */
if (vacrel->nindexes > 0 && vacrel->do_index_cleanup)
@@ -1065,28 +1544,37 @@ lazy_scan_heap(LVRelState *vacrel)
}
/*
- * heap_vac_scan_next_block() -- get next block for vacuum to process
- *
- * lazy_scan_heap() calls here every time it needs to get the next block to
- * prune and vacuum. The function uses the visibility map, vacuum options,
- * and various thresholds to skip blocks which do not need to be processed and
- * sets blkno to the next block to process.
- *
- * The block number and visibility status of the next block to process are set
- * in *blkno and *all_visible_according_to_vm. The return value is false if
- * there are no further blocks to process.
- *
- * vacrel is an in/out parameter here. Vacuum options and information about
- * the relation are read. vacrel->skippedallvis is set if we skip a block
- * that's all-visible but not all-frozen, to ensure that we don't update
- * relfrozenxid in that case. vacrel also holds information about the next
- * unskippable block, as bookkeeping for this function.
+ * heap_vac_scan_next_block() -- read stream callback to get the next block
+ * for vacuum to process
+ *
+ * Every time lazy_scan_heap() needs a new block to process during its first
+ * phase, it invokes read_stream_next_buffer() with a stream set up to call
+ * heap_vac_scan_next_block() to get the next block.
+ *
+ * heap_vac_scan_next_block() uses the visibility map, vacuum options, and
+ * various thresholds to skip blocks which do not need to be processed and
+ * returns the next block to process or InvalidBlockNumber if there are no
+ * remaining blocks.
+ *
+ * The visibility status of the next block to process and whether or not it
+ * was eager scanned is set in the per_buffer_data.
+ *
+ * callback_private_data contains a reference to the LVRelState, passed to the
+ * read stream API during stream setup. The LVRelState is an in/out parameter
+ * here (locally named `vacrel`). Vacuum options and information about the
+ * relation are read from it. vacrel->skippedallvis is set if we skip a block
+ * that's all-visible but not all-frozen (to ensure that we don't update
+ * relfrozenxid in that case). vacrel also holds information about the next
+ * unskippable block -- as bookkeeping for this function.
*/
-static bool
-heap_vac_scan_next_block(LVRelState *vacrel, BlockNumber *blkno,
- bool *all_visible_according_to_vm)
+static BlockNumber
+heap_vac_scan_next_block(ReadStream *stream,
+ void *callback_private_data,
+ void *per_buffer_data)
{
BlockNumber next_block;
+ LVRelState *vacrel = callback_private_data;
+ uint8 blk_info = 0;
/* relies on InvalidBlockNumber + 1 overflowing to 0 on first call */
next_block = vacrel->current_block + 1;
@@ -1099,8 +1587,7 @@ heap_vac_scan_next_block(LVRelState *vacrel, BlockNumber *blkno,
ReleaseBuffer(vacrel->next_unskippable_vmbuffer);
vacrel->next_unskippable_vmbuffer = InvalidBuffer;
}
- *blkno = vacrel->rel_pages;
- return false;
+ return InvalidBlockNumber;
}
/*
@@ -1149,9 +1636,10 @@ heap_vac_scan_next_block(LVRelState *vacrel, BlockNumber *blkno,
* but chose not to. We know that they are all-visible in the VM,
* otherwise they would've been unskippable.
*/
- *blkno = vacrel->current_block = next_block;
- *all_visible_according_to_vm = true;
- return true;
+ vacrel->current_block = next_block;
+ blk_info |= VAC_BLK_ALL_VISIBLE_ACCORDING_TO_VM;
+ *((uint8 *) per_buffer_data) = blk_info;
+ return vacrel->current_block;
}
else
{
@@ -1161,9 +1649,13 @@ heap_vac_scan_next_block(LVRelState *vacrel, BlockNumber *blkno,
*/
Assert(next_block == vacrel->next_unskippable_block);
- *blkno = vacrel->current_block = next_block;
- *all_visible_according_to_vm = vacrel->next_unskippable_allvis;
- return true;
+ vacrel->current_block = next_block;
+ if (vacrel->next_unskippable_allvis)
+ blk_info |= VAC_BLK_ALL_VISIBLE_ACCORDING_TO_VM;
+ if (vacrel->next_unskippable_eager_scanned)
+ blk_info |= VAC_BLK_WAS_EAGER_SCANNED;
+ *((uint8 *) per_buffer_data) = blk_info;
+ return vacrel->current_block;
}
}
@@ -1186,11 +1678,12 @@ find_next_unskippable_block(LVRelState *vacrel, bool *skipsallvis)
BlockNumber rel_pages = vacrel->rel_pages;
BlockNumber next_unskippable_block = vacrel->next_unskippable_block + 1;
Buffer next_unskippable_vmbuffer = vacrel->next_unskippable_vmbuffer;
+ bool next_unskippable_eager_scanned = false;
bool next_unskippable_allvis;
*skipsallvis = false;
- for (;;)
+ for (;; next_unskippable_block++)
{
uint8 mapbits = visibilitymap_get_status(vacrel->rel,
next_unskippable_block,
@@ -1198,6 +1691,19 @@ find_next_unskippable_block(LVRelState *vacrel, bool *skipsallvis)
next_unskippable_allvis = (mapbits & VISIBILITYMAP_ALL_VISIBLE) != 0;
+ /*
+ * At the start of each eager scan region, normal vacuums with eager
+ * scanning enabled reset the failure counter, allowing vacuum to
+ * resume eager scanning if it had been suspended in the previous
+ * region.
+ */
+ if (next_unskippable_block >= vacrel->next_eager_scan_region_start)
+ {
+ vacrel->eager_scan_remaining_fails =
+ vacrel->eager_scan_max_fails_per_region;
+ vacrel->next_eager_scan_region_start += EAGER_SCAN_REGION_SIZE;
+ }
+
/*
* A block is unskippable if it is not all visible according to the
* visibility map.
@@ -1226,28 +1732,41 @@ find_next_unskippable_block(LVRelState *vacrel, bool *skipsallvis)
break;
/*
- * Aggressive VACUUM caller can't skip pages just because they are
- * all-visible. They may still skip all-frozen pages, which can't
- * contain XIDs < OldestXmin (XIDs that aren't already frozen by now).
+ * All-frozen pages cannot contain XIDs < OldestXmin (XIDs that aren't
+ * already frozen by now), so this page can be skipped.
*/
- if ((mapbits & VISIBILITYMAP_ALL_FROZEN) == 0)
- {
- if (vacrel->aggressive)
- break;
+ if ((mapbits & VISIBILITYMAP_ALL_FROZEN) != 0)
+ continue;
- /*
- * All-visible block is safe to skip in non-aggressive case. But
- * remember that the final range contains such a block for later.
- */
- *skipsallvis = true;
+ /*
+ * Aggressive vacuums cannot skip any all-visible pages that are not
+ * also all-frozen.
+ */
+ if (vacrel->aggressive)
+ break;
+
+ /*
+ * Normal vacuums with eager scanning enabled only skip all-visible
+ * but not all-frozen pages if they have hit the failure limit for the
+ * current eager scan region.
+ */
+ if (vacrel->eager_scan_remaining_fails > 0)
+ {
+ next_unskippable_eager_scanned = true;
+ break;
}
- next_unskippable_block++;
+ /*
+ * All-visible blocks are safe to skip in a normal vacuum. But
+ * remember that the final range contains such a block for later.
+ */
+ *skipsallvis = true;
}
/* write the local variables back to vacrel */
vacrel->next_unskippable_block = next_unskippable_block;
vacrel->next_unskippable_allvis = next_unskippable_allvis;
+ vacrel->next_unskippable_eager_scanned = next_unskippable_eager_scanned;
vacrel->next_unskippable_vmbuffer = next_unskippable_vmbuffer;
}
@@ -1278,6 +1797,12 @@ find_next_unskippable_block(LVRelState *vacrel, bool *skipsallvis)
* lazy_scan_prune (or lazy_scan_noprune). Otherwise returns true, indicating
* that lazy_scan_heap is done processing the page, releasing lock on caller's
* behalf.
+ *
+ * No vm_page_frozen output parameter (like that passed to lazy_scan_prune())
+ * is passed here because neither empty nor new pages can be eagerly frozen.
+ * New pages are never frozen. Empty pages are always set frozen in the VM at
+ * the same time that they are set all-visible, and we don't eagerly scan
+ * frozen pages.
*/
static bool
lazy_scan_new_or_empty(LVRelState *vacrel, Buffer buf, BlockNumber blkno,
@@ -1366,10 +1891,16 @@ lazy_scan_new_or_empty(LVRelState *vacrel, Buffer buf, BlockNumber blkno,
log_newpage_buffer(buf, true);
PageSetAllVisible(page);
- visibilitymap_set(vacrel->rel, blkno, buf, InvalidXLogRecPtr,
+ visibilitymap_set(vacrel->rel, blkno, buf,
+ InvalidXLogRecPtr,
vmbuffer, InvalidTransactionId,
- VISIBILITYMAP_ALL_VISIBLE | VISIBILITYMAP_ALL_FROZEN);
+ VISIBILITYMAP_ALL_VISIBLE |
+ VISIBILITYMAP_ALL_FROZEN);
END_CRIT_SECTION();
+
+ /* Count the newly all-frozen pages for logging */
+ vacrel->vm_new_visible_pages++;
+ vacrel->vm_new_visible_frozen_pages++;
}
freespace = PageGetHeapFreeSpace(page);
@@ -1401,15 +1932,22 @@ cmpOffsetNumbers(const void *a, const void *b)
*
* *has_lpdead_items is set to true or false depending on whether, upon return
* from this function, any LP_DEAD items are still present on the page.
+ *
+ * *vm_page_frozen is set to true if the page is newly set all-frozen in the
+ * VM. The caller currently only uses this for determining whether an eagerly
+ * scanned page was successfully set all-frozen.
+ *
+ * Returns the number of tuples deleted from the page during HOT pruning.
*/
-static void
+static int
lazy_scan_prune(LVRelState *vacrel,
Buffer buf,
BlockNumber blkno,
Page page,
Buffer vmbuffer,
bool all_visible_according_to_vm,
- bool *has_lpdead_items)
+ bool *has_lpdead_items,
+ bool *vm_page_frozen)
{
Relation rel = vacrel->rel;
PruneFreezeResult presult;
@@ -1447,11 +1985,12 @@ lazy_scan_prune(LVRelState *vacrel,
if (presult.nfrozen > 0)
{
/*
- * We don't increment the frozen_pages instrumentation counter when
- * nfrozen == 0, since it only counts pages with newly frozen tuples
- * (don't confuse that with pages newly set all-frozen in VM).
+ * We don't increment the new_frozen_tuple_pages instrumentation
+ * counter when nfrozen == 0, since it only counts pages with newly
+ * frozen tuples (don't confuse that with pages newly set all-frozen
+ * in VM).
*/
- vacrel->frozen_pages++;
+ vacrel->new_frozen_tuple_pages++;
}
/*
@@ -1523,6 +2062,7 @@ lazy_scan_prune(LVRelState *vacrel,
*/
if (!all_visible_according_to_vm && presult.all_visible)
{
+ uint8 old_vmbits;
uint8 flags = VISIBILITYMAP_ALL_VISIBLE;
if (presult.all_frozen)
@@ -1546,9 +2086,30 @@ lazy_scan_prune(LVRelState *vacrel,
*/
PageSetAllVisible(page);
MarkBufferDirty(buf);
- visibilitymap_set(vacrel->rel, blkno, buf, InvalidXLogRecPtr,
- vmbuffer, presult.vm_conflict_horizon,
- flags);
+ old_vmbits = visibilitymap_set(vacrel->rel, blkno, buf,
+ InvalidXLogRecPtr,
+ vmbuffer, presult.vm_conflict_horizon,
+ flags);
+
+ /*
+ * If the page wasn't already set all-visible and/or all-frozen in the
+ * VM, count it as newly set for logging.
+ */
+ if ((old_vmbits & VISIBILITYMAP_ALL_VISIBLE) == 0)
+ {
+ vacrel->vm_new_visible_pages++;
+ if (presult.all_frozen)
+ {
+ vacrel->vm_new_visible_frozen_pages++;
+ *vm_page_frozen = true;
+ }
+ }
+ else if ((old_vmbits & VISIBILITYMAP_ALL_FROZEN) == 0 &&
+ presult.all_frozen)
+ {
+ vacrel->vm_new_frozen_pages++;
+ *vm_page_frozen = true;
+ }
}
/*
@@ -1560,8 +2121,11 @@ lazy_scan_prune(LVRelState *vacrel,
else if (all_visible_according_to_vm && !PageIsAllVisible(page) &&
visibilitymap_get_status(vacrel->rel, blkno, &vmbuffer) != 0)
{
- elog(WARNING, "page is not marked all-visible but visibility map bit is set in relation \"%s\" page %u",
- vacrel->relname, blkno);
+ ereport(WARNING,
+ (errcode(ERRCODE_DATA_CORRUPTED),
+ errmsg("page is not marked all-visible but visibility map bit is set in relation \"%s\" page %u",
+ vacrel->relname, blkno)));
+
visibilitymap_clear(vacrel->rel, blkno, vmbuffer,
VISIBILITYMAP_VALID_BITS);
}
@@ -1582,8 +2146,11 @@ lazy_scan_prune(LVRelState *vacrel,
*/
else if (presult.lpdead_items > 0 && PageIsAllVisible(page))
{
- elog(WARNING, "page containing LP_DEAD items is marked as all-visible in relation \"%s\" page %u",
- vacrel->relname, blkno);
+ ereport(WARNING,
+ (errcode(ERRCODE_DATA_CORRUPTED),
+ errmsg("page containing LP_DEAD items is marked as all-visible in relation \"%s\" page %u",
+ vacrel->relname, blkno)));
+
PageClearAllVisible(page);
MarkBufferDirty(buf);
visibilitymap_clear(vacrel->rel, blkno, vmbuffer,
@@ -1598,6 +2165,8 @@ lazy_scan_prune(LVRelState *vacrel,
else if (all_visible_according_to_vm && presult.all_visible &&
presult.all_frozen && !VM_ALL_FROZEN(vacrel->rel, blkno, &vmbuffer))
{
+ uint8 old_vmbits;
+
/*
* Avoid relying on all_visible_according_to_vm as a proxy for the
* page-level PD_ALL_VISIBLE bit being set, since it might have become
@@ -1617,11 +2186,38 @@ lazy_scan_prune(LVRelState *vacrel,
* was logged when the page's tuples were frozen.
*/
Assert(!TransactionIdIsValid(presult.vm_conflict_horizon));
- visibilitymap_set(vacrel->rel, blkno, buf, InvalidXLogRecPtr,
- vmbuffer, InvalidTransactionId,
- VISIBILITYMAP_ALL_VISIBLE |
- VISIBILITYMAP_ALL_FROZEN);
+ old_vmbits = visibilitymap_set(vacrel->rel, blkno, buf,
+ InvalidXLogRecPtr,
+ vmbuffer, InvalidTransactionId,
+ VISIBILITYMAP_ALL_VISIBLE |
+ VISIBILITYMAP_ALL_FROZEN);
+
+ /*
+ * The page was likely already set all-visible in the VM. However,
+ * there is a small chance that it was modified sometime between
+ * setting all_visible_according_to_vm and checking the visibility
+ * during pruning. Check the return value of old_vmbits anyway to
+ * ensure the visibility map counters used for logging are accurate.
+ */
+ if ((old_vmbits & VISIBILITYMAP_ALL_VISIBLE) == 0)
+ {
+ vacrel->vm_new_visible_pages++;
+ vacrel->vm_new_visible_frozen_pages++;
+ *vm_page_frozen = true;
+ }
+
+ /*
+ * We already checked that the page was not set all-frozen in the VM
+ * above, so we don't need to test the value of old_vmbits.
+ */
+ else
+ {
+ vacrel->vm_new_frozen_pages++;
+ *vm_page_frozen = true;
+ }
}
+
+ return presult.ndeleted;
}
/*
@@ -1924,7 +2520,7 @@ lazy_vacuum(LVRelState *vacrel)
*/
threshold = (double) vacrel->rel_pages * BYPASS_THRESHOLD_PAGES;
bypass = (vacrel->lpdead_item_pages < threshold &&
- (TidStoreMemoryUsage(vacrel->dead_items) < (32L * 1024L * 1024L)));
+ TidStoreMemoryUsage(vacrel->dead_items) < 32 * 1024 * 1024);
}
if (bypass)
@@ -2080,6 +2676,34 @@ lazy_vacuum_all_indexes(LVRelState *vacrel)
return allindexes;
}
+/*
+ * Read stream callback for vacuum's third phase (second pass over the heap).
+ * Gets the next block from the TID store and returns it or InvalidBlockNumber
+ * if there are no further blocks to vacuum.
+ *
+ * NB: Assumed to be safe to use with READ_STREAM_USE_BATCHING.
+ */
+static BlockNumber
+vacuum_reap_lp_read_stream_next(ReadStream *stream,
+ void *callback_private_data,
+ void *per_buffer_data)
+{
+ TidStoreIter *iter = callback_private_data;
+ TidStoreIterResult *iter_result;
+
+ iter_result = TidStoreIterateNext(iter);
+ if (iter_result == NULL)
+ return InvalidBlockNumber;
+
+ /*
+ * Save the TidStoreIterResult for later, so we can extract the offsets.
+ * It is safe to copy the result, according to TidStoreIterateNext().
+ */
+ memcpy(per_buffer_data, iter_result, sizeof(*iter_result));
+
+ return iter_result->blkno;
+}
+
/*
* lazy_vacuum_heap_rel() -- second pass over the heap for two pass strategy
*
@@ -2100,11 +2724,11 @@ lazy_vacuum_all_indexes(LVRelState *vacrel)
static void
lazy_vacuum_heap_rel(LVRelState *vacrel)
{
+ ReadStream *stream;
BlockNumber vacuumed_pages = 0;
Buffer vmbuffer = InvalidBuffer;
LVSavedErrInfo saved_err_info;
TidStoreIter *iter;
- TidStoreIterResult *iter_result;
Assert(vacrel->do_index_vacuuming);
Assert(vacrel->do_index_cleanup);
@@ -2120,17 +2744,47 @@ lazy_vacuum_heap_rel(LVRelState *vacrel)
InvalidBlockNumber, InvalidOffsetNumber);
iter = TidStoreBeginIterate(vacrel->dead_items);
- while ((iter_result = TidStoreIterateNext(iter)) != NULL)
+
+ /*
+ * Set up the read stream for vacuum's second pass through the heap.
+ *
+ * It is safe to use batchmode, as vacuum_reap_lp_read_stream_next() does
+ * not need to wait for IO and does not perform locking. Once we support
+ * parallelism it should still be fine, as presumably the holder of locks
+ * would never be blocked by IO while holding the lock.
+ */
+ stream = read_stream_begin_relation(READ_STREAM_MAINTENANCE |
+ READ_STREAM_USE_BATCHING,
+ vacrel->bstrategy,
+ vacrel->rel,
+ MAIN_FORKNUM,
+ vacuum_reap_lp_read_stream_next,
+ iter,
+ sizeof(TidStoreIterResult));
+
+ while (true)
{
BlockNumber blkno;
Buffer buf;
Page page;
+ TidStoreIterResult *iter_result;
Size freespace;
+ OffsetNumber offsets[MaxOffsetNumber];
+ int num_offsets;
+
+ vacuum_delay_point(false);
+
+ buf = read_stream_next_buffer(stream, (void **) &iter_result);
+
+ /* The relation is exhausted */
+ if (!BufferIsValid(buf))
+ break;
- vacuum_delay_point();
+ vacrel->blkno = blkno = BufferGetBlockNumber(buf);
- blkno = iter_result->blkno;
- vacrel->blkno = blkno;
+ Assert(iter_result);
+ num_offsets = TidStoreGetBlockOffsets(iter_result, offsets, lengthof(offsets));
+ Assert(num_offsets <= lengthof(offsets));
/*
* Pin the visibility map page in case we need to mark the page
@@ -2140,11 +2794,9 @@ lazy_vacuum_heap_rel(LVRelState *vacrel)
visibilitymap_pin(vacrel->rel, blkno, &vmbuffer);
/* We need a non-cleanup exclusive lock to mark dead_items unused */
- buf = ReadBufferExtended(vacrel->rel, MAIN_FORKNUM, blkno, RBM_NORMAL,
- vacrel->bstrategy);
LockBuffer(buf, BUFFER_LOCK_EXCLUSIVE);
- lazy_vacuum_heap_page(vacrel, blkno, buf, iter_result->offsets,
- iter_result->num_offsets, vmbuffer);
+ lazy_vacuum_heap_page(vacrel, blkno, buf, offsets,
+ num_offsets, vmbuffer);
/* Now that we've vacuumed the page, record its available space */
page = BufferGetPage(buf);
@@ -2154,6 +2806,8 @@ lazy_vacuum_heap_rel(LVRelState *vacrel)
RecordPageWithFreeSpace(vacrel->rel, blkno, freespace);
vacuumed_pages++;
}
+
+ read_stream_end(stream);
TidStoreEndIterate(iter);
vacrel->blkno = InvalidBlockNumber;
@@ -2169,8 +2823,8 @@ lazy_vacuum_heap_rel(LVRelState *vacrel)
vacuumed_pages == vacrel->lpdead_item_pages));
ereport(DEBUG2,
- (errmsg("table \"%s\": removed %lld dead item identifiers in %u pages",
- vacrel->relname, (long long) vacrel->dead_items_info->num_items,
+ (errmsg("table \"%s\": removed %" PRId64 " dead item identifiers in %u pages",
+ vacrel->relname, vacrel->dead_items_info->num_items,
vacuumed_pages)));
/* Revert to the previous phase information for error traceback */
@@ -2270,8 +2924,15 @@ lazy_vacuum_heap_page(LVRelState *vacrel, BlockNumber blkno, Buffer buffer,
}
PageSetAllVisible(page);
- visibilitymap_set(vacrel->rel, blkno, buffer, InvalidXLogRecPtr,
- vmbuffer, visibility_cutoff_xid, flags);
+ visibilitymap_set(vacrel->rel, blkno, buffer,
+ InvalidXLogRecPtr,
+ vmbuffer, visibility_cutoff_xid,
+ flags);
+
+ /* Count the newly set VM page for logging */
+ vacrel->vm_new_visible_pages++;
+ if (all_frozen)
+ vacrel->vm_new_visible_frozen_pages++;
}
/* Revert to the previous phase information for error traceback */
@@ -2440,7 +3101,7 @@ lazy_vacuum_one_index(Relation indrel, IndexBulkDeleteResult *istat,
InvalidBlockNumber, InvalidOffsetNumber);
/* Do bulk deletion */
- istat = vac_bulkdel_one_index(&ivinfo, istat, (void *) vacrel->dead_items,
+ istat = vac_bulkdel_one_index(&ivinfo, istat, vacrel->dead_items,
vacrel->dead_items_info);
/* Revert to the previous phase information for error traceback */
@@ -2868,7 +3529,7 @@ dead_items_alloc(LVRelState *vacrel, int nworkers)
*/
dead_items_info = (VacDeadItemsInfo *) palloc(sizeof(VacDeadItemsInfo));
- dead_items_info->max_bytes = vac_work_mem * 1024L;
+ dead_items_info->max_bytes = vac_work_mem * (Size) 1024;
dead_items_info->num_items = 0;
vacrel->dead_items_info = dead_items_info;
@@ -2882,14 +3543,19 @@ static void
dead_items_add(LVRelState *vacrel, BlockNumber blkno, OffsetNumber *offsets,
int num_offsets)
{
- TidStore *dead_items = vacrel->dead_items;
+ const int prog_index[2] = {
+ PROGRESS_VACUUM_NUM_DEAD_ITEM_IDS,
+ PROGRESS_VACUUM_DEAD_TUPLE_BYTES
+ };
+ int64 prog_val[2];
- TidStoreSetBlockOffsets(dead_items, blkno, offsets, num_offsets);
+ TidStoreSetBlockOffsets(vacrel->dead_items, blkno, offsets, num_offsets);
vacrel->dead_items_info->num_items += num_offsets;
- /* update the memory usage report */
- pgstat_progress_update_param(PROGRESS_VACUUM_DEAD_TUPLE_BYTES,
- TidStoreMemoryUsage(dead_items));
+ /* update the progress information */
+ prog_val[0] = vacrel->dead_items_info->num_items;
+ prog_val[1] = TidStoreMemoryUsage(vacrel->dead_items);
+ pgstat_progress_update_multi_param(2, prog_index, prog_val);
}
/*
@@ -2898,8 +3564,6 @@ dead_items_add(LVRelState *vacrel, BlockNumber blkno, OffsetNumber *offsets,
static void
dead_items_reset(LVRelState *vacrel)
{
- TidStore *dead_items = vacrel->dead_items;
-
if (ParallelVacuumIsActive(vacrel))
{
parallel_vacuum_reset_dead_items(vacrel->pvs);
@@ -2907,7 +3571,7 @@ dead_items_reset(LVRelState *vacrel)
}
/* Recreate the tidstore with the same max_bytes limitation */
- TidStoreDestroy(dead_items);
+ TidStoreDestroy(vacrel->dead_items);
vacrel->dead_items = TidStoreCreateLocal(vacrel->dead_items_info->max_bytes, true);
/* Reset the counter */
@@ -3079,7 +3743,7 @@ update_relstats_all_indexes(LVRelState *vacrel)
vac_update_relstats(indrel,
istat->num_pages,
istat->num_index_tuples,
- 0,
+ 0, 0,
false,
InvalidTransactionId,
InvalidMultiXactId,
diff --git a/src/backend/access/heap/visibilitymap.c b/src/backend/access/heap/visibilitymap.c
index 8b24e7bc33cf6..7306c16f05cd3 100644
--- a/src/backend/access/heap/visibilitymap.c
+++ b/src/backend/access/heap/visibilitymap.c
@@ -3,7 +3,7 @@
* visibilitymap.c
* bitmap for tracking visibility of heap tuples
*
- * Portions Copyright (c) 1996-2024, PostgreSQL Global Development Group
+ * Portions Copyright (c) 1996-2025, PostgreSQL Global Development Group
* Portions Copyright (c) 1994, Regents of the University of California
*
*
@@ -239,8 +239,10 @@ visibilitymap_pin_ok(BlockNumber heapBlk, Buffer vmbuf)
* You must pass a buffer containing the correct map page to this function.
* Call visibilitymap_pin first to pin the right one. This function doesn't do
* any I/O.
+ *
+ * Returns the state of the page's VM bits before setting flags.
*/
-void
+uint8
visibilitymap_set(Relation rel, BlockNumber heapBlk, Buffer heapBuf,
XLogRecPtr recptr, Buffer vmBuf, TransactionId cutoff_xid,
uint8 flags)
@@ -250,13 +252,15 @@ visibilitymap_set(Relation rel, BlockNumber heapBlk, Buffer heapBuf,
uint8 mapOffset = HEAPBLK_TO_OFFSET(heapBlk);
Page page;
uint8 *map;
+ uint8 status;
#ifdef TRACE_VISIBILITYMAP
- elog(DEBUG1, "vm_set %s %d", RelationGetRelationName(rel), heapBlk);
+ elog(DEBUG1, "vm_set flags 0x%02X for %s %d",
+ flags, RelationGetRelationName(rel), heapBlk);
#endif
Assert(InRecovery || XLogRecPtrIsInvalid(recptr));
- Assert(InRecovery || PageIsAllVisible((Page) BufferGetPage(heapBuf)));
+ Assert(InRecovery || PageIsAllVisible(BufferGetPage(heapBuf)));
Assert((flags & VISIBILITYMAP_VALID_BITS) == flags);
/* Must never set all_frozen bit without also setting all_visible bit */
@@ -266,6 +270,8 @@ visibilitymap_set(Relation rel, BlockNumber heapBlk, Buffer heapBuf,
if (BufferIsValid(heapBuf) && BufferGetBlockNumber(heapBuf) != heapBlk)
elog(ERROR, "wrong heap buffer passed to visibilitymap_set");
+ Assert(!BufferIsValid(heapBuf) || BufferIsExclusiveLocked(heapBuf));
+
/* Check that we have the right VM page pinned */
if (!BufferIsValid(vmBuf) || BufferGetBlockNumber(vmBuf) != mapBlock)
elog(ERROR, "wrong VM buffer passed to visibilitymap_set");
@@ -274,7 +280,8 @@ visibilitymap_set(Relation rel, BlockNumber heapBlk, Buffer heapBuf,
map = (uint8 *) PageGetContents(page);
LockBuffer(vmBuf, BUFFER_LOCK_EXCLUSIVE);
- if (flags != (map[mapByte] >> mapOffset & VISIBILITYMAP_VALID_BITS))
+ status = (map[mapByte] >> mapOffset) & VISIBILITYMAP_VALID_BITS;
+ if (flags != status)
{
START_CRIT_SECTION();
@@ -311,6 +318,7 @@ visibilitymap_set(Relation rel, BlockNumber heapBlk, Buffer heapBuf,
}
LockBuffer(vmBuf, BUFFER_LOCK_UNLOCK);
+ return status;
}
/*
@@ -359,7 +367,7 @@ visibilitymap_get_status(Relation rel, BlockNumber heapBlk, Buffer *vmbuf)
{
*vmbuf = vm_readbuf(rel, mapBlock, false);
if (!BufferIsValid(*vmbuf))
- return false;
+ return (uint8) 0;
}
map = PageGetContents(BufferGetPage(*vmbuf));
diff --git a/src/backend/access/index/amapi.c b/src/backend/access/index/amapi.c
index 079fb7cba65ef..60684c5342279 100644
--- a/src/backend/access/index/amapi.c
+++ b/src/backend/access/index/amapi.c
@@ -3,7 +3,7 @@
* amapi.c
* Support routines for API for Postgres index access methods.
*
- * Copyright (c) 2015-2024, PostgreSQL Global Development Group
+ * Copyright (c) 2015-2025, PostgreSQL Global Development Group
*
*
* IDENTIFICATION
@@ -42,6 +42,19 @@ GetIndexAmRoutine(Oid amhandler)
elog(ERROR, "index access method handler function %u did not return an IndexAmRoutine struct",
amhandler);
+ /* Assert that all required callbacks are present. */
+ Assert(routine->ambuild != NULL);
+ Assert(routine->ambuildempty != NULL);
+ Assert(routine->aminsert != NULL);
+ Assert(routine->ambulkdelete != NULL);
+ Assert(routine->amvacuumcleanup != NULL);
+ Assert(routine->amcostestimate != NULL);
+ Assert(routine->amoptions != NULL);
+ Assert(routine->amvalidate != NULL);
+ Assert(routine->ambeginscan != NULL);
+ Assert(routine->amrescan != NULL);
+ Assert(routine->amendscan != NULL);
+
return routine;
}
@@ -107,6 +120,66 @@ GetIndexAmRoutineByAmId(Oid amoid, bool noerror)
}
+/*
+ * IndexAmTranslateStrategy - given an access method and strategy, get the
+ * corresponding compare type.
+ *
+ * If missing_ok is false, throw an error if no compare type is found. If
+ * true, just return COMPARE_INVALID.
+ */
+CompareType
+IndexAmTranslateStrategy(StrategyNumber strategy, Oid amoid, Oid opfamily, bool missing_ok)
+{
+ CompareType result;
+ IndexAmRoutine *amroutine;
+
+ /* shortcut for common case */
+ if (amoid == BTREE_AM_OID &&
+ (strategy > InvalidStrategy && strategy <= BTMaxStrategyNumber))
+ return (CompareType) strategy;
+
+ amroutine = GetIndexAmRoutineByAmId(amoid, false);
+ if (amroutine->amtranslatestrategy)
+ result = amroutine->amtranslatestrategy(strategy, opfamily);
+ else
+ result = COMPARE_INVALID;
+
+ if (!missing_ok && result == COMPARE_INVALID)
+ elog(ERROR, "could not translate strategy number %d for index AM %u", strategy, amoid);
+
+ return result;
+}
+
+/*
+ * IndexAmTranslateCompareType - given an access method and compare type, get
+ * the corresponding strategy number.
+ *
+ * If missing_ok is false, throw an error if no strategy is found correlating
+ * to the given cmptype. If true, just return InvalidStrategy.
+ */
+StrategyNumber
+IndexAmTranslateCompareType(CompareType cmptype, Oid amoid, Oid opfamily, bool missing_ok)
+{
+ StrategyNumber result;
+ IndexAmRoutine *amroutine;
+
+ /* shortcut for common case */
+ if (amoid == BTREE_AM_OID &&
+ (cmptype > COMPARE_INVALID && cmptype <= COMPARE_GT))
+ return (StrategyNumber) cmptype;
+
+ amroutine = GetIndexAmRoutineByAmId(amoid, false);
+ if (amroutine->amtranslatecmptype)
+ result = amroutine->amtranslatecmptype(cmptype, opfamily);
+ else
+ result = InvalidStrategy;
+
+ if (!missing_ok && result == InvalidStrategy)
+ elog(ERROR, "could not translate compare type %u for index AM %u", cmptype, amoid);
+
+ return result;
+}
+
/*
* Ask appropriate access method to validate the specified opclass.
*/
diff --git a/src/backend/access/index/amvalidate.c b/src/backend/access/index/amvalidate.c
index 32bb477f3283c..4cf237019adaf 100644
--- a/src/backend/access/index/amvalidate.c
+++ b/src/backend/access/index/amvalidate.c
@@ -4,7 +4,7 @@
* Support routines for index access methods' amvalidate and
* amadjustmembers functions.
*
- * Copyright (c) 2016-2024, PostgreSQL Global Development Group
+ * Copyright (c) 2016-2025, PostgreSQL Global Development Group
*
*
* IDENTIFICATION
diff --git a/src/backend/access/index/genam.c b/src/backend/access/index/genam.c
index de751e8e4a30a..0cb27af131095 100644
--- a/src/backend/access/index/genam.c
+++ b/src/backend/access/index/genam.c
@@ -3,7 +3,7 @@
* genam.c
* general index access method routines
*
- * Portions Copyright (c) 1996-2024, PostgreSQL Global Development Group
+ * Portions Copyright (c) 1996-2025, PostgreSQL Global Development Group
* Portions Copyright (c) 1994, Regents of the University of California
*
*
@@ -20,6 +20,7 @@
#include "postgres.h"
#include "access/genam.h"
+#include "access/heapam.h"
#include "access/relscan.h"
#include "access/tableam.h"
#include "access/transam.h"
@@ -29,6 +30,7 @@
#include "storage/bufmgr.h"
#include "storage/procarray.h"
#include "utils/acl.h"
+#include "utils/injection_point.h"
#include "utils/lsyscache.h"
#include "utils/rel.h"
#include "utils/rls.h"
@@ -117,6 +119,7 @@ RelationGetIndexScan(Relation indexRelation, int nkeys, int norderbys)
scan->ignore_killed_tuples = !scan->xactStartedInRecovery;
scan->opaque = NULL;
+ scan->instrument = NULL;
scan->xs_itup = NULL;
scan->xs_itupdesc = NULL;
@@ -154,8 +157,9 @@ IndexScanEnd(IndexScanDesc scan)
*
* Construct a string describing the contents of an index entry, in the
* form "(key_name, ...)=(key_value, ...)". This is currently used
- * for building unique-constraint and exclusion-constraint error messages,
- * so only key columns of the index are checked and printed.
+ * for building unique-constraint, exclusion-constraint error messages, and
+ * logical replication conflict error messages so only key columns of the index
+ * are checked and printed.
*
* Note that if the user does not have permissions to view all of the
* columns involved then a NULL is returned. Returning a partial key seems
@@ -371,7 +375,7 @@ index_compute_xid_horizon_for_tuples(Relation irel,
* nkeys, key: scan keys
*
* The attribute numbers in the scan key should be set for the heap case.
- * If we choose to index, we reset them to 1..n to reference the index
+ * If we choose to index, we convert them to 1..n to reference the index
* columns. Note this means there must be one scankey qualification per
* index column! This is checked by the Asserts in the normal, index-using
* case, but won't be checked if the heapscan path is taken.
@@ -419,17 +423,22 @@ systable_beginscan(Relation heapRelation,
if (irel)
{
int i;
+ ScanKey idxkey;
- /* Change attribute numbers to be index column numbers. */
+ idxkey = palloc_array(ScanKeyData, nkeys);
+
+ /* Convert attribute numbers to be index column numbers. */
for (i = 0; i < nkeys; i++)
{
int j;
+ memcpy(&idxkey[i], &key[i], sizeof(ScanKeyData));
+
for (j = 0; j < IndexRelationGetNumberOfAttributes(irel); j++)
{
if (key[i].sk_attno == irel->rd_index->indkey.values[j])
{
- key[i].sk_attno = j + 1;
+ idxkey[i].sk_attno = j + 1;
break;
}
}
@@ -438,9 +447,11 @@ systable_beginscan(Relation heapRelation,
}
sysscan->iscan = index_beginscan(heapRelation, irel,
- snapshot, nkeys, 0);
- index_rescan(sysscan->iscan, key, nkeys, NULL, 0);
+ snapshot, NULL, nkeys, 0);
+ index_rescan(sysscan->iscan, idxkey, nkeys, NULL, 0);
sysscan->scan = NULL;
+
+ pfree(idxkey);
}
else
{
@@ -566,17 +577,13 @@ systable_recheck_tuple(SysScanDesc sysscan, HeapTuple tup)
Assert(tup == ExecFetchSlotHeapTuple(sysscan->slot, false, NULL));
- /*
- * Trust that table_tuple_satisfies_snapshot() and its subsidiaries
- * (commonly LockBuffer() and HeapTupleSatisfiesMVCC()) do not themselves
- * acquire snapshots, so we need not register the snapshot. Those
- * facilities are too low-level to have any business scanning tables.
- */
freshsnap = GetCatalogSnapshot(RelationGetRelid(sysscan->heap_rel));
+ freshsnap = RegisterSnapshot(freshsnap);
result = table_tuple_satisfies_snapshot(sysscan->heap_rel,
sysscan->slot,
freshsnap);
+ UnregisterSnapshot(freshsnap);
/*
* Handle the concurrent abort while fetching the catalog tuple during
@@ -647,6 +654,7 @@ systable_beginscan_ordered(Relation heapRelation,
{
SysScanDesc sysscan;
int i;
+ ScanKey idxkey;
/* REINDEX can probably be a hard error here ... */
if (ReindexIsProcessingIndex(RelationGetRelid(indexRelation)))
@@ -678,16 +686,20 @@ systable_beginscan_ordered(Relation heapRelation,
sysscan->snapshot = NULL;
}
- /* Change attribute numbers to be index column numbers. */
+ idxkey = palloc_array(ScanKeyData, nkeys);
+
+ /* Convert attribute numbers to be index column numbers. */
for (i = 0; i < nkeys; i++)
{
int j;
+ memcpy(&idxkey[i], &key[i], sizeof(ScanKeyData));
+
for (j = 0; j < IndexRelationGetNumberOfAttributes(indexRelation); j++)
{
if (key[i].sk_attno == indexRelation->rd_index->indkey.values[j])
{
- key[i].sk_attno = j + 1;
+ idxkey[i].sk_attno = j + 1;
break;
}
}
@@ -696,10 +708,20 @@ systable_beginscan_ordered(Relation heapRelation,
}
sysscan->iscan = index_beginscan(heapRelation, indexRelation,
- snapshot, nkeys, 0);
- index_rescan(sysscan->iscan, key, nkeys, NULL, 0);
+ snapshot, NULL, nkeys, 0);
+ index_rescan(sysscan->iscan, idxkey, nkeys, NULL, 0);
sysscan->scan = NULL;
+ pfree(idxkey);
+
+ /*
+ * If CheckXidAlive is set then set a flag to indicate that system table
+ * scan is in-progress. See detailed comments in xact.c where these
+ * variables are declared.
+ */
+ if (TransactionIdIsValid(CheckXidAlive))
+ bsysscan = true;
+
return sysscan;
}
@@ -744,5 +766,148 @@ systable_endscan_ordered(SysScanDesc sysscan)
index_endscan(sysscan->iscan);
if (sysscan->snapshot)
UnregisterSnapshot(sysscan->snapshot);
+
+ /*
+ * Reset the bsysscan flag at the end of the systable scan. See detailed
+ * comments in xact.c where these variables are declared.
+ */
+ if (TransactionIdIsValid(CheckXidAlive))
+ bsysscan = false;
+
pfree(sysscan);
}
+
+/*
+ * systable_inplace_update_begin --- update a row "in place" (overwrite it)
+ *
+ * Overwriting violates both MVCC and transactional safety, so the uses of
+ * this function in Postgres are extremely limited. Nonetheless we find some
+ * places to use it. See README.tuplock section "Locking to write
+ * inplace-updated tables" and later sections for expectations of readers and
+ * writers of a table that gets inplace updates. Standard flow:
+ *
+ * ... [any slow preparation not requiring oldtup] ...
+ * systable_inplace_update_begin([...], &tup, &inplace_state);
+ * if (!HeapTupleIsValid(tup))
+ * elog(ERROR, [...]);
+ * ... [buffer is exclusive-locked; mutate "tup"] ...
+ * if (dirty)
+ * systable_inplace_update_finish(inplace_state, tup);
+ * else
+ * systable_inplace_update_cancel(inplace_state);
+ *
+ * The first several params duplicate the systable_beginscan() param list.
+ * "oldtupcopy" is an output parameter, assigned NULL if the key ceases to
+ * find a live tuple. (In PROC_IN_VACUUM, that is a low-probability transient
+ * condition.) If "oldtupcopy" gets non-NULL, you must pass output parameter
+ * "state" to systable_inplace_update_finish() or
+ * systable_inplace_update_cancel().
+ */
+void
+systable_inplace_update_begin(Relation relation,
+ Oid indexId,
+ bool indexOK,
+ Snapshot snapshot,
+ int nkeys, const ScanKeyData *key,
+ HeapTuple *oldtupcopy,
+ void **state)
+{
+ int retries = 0;
+ SysScanDesc scan;
+ HeapTuple oldtup;
+ BufferHeapTupleTableSlot *bslot;
+
+ /*
+ * For now, we don't allow parallel updates. Unlike a regular update,
+ * this should never create a combo CID, so it might be possible to relax
+ * this restriction, but not without more thought and testing. It's not
+ * clear that it would be useful, anyway.
+ */
+ if (IsInParallelMode())
+ ereport(ERROR,
+ (errcode(ERRCODE_INVALID_TRANSACTION_STATE),
+ errmsg("cannot update tuples during a parallel operation")));
+
+ /*
+ * Accept a snapshot argument, for symmetry, but this function advances
+ * its snapshot as needed to reach the tail of the updated tuple chain.
+ */
+ Assert(snapshot == NULL);
+
+ Assert(IsInplaceUpdateRelation(relation) || !IsSystemRelation(relation));
+
+ /* Loop for an exclusive-locked buffer of a non-updated tuple. */
+ do
+ {
+ TupleTableSlot *slot;
+
+ CHECK_FOR_INTERRUPTS();
+
+ /*
+ * Processes issuing heap_update (e.g. GRANT) at maximum speed could
+ * drive us to this error. A hostile table owner has stronger ways to
+ * damage their own table, so that's minor.
+ */
+ if (retries++ > 10000)
+ elog(ERROR, "giving up after too many tries to overwrite row");
+
+ INJECTION_POINT("inplace-before-pin", NULL);
+ scan = systable_beginscan(relation, indexId, indexOK, snapshot,
+ nkeys, unconstify(ScanKeyData *, key));
+ oldtup = systable_getnext(scan);
+ if (!HeapTupleIsValid(oldtup))
+ {
+ systable_endscan(scan);
+ *oldtupcopy = NULL;
+ return;
+ }
+
+ slot = scan->slot;
+ Assert(TTS_IS_BUFFERTUPLE(slot));
+ bslot = (BufferHeapTupleTableSlot *) slot;
+ } while (!heap_inplace_lock(scan->heap_rel,
+ bslot->base.tuple, bslot->buffer,
+ (void (*) (void *)) systable_endscan, scan));
+
+ *oldtupcopy = heap_copytuple(oldtup);
+ *state = scan;
+}
+
+/*
+ * systable_inplace_update_finish --- second phase of inplace update
+ *
+ * The tuple cannot change size, and therefore its header fields and null
+ * bitmap (if any) don't change either.
+ */
+void
+systable_inplace_update_finish(void *state, HeapTuple tuple)
+{
+ SysScanDesc scan = (SysScanDesc) state;
+ Relation relation = scan->heap_rel;
+ TupleTableSlot *slot = scan->slot;
+ BufferHeapTupleTableSlot *bslot = (BufferHeapTupleTableSlot *) slot;
+ HeapTuple oldtup = bslot->base.tuple;
+ Buffer buffer = bslot->buffer;
+
+ heap_inplace_update_and_unlock(relation, oldtup, tuple, buffer);
+ systable_endscan(scan);
+}
+
+/*
+ * systable_inplace_update_cancel --- abandon inplace update
+ *
+ * This is an alternative to making a no-op update.
+ */
+void
+systable_inplace_update_cancel(void *state)
+{
+ SysScanDesc scan = (SysScanDesc) state;
+ Relation relation = scan->heap_rel;
+ TupleTableSlot *slot = scan->slot;
+ BufferHeapTupleTableSlot *bslot = (BufferHeapTupleTableSlot *) slot;
+ HeapTuple oldtup = bslot->base.tuple;
+ Buffer buffer = bslot->buffer;
+
+ heap_inplace_unlock(relation, oldtup, buffer);
+ systable_endscan(scan);
+}
diff --git a/src/backend/access/index/indexam.c b/src/backend/access/index/indexam.c
index dcd04b813d8d9..86d11f4ec791d 100644
--- a/src/backend/access/index/indexam.c
+++ b/src/backend/access/index/indexam.c
@@ -3,7 +3,7 @@
* indexam.c
* general index access method routines
*
- * Portions Copyright (c) 1996-2024, PostgreSQL Global Development Group
+ * Portions Copyright (c) 1996-2025, PostgreSQL Global Development Group
* Portions Copyright (c) 1994, Regents of the University of California
*
*
@@ -256,12 +256,23 @@ IndexScanDesc
index_beginscan(Relation heapRelation,
Relation indexRelation,
Snapshot snapshot,
+ IndexScanInstrumentation *instrument,
int nkeys, int norderbys)
{
IndexScanDesc scan;
Assert(snapshot != InvalidSnapshot);
+ /* Check that a historic snapshot is not used for non-catalog tables */
+ if (IsHistoricMVCCSnapshot(snapshot) &&
+ !RelationIsAccessibleInLogicalDecoding(heapRelation))
+ {
+ ereport(ERROR,
+ (errcode(ERRCODE_INVALID_TRANSACTION_STATE),
+ errmsg("cannot query non-catalog table \"%s\" during logical decoding",
+ RelationGetRelationName(heapRelation))));
+ }
+
scan = index_beginscan_internal(indexRelation, nkeys, norderbys, snapshot, NULL, false);
/*
@@ -270,6 +281,7 @@ index_beginscan(Relation heapRelation,
*/
scan->heapRelation = heapRelation;
scan->xs_snapshot = snapshot;
+ scan->instrument = instrument;
/* prepare to fetch index matches from table */
scan->xs_heapfetch = table_index_fetch_begin(heapRelation);
@@ -286,6 +298,7 @@ index_beginscan(Relation heapRelation,
IndexScanDesc
index_beginscan_bitmap(Relation indexRelation,
Snapshot snapshot,
+ IndexScanInstrumentation *instrument,
int nkeys)
{
IndexScanDesc scan;
@@ -299,6 +312,7 @@ index_beginscan_bitmap(Relation indexRelation,
* up by RelationGetIndexScan.
*/
scan->xs_snapshot = snapshot;
+ scan->instrument = instrument;
return scan;
}
@@ -448,14 +462,19 @@ index_restrpos(IndexScanDesc scan)
/*
* index_parallelscan_estimate - estimate shared memory for parallel scan
+ *
+ * When instrument=true, estimate includes SharedIndexScanInstrumentation
+ * space. When parallel_aware=true, estimate includes whatever space the
+ * index AM's amestimateparallelscan routine requested when called.
*/
Size
index_parallelscan_estimate(Relation indexRelation, int nkeys, int norderbys,
- Snapshot snapshot)
+ Snapshot snapshot, bool instrument,
+ bool parallel_aware, int nworkers)
{
Size nbytes;
- Assert(snapshot != InvalidSnapshot);
+ Assert(instrument || parallel_aware);
RELATION_CHECKS;
@@ -463,14 +482,25 @@ index_parallelscan_estimate(Relation indexRelation, int nkeys, int norderbys,
nbytes = add_size(nbytes, EstimateSnapshotSpace(snapshot));
nbytes = MAXALIGN(nbytes);
+ if (instrument)
+ {
+ Size sharedinfosz;
+
+ sharedinfosz = offsetof(SharedIndexScanInstrumentation, winstrument) +
+ nworkers * sizeof(IndexScanInstrumentation);
+ nbytes = add_size(nbytes, sharedinfosz);
+ nbytes = MAXALIGN(nbytes);
+ }
+
/*
- * If amestimateparallelscan is not provided, assume there is no
- * AM-specific data needed. (It's hard to believe that could work, but
- * it's easy enough to cater to it here.)
+ * If parallel scan index AM interface can't be used (or index AM provides
+ * no such interface), assume there is no AM-specific data needed
*/
- if (indexRelation->rd_indam->amestimateparallelscan != NULL)
+ if (parallel_aware &&
+ indexRelation->rd_indam->amestimateparallelscan != NULL)
nbytes = add_size(nbytes,
- indexRelation->rd_indam->amestimateparallelscan(nkeys,
+ indexRelation->rd_indam->amestimateparallelscan(indexRelation,
+ nkeys,
norderbys));
return nbytes;
@@ -488,11 +518,14 @@ index_parallelscan_estimate(Relation indexRelation, int nkeys, int norderbys,
*/
void
index_parallelscan_initialize(Relation heapRelation, Relation indexRelation,
- Snapshot snapshot, ParallelIndexScanDesc target)
+ Snapshot snapshot, bool instrument,
+ bool parallel_aware, int nworkers,
+ SharedIndexScanInstrumentation **sharedinfo,
+ ParallelIndexScanDesc target)
{
Size offset;
- Assert(snapshot != InvalidSnapshot);
+ Assert(instrument || parallel_aware);
RELATION_CHECKS;
@@ -500,17 +533,36 @@ index_parallelscan_initialize(Relation heapRelation, Relation indexRelation,
EstimateSnapshotSpace(snapshot));
offset = MAXALIGN(offset);
- target->ps_relid = RelationGetRelid(heapRelation);
- target->ps_indexid = RelationGetRelid(indexRelation);
- target->ps_offset = offset;
+ target->ps_locator = heapRelation->rd_locator;
+ target->ps_indexlocator = indexRelation->rd_locator;
+ target->ps_offset_ins = 0;
+ target->ps_offset_am = 0;
SerializeSnapshot(snapshot, target->ps_snapshot_data);
+ if (instrument)
+ {
+ Size sharedinfosz;
+
+ target->ps_offset_ins = offset;
+ sharedinfosz = offsetof(SharedIndexScanInstrumentation, winstrument) +
+ nworkers * sizeof(IndexScanInstrumentation);
+ offset = add_size(offset, sharedinfosz);
+ offset = MAXALIGN(offset);
+
+ /* Set leader's *sharedinfo pointer, and initialize stats */
+ *sharedinfo = (SharedIndexScanInstrumentation *)
+ OffsetToPointer(target, target->ps_offset_ins);
+ memset(*sharedinfo, 0, sharedinfosz);
+ (*sharedinfo)->num_workers = nworkers;
+ }
+
/* aminitparallelscan is optional; assume no-op if not provided by AM */
- if (indexRelation->rd_indam->aminitparallelscan != NULL)
+ if (parallel_aware && indexRelation->rd_indam->aminitparallelscan != NULL)
{
void *amtarget;
- amtarget = OffsetToPointer(target, offset);
+ target->ps_offset_am = offset;
+ amtarget = OffsetToPointer(target, target->ps_offset_am);
indexRelation->rd_indam->aminitparallelscan(amtarget);
}
}
@@ -538,13 +590,17 @@ index_parallelrescan(IndexScanDesc scan)
* Caller must be holding suitable locks on the heap and the index.
*/
IndexScanDesc
-index_beginscan_parallel(Relation heaprel, Relation indexrel, int nkeys,
- int norderbys, ParallelIndexScanDesc pscan)
+index_beginscan_parallel(Relation heaprel, Relation indexrel,
+ IndexScanInstrumentation *instrument,
+ int nkeys, int norderbys,
+ ParallelIndexScanDesc pscan)
{
Snapshot snapshot;
IndexScanDesc scan;
- Assert(RelationGetRelid(heaprel) == pscan->ps_relid);
+ Assert(RelFileLocatorEquals(heaprel->rd_locator, pscan->ps_locator));
+ Assert(RelFileLocatorEquals(indexrel->rd_locator, pscan->ps_indexlocator));
+
snapshot = RestoreSnapshot(pscan->ps_snapshot_data);
RegisterSnapshot(snapshot);
scan = index_beginscan_internal(indexrel, nkeys, norderbys, snapshot,
@@ -556,6 +612,7 @@ index_beginscan_parallel(Relation heaprel, Relation indexrel, int nkeys,
*/
scan->heapRelation = heaprel;
scan->xs_snapshot = snapshot;
+ scan->instrument = instrument;
/* prepare to fetch index matches from table */
scan->xs_heapfetch = table_index_fetch_begin(heaprel);
@@ -939,11 +996,6 @@ index_store_float8_orderby_distances(IndexScanDesc scan, Oid *orderByTypes,
{
if (orderByTypes[i] == FLOAT8OID)
{
-#ifndef USE_FLOAT8_BYVAL
- /* must free any old value to avoid memory leakage */
- if (!scan->xs_orderbynulls[i])
- pfree(DatumGetPointer(scan->xs_orderbyvals[i]));
-#endif
if (distances && !distances[i].isnull)
{
scan->xs_orderbyvals[i] = Float8GetDatum(distances[i].value);
diff --git a/src/backend/access/index/meson.build b/src/backend/access/index/meson.build
index 641b5bd0c272e..e29c03089fd6d 100644
--- a/src/backend/access/index/meson.build
+++ b/src/backend/access/index/meson.build
@@ -1,4 +1,4 @@
-# Copyright (c) 2022-2024, PostgreSQL Global Development Group
+# Copyright (c) 2022-2025, PostgreSQL Global Development Group
backend_sources += files(
'amapi.c',
diff --git a/src/backend/access/meson.build b/src/backend/access/meson.build
index 62a371db7f75c..7a2d0ddb68942 100644
--- a/src/backend/access/meson.build
+++ b/src/backend/access/meson.build
@@ -1,4 +1,4 @@
-# Copyright (c) 2022-2024, PostgreSQL Global Development Group
+# Copyright (c) 2022-2025, PostgreSQL Global Development Group
subdir('brin')
subdir('common')
diff --git a/src/backend/access/nbtree/Makefile b/src/backend/access/nbtree/Makefile
index d69808e78c61e..c5cd4e0177fa5 100644
--- a/src/backend/access/nbtree/Makefile
+++ b/src/backend/access/nbtree/Makefile
@@ -17,6 +17,7 @@ OBJS = \
nbtdedup.o \
nbtinsert.o \
nbtpage.o \
+ nbtpreprocesskeys.o \
nbtree.o \
nbtsearch.o \
nbtsort.o \
diff --git a/src/backend/access/nbtree/README b/src/backend/access/nbtree/README
index 52e646c7f759a..53d4a61dc3f19 100644
--- a/src/backend/access/nbtree/README
+++ b/src/backend/access/nbtree/README
@@ -99,9 +99,9 @@ cannot miss any items it should have seen, nor accidentally return the same
item twice. The scan must remember the page's right-link at the time it
was scanned, since that is the page to move right to; if we move right to
the current right-link then we'd re-scan any items moved by a page split.
-We don't similarly remember the left-link, since it's best to use the most
-up-to-date left-link when trying to move left (see detailed move-left
-algorithm below).
+We also remember the left-link, and follow it when the scan moves backwards
+(though this requires extra handling to account for concurrent splits of
+the left sibling; see detailed move-left algorithm below).
In most cases we release our lock and pin on a page before attempting
to acquire pin and lock on the page we are moving to. In a few places
diff --git a/src/backend/access/nbtree/meson.build b/src/backend/access/nbtree/meson.build
index 232f64b9447d8..80962de6e6ed9 100644
--- a/src/backend/access/nbtree/meson.build
+++ b/src/backend/access/nbtree/meson.build
@@ -1,10 +1,11 @@
-# Copyright (c) 2022-2024, PostgreSQL Global Development Group
+# Copyright (c) 2022-2025, PostgreSQL Global Development Group
backend_sources += files(
'nbtcompare.c',
'nbtdedup.c',
'nbtinsert.c',
'nbtpage.c',
+ 'nbtpreprocesskeys.c',
'nbtree.c',
'nbtsearch.c',
'nbtsort.c',
diff --git a/src/backend/access/nbtree/nbtcompare.c b/src/backend/access/nbtree/nbtcompare.c
index 1c72867c84e5e..188c27b4925f7 100644
--- a/src/backend/access/nbtree/nbtcompare.c
+++ b/src/backend/access/nbtree/nbtcompare.c
@@ -3,7 +3,7 @@
* nbtcompare.c
* Comparison functions for btree access method.
*
- * Portions Copyright (c) 1996-2024, PostgreSQL Global Development Group
+ * Portions Copyright (c) 1996-2025, PostgreSQL Global Development Group
* Portions Copyright (c) 1994, Regents of the University of California
*
*
@@ -58,6 +58,7 @@
#include
#include "utils/fmgrprotos.h"
+#include "utils/skipsupport.h"
#include "utils/sortsupport.h"
#ifdef STRESS_SORT_INT_MIN
@@ -78,6 +79,51 @@ btboolcmp(PG_FUNCTION_ARGS)
PG_RETURN_INT32((int32) a - (int32) b);
}
+static Datum
+bool_decrement(Relation rel, Datum existing, bool *underflow)
+{
+ bool bexisting = DatumGetBool(existing);
+
+ if (bexisting == false)
+ {
+ /* return value is undefined */
+ *underflow = true;
+ return (Datum) 0;
+ }
+
+ *underflow = false;
+ return BoolGetDatum(bexisting - 1);
+}
+
+static Datum
+bool_increment(Relation rel, Datum existing, bool *overflow)
+{
+ bool bexisting = DatumGetBool(existing);
+
+ if (bexisting == true)
+ {
+ /* return value is undefined */
+ *overflow = true;
+ return (Datum) 0;
+ }
+
+ *overflow = false;
+ return BoolGetDatum(bexisting + 1);
+}
+
+Datum
+btboolskipsupport(PG_FUNCTION_ARGS)
+{
+ SkipSupport sksup = (SkipSupport) PG_GETARG_POINTER(0);
+
+ sksup->decrement = bool_decrement;
+ sksup->increment = bool_increment;
+ sksup->low_elem = BoolGetDatum(false);
+ sksup->high_elem = BoolGetDatum(true);
+
+ PG_RETURN_VOID();
+}
+
Datum
btint2cmp(PG_FUNCTION_ARGS)
{
@@ -105,6 +151,51 @@ btint2sortsupport(PG_FUNCTION_ARGS)
PG_RETURN_VOID();
}
+static Datum
+int2_decrement(Relation rel, Datum existing, bool *underflow)
+{
+ int16 iexisting = DatumGetInt16(existing);
+
+ if (iexisting == PG_INT16_MIN)
+ {
+ /* return value is undefined */
+ *underflow = true;
+ return (Datum) 0;
+ }
+
+ *underflow = false;
+ return Int16GetDatum(iexisting - 1);
+}
+
+static Datum
+int2_increment(Relation rel, Datum existing, bool *overflow)
+{
+ int16 iexisting = DatumGetInt16(existing);
+
+ if (iexisting == PG_INT16_MAX)
+ {
+ /* return value is undefined */
+ *overflow = true;
+ return (Datum) 0;
+ }
+
+ *overflow = false;
+ return Int16GetDatum(iexisting + 1);
+}
+
+Datum
+btint2skipsupport(PG_FUNCTION_ARGS)
+{
+ SkipSupport sksup = (SkipSupport) PG_GETARG_POINTER(0);
+
+ sksup->decrement = int2_decrement;
+ sksup->increment = int2_increment;
+ sksup->low_elem = Int16GetDatum(PG_INT16_MIN);
+ sksup->high_elem = Int16GetDatum(PG_INT16_MAX);
+
+ PG_RETURN_VOID();
+}
+
Datum
btint4cmp(PG_FUNCTION_ARGS)
{
@@ -128,6 +219,51 @@ btint4sortsupport(PG_FUNCTION_ARGS)
PG_RETURN_VOID();
}
+static Datum
+int4_decrement(Relation rel, Datum existing, bool *underflow)
+{
+ int32 iexisting = DatumGetInt32(existing);
+
+ if (iexisting == PG_INT32_MIN)
+ {
+ /* return value is undefined */
+ *underflow = true;
+ return (Datum) 0;
+ }
+
+ *underflow = false;
+ return Int32GetDatum(iexisting - 1);
+}
+
+static Datum
+int4_increment(Relation rel, Datum existing, bool *overflow)
+{
+ int32 iexisting = DatumGetInt32(existing);
+
+ if (iexisting == PG_INT32_MAX)
+ {
+ /* return value is undefined */
+ *overflow = true;
+ return (Datum) 0;
+ }
+
+ *overflow = false;
+ return Int32GetDatum(iexisting + 1);
+}
+
+Datum
+btint4skipsupport(PG_FUNCTION_ARGS)
+{
+ SkipSupport sksup = (SkipSupport) PG_GETARG_POINTER(0);
+
+ sksup->decrement = int4_decrement;
+ sksup->increment = int4_increment;
+ sksup->low_elem = Int32GetDatum(PG_INT32_MIN);
+ sksup->high_elem = Int32GetDatum(PG_INT32_MAX);
+
+ PG_RETURN_VOID();
+}
+
Datum
btint8cmp(PG_FUNCTION_ARGS)
{
@@ -142,32 +278,57 @@ btint8cmp(PG_FUNCTION_ARGS)
PG_RETURN_INT32(A_LESS_THAN_B);
}
-#if SIZEOF_DATUM < 8
-static int
-btint8fastcmp(Datum x, Datum y, SortSupport ssup)
+Datum
+btint8sortsupport(PG_FUNCTION_ARGS)
{
- int64 a = DatumGetInt64(x);
- int64 b = DatumGetInt64(y);
+ SortSupport ssup = (SortSupport) PG_GETARG_POINTER(0);
- if (a > b)
- return A_GREATER_THAN_B;
- else if (a == b)
- return 0;
- else
- return A_LESS_THAN_B;
+ ssup->comparator = ssup_datum_signed_cmp;
+ PG_RETURN_VOID();
+}
+
+static Datum
+int8_decrement(Relation rel, Datum existing, bool *underflow)
+{
+ int64 iexisting = DatumGetInt64(existing);
+
+ if (iexisting == PG_INT64_MIN)
+ {
+ /* return value is undefined */
+ *underflow = true;
+ return (Datum) 0;
+ }
+
+ *underflow = false;
+ return Int64GetDatum(iexisting - 1);
+}
+
+static Datum
+int8_increment(Relation rel, Datum existing, bool *overflow)
+{
+ int64 iexisting = DatumGetInt64(existing);
+
+ if (iexisting == PG_INT64_MAX)
+ {
+ /* return value is undefined */
+ *overflow = true;
+ return (Datum) 0;
+ }
+
+ *overflow = false;
+ return Int64GetDatum(iexisting + 1);
}
-#endif
Datum
-btint8sortsupport(PG_FUNCTION_ARGS)
+btint8skipsupport(PG_FUNCTION_ARGS)
{
- SortSupport ssup = (SortSupport) PG_GETARG_POINTER(0);
+ SkipSupport sksup = (SkipSupport) PG_GETARG_POINTER(0);
+
+ sksup->decrement = int8_decrement;
+ sksup->increment = int8_increment;
+ sksup->low_elem = Int64GetDatum(PG_INT64_MIN);
+ sksup->high_elem = Int64GetDatum(PG_INT64_MAX);
-#if SIZEOF_DATUM >= 8
- ssup->comparator = ssup_datum_signed_cmp;
-#else
- ssup->comparator = btint8fastcmp;
-#endif
PG_RETURN_VOID();
}
@@ -292,6 +453,51 @@ btoidsortsupport(PG_FUNCTION_ARGS)
PG_RETURN_VOID();
}
+static Datum
+oid_decrement(Relation rel, Datum existing, bool *underflow)
+{
+ Oid oexisting = DatumGetObjectId(existing);
+
+ if (oexisting == InvalidOid)
+ {
+ /* return value is undefined */
+ *underflow = true;
+ return (Datum) 0;
+ }
+
+ *underflow = false;
+ return ObjectIdGetDatum(oexisting - 1);
+}
+
+static Datum
+oid_increment(Relation rel, Datum existing, bool *overflow)
+{
+ Oid oexisting = DatumGetObjectId(existing);
+
+ if (oexisting == OID_MAX)
+ {
+ /* return value is undefined */
+ *overflow = true;
+ return (Datum) 0;
+ }
+
+ *overflow = false;
+ return ObjectIdGetDatum(oexisting + 1);
+}
+
+Datum
+btoidskipsupport(PG_FUNCTION_ARGS)
+{
+ SkipSupport sksup = (SkipSupport) PG_GETARG_POINTER(0);
+
+ sksup->decrement = oid_decrement;
+ sksup->increment = oid_increment;
+ sksup->low_elem = ObjectIdGetDatum(InvalidOid);
+ sksup->high_elem = ObjectIdGetDatum(OID_MAX);
+
+ PG_RETURN_VOID();
+}
+
Datum
btoidvectorcmp(PG_FUNCTION_ARGS)
{
@@ -325,3 +531,50 @@ btcharcmp(PG_FUNCTION_ARGS)
/* Be careful to compare chars as unsigned */
PG_RETURN_INT32((int32) ((uint8) a) - (int32) ((uint8) b));
}
+
+static Datum
+char_decrement(Relation rel, Datum existing, bool *underflow)
+{
+ uint8 cexisting = DatumGetUInt8(existing);
+
+ if (cexisting == 0)
+ {
+ /* return value is undefined */
+ *underflow = true;
+ return (Datum) 0;
+ }
+
+ *underflow = false;
+ return CharGetDatum((uint8) cexisting - 1);
+}
+
+static Datum
+char_increment(Relation rel, Datum existing, bool *overflow)
+{
+ uint8 cexisting = DatumGetUInt8(existing);
+
+ if (cexisting == UCHAR_MAX)
+ {
+ /* return value is undefined */
+ *overflow = true;
+ return (Datum) 0;
+ }
+
+ *overflow = false;
+ return CharGetDatum((uint8) cexisting + 1);
+}
+
+Datum
+btcharskipsupport(PG_FUNCTION_ARGS)
+{
+ SkipSupport sksup = (SkipSupport) PG_GETARG_POINTER(0);
+
+ sksup->decrement = char_decrement;
+ sksup->increment = char_increment;
+
+ /* btcharcmp compares chars as unsigned */
+ sksup->low_elem = UInt8GetDatum(0);
+ sksup->high_elem = UInt8GetDatum(UCHAR_MAX);
+
+ PG_RETURN_VOID();
+}
diff --git a/src/backend/access/nbtree/nbtdedup.c b/src/backend/access/nbtree/nbtdedup.c
index 456d86b51c95d..ab0b6946cb031 100644
--- a/src/backend/access/nbtree/nbtdedup.c
+++ b/src/backend/access/nbtree/nbtdedup.c
@@ -3,7 +3,7 @@
* nbtdedup.c
* Deduplicate or bottom-up delete items in Postgres btrees.
*
- * Portions Copyright (c) 1996-2024, PostgreSQL Global Development Group
+ * Portions Copyright (c) 1996-2025, PostgreSQL Global Development Group
* Portions Copyright (c) 1994, Regents of the University of California
*
*
@@ -16,6 +16,7 @@
#include "access/nbtree.h"
#include "access/nbtxlog.h"
+#include "access/tableam.h"
#include "access/xloginsert.h"
#include "miscadmin.h"
#include "utils/rel.h"
@@ -84,7 +85,7 @@ _bt_dedup_pass(Relation rel, Buffer buf, IndexTuple newitem, Size newitemsz,
state = (BTDedupState) palloc(sizeof(BTDedupStateData));
state->deduplicate = true;
state->nmaxitems = 0;
- state->maxpostingsize = Min(BTMaxItemSize(page) / 2, INDEX_SIZE_MASK);
+ state->maxpostingsize = Min(BTMaxItemSize / 2, INDEX_SIZE_MASK);
/* Metadata about base tuple of current pending posting list */
state->base = NULL;
state->baseoff = InvalidOffsetNumber;
@@ -252,14 +253,14 @@ _bt_dedup_pass(Relation rel, Buffer buf, IndexTuple newitem, Size newitemsz,
XLogBeginInsert();
XLogRegisterBuffer(0, buf, REGBUF_STANDARD);
- XLogRegisterData((char *) &xlrec_dedup, SizeOfBtreeDedup);
+ XLogRegisterData(&xlrec_dedup, SizeOfBtreeDedup);
/*
* The intervals array is not in the buffer, but pretend that it is.
* When XLogInsert stores the whole buffer, the array need not be
* stored too.
*/
- XLogRegisterBufData(0, (char *) state->intervals,
+ XLogRegisterBufData(0, state->intervals,
state->nintervals * sizeof(BTDedupInterval));
recptr = XLogInsert(RM_BTREE_ID, XLOG_BTREE_DEDUP);
@@ -568,7 +569,7 @@ _bt_dedup_finish_pending(Page newpage, BTDedupState state)
/* Use original, unchanged base tuple */
tuplesz = IndexTupleSize(state->base);
Assert(tuplesz == MAXALIGN(IndexTupleSize(state->base)));
- Assert(tuplesz <= BTMaxItemSize(newpage));
+ Assert(tuplesz <= BTMaxItemSize);
if (PageAddItem(newpage, (Item) state->base, tuplesz, tupoff,
false, false) == InvalidOffsetNumber)
elog(ERROR, "deduplication failed to add tuple to page");
@@ -588,7 +589,7 @@ _bt_dedup_finish_pending(Page newpage, BTDedupState state)
state->intervals[state->nintervals].nitems = state->nitems;
Assert(tuplesz == MAXALIGN(IndexTupleSize(final)));
- Assert(tuplesz <= BTMaxItemSize(newpage));
+ Assert(tuplesz <= BTMaxItemSize);
if (PageAddItem(newpage, (Item) final, tuplesz, tupoff, false,
false) == InvalidOffsetNumber)
elog(ERROR, "deduplication failed to add tuple to page");
diff --git a/src/backend/access/nbtree/nbtinsert.c b/src/backend/access/nbtree/nbtinsert.c
index 7e8902e48cde7..be60781fc98ec 100644
--- a/src/backend/access/nbtree/nbtinsert.c
+++ b/src/backend/access/nbtree/nbtinsert.c
@@ -3,7 +3,7 @@
* nbtinsert.c
* Item insertion in Lehman and Yao btrees for Postgres.
*
- * Portions Copyright (c) 1996-2024, PostgreSQL Global Development Group
+ * Portions Copyright (c) 1996-2025, PostgreSQL Global Development Group
* Portions Copyright (c) 1994, Regents of the University of California
*
*
@@ -17,6 +17,7 @@
#include "access/nbtree.h"
#include "access/nbtxlog.h"
+#include "access/tableam.h"
#include "access/transam.h"
#include "access/xloginsert.h"
#include "common/int.h"
@@ -827,7 +828,7 @@ _bt_findinsertloc(Relation rel,
opaque = BTPageGetOpaque(page);
/* Check 1/3 of a page restriction */
- if (unlikely(insertstate->itemsz > BTMaxItemSize(page)))
+ if (unlikely(insertstate->itemsz > BTMaxItemSize))
_bt_check_third_page(rel, heapRel, itup_key->heapkeyspace, page,
insertstate->itup);
@@ -1320,7 +1321,7 @@ _bt_insertonpg(Relation rel,
xlrec.offnum = newitemoff;
XLogBeginInsert();
- XLogRegisterData((char *) &xlrec, SizeOfBtreeInsert);
+ XLogRegisterData(&xlrec, SizeOfBtreeInsert);
if (isleaf && postingoff == 0)
{
@@ -1358,7 +1359,7 @@ _bt_insertonpg(Relation rel,
XLogRegisterBuffer(2, metabuf,
REGBUF_WILL_INIT | REGBUF_STANDARD);
- XLogRegisterBufData(2, (char *) &xlmeta,
+ XLogRegisterBufData(2, &xlmeta,
sizeof(xl_btree_metadata));
}
}
@@ -1367,7 +1368,7 @@ _bt_insertonpg(Relation rel,
if (postingoff == 0)
{
/* Just log itup from caller */
- XLogRegisterBufData(0, (char *) itup, IndexTupleSize(itup));
+ XLogRegisterBufData(0, itup, IndexTupleSize(itup));
}
else
{
@@ -1381,8 +1382,8 @@ _bt_insertonpg(Relation rel,
*/
upostingoff = postingoff;
- XLogRegisterBufData(0, (char *) &upostingoff, sizeof(uint16));
- XLogRegisterBufData(0, (char *) origitup,
+ XLogRegisterBufData(0, &upostingoff, sizeof(uint16));
+ XLogRegisterBufData(0, origitup,
IndexTupleSize(origitup));
}
@@ -1720,7 +1721,7 @@ _bt_split(Relation rel, Relation heaprel, BTScanInsert itup_key, Buffer buf,
rbuf = _bt_allocbuf(rel, heaprel);
rightpage = BufferGetPage(rbuf);
rightpagenumber = BufferGetBlockNumber(rbuf);
- /* rightpage was initialized by _bt_getbuf */
+ /* rightpage was initialized by _bt_allocbuf */
ropaque = BTPageGetOpaque(rightpage);
/*
@@ -1979,7 +1980,7 @@ _bt_split(Relation rel, Relation heaprel, BTScanInsert itup_key, Buffer buf,
xlrec.postingoff = postingoff;
XLogBeginInsert();
- XLogRegisterData((char *) &xlrec, SizeOfBtreeSplit);
+ XLogRegisterData(&xlrec, SizeOfBtreeSplit);
XLogRegisterBuffer(0, buf, REGBUF_STANDARD);
XLogRegisterBuffer(1, rbuf, REGBUF_WILL_INIT);
@@ -2017,13 +2018,13 @@ _bt_split(Relation rel, Relation heaprel, BTScanInsert itup_key, Buffer buf,
* newitem-logged case).
*/
if (newitemonleft && xlrec.postingoff == 0)
- XLogRegisterBufData(0, (char *) newitem, newitemsz);
+ XLogRegisterBufData(0, newitem, newitemsz);
else if (xlrec.postingoff != 0)
{
Assert(isleaf);
Assert(newitemonleft || firstrightoff == newitemoff);
Assert(newitemsz == IndexTupleSize(orignewitem));
- XLogRegisterBufData(0, (char *) orignewitem, newitemsz);
+ XLogRegisterBufData(0, orignewitem, newitemsz);
}
/* Log the left page's new high key */
@@ -2033,7 +2034,7 @@ _bt_split(Relation rel, Relation heaprel, BTScanInsert itup_key, Buffer buf,
itemid = PageGetItemId(origpage, P_HIKEY);
lefthighkey = (IndexTuple) PageGetItem(origpage, itemid);
}
- XLogRegisterBufData(0, (char *) lefthighkey,
+ XLogRegisterBufData(0, lefthighkey,
MAXALIGN(IndexTupleSize(lefthighkey)));
/*
@@ -2564,7 +2565,7 @@ _bt_newlevel(Relation rel, Relation heaprel, Buffer lbuf, Buffer rbuf)
xlrec.level = metad->btm_level;
XLogBeginInsert();
- XLogRegisterData((char *) &xlrec, SizeOfBtreeNewroot);
+ XLogRegisterData(&xlrec, SizeOfBtreeNewroot);
XLogRegisterBuffer(0, rootbuf, REGBUF_WILL_INIT);
XLogRegisterBuffer(1, lbuf, REGBUF_STANDARD);
@@ -2579,7 +2580,7 @@ _bt_newlevel(Relation rel, Relation heaprel, Buffer lbuf, Buffer rbuf)
md.last_cleanup_num_delpages = metad->btm_last_cleanup_num_delpages;
md.allequalimage = metad->btm_allequalimage;
- XLogRegisterBufData(2, (char *) &md, sizeof(xl_btree_metadata));
+ XLogRegisterBufData(2, &md, sizeof(xl_btree_metadata));
/*
* Direct access to page is not good but faster - we should implement
diff --git a/src/backend/access/nbtree/nbtpage.c b/src/backend/access/nbtree/nbtpage.c
index 01bbece6bfd9d..c79dd38ee18f3 100644
--- a/src/backend/access/nbtree/nbtpage.c
+++ b/src/backend/access/nbtree/nbtpage.c
@@ -4,7 +4,7 @@
* BTree-specific page management code for the Postgres btree access
* method.
*
- * Portions Copyright (c) 1996-2024, PostgreSQL Global Development Group
+ * Portions Copyright (c) 1996-2025, PostgreSQL Global Development Group
* Portions Copyright (c) 1994, Regents of the University of California
*
*
@@ -299,7 +299,7 @@ _bt_set_cleanup_info(Relation rel, BlockNumber num_delpages)
md.last_cleanup_num_delpages = num_delpages;
md.allequalimage = metad->btm_allequalimage;
- XLogRegisterBufData(0, (char *) &md, sizeof(xl_btree_metadata));
+ XLogRegisterBufData(0, &md, sizeof(xl_btree_metadata));
recptr = XLogInsert(RM_BTREE_ID, XLOG_BTREE_META_CLEANUP);
@@ -488,12 +488,12 @@ _bt_getroot(Relation rel, Relation heaprel, int access)
md.last_cleanup_num_delpages = 0;
md.allequalimage = metad->btm_allequalimage;
- XLogRegisterBufData(2, (char *) &md, sizeof(xl_btree_metadata));
+ XLogRegisterBufData(2, &md, sizeof(xl_btree_metadata));
xlrec.rootblk = rootblkno;
xlrec.level = 0;
- XLogRegisterData((char *) &xlrec, SizeOfBtreeNewroot);
+ XLogRegisterData(&xlrec, SizeOfBtreeNewroot);
recptr = XLogInsert(RM_BTREE_ID, XLOG_BTREE_NEWROOT);
@@ -948,7 +948,7 @@ _bt_allocbuf(Relation rel, Relation heaprel)
RelationIsAccessibleInLogicalDecoding(heaprel);
XLogBeginInsert();
- XLogRegisterData((char *) &xlrec_reuse, SizeOfBtreeReusePage);
+ XLogRegisterData(&xlrec_reuse, SizeOfBtreeReusePage);
XLogInsert(RM_BTREE_ID, XLOG_BTREE_REUSE_PAGE);
}
@@ -1234,15 +1234,15 @@ _bt_delitems_vacuum(Relation rel, Buffer buf,
XLogBeginInsert();
XLogRegisterBuffer(0, buf, REGBUF_STANDARD);
- XLogRegisterData((char *) &xlrec_vacuum, SizeOfBtreeVacuum);
+ XLogRegisterData(&xlrec_vacuum, SizeOfBtreeVacuum);
if (ndeletable > 0)
- XLogRegisterBufData(0, (char *) deletable,
+ XLogRegisterBufData(0, deletable,
ndeletable * sizeof(OffsetNumber));
if (nupdatable > 0)
{
- XLogRegisterBufData(0, (char *) updatedoffsets,
+ XLogRegisterBufData(0, updatedoffsets,
nupdatable * sizeof(OffsetNumber));
XLogRegisterBufData(0, updatedbuf, updatedbuflen);
}
@@ -1353,15 +1353,15 @@ _bt_delitems_delete(Relation rel, Buffer buf,
XLogBeginInsert();
XLogRegisterBuffer(0, buf, REGBUF_STANDARD);
- XLogRegisterData((char *) &xlrec_delete, SizeOfBtreeDelete);
+ XLogRegisterData(&xlrec_delete, SizeOfBtreeDelete);
if (ndeletable > 0)
- XLogRegisterBufData(0, (char *) deletable,
+ XLogRegisterBufData(0, deletable,
ndeletable * sizeof(OffsetNumber));
if (nupdatable > 0)
{
- XLogRegisterBufData(0, (char *) updatedoffsets,
+ XLogRegisterBufData(0, updatedoffsets,
nupdatable * sizeof(OffsetNumber));
XLogRegisterBufData(0, updatedbuf, updatedbuflen);
}
@@ -2269,7 +2269,7 @@ _bt_mark_page_halfdead(Relation rel, Relation heaprel, Buffer leafbuf,
xlrec.leftblk = opaque->btpo_prev;
xlrec.rightblk = opaque->btpo_next;
- XLogRegisterData((char *) &xlrec, SizeOfBtreeMarkPageHalfDead);
+ XLogRegisterData(&xlrec, SizeOfBtreeMarkPageHalfDead);
recptr = XLogInsert(RM_BTREE_ID, XLOG_BTREE_MARK_PAGE_HALFDEAD);
@@ -2694,7 +2694,7 @@ _bt_unlink_halfdead_page(Relation rel, Buffer leafbuf, BlockNumber scanblkno,
xlrec.leafrightsib = leafrightsib;
xlrec.leaftopparent = leaftopparent;
- XLogRegisterData((char *) &xlrec, SizeOfBtreeUnlinkPage);
+ XLogRegisterData(&xlrec, SizeOfBtreeUnlinkPage);
if (BufferIsValid(metabuf))
{
@@ -2709,7 +2709,7 @@ _bt_unlink_halfdead_page(Relation rel, Buffer leafbuf, BlockNumber scanblkno,
xlmeta.last_cleanup_num_delpages = metad->btm_last_cleanup_num_delpages;
xlmeta.allequalimage = metad->btm_allequalimage;
- XLogRegisterBufData(4, (char *) &xlmeta, sizeof(xl_btree_metadata));
+ XLogRegisterBufData(4, &xlmeta, sizeof(xl_btree_metadata));
xlinfo = XLOG_BTREE_UNLINK_PAGE_META;
}
else
@@ -2953,7 +2953,7 @@ _bt_lock_subtree_parent(Relation rel, Relation heaprel, BlockNumber child,
void
_bt_pendingfsm_init(Relation rel, BTVacState *vstate, bool cleanuponly)
{
- int64 maxbufsize;
+ Size maxbufsize;
/*
* Don't bother with optimization in cleanup-only case -- we don't expect
@@ -2969,12 +2969,13 @@ _bt_pendingfsm_init(Relation rel, BTVacState *vstate, bool cleanuponly)
* int overflow here.
*/
vstate->bufsize = 256;
- maxbufsize = (work_mem * 1024L) / sizeof(BTPendingFSM);
- maxbufsize = Min(maxbufsize, INT_MAX);
+ maxbufsize = (work_mem * (Size) 1024) / sizeof(BTPendingFSM);
maxbufsize = Min(maxbufsize, MaxAllocSize / sizeof(BTPendingFSM));
+ /* BTVacState.maxbufsize has type int */
+ maxbufsize = Min(maxbufsize, INT_MAX);
/* Stay sane with small work_mem */
maxbufsize = Max(maxbufsize, vstate->bufsize);
- vstate->maxbufsize = maxbufsize;
+ vstate->maxbufsize = (int) maxbufsize;
/* Allocate buffer, indicate that there are currently 0 pending pages */
vstate->pendingpages = palloc(sizeof(BTPendingFSM) * vstate->bufsize);
diff --git a/src/backend/access/nbtree/nbtpreprocesskeys.c b/src/backend/access/nbtree/nbtpreprocesskeys.c
new file mode 100644
index 0000000000000..936b93f157a8b
--- /dev/null
+++ b/src/backend/access/nbtree/nbtpreprocesskeys.c
@@ -0,0 +1,2836 @@
+/*-------------------------------------------------------------------------
+ *
+ * nbtpreprocesskeys.c
+ * Preprocessing for Postgres btree scan keys.
+ *
+ * Portions Copyright (c) 1996-2025, PostgreSQL Global Development Group
+ * Portions Copyright (c) 1994, Regents of the University of California
+ *
+ *
+ * IDENTIFICATION
+ * src/backend/access/nbtree/nbtpreprocesskeys.c
+ *
+ *-------------------------------------------------------------------------
+ */
+
+#include "postgres.h"
+
+#include "access/nbtree.h"
+#include "access/relscan.h"
+#include "common/int.h"
+#include "lib/qunique.h"
+#include "utils/array.h"
+#include "utils/lsyscache.h"
+#include "utils/memutils.h"
+#include "utils/rel.h"
+
+typedef struct BTScanKeyPreproc
+{
+ ScanKey inkey;
+ int inkeyi;
+ int arrayidx;
+} BTScanKeyPreproc;
+
+typedef struct BTSortArrayContext
+{
+ FmgrInfo *sortproc;
+ Oid collation;
+ bool reverse;
+} BTSortArrayContext;
+
+static bool _bt_fix_scankey_strategy(ScanKey skey, int16 *indoption);
+static void _bt_mark_scankey_required(ScanKey skey);
+static bool _bt_compare_scankey_args(IndexScanDesc scan, ScanKey op,
+ ScanKey leftarg, ScanKey rightarg,
+ BTArrayKeyInfo *array, FmgrInfo *orderproc,
+ bool *result);
+static bool _bt_compare_array_scankey_args(IndexScanDesc scan,
+ ScanKey arraysk, ScanKey skey,
+ FmgrInfo *orderproc, BTArrayKeyInfo *array,
+ bool *qual_ok);
+static bool _bt_saoparray_shrink(IndexScanDesc scan, ScanKey arraysk,
+ ScanKey skey, FmgrInfo *orderproc,
+ BTArrayKeyInfo *array, bool *qual_ok);
+static bool _bt_skiparray_shrink(IndexScanDesc scan, ScanKey skey,
+ BTArrayKeyInfo *array, bool *qual_ok);
+static void _bt_skiparray_strat_adjust(IndexScanDesc scan, ScanKey arraysk,
+ BTArrayKeyInfo *array);
+static void _bt_skiparray_strat_decrement(IndexScanDesc scan, ScanKey arraysk,
+ BTArrayKeyInfo *array);
+static void _bt_skiparray_strat_increment(IndexScanDesc scan, ScanKey arraysk,
+ BTArrayKeyInfo *array);
+static void _bt_unmark_keys(IndexScanDesc scan, int *keyDataMap);
+static int _bt_reorder_array_cmp(const void *a, const void *b);
+static ScanKey _bt_preprocess_array_keys(IndexScanDesc scan, int *new_numberOfKeys);
+static void _bt_preprocess_array_keys_final(IndexScanDesc scan, int *keyDataMap);
+static int _bt_num_array_keys(IndexScanDesc scan, Oid *skip_eq_ops_out,
+ int *numSkipArrayKeys_out);
+static Datum _bt_find_extreme_element(IndexScanDesc scan, ScanKey skey,
+ Oid elemtype, StrategyNumber strat,
+ Datum *elems, int nelems);
+static void _bt_setup_array_cmp(IndexScanDesc scan, ScanKey skey, Oid elemtype,
+ FmgrInfo *orderproc, FmgrInfo **sortprocp);
+static int _bt_sort_array_elements(ScanKey skey, FmgrInfo *sortproc,
+ bool reverse, Datum *elems, int nelems);
+static bool _bt_merge_arrays(IndexScanDesc scan, ScanKey skey,
+ FmgrInfo *sortproc, bool reverse,
+ Oid origelemtype, Oid nextelemtype,
+ Datum *elems_orig, int *nelems_orig,
+ Datum *elems_next, int nelems_next);
+static int _bt_compare_array_elements(const void *a, const void *b, void *arg);
+
+
+/*
+ * _bt_preprocess_keys() -- Preprocess scan keys
+ *
+ * The given search-type keys (taken from scan->keyData[])
+ * are copied to so->keyData[] with possible transformation.
+ * scan->numberOfKeys is the number of input keys, so->numberOfKeys gets
+ * the number of output keys. Calling here a second or subsequent time
+ * (during the same btrescan) is a no-op.
+ *
+ * The output keys are marked with additional sk_flags bits beyond the
+ * system-standard bits supplied by the caller. The DESC and NULLS_FIRST
+ * indoption bits for the relevant index attribute are copied into the flags.
+ * Also, for a DESC column, we commute (flip) all the sk_strategy numbers
+ * so that the index sorts in the desired direction.
+ *
+ * One key purpose of this routine is to discover which scan keys must be
+ * satisfied to continue the scan. It also attempts to eliminate redundant
+ * keys and detect contradictory keys. (If the index opfamily provides
+ * incomplete sets of cross-type operators, we may fail to detect redundant
+ * or contradictory keys, but we can survive that.)
+ *
+ * Required output keys are sorted by index attribute. Presently we expect
+ * (but verify) that the input keys are already so sorted --- this is done
+ * by match_clauses_to_index() in indxpath.c. Some reordering of the keys
+ * within each attribute may be done as a byproduct of the processing here.
+ * That process must leave array scan keys (within an attribute) in the same
+ * order as corresponding entries from the scan's BTArrayKeyInfo array info.
+ * We might also construct skip array scan keys that weren't present in the
+ * original input keys; these are also output in standard attribute order.
+ *
+ * The output keys are marked with flags SK_BT_REQFWD and/or SK_BT_REQBKWD
+ * if they must be satisfied in order to continue the scan forward or backward
+ * respectively. _bt_checkkeys uses these flags. For example, if the quals
+ * are "x = 1 AND y < 4 AND z < 5", then _bt_checkkeys will reject a tuple
+ * (1,2,7), but we must continue the scan in case there are tuples (1,3,z).
+ * But once we reach tuples like (1,4,z) we can stop scanning because no
+ * later tuples could match. This is reflected by marking the x and y keys,
+ * but not the z key, with SK_BT_REQFWD. In general, the keys for leading
+ * attributes with "=" keys are marked both SK_BT_REQFWD and SK_BT_REQBKWD.
+ * For the first attribute without an "=" key, any "<" and "<=" keys are
+ * marked SK_BT_REQFWD while any ">" and ">=" keys are marked SK_BT_REQBKWD.
+ * This can be seen to be correct by considering the above example.
+ *
+ * If we never generated skip array scan keys, it would be possible for "gaps"
+ * to appear that make it unsafe to mark any subsequent input scan keys
+ * (copied from scan->keyData[]) as required to continue the scan. Prior to
+ * Postgres 18, a qual like "WHERE y = 4" always resulted in a full scan.
+ * This qual now becomes "WHERE x = ANY('{every possible x value}') and y = 4"
+ * on output. In other words, preprocessing now adds a skip array on "x".
+ * This has the potential to be much more efficient than a full index scan
+ * (though it behaves like a full scan when there's many distinct "x" values).
+ *
+ * Typically, redundant keys are eliminated: we keep only the tightest
+ * >/>= bound and the tightest 4::int AND x > 10::bigint AND x < 70", and we are unable to
+ * determine which > key is more restrictive for lack of a suitable cross-type
+ * operator. We'll arbitrarily pick one of the > keys; the other > key won't
+ * be marked required. Obviously, the scan will be less efficient if we
+ * choose x > 4 over x > 10 -- but it can still largely proceed as if there
+ * was only a single > condition. "x > 10" will be placed at the end of the
+ * so->keyData[] output array. It'll always be evaluated last, after the keys
+ * that could be marked required in the usual way (after "x > 4 AND x < 70").
+ * This can sometimes result in so->keyData[] keys that aren't even in index
+ * attribute order (if the qual involves multiple attributes). The scan's
+ * required keys will still be in attribute order, though, so it can't matter.
+ *
+ * This scheme ensures that _bt_first always uses the same set of keys at the
+ * start of a forwards scan as those _bt_checkkeys uses to determine when to
+ * end a similar backwards scan (and vice-versa). _bt_advance_array_keys
+ * depends on this: it expects to be able to reliably predict what the next
+ * _bt_first call will do by testing whether _bt_checkkeys' routines report
+ * that the final tuple on the page is past the end of matches for the scan's
+ * keys with the scan direction flipped. If it is (if continuescan=false),
+ * then it follows that calling _bt_first will, at a minimum, relocate the
+ * scan to the very next leaf page (in the current scan direction).
+ *
+ * As a byproduct of this work, we can detect contradictory quals such
+ * as "x = 1 AND x > 2". If we see that, we return so->qual_ok = false,
+ * indicating the scan need not be run at all since no tuples can match.
+ * (In this case we do not bother completing the output key array!)
+ * Again, missing cross-type operators might cause us to fail to prove the
+ * quals contradictory when they really are, but the scan will work correctly.
+ *
+ * Skip array = keys will even be generated in the presence of "contradictory"
+ * inequality quals when it'll enable marking later input quals as required.
+ * We'll merge any such inequalities into the generated skip array by setting
+ * its array.low_compare or array.high_compare key field. The resulting skip
+ * array will generate its array elements from a range that's constrained by
+ * any merged input inequalities (which won't get output in so->keyData[]).
+ *
+ * Row comparison keys currently have a couple of notable limitations.
+ * Right now we just transfer them into the preprocessed array without any
+ * editorialization. We can treat them the same as an ordinary inequality
+ * comparison on the row's first index column, for the purposes of the logic
+ * about required keys. Also, we are unable to merge a row comparison key
+ * into a skip array (only ordinary inequalities are merged). A key that
+ * comes after a Row comparison key is therefore never marked as required.
+ *
+ * Note: the reason we have to copy the preprocessed scan keys into private
+ * storage is that we are modifying the array based on comparisons of the
+ * key argument values, which could change on a rescan. Therefore we can't
+ * overwrite the source data.
+ */
+void
+_bt_preprocess_keys(IndexScanDesc scan)
+{
+ BTScanOpaque so = (BTScanOpaque) scan->opaque;
+ int numberOfKeys = scan->numberOfKeys;
+ int16 *indoption = scan->indexRelation->rd_indoption;
+ int new_numberOfKeys;
+ int numberOfEqualCols;
+ ScanKey inkeys;
+ BTScanKeyPreproc xform[BTMaxStrategyNumber];
+ bool test_result,
+ redundant_key_kept = false;
+ AttrNumber attno;
+ ScanKey arrayKeyData;
+ int *keyDataMap = NULL;
+ int arrayidx = 0;
+
+ if (so->numberOfKeys > 0)
+ {
+ /*
+ * Only need to do preprocessing once per btrescan, at most. All
+ * calls after the first are handled as no-ops.
+ */
+ return;
+ }
+
+ /* initialize result variables */
+ so->qual_ok = true;
+ so->numberOfKeys = 0;
+
+ if (numberOfKeys < 1)
+ return; /* done if qual-less scan */
+
+ /* If any keys are SK_SEARCHARRAY type, set up array-key info */
+ arrayKeyData = _bt_preprocess_array_keys(scan, &numberOfKeys);
+ if (!so->qual_ok)
+ {
+ /* unmatchable array, so give up */
+ return;
+ }
+
+ /*
+ * Treat arrayKeyData[] (a partially preprocessed copy of scan->keyData[])
+ * as our input if _bt_preprocess_array_keys just allocated it, else just
+ * use scan->keyData[]
+ */
+ if (arrayKeyData)
+ {
+ inkeys = arrayKeyData;
+
+ /* Also maintain keyDataMap for remapping so->orderProcs[] later */
+ keyDataMap = MemoryContextAlloc(so->arrayContext,
+ numberOfKeys * sizeof(int));
+
+ /*
+ * Also enlarge output array when it might otherwise not have room for
+ * a skip array's scan key
+ */
+ if (numberOfKeys > scan->numberOfKeys)
+ so->keyData = repalloc(so->keyData,
+ numberOfKeys * sizeof(ScanKeyData));
+ }
+ else
+ inkeys = scan->keyData;
+
+ /* we check that input keys are correctly ordered */
+ if (inkeys[0].sk_attno < 1)
+ elog(ERROR, "btree index keys must be ordered by attribute");
+
+ /* We can short-circuit most of the work if there's just one key */
+ if (numberOfKeys == 1)
+ {
+ /* Apply indoption to scankey (might change sk_strategy!) */
+ if (!_bt_fix_scankey_strategy(&inkeys[0], indoption))
+ so->qual_ok = false;
+ memcpy(&so->keyData[0], &inkeys[0], sizeof(ScanKeyData));
+ so->numberOfKeys = 1;
+ /* We can mark the qual as required if it's for first index col */
+ if (inkeys[0].sk_attno == 1)
+ _bt_mark_scankey_required(&so->keyData[0]);
+ if (arrayKeyData)
+ {
+ /*
+ * Don't call _bt_preprocess_array_keys_final in this fast path
+ * (we'll miss out on the single value array transformation, but
+ * that's not nearly as important when there's only one scan key)
+ */
+ Assert(so->keyData[0].sk_flags & SK_SEARCHARRAY);
+ Assert(so->keyData[0].sk_strategy != BTEqualStrategyNumber ||
+ (so->arrayKeys[0].scan_key == 0 &&
+ !(so->keyData[0].sk_flags & SK_BT_SKIP) &&
+ OidIsValid(so->orderProcs[0].fn_oid)));
+ }
+
+ return;
+ }
+
+ /*
+ * Otherwise, do the full set of pushups.
+ */
+ new_numberOfKeys = 0;
+ numberOfEqualCols = 0;
+
+ /*
+ * Initialize for processing of keys for attr 1.
+ *
+ * xform[i] points to the currently best scan key of strategy type i+1; it
+ * is NULL if we haven't yet found such a key for this attr.
+ */
+ attno = 1;
+ memset(xform, 0, sizeof(xform));
+
+ /*
+ * Loop iterates from 0 to numberOfKeys inclusive; we use the last pass to
+ * handle after-last-key processing. Actual exit from the loop is at the
+ * "break" statement below.
+ */
+ for (int i = 0;; i++)
+ {
+ ScanKey inkey = inkeys + i;
+ int j;
+
+ if (i < numberOfKeys)
+ {
+ /* Apply indoption to scankey (might change sk_strategy!) */
+ if (!_bt_fix_scankey_strategy(inkey, indoption))
+ {
+ /* NULL can't be matched, so give up */
+ so->qual_ok = false;
+ return;
+ }
+ }
+
+ /*
+ * If we are at the end of the keys for a particular attr, finish up
+ * processing and emit the cleaned-up keys.
+ */
+ if (i == numberOfKeys || inkey->sk_attno != attno)
+ {
+ int priorNumberOfEqualCols = numberOfEqualCols;
+
+ /* check input keys are correctly ordered */
+ if (i < numberOfKeys && inkey->sk_attno < attno)
+ elog(ERROR, "btree index keys must be ordered by attribute");
+
+ /*
+ * If = has been specified, all other keys can be eliminated as
+ * redundant. Note that this is no less true if the = key is
+ * SEARCHARRAY; the only real difference is that the inequality
+ * key _becomes_ redundant by making _bt_compare_scankey_args
+ * eliminate the subset of elements that won't need to be matched
+ * (with SAOP arrays and skip arrays alike).
+ *
+ * If we have a case like "key = 1 AND key > 2", we set qual_ok to
+ * false and abandon further processing. We'll do the same thing
+ * given a case like "key IN (0, 1) AND key > 2".
+ *
+ * We also have to deal with the case of "key IS NULL", which is
+ * unsatisfiable in combination with any other index condition. By
+ * the time we get here, that's been classified as an equality
+ * check, and we've rejected any combination of it with a regular
+ * equality condition; but not with other types of conditions.
+ */
+ if (xform[BTEqualStrategyNumber - 1].inkey)
+ {
+ ScanKey eq = xform[BTEqualStrategyNumber - 1].inkey;
+ BTArrayKeyInfo *array = NULL;
+ FmgrInfo *orderproc = NULL;
+
+ if (arrayKeyData && (eq->sk_flags & SK_SEARCHARRAY))
+ {
+ int eq_in_ikey,
+ eq_arrayidx;
+
+ eq_in_ikey = xform[BTEqualStrategyNumber - 1].inkeyi;
+ eq_arrayidx = xform[BTEqualStrategyNumber - 1].arrayidx;
+ array = &so->arrayKeys[eq_arrayidx - 1];
+ orderproc = so->orderProcs + eq_in_ikey;
+
+ Assert(array->scan_key == eq_in_ikey);
+ Assert(OidIsValid(orderproc->fn_oid));
+ }
+
+ for (j = BTMaxStrategyNumber; --j >= 0;)
+ {
+ ScanKey chk = xform[j].inkey;
+
+ if (!chk || j == (BTEqualStrategyNumber - 1))
+ continue;
+
+ if (eq->sk_flags & SK_SEARCHNULL)
+ {
+ /* IS NULL is contradictory to anything else */
+ so->qual_ok = false;
+ return;
+ }
+
+ if (_bt_compare_scankey_args(scan, chk, eq, chk,
+ array, orderproc,
+ &test_result))
+ {
+ if (!test_result)
+ {
+ /* keys proven mutually contradictory */
+ so->qual_ok = false;
+ return;
+ }
+ /* else discard the redundant non-equality key */
+ xform[j].inkey = NULL;
+ xform[j].inkeyi = -1;
+ }
+ else
+ redundant_key_kept = true;
+ }
+ /* track number of attrs for which we have "=" keys */
+ numberOfEqualCols++;
+ }
+
+ /* try to keep only one of <, <= */
+ if (xform[BTLessStrategyNumber - 1].inkey &&
+ xform[BTLessEqualStrategyNumber - 1].inkey)
+ {
+ ScanKey lt = xform[BTLessStrategyNumber - 1].inkey;
+ ScanKey le = xform[BTLessEqualStrategyNumber - 1].inkey;
+
+ if (_bt_compare_scankey_args(scan, le, lt, le, NULL, NULL,
+ &test_result))
+ {
+ if (test_result)
+ xform[BTLessEqualStrategyNumber - 1].inkey = NULL;
+ else
+ xform[BTLessStrategyNumber - 1].inkey = NULL;
+ }
+ else
+ redundant_key_kept = true;
+ }
+
+ /* try to keep only one of >, >= */
+ if (xform[BTGreaterStrategyNumber - 1].inkey &&
+ xform[BTGreaterEqualStrategyNumber - 1].inkey)
+ {
+ ScanKey gt = xform[BTGreaterStrategyNumber - 1].inkey;
+ ScanKey ge = xform[BTGreaterEqualStrategyNumber - 1].inkey;
+
+ if (_bt_compare_scankey_args(scan, ge, gt, ge, NULL, NULL,
+ &test_result))
+ {
+ if (test_result)
+ xform[BTGreaterEqualStrategyNumber - 1].inkey = NULL;
+ else
+ xform[BTGreaterStrategyNumber - 1].inkey = NULL;
+ }
+ else
+ redundant_key_kept = true;
+ }
+
+ /*
+ * Emit the cleaned-up keys into the so->keyData[] array, and then
+ * mark them if they are required. They are required (possibly
+ * only in one direction) if all attrs before this one had "=".
+ *
+ * In practice we'll rarely output non-required scan keys here;
+ * typically, _bt_preprocess_array_keys has already added "=" keys
+ * sufficient to form an unbroken series of "=" constraints on all
+ * attrs prior to the attr from the final scan->keyData[] key.
+ */
+ for (j = BTMaxStrategyNumber; --j >= 0;)
+ {
+ if (xform[j].inkey)
+ {
+ ScanKey outkey = &so->keyData[new_numberOfKeys++];
+
+ memcpy(outkey, xform[j].inkey, sizeof(ScanKeyData));
+ if (arrayKeyData)
+ keyDataMap[new_numberOfKeys - 1] = xform[j].inkeyi;
+ if (priorNumberOfEqualCols == attno - 1)
+ _bt_mark_scankey_required(outkey);
+ }
+ }
+
+ /*
+ * Exit loop here if done.
+ */
+ if (i == numberOfKeys)
+ break;
+
+ /* Re-initialize for new attno */
+ attno = inkey->sk_attno;
+ memset(xform, 0, sizeof(xform));
+ }
+
+ /* check strategy this key's operator corresponds to */
+ j = inkey->sk_strategy - 1;
+
+ if (inkey->sk_strategy == BTEqualStrategyNumber &&
+ (inkey->sk_flags & SK_SEARCHARRAY))
+ {
+ /* must track how input scan keys map to arrays */
+ Assert(arrayKeyData);
+ arrayidx++;
+ }
+
+ /*
+ * have we seen a scan key for this same attribute and using this same
+ * operator strategy before now?
+ */
+ if (xform[j].inkey == NULL)
+ {
+ /* nope, so this scan key wins by default (at least for now) */
+ xform[j].inkey = inkey;
+ xform[j].inkeyi = i;
+ xform[j].arrayidx = arrayidx;
+ }
+ else
+ {
+ FmgrInfo *orderproc = NULL;
+ BTArrayKeyInfo *array = NULL;
+
+ /*
+ * Seen one of these before, so keep only the more restrictive key
+ * if possible
+ */
+ if (j == (BTEqualStrategyNumber - 1) && arrayKeyData)
+ {
+ /*
+ * Have to set up array keys
+ */
+ if (inkey->sk_flags & SK_SEARCHARRAY)
+ {
+ array = &so->arrayKeys[arrayidx - 1];
+ orderproc = so->orderProcs + i;
+
+ Assert(array->scan_key == i);
+ Assert(OidIsValid(orderproc->fn_oid));
+ Assert(!(inkey->sk_flags & SK_BT_SKIP));
+ }
+ else if (xform[j].inkey->sk_flags & SK_SEARCHARRAY)
+ {
+ array = &so->arrayKeys[xform[j].arrayidx - 1];
+ orderproc = so->orderProcs + xform[j].inkeyi;
+
+ Assert(array->scan_key == xform[j].inkeyi);
+ Assert(OidIsValid(orderproc->fn_oid));
+ Assert(!(xform[j].inkey->sk_flags & SK_BT_SKIP));
+ }
+
+ /*
+ * Both scan keys might have arrays, in which case we'll
+ * arbitrarily pass only one of the arrays. That won't
+ * matter, since _bt_compare_scankey_args is aware that two
+ * SEARCHARRAY scan keys mean that _bt_preprocess_array_keys
+ * failed to eliminate redundant arrays through array merging.
+ * _bt_compare_scankey_args just returns false when it sees
+ * this; it won't even try to examine either array.
+ */
+ }
+
+ if (_bt_compare_scankey_args(scan, inkey, inkey, xform[j].inkey,
+ array, orderproc, &test_result))
+ {
+ /* Have all we need to determine redundancy */
+ if (test_result)
+ {
+ /*
+ * New key is more restrictive, and so replaces old key...
+ */
+ if (j != (BTEqualStrategyNumber - 1) ||
+ !(xform[j].inkey->sk_flags & SK_SEARCHARRAY))
+ {
+ xform[j].inkey = inkey;
+ xform[j].inkeyi = i;
+ xform[j].arrayidx = arrayidx;
+ }
+ else
+ {
+ /*
+ * ...unless we have to keep the old key because it's
+ * an array that rendered the new key redundant. We
+ * need to make sure that we don't throw away an array
+ * scan key. _bt_preprocess_array_keys_final expects
+ * us to keep all of the arrays that weren't already
+ * eliminated by _bt_preprocess_array_keys earlier on.
+ */
+ Assert(!(inkey->sk_flags & SK_SEARCHARRAY));
+ }
+ }
+ else if (j == (BTEqualStrategyNumber - 1))
+ {
+ /* key == a && key == b, but a != b */
+ so->qual_ok = false;
+ return;
+ }
+ /* else old key is more restrictive, keep it */
+ }
+ else
+ {
+ /*
+ * We can't determine which key is more restrictive. Push
+ * xform[j] directly to the output array, then set xform[j] to
+ * the new scan key.
+ *
+ * Note: We do things this way around so that our arrays are
+ * always in the same order as their corresponding scan keys.
+ * _bt_preprocess_array_keys_final expects this.
+ */
+ ScanKey outkey = &so->keyData[new_numberOfKeys++];
+
+ memcpy(outkey, xform[j].inkey, sizeof(ScanKeyData));
+ if (arrayKeyData)
+ keyDataMap[new_numberOfKeys - 1] = xform[j].inkeyi;
+ if (numberOfEqualCols == attno - 1)
+ _bt_mark_scankey_required(outkey);
+ xform[j].inkey = inkey;
+ xform[j].inkeyi = i;
+ xform[j].arrayidx = arrayidx;
+ redundant_key_kept = true;
+ }
+ }
+ }
+
+ so->numberOfKeys = new_numberOfKeys;
+
+ /*
+ * Now that we've built a temporary mapping from so->keyData[] (output
+ * scan keys) to arrayKeyData[] (our input scan keys), fix array->scan_key
+ * references. Also consolidate the so->orderProcs[] array such that it
+ * can be subscripted using so->keyData[]-wise offsets.
+ */
+ if (arrayKeyData)
+ _bt_preprocess_array_keys_final(scan, keyDataMap);
+
+ /*
+ * If there are remaining redundant inequality keys, we must make sure
+ * that each index attribute has no more than one required >/>= key, and
+ * no more than one required qual_ok)
+ _bt_unmark_keys(scan, keyDataMap);
+
+ /* Could pfree arrayKeyData/keyDataMap now, but not worth the cycles */
+}
+
+/*
+ * Adjust a scankey's strategy and flags setting as needed for indoptions.
+ *
+ * We copy the appropriate indoption value into the scankey sk_flags
+ * (shifting to avoid clobbering system-defined flag bits). Also, if
+ * the DESC option is set, commute (flip) the operator strategy number.
+ *
+ * A secondary purpose is to check for IS NULL/NOT NULL scankeys and set up
+ * the strategy field correctly for them.
+ *
+ * Lastly, for ordinary scankeys (not IS NULL/NOT NULL), we check for a
+ * NULL comparison value. Since all btree operators are assumed strict,
+ * a NULL means that the qual cannot be satisfied. We return true if the
+ * comparison value isn't NULL, or false if the scan should be abandoned.
+ *
+ * This function is applied to the *input* scankey structure; therefore
+ * on a rescan we will be looking at already-processed scankeys. Hence
+ * we have to be careful not to re-commute the strategy if we already did it.
+ * It's a bit ugly to modify the caller's copy of the scankey but in practice
+ * there shouldn't be any problem, since the index's indoptions are certainly
+ * not going to change while the scankey survives.
+ */
+static bool
+_bt_fix_scankey_strategy(ScanKey skey, int16 *indoption)
+{
+ int addflags;
+
+ addflags = indoption[skey->sk_attno - 1] << SK_BT_INDOPTION_SHIFT;
+
+ /*
+ * We treat all btree operators as strict (even if they're not so marked
+ * in pg_proc). This means that it is impossible for an operator condition
+ * with a NULL comparison constant to succeed, and we can reject it right
+ * away.
+ *
+ * However, we now also support "x IS NULL" clauses as search conditions,
+ * so in that case keep going. The planner has not filled in any
+ * particular strategy in this case, so set it to BTEqualStrategyNumber
+ * --- we can treat IS NULL as an equality operator for purposes of search
+ * strategy.
+ *
+ * Likewise, "x IS NOT NULL" is supported. We treat that as either "less
+ * than NULL" in a NULLS LAST index, or "greater than NULL" in a NULLS
+ * FIRST index.
+ *
+ * Note: someday we might have to fill in sk_collation from the index
+ * column's collation. At the moment this is a non-issue because we'll
+ * never actually call the comparison operator on a NULL.
+ */
+ if (skey->sk_flags & SK_ISNULL)
+ {
+ /* SK_ISNULL shouldn't be set in a row header scankey */
+ Assert(!(skey->sk_flags & SK_ROW_HEADER));
+
+ /* Set indoption flags in scankey (might be done already) */
+ skey->sk_flags |= addflags;
+
+ /* Set correct strategy for IS NULL or NOT NULL search */
+ if (skey->sk_flags & SK_SEARCHNULL)
+ {
+ skey->sk_strategy = BTEqualStrategyNumber;
+ skey->sk_subtype = InvalidOid;
+ skey->sk_collation = InvalidOid;
+ }
+ else if (skey->sk_flags & SK_SEARCHNOTNULL)
+ {
+ if (skey->sk_flags & SK_BT_NULLS_FIRST)
+ skey->sk_strategy = BTGreaterStrategyNumber;
+ else
+ skey->sk_strategy = BTLessStrategyNumber;
+ skey->sk_subtype = InvalidOid;
+ skey->sk_collation = InvalidOid;
+ }
+ else
+ {
+ /* regular qual, so it cannot be satisfied */
+ return false;
+ }
+
+ /* Needn't do the rest */
+ return true;
+ }
+
+ /* Adjust strategy for DESC, if we didn't already */
+ if ((addflags & SK_BT_DESC) && !(skey->sk_flags & SK_BT_DESC))
+ skey->sk_strategy = BTCommuteStrategyNumber(skey->sk_strategy);
+ skey->sk_flags |= addflags;
+
+ /* If it's a row header, fix row member flags and strategies similarly */
+ if (skey->sk_flags & SK_ROW_HEADER)
+ {
+ ScanKey subkey = (ScanKey) DatumGetPointer(skey->sk_argument);
+
+ if (subkey->sk_flags & SK_ISNULL)
+ {
+ /* First row member is NULL, so RowCompare is unsatisfiable */
+ Assert(subkey->sk_flags & SK_ROW_MEMBER);
+ return false;
+ }
+
+ for (;;)
+ {
+ Assert(subkey->sk_flags & SK_ROW_MEMBER);
+ addflags = indoption[subkey->sk_attno - 1] << SK_BT_INDOPTION_SHIFT;
+ if ((addflags & SK_BT_DESC) && !(subkey->sk_flags & SK_BT_DESC))
+ subkey->sk_strategy = BTCommuteStrategyNumber(subkey->sk_strategy);
+ subkey->sk_flags |= addflags;
+ if (subkey->sk_flags & SK_ROW_END)
+ break;
+ subkey++;
+ }
+ }
+
+ return true;
+}
+
+/*
+ * Mark a scankey as "required to continue the scan".
+ *
+ * Depending on the operator type, the key may be required for both scan
+ * directions or just one. Also, if the key is a row comparison header,
+ * we have to mark the appropriate subsidiary ScanKeys as required. In such
+ * cases, the first subsidiary key is required, but subsequent ones are
+ * required only as long as they correspond to successive index columns and
+ * match the leading column as to sort direction. Otherwise the row
+ * comparison ordering is different from the index ordering and so we can't
+ * stop the scan on the basis of those lower-order columns.
+ *
+ * Note: when we set required-key flag bits in a subsidiary scankey, we are
+ * scribbling on a data structure belonging to the index AM's caller, not on
+ * our private copy. This should be OK because the marking will not change
+ * from scan to scan within a query, and so we'd just re-mark the same way
+ * anyway on a rescan. Something to keep an eye on though.
+ */
+static void
+_bt_mark_scankey_required(ScanKey skey)
+{
+ int addflags;
+
+ switch (skey->sk_strategy)
+ {
+ case BTLessStrategyNumber:
+ case BTLessEqualStrategyNumber:
+ addflags = SK_BT_REQFWD;
+ break;
+ case BTEqualStrategyNumber:
+ addflags = SK_BT_REQFWD | SK_BT_REQBKWD;
+ break;
+ case BTGreaterEqualStrategyNumber:
+ case BTGreaterStrategyNumber:
+ addflags = SK_BT_REQBKWD;
+ break;
+ default:
+ elog(ERROR, "unrecognized StrategyNumber: %d",
+ (int) skey->sk_strategy);
+ addflags = 0; /* keep compiler quiet */
+ break;
+ }
+
+ skey->sk_flags |= addflags;
+
+ if (skey->sk_flags & SK_ROW_HEADER)
+ {
+ ScanKey subkey = (ScanKey) DatumGetPointer(skey->sk_argument);
+ AttrNumber attno = skey->sk_attno;
+
+ /* First subkey should be same column/operator as the header */
+ Assert(subkey->sk_attno == attno);
+ Assert(subkey->sk_strategy == skey->sk_strategy);
+
+ for (;;)
+ {
+ Assert(subkey->sk_flags & SK_ROW_MEMBER);
+ if (subkey->sk_attno != attno)
+ break; /* non-adjacent key, so not required */
+ if (subkey->sk_strategy != skey->sk_strategy)
+ break; /* wrong direction, so not required */
+ subkey->sk_flags |= addflags;
+ if (subkey->sk_flags & SK_ROW_END)
+ break;
+ subkey++;
+ attno++;
+ }
+ }
+}
+
+/*
+ * Compare two scankey values using a specified operator.
+ *
+ * The test we want to perform is logically "leftarg op rightarg", where
+ * leftarg and rightarg are the sk_argument values in those ScanKeys, and
+ * the comparison operator is the one in the op ScanKey. However, in
+ * cross-data-type situations we may need to look up the correct operator in
+ * the index's opfamily: it is the one having amopstrategy = op->sk_strategy
+ * and amoplefttype/amoprighttype equal to the two argument datatypes.
+ *
+ * If the opfamily doesn't supply a complete set of cross-type operators we
+ * may not be able to make the comparison. If we can make the comparison
+ * we store the operator result in *result and return true. We return false
+ * if the comparison could not be made.
+ *
+ * If either leftarg or rightarg are an array, we'll apply array-specific
+ * rules to determine which array elements are redundant on behalf of caller.
+ * It is up to our caller to save whichever of the two scan keys is the array,
+ * and discard the non-array scan key (the non-array scan key is guaranteed to
+ * be redundant with any complete opfamily). Caller isn't expected to call
+ * here with a pair of array scan keys provided we're dealing with a complete
+ * opfamily (_bt_preprocess_array_keys will merge array keys together to make
+ * sure of that).
+ *
+ * Note: we'll also shrink caller's array as needed to eliminate redundant
+ * array elements. One reason why caller should prefer to discard non-array
+ * scan keys is so that we'll have the opportunity to shrink the array
+ * multiple times, in multiple calls (for each of several other scan keys on
+ * the same index attribute).
+ *
+ * Note: op always points at the same ScanKey as either leftarg or rightarg.
+ * Since we don't scribble on the scankeys themselves, this aliasing should
+ * cause no trouble.
+ *
+ * Note: this routine needs to be insensitive to any DESC option applied
+ * to the index column. For example, "x < 4" is a tighter constraint than
+ * "x < 5" regardless of which way the index is sorted.
+ */
+static bool
+_bt_compare_scankey_args(IndexScanDesc scan, ScanKey op,
+ ScanKey leftarg, ScanKey rightarg,
+ BTArrayKeyInfo *array, FmgrInfo *orderproc,
+ bool *result)
+{
+ Relation rel = scan->indexRelation;
+ Oid lefttype,
+ righttype,
+ optype,
+ opcintype,
+ cmp_op;
+ StrategyNumber strat;
+
+ Assert(!((leftarg->sk_flags | rightarg->sk_flags) & SK_ROW_MEMBER));
+
+ /*
+ * First, deal with cases where one or both args are NULL. This should
+ * only happen when the scankeys represent IS NULL/NOT NULL conditions.
+ */
+ if ((leftarg->sk_flags | rightarg->sk_flags) & SK_ISNULL)
+ {
+ bool leftnull,
+ rightnull;
+
+ /* Handle skip array comparison with IS NOT NULL scan key */
+ if ((leftarg->sk_flags | rightarg->sk_flags) & SK_BT_SKIP)
+ {
+ /* Shouldn't generate skip array in presence of IS NULL key */
+ Assert(!((leftarg->sk_flags | rightarg->sk_flags) & SK_SEARCHNULL));
+ Assert((leftarg->sk_flags | rightarg->sk_flags) & SK_SEARCHNOTNULL);
+
+ /* Skip array will have no NULL element/IS NULL scan key */
+ Assert(array->num_elems == -1);
+ array->null_elem = false;
+
+ /* IS NOT NULL key (could be leftarg or rightarg) now redundant */
+ *result = true;
+ return true;
+ }
+
+ if (leftarg->sk_flags & SK_ISNULL)
+ {
+ Assert(leftarg->sk_flags & (SK_SEARCHNULL | SK_SEARCHNOTNULL));
+ leftnull = true;
+ }
+ else
+ leftnull = false;
+ if (rightarg->sk_flags & SK_ISNULL)
+ {
+ Assert(rightarg->sk_flags & (SK_SEARCHNULL | SK_SEARCHNOTNULL));
+ rightnull = true;
+ }
+ else
+ rightnull = false;
+
+ /*
+ * We treat NULL as either greater than or less than all other values.
+ * Since true > false, the tests below work correctly for NULLS LAST
+ * logic. If the index is NULLS FIRST, we need to flip the strategy.
+ */
+ strat = op->sk_strategy;
+ if (op->sk_flags & SK_BT_NULLS_FIRST)
+ strat = BTCommuteStrategyNumber(strat);
+
+ switch (strat)
+ {
+ case BTLessStrategyNumber:
+ *result = (leftnull < rightnull);
+ break;
+ case BTLessEqualStrategyNumber:
+ *result = (leftnull <= rightnull);
+ break;
+ case BTEqualStrategyNumber:
+ *result = (leftnull == rightnull);
+ break;
+ case BTGreaterEqualStrategyNumber:
+ *result = (leftnull >= rightnull);
+ break;
+ case BTGreaterStrategyNumber:
+ *result = (leftnull > rightnull);
+ break;
+ default:
+ elog(ERROR, "unrecognized StrategyNumber: %d", (int) strat);
+ *result = false; /* keep compiler quiet */
+ break;
+ }
+ return true;
+ }
+
+ /*
+ * We don't yet know how to determine redundancy when it involves a row
+ * compare key (barring simple cases involving IS NULL/IS NOT NULL)
+ */
+ if ((leftarg->sk_flags | rightarg->sk_flags) & SK_ROW_HEADER)
+ {
+ Assert(!((leftarg->sk_flags | rightarg->sk_flags) & SK_BT_SKIP));
+ return false;
+ }
+
+ /*
+ * If either leftarg or rightarg are equality-type array scankeys, we need
+ * specialized handling (since by now we know that IS NULL wasn't used)
+ */
+ if (array)
+ {
+ bool leftarray,
+ rightarray;
+
+ leftarray = ((leftarg->sk_flags & SK_SEARCHARRAY) &&
+ leftarg->sk_strategy == BTEqualStrategyNumber);
+ rightarray = ((rightarg->sk_flags & SK_SEARCHARRAY) &&
+ rightarg->sk_strategy == BTEqualStrategyNumber);
+
+ /*
+ * _bt_preprocess_array_keys is responsible for merging together array
+ * scan keys, and will do so whenever the opfamily has the required
+ * cross-type support. If it failed to do that, we handle it just
+ * like the case where we can't make the comparison ourselves.
+ */
+ if (leftarray && rightarray)
+ {
+ /* Can't make the comparison */
+ *result = false; /* suppress compiler warnings */
+ Assert(!((leftarg->sk_flags | rightarg->sk_flags) & SK_BT_SKIP));
+ return false;
+ }
+
+ /*
+ * Otherwise we need to determine if either one of leftarg or rightarg
+ * uses an array, then pass this through to a dedicated helper
+ * function.
+ */
+ if (leftarray)
+ return _bt_compare_array_scankey_args(scan, leftarg, rightarg,
+ orderproc, array, result);
+ else if (rightarray)
+ return _bt_compare_array_scankey_args(scan, rightarg, leftarg,
+ orderproc, array, result);
+
+ /* FALL THRU */
+ }
+
+ /*
+ * The opfamily we need to worry about is identified by the index column.
+ */
+ Assert(leftarg->sk_attno == rightarg->sk_attno);
+
+ opcintype = rel->rd_opcintype[leftarg->sk_attno - 1];
+
+ /*
+ * Determine the actual datatypes of the ScanKey arguments. We have to
+ * support the convention that sk_subtype == InvalidOid means the opclass
+ * input type; this is a hack to simplify life for ScanKeyInit().
+ */
+ lefttype = leftarg->sk_subtype;
+ if (lefttype == InvalidOid)
+ lefttype = opcintype;
+ righttype = rightarg->sk_subtype;
+ if (righttype == InvalidOid)
+ righttype = opcintype;
+ optype = op->sk_subtype;
+ if (optype == InvalidOid)
+ optype = opcintype;
+
+ /*
+ * If leftarg and rightarg match the types expected for the "op" scankey,
+ * we can use its already-looked-up comparison function.
+ */
+ if (lefttype == opcintype && righttype == optype)
+ {
+ *result = DatumGetBool(FunctionCall2Coll(&op->sk_func,
+ op->sk_collation,
+ leftarg->sk_argument,
+ rightarg->sk_argument));
+ return true;
+ }
+
+ /*
+ * Otherwise, we need to go to the syscache to find the appropriate
+ * operator. (This cannot result in infinite recursion, since no
+ * indexscan initiated by syscache lookup will use cross-data-type
+ * operators.)
+ *
+ * If the sk_strategy was flipped by _bt_fix_scankey_strategy, we have to
+ * un-flip it to get the correct opfamily member.
+ */
+ strat = op->sk_strategy;
+ if (op->sk_flags & SK_BT_DESC)
+ strat = BTCommuteStrategyNumber(strat);
+
+ cmp_op = get_opfamily_member(rel->rd_opfamily[leftarg->sk_attno - 1],
+ lefttype,
+ righttype,
+ strat);
+ if (OidIsValid(cmp_op))
+ {
+ RegProcedure cmp_proc = get_opcode(cmp_op);
+
+ if (RegProcedureIsValid(cmp_proc))
+ {
+ *result = DatumGetBool(OidFunctionCall2Coll(cmp_proc,
+ op->sk_collation,
+ leftarg->sk_argument,
+ rightarg->sk_argument));
+ return true;
+ }
+ }
+
+ /* Can't make the comparison */
+ *result = false; /* suppress compiler warnings */
+ return false;
+}
+
+/*
+ * Compare an array scan key to a scalar scan key, eliminating contradictory
+ * array elements such that the scalar scan key becomes redundant.
+ *
+ * If the opfamily is incomplete we may not be able to determine which
+ * elements are contradictory. When we return true we'll have validly set
+ * *qual_ok, guaranteeing that at least the scalar scan key can be considered
+ * redundant. We return false if the comparison could not be made (caller
+ * must keep both scan keys when this happens).
+ *
+ * Note: it's up to caller to deal with IS [NOT] NULL scan keys, as well as
+ * row comparison scan keys. We only deal with scalar scan keys.
+ */
+static bool
+_bt_compare_array_scankey_args(IndexScanDesc scan, ScanKey arraysk, ScanKey skey,
+ FmgrInfo *orderproc, BTArrayKeyInfo *array,
+ bool *qual_ok)
+{
+ Assert(arraysk->sk_attno == skey->sk_attno);
+ Assert(!(arraysk->sk_flags & (SK_ISNULL | SK_ROW_HEADER | SK_ROW_MEMBER)));
+ Assert((arraysk->sk_flags & SK_SEARCHARRAY) &&
+ arraysk->sk_strategy == BTEqualStrategyNumber);
+ /* don't expect to have to deal with NULLs/row comparison scan keys */
+ Assert(!(skey->sk_flags & (SK_ISNULL | SK_ROW_HEADER | SK_ROW_MEMBER)));
+ Assert(!(skey->sk_flags & SK_SEARCHARRAY) ||
+ skey->sk_strategy != BTEqualStrategyNumber);
+
+ /*
+ * Just call the appropriate helper function based on whether it's a SAOP
+ * array or a skip array. Both helpers will set *qual_ok in passing.
+ */
+ if (array->num_elems != -1)
+ return _bt_saoparray_shrink(scan, arraysk, skey, orderproc, array,
+ qual_ok);
+ else
+ return _bt_skiparray_shrink(scan, skey, array, qual_ok);
+}
+
+/*
+ * Preprocessing of SAOP array scan key, used to determine which array
+ * elements are eliminated as contradictory by a non-array scalar key.
+ *
+ * _bt_compare_array_scankey_args helper function.
+ *
+ * Array elements can be eliminated as contradictory when excluded by some
+ * other operator on the same attribute. For example, with an index scan qual
+ * "WHERE a IN (1, 2, 3) AND a < 2", all array elements except the value "1"
+ * are eliminated, and the < scan key is eliminated as redundant. Cases where
+ * every array element is eliminated by a redundant scalar scan key have an
+ * unsatisfiable qual, which we handle by setting *qual_ok=false for caller.
+ */
+static bool
+_bt_saoparray_shrink(IndexScanDesc scan, ScanKey arraysk, ScanKey skey,
+ FmgrInfo *orderproc, BTArrayKeyInfo *array, bool *qual_ok)
+{
+ Relation rel = scan->indexRelation;
+ Oid opcintype = rel->rd_opcintype[arraysk->sk_attno - 1];
+ int cmpresult = 0,
+ cmpexact = 0,
+ matchelem,
+ new_nelems = 0;
+ FmgrInfo crosstypeproc;
+ FmgrInfo *orderprocp = orderproc;
+
+ Assert(array->num_elems > 0);
+ Assert(!(arraysk->sk_flags & SK_BT_SKIP));
+
+ /*
+ * _bt_binsrch_array_skey searches an array for the entry best matching a
+ * datum of opclass input type for the index's attribute (on-disk type).
+ * We can reuse the array's ORDER proc whenever the non-array scan key's
+ * type is a match for the corresponding attribute's input opclass type.
+ * Otherwise, we have to do another ORDER proc lookup so that our call to
+ * _bt_binsrch_array_skey applies the correct comparator.
+ *
+ * Note: we have to support the convention that sk_subtype == InvalidOid
+ * means the opclass input type; this is a hack to simplify life for
+ * ScanKeyInit().
+ */
+ if (skey->sk_subtype != opcintype && skey->sk_subtype != InvalidOid)
+ {
+ RegProcedure cmp_proc;
+ Oid arraysk_elemtype;
+
+ /*
+ * Need an ORDER proc lookup to detect redundancy/contradictoriness
+ * with this pair of scankeys.
+ *
+ * Scalar scan key's argument will be passed to _bt_compare_array_skey
+ * as its tupdatum/lefthand argument (rhs arg is for array elements).
+ */
+ arraysk_elemtype = arraysk->sk_subtype;
+ if (arraysk_elemtype == InvalidOid)
+ arraysk_elemtype = rel->rd_opcintype[arraysk->sk_attno - 1];
+ cmp_proc = get_opfamily_proc(rel->rd_opfamily[arraysk->sk_attno - 1],
+ skey->sk_subtype, arraysk_elemtype,
+ BTORDER_PROC);
+ if (!RegProcedureIsValid(cmp_proc))
+ {
+ /* Can't make the comparison */
+ *qual_ok = false; /* suppress compiler warnings */
+ return false;
+ }
+
+ /* We have all we need to determine redundancy/contradictoriness */
+ orderprocp = &crosstypeproc;
+ fmgr_info(cmp_proc, orderprocp);
+ }
+
+ matchelem = _bt_binsrch_array_skey(orderprocp, false,
+ NoMovementScanDirection,
+ skey->sk_argument, false, array,
+ arraysk, &cmpresult);
+
+ switch (skey->sk_strategy)
+ {
+ case BTLessStrategyNumber:
+ cmpexact = 1; /* exclude exact match, if any */
+ /* FALL THRU */
+ case BTLessEqualStrategyNumber:
+ if (cmpresult >= cmpexact)
+ matchelem++;
+ /* Resize, keeping elements from the start of the array */
+ new_nelems = matchelem;
+ break;
+ case BTEqualStrategyNumber:
+ if (cmpresult != 0)
+ {
+ /* qual is unsatisfiable */
+ new_nelems = 0;
+ }
+ else
+ {
+ /* Shift matching element to the start of the array, resize */
+ array->elem_values[0] = array->elem_values[matchelem];
+ new_nelems = 1;
+ }
+ break;
+ case BTGreaterEqualStrategyNumber:
+ cmpexact = 1; /* include exact match, if any */
+ /* FALL THRU */
+ case BTGreaterStrategyNumber:
+ if (cmpresult >= cmpexact)
+ matchelem++;
+ /* Shift matching elements to the start of the array, resize */
+ new_nelems = array->num_elems - matchelem;
+ memmove(array->elem_values, array->elem_values + matchelem,
+ sizeof(Datum) * new_nelems);
+ break;
+ default:
+ elog(ERROR, "unrecognized StrategyNumber: %d",
+ (int) skey->sk_strategy);
+ break;
+ }
+
+ Assert(new_nelems >= 0);
+ Assert(new_nelems <= array->num_elems);
+
+ array->num_elems = new_nelems;
+ *qual_ok = new_nelems > 0;
+
+ return true;
+}
+
+/*
+ * Preprocessing of skip array scan key, used to determine redundancy against
+ * a non-array scalar scan key (must be an inequality).
+ *
+ * _bt_compare_array_scankey_args helper function.
+ *
+ * Skip arrays work by procedurally generating their elements as needed, so we
+ * just store the inequality as the skip array's low_compare or high_compare
+ * (except when there's already a more restrictive low_compare/high_compare).
+ * The array's final elements are the range of values that still satisfy the
+ * array's final low_compare and high_compare.
+ */
+static bool
+_bt_skiparray_shrink(IndexScanDesc scan, ScanKey skey, BTArrayKeyInfo *array,
+ bool *qual_ok)
+{
+ bool test_result;
+
+ Assert(array->num_elems == -1);
+
+ /*
+ * Array's index attribute will be constrained by a strict operator/key.
+ * Array must not "contain a NULL element" (i.e. the scan must not apply
+ * "IS NULL" qual when it reaches the end of the index that stores NULLs).
+ */
+ array->null_elem = false;
+ *qual_ok = true;
+
+ /*
+ * Consider if we should treat caller's scalar scan key as the skip
+ * array's high_compare or low_compare.
+ *
+ * In general the current array element must either be a copy of a value
+ * taken from an index tuple, or a derivative value generated by opclass's
+ * skip support function. That way the scan can always safely assume that
+ * it's okay to use the only-input-opclass-type proc from so->orderProcs[]
+ * (they can be cross-type with SAOP arrays, but never with skip arrays).
+ *
+ * This approach is enabled by MINVAL/MAXVAL sentinel key markings, which
+ * can be thought of as representing either the lowest or highest matching
+ * array element (excluding the NULL element, where applicable, though as
+ * just discussed it isn't applicable to this range skip array anyway).
+ * Array keys marked MINVAL/MAXVAL never have a valid datum in their
+ * sk_argument field. The scan directly applies the array's low_compare
+ * key when it encounters MINVAL in the array key proper (just as it
+ * applies high_compare when it sees MAXVAL set in the array key proper).
+ * The scan must never use the array's so->orderProcs[] proc against
+ * low_compare's/high_compare's sk_argument, either (so->orderProcs[] is
+ * only intended to be used with rhs datums from the array proper/index).
+ */
+ switch (skey->sk_strategy)
+ {
+ case BTLessStrategyNumber:
+ case BTLessEqualStrategyNumber:
+ if (array->high_compare)
+ {
+ /* replace existing high_compare with caller's key? */
+ if (!_bt_compare_scankey_args(scan, array->high_compare, skey,
+ array->high_compare, NULL, NULL,
+ &test_result))
+ return false; /* can't determine more restrictive key */
+
+ if (!test_result)
+ return true; /* no, just discard caller's key */
+
+ /* yes, replace existing high_compare with caller's key */
+ }
+
+ /* caller's key becomes skip array's high_compare */
+ array->high_compare = skey;
+ break;
+ case BTGreaterEqualStrategyNumber:
+ case BTGreaterStrategyNumber:
+ if (array->low_compare)
+ {
+ /* replace existing low_compare with caller's key? */
+ if (!_bt_compare_scankey_args(scan, array->low_compare, skey,
+ array->low_compare, NULL, NULL,
+ &test_result))
+ return false; /* can't determine more restrictive key */
+
+ if (!test_result)
+ return true; /* no, just discard caller's key */
+
+ /* yes, replace existing low_compare with caller's key */
+ }
+
+ /* caller's key becomes skip array's low_compare */
+ array->low_compare = skey;
+ break;
+ case BTEqualStrategyNumber:
+ default:
+ elog(ERROR, "unrecognized StrategyNumber: %d",
+ (int) skey->sk_strategy);
+ break;
+ }
+
+ return true;
+}
+
+/*
+ * Applies the opfamily's skip support routine to convert the skip array's >
+ * low_compare key (if any) into a >= key, and to convert its < high_compare
+ * key (if any) into a <= key. Decrements the high_compare key's sk_argument,
+ * and/or increments the low_compare key's sk_argument (also adjusts their
+ * operator strategies, while changing the operator as appropriate).
+ *
+ * This optional optimization reduces the number of descents required within
+ * _bt_first. Whenever _bt_first is called with a skip array whose current
+ * array element is the sentinel value MINVAL, using a transformed >= key
+ * instead of using the original > key makes it safe to include lower-order
+ * scan keys in the insertion scan key (there must be lower-order scan keys
+ * after the skip array). We will avoid an extra _bt_first to find the first
+ * value in the index > sk_argument -- at least when the first real matching
+ * value in the index happens to be an exact match for the sk_argument value
+ * that we produced here by incrementing the original input key's sk_argument.
+ * (Backwards scans derive the same benefit when they encounter the sentinel
+ * value MAXVAL, by converting the high_compare key from < to <=.)
+ *
+ * Note: The transformation is only correct when it cannot allow the scan to
+ * overlook matching tuples, but we don't have enough semantic information to
+ * safely make sure that can't happen during scans with cross-type operators.
+ * That's why we'll never apply the transformation in cross-type scenarios.
+ * For example, if we attempted to convert "sales_ts > '2024-01-01'::date"
+ * into "sales_ts >= '2024-01-02'::date" given a "sales_ts" attribute whose
+ * input opclass is timestamp_ops, the scan would overlook almost all (or all)
+ * tuples for sales that fell on '2024-01-01'.
+ *
+ * Note: We can safely modify array->low_compare/array->high_compare in place
+ * because they just point to copies of our scan->keyData[] input scan keys
+ * (namely the copies returned by _bt_preprocess_array_keys to be used as
+ * input into the standard preprocessing steps in _bt_preprocess_keys).
+ * Everything will be reset if there's a rescan.
+ */
+static void
+_bt_skiparray_strat_adjust(IndexScanDesc scan, ScanKey arraysk,
+ BTArrayKeyInfo *array)
+{
+ BTScanOpaque so = (BTScanOpaque) scan->opaque;
+ MemoryContext oldContext;
+
+ /*
+ * Called last among all preprocessing steps, when the skip array's final
+ * low_compare and high_compare have both been chosen
+ */
+ Assert(arraysk->sk_flags & SK_BT_SKIP);
+ Assert(array->num_elems == -1 && !array->null_elem && array->sksup);
+
+ oldContext = MemoryContextSwitchTo(so->arrayContext);
+
+ if (array->high_compare &&
+ array->high_compare->sk_strategy == BTLessStrategyNumber)
+ _bt_skiparray_strat_decrement(scan, arraysk, array);
+
+ if (array->low_compare &&
+ array->low_compare->sk_strategy == BTGreaterStrategyNumber)
+ _bt_skiparray_strat_increment(scan, arraysk, array);
+
+ MemoryContextSwitchTo(oldContext);
+}
+
+/*
+ * Convert skip array's > low_compare key into a >= key
+ */
+static void
+_bt_skiparray_strat_decrement(IndexScanDesc scan, ScanKey arraysk,
+ BTArrayKeyInfo *array)
+{
+ Relation rel = scan->indexRelation;
+ Oid opfamily = rel->rd_opfamily[arraysk->sk_attno - 1],
+ opcintype = rel->rd_opcintype[arraysk->sk_attno - 1],
+ leop;
+ RegProcedure cmp_proc;
+ ScanKey high_compare = array->high_compare;
+ Datum orig_sk_argument = high_compare->sk_argument,
+ new_sk_argument;
+ bool uflow;
+
+ Assert(high_compare->sk_strategy == BTLessStrategyNumber);
+
+ /*
+ * Only perform the transformation when the operator type matches the
+ * index attribute's input opclass type
+ */
+ if (high_compare->sk_subtype != opcintype &&
+ high_compare->sk_subtype != InvalidOid)
+ return;
+
+ /* Decrement, handling underflow by marking the qual unsatisfiable */
+ new_sk_argument = array->sksup->decrement(rel, orig_sk_argument, &uflow);
+ if (uflow)
+ {
+ BTScanOpaque so = (BTScanOpaque) scan->opaque;
+
+ so->qual_ok = false;
+ return;
+ }
+
+ /* Look up <= operator (might fail) */
+ leop = get_opfamily_member(opfamily, opcintype, opcintype,
+ BTLessEqualStrategyNumber);
+ if (!OidIsValid(leop))
+ return;
+ cmp_proc = get_opcode(leop);
+ if (RegProcedureIsValid(cmp_proc))
+ {
+ /* Transform < high_compare key into <= key */
+ fmgr_info(cmp_proc, &high_compare->sk_func);
+ high_compare->sk_argument = new_sk_argument;
+ high_compare->sk_strategy = BTLessEqualStrategyNumber;
+ }
+}
+
+/*
+ * Convert skip array's < low_compare key into a <= key
+ */
+static void
+_bt_skiparray_strat_increment(IndexScanDesc scan, ScanKey arraysk,
+ BTArrayKeyInfo *array)
+{
+ Relation rel = scan->indexRelation;
+ Oid opfamily = rel->rd_opfamily[arraysk->sk_attno - 1],
+ opcintype = rel->rd_opcintype[arraysk->sk_attno - 1],
+ geop;
+ RegProcedure cmp_proc;
+ ScanKey low_compare = array->low_compare;
+ Datum orig_sk_argument = low_compare->sk_argument,
+ new_sk_argument;
+ bool oflow;
+
+ Assert(low_compare->sk_strategy == BTGreaterStrategyNumber);
+
+ /*
+ * Only perform the transformation when the operator type matches the
+ * index attribute's input opclass type
+ */
+ if (low_compare->sk_subtype != opcintype &&
+ low_compare->sk_subtype != InvalidOid)
+ return;
+
+ /* Increment, handling overflow by marking the qual unsatisfiable */
+ new_sk_argument = array->sksup->increment(rel, orig_sk_argument, &oflow);
+ if (oflow)
+ {
+ BTScanOpaque so = (BTScanOpaque) scan->opaque;
+
+ so->qual_ok = false;
+ return;
+ }
+
+ /* Look up >= operator (might fail) */
+ geop = get_opfamily_member(opfamily, opcintype, opcintype,
+ BTGreaterEqualStrategyNumber);
+ if (!OidIsValid(geop))
+ return;
+ cmp_proc = get_opcode(geop);
+ if (RegProcedureIsValid(cmp_proc))
+ {
+ /* Transform > low_compare key into >= key */
+ fmgr_info(cmp_proc, &low_compare->sk_func);
+ low_compare->sk_argument = new_sk_argument;
+ low_compare->sk_strategy = BTGreaterEqualStrategyNumber;
+ }
+}
+
+/*
+ * _bt_unmark_keys() -- make superfluous required keys nonrequired after all
+ *
+ * When _bt_preprocess_keys fails to eliminate one or more redundant keys, it
+ * calls here to make sure that no index attribute has more than one > or >=
+ * key marked required, and no more than one required < or <= key. Attributes
+ * with = keys will always get one = key as their required key. All other
+ * keys that were initially marked required get "unmarked" here. That way,
+ * _bt_first and _bt_checkkeys will reliably agree on which keys to use to
+ * start and/or to end the scan.
+ *
+ * We also relocate keys that become/started out nonrequired to the end of
+ * so->keyData[]. That way, _bt_first and _bt_checkkeys cannot fail to reach
+ * a required key due to some earlier nonrequired key getting in the way.
+ *
+ * Only call here when _bt_compare_scankey_args returned false at least once
+ * (otherwise, calling here will just waste cycles).
+ */
+static void
+_bt_unmark_keys(IndexScanDesc scan, int *keyDataMap)
+{
+ BTScanOpaque so = (BTScanOpaque) scan->opaque;
+ AttrNumber attno;
+ bool *unmarkikey;
+ int nunmark,
+ nunmarked,
+ nkept,
+ firsti;
+ ScanKey keepKeys,
+ unmarkKeys;
+ FmgrInfo *keepOrderProcs = NULL,
+ *unmarkOrderProcs = NULL;
+ bool haveReqEquals,
+ haveReqForward,
+ haveReqBackward;
+
+ /*
+ * Do an initial pass over so->keyData[] that determines which keys to
+ * keep as required. We expect so->keyData[] to still be in attribute
+ * order when we're called (though we don't expect any particular order
+ * among each attribute's keys).
+ *
+ * When both equality and inequality keys remain on a single attribute, we
+ * *must* make sure that exactly one of the equalities remains required.
+ * Any requiredness markings that we might leave on later keys/attributes
+ * are predicated on there being required = keys on all prior columns.
+ */
+ unmarkikey = palloc0(so->numberOfKeys * sizeof(bool));
+ nunmark = 0;
+
+ /* Set things up for first key's attribute */
+ attno = so->keyData[0].sk_attno;
+ firsti = 0;
+ haveReqEquals = false;
+ haveReqForward = false;
+ haveReqBackward = false;
+ for (int i = 0; i < so->numberOfKeys; i++)
+ {
+ ScanKey origkey = &so->keyData[i];
+
+ if (origkey->sk_attno != attno)
+ {
+ /* Reset for next attribute */
+ attno = origkey->sk_attno;
+ firsti = i;
+
+ haveReqEquals = false;
+ haveReqForward = false;
+ haveReqBackward = false;
+ }
+
+ /* Equalities get priority over inequalities */
+ if (haveReqEquals)
+ {
+ /*
+ * We already found the first "=" key for this attribute. We've
+ * already decided that all its other keys will be unmarked.
+ */
+ Assert(!(origkey->sk_flags & SK_SEARCHNULL));
+ unmarkikey[i] = true;
+ nunmark++;
+ continue;
+ }
+ else if ((origkey->sk_flags & SK_BT_REQFWD) &&
+ (origkey->sk_flags & SK_BT_REQBKWD))
+ {
+ /*
+ * Found the first "=" key for attno. All other attno keys will
+ * be unmarked.
+ */
+ Assert(origkey->sk_strategy == BTEqualStrategyNumber);
+
+ haveReqEquals = true;
+ for (int j = firsti; j < i; j++)
+ {
+ /* Unmark any prior inequality keys on attno after all */
+ if (!unmarkikey[j])
+ {
+ unmarkikey[j] = true;
+ nunmark++;
+ }
+ }
+ continue;
+ }
+
+ /* Deal with inequalities next */
+ if ((origkey->sk_flags & SK_BT_REQFWD) && !haveReqForward)
+ {
+ haveReqForward = true;
+ continue;
+ }
+ else if ((origkey->sk_flags & SK_BT_REQBKWD) && !haveReqBackward)
+ {
+ haveReqBackward = true;
+ continue;
+ }
+
+ /*
+ * We have either a redundant inequality key that will be unmarked, or
+ * we have a key that wasn't marked required in the first place
+ */
+ unmarkikey[i] = true;
+ nunmark++;
+ }
+
+ /* Should only be called when _bt_compare_scankey_args reported failure */
+ Assert(nunmark > 0);
+
+ /*
+ * Next, allocate temp arrays: one for required keys that'll remain
+ * required, the other for all remaining keys
+ */
+ unmarkKeys = palloc(nunmark * sizeof(ScanKeyData));
+ keepKeys = palloc((so->numberOfKeys - nunmark) * sizeof(ScanKeyData));
+ nunmarked = 0;
+ nkept = 0;
+ if (so->numArrayKeys)
+ {
+ unmarkOrderProcs = palloc(nunmark * sizeof(FmgrInfo));
+ keepOrderProcs = palloc((so->numberOfKeys - nunmark) * sizeof(FmgrInfo));
+ }
+
+ /*
+ * Next, copy the contents of so->keyData[] into the appropriate temp
+ * array.
+ *
+ * Scans with = array keys need us to maintain invariants around the order
+ * of so->orderProcs[] and so->arrayKeys[] relative to so->keyData[]. See
+ * _bt_preprocess_array_keys_final for a full explanation.
+ */
+ for (int i = 0; i < so->numberOfKeys; i++)
+ {
+ ScanKey origkey = &so->keyData[i];
+ ScanKey unmark;
+
+ if (!unmarkikey[i])
+ {
+ /*
+ * Key gets to keep its original requiredness markings.
+ *
+ * Key will stay in its original position, unless we're going to
+ * unmark an earlier key (in which case this key gets moved back).
+ */
+ memcpy(keepKeys + nkept, origkey, sizeof(ScanKeyData));
+
+ if (so->numArrayKeys)
+ {
+ keyDataMap[i] = nkept;
+ memcpy(keepOrderProcs + nkept, &so->orderProcs[i],
+ sizeof(FmgrInfo));
+ }
+
+ nkept++;
+ continue;
+ }
+
+ /*
+ * Key will be unmarked as needed, and moved to the end of the array,
+ * next to other keys that will become (or always were) nonrequired
+ */
+ unmark = unmarkKeys + nunmarked;
+ memcpy(unmark, origkey, sizeof(ScanKeyData));
+
+ if (so->numArrayKeys)
+ {
+ keyDataMap[i] = (so->numberOfKeys - nunmark) + nunmarked;
+ memcpy(&unmarkOrderProcs[nunmarked], &so->orderProcs[i],
+ sizeof(FmgrInfo));
+ }
+
+ /*
+ * Preprocessing only generates skip arrays when it knows that they'll
+ * be the only required = key on the attr. We'll never unmark them.
+ */
+ Assert(!(unmark->sk_flags & SK_BT_SKIP));
+
+ /*
+ * Also shouldn't have to unmark an IS NULL or an IS NOT NULL key.
+ * They aren't cross-type, so an incomplete opfamily can't matter.
+ */
+ Assert(!(unmark->sk_flags & SK_ISNULL) ||
+ !(unmark->sk_flags & (SK_BT_REQFWD | SK_BT_REQBKWD)));
+
+ /* Clear requiredness flags on redundant key (and on any subkeys) */
+ unmark->sk_flags &= ~(SK_BT_REQFWD | SK_BT_REQBKWD);
+ if (unmark->sk_flags & SK_ROW_HEADER)
+ {
+ ScanKey subkey = (ScanKey) DatumGetPointer(unmark->sk_argument);
+
+ Assert(subkey->sk_strategy == unmark->sk_strategy);
+ for (;;)
+ {
+ Assert(subkey->sk_flags & SK_ROW_MEMBER);
+ subkey->sk_flags &= ~(SK_BT_REQFWD | SK_BT_REQBKWD);
+ if (subkey->sk_flags & SK_ROW_END)
+ break;
+ subkey++;
+ }
+ }
+
+ nunmarked++;
+ }
+
+ /* Copy both temp arrays back into so->keyData[] to reorder */
+ Assert(nkept == so->numberOfKeys - nunmark);
+ Assert(nunmarked == nunmark);
+ memcpy(so->keyData, keepKeys, sizeof(ScanKeyData) * nkept);
+ memcpy(so->keyData + nkept, unmarkKeys, sizeof(ScanKeyData) * nunmarked);
+
+ /* Done with temp arrays */
+ pfree(unmarkikey);
+ pfree(keepKeys);
+ pfree(unmarkKeys);
+
+ /*
+ * Now copy so->orderProcs[] temp entries needed by scans with = array
+ * keys back (just like with the so->keyData[] temp arrays)
+ */
+ if (so->numArrayKeys)
+ {
+ memcpy(so->orderProcs, keepOrderProcs, sizeof(FmgrInfo) * nkept);
+ memcpy(so->orderProcs + nkept, unmarkOrderProcs,
+ sizeof(FmgrInfo) * nunmarked);
+
+ /* Also fix-up array->scan_key references */
+ for (int arridx = 0; arridx < so->numArrayKeys; arridx++)
+ {
+ BTArrayKeyInfo *array = &so->arrayKeys[arridx];
+
+ array->scan_key = keyDataMap[array->scan_key];
+ }
+
+ /*
+ * Sort so->arrayKeys[] based on its new BTArrayKeyInfo.scan_key
+ * offsets, so that its order matches so->keyData[] order as expected
+ */
+ qsort(so->arrayKeys, so->numArrayKeys, sizeof(BTArrayKeyInfo),
+ _bt_reorder_array_cmp);
+
+ /* Done with temp arrays */
+ pfree(unmarkOrderProcs);
+ pfree(keepOrderProcs);
+ }
+}
+
+/*
+ * qsort comparator for reordering so->arrayKeys[] BTArrayKeyInfo entries
+ */
+static int
+_bt_reorder_array_cmp(const void *a, const void *b)
+{
+ BTArrayKeyInfo *arraya = (BTArrayKeyInfo *) a;
+ BTArrayKeyInfo *arrayb = (BTArrayKeyInfo *) b;
+
+ return pg_cmp_s32(arraya->scan_key, arrayb->scan_key);
+}
+
+/*
+ * _bt_preprocess_array_keys() -- Preprocess SK_SEARCHARRAY scan keys
+ *
+ * If there are any SK_SEARCHARRAY scan keys, deconstruct the array(s) and
+ * set up BTArrayKeyInfo info for each one that is an equality-type key.
+ * Returns modified scan keys as input for further, standard preprocessing.
+ *
+ * Currently we perform two kinds of preprocessing to deal with redundancies.
+ * For inequality array keys, it's sufficient to find the extreme element
+ * value and replace the whole array with that scalar value. This eliminates
+ * all but one array element as redundant. Similarly, we are capable of
+ * "merging together" multiple equality array keys (from two or more input
+ * scan keys) into a single output scan key containing only the intersecting
+ * array elements. This can eliminate many redundant array elements, as well
+ * as eliminating whole array scan keys as redundant. It can also allow us to
+ * detect contradictory quals.
+ *
+ * Caller must pass *new_numberOfKeys to give us a way to change the number of
+ * scan keys that caller treats as input to standard preprocessing steps. The
+ * returned array is smaller than scan->keyData[] when we could eliminate a
+ * redundant array scan key (redundant with another array scan key). It is
+ * convenient for _bt_preprocess_keys caller to have to deal with no more than
+ * one equality strategy array scan key per index attribute. We'll always be
+ * able to set things up that way when complete opfamilies are used.
+ *
+ * We're also responsible for generating skip arrays (and their associated
+ * scan keys) here. This enables skip scan. We do this for index attributes
+ * that initially lacked an equality condition within scan->keyData[], iff
+ * doing so allows a later scan key (that was passed to us in scan->keyData[])
+ * to be marked required by our _bt_preprocess_keys caller.
+ *
+ * We set the scan key references from the scan's BTArrayKeyInfo info array to
+ * offsets into the temp modified input array returned to caller. Scans that
+ * have array keys should call _bt_preprocess_array_keys_final when standard
+ * preprocessing steps are complete. This will convert the scan key offset
+ * references into references to the scan's so->keyData[] output scan keys.
+ *
+ * Note: the reason we need to return a temp scan key array, rather than just
+ * modifying scan->keyData[], is that callers are permitted to call btrescan
+ * without supplying a new set of scankey data. Certain other preprocessing
+ * routines (e.g., _bt_fix_scankey_strategy) _can_ modify scan->keyData[], but
+ * we can't make that work here because our modifications are non-idempotent.
+ */
+static ScanKey
+_bt_preprocess_array_keys(IndexScanDesc scan, int *new_numberOfKeys)
+{
+ BTScanOpaque so = (BTScanOpaque) scan->opaque;
+ Relation rel = scan->indexRelation;
+ int16 *indoption = rel->rd_indoption;
+ Oid skip_eq_ops[INDEX_MAX_KEYS];
+ int numArrayKeys,
+ numSkipArrayKeys,
+ numArrayKeyData;
+ AttrNumber attno_skip = 1;
+ int origarrayatt = InvalidAttrNumber,
+ origarraykey = -1;
+ Oid origelemtype = InvalidOid;
+ MemoryContext oldContext;
+ ScanKey arrayKeyData; /* modified copy of scan->keyData */
+
+ /*
+ * Check the number of input array keys within scan->keyData[] input keys
+ * (also checks if we should add extra skip arrays based on input keys)
+ */
+ numArrayKeys = _bt_num_array_keys(scan, skip_eq_ops, &numSkipArrayKeys);
+
+ /* Quit if nothing to do. */
+ if (numArrayKeys == 0)
+ return NULL;
+
+ /*
+ * Estimated final size of arrayKeyData[] array we'll return to our caller
+ * is the size of the original scan->keyData[] input array, plus space for
+ * any additional skip array scan keys we'll need to generate below
+ */
+ numArrayKeyData = scan->numberOfKeys + numSkipArrayKeys;
+
+ /*
+ * Make a scan-lifespan context to hold array-associated data, or reset it
+ * if we already have one from a previous rescan cycle.
+ */
+ if (so->arrayContext == NULL)
+ so->arrayContext = AllocSetContextCreate(CurrentMemoryContext,
+ "BTree array context",
+ ALLOCSET_SMALL_SIZES);
+ else
+ MemoryContextReset(so->arrayContext);
+
+ oldContext = MemoryContextSwitchTo(so->arrayContext);
+
+ /* Create output scan keys in the workspace context */
+ arrayKeyData = (ScanKey) palloc(numArrayKeyData * sizeof(ScanKeyData));
+
+ /* Allocate space for per-array data in the workspace context */
+ so->skipScan = (numSkipArrayKeys > 0);
+ so->arrayKeys = (BTArrayKeyInfo *) palloc(numArrayKeys * sizeof(BTArrayKeyInfo));
+
+ /* Allocate space for ORDER procs used to help _bt_checkkeys */
+ so->orderProcs = (FmgrInfo *) palloc(numArrayKeyData * sizeof(FmgrInfo));
+
+ numArrayKeys = 0;
+ numArrayKeyData = 0;
+ for (int input_ikey = 0; input_ikey < scan->numberOfKeys; input_ikey++)
+ {
+ ScanKey inkey = scan->keyData + input_ikey,
+ cur;
+ FmgrInfo sortproc;
+ FmgrInfo *sortprocp = &sortproc;
+ Oid elemtype;
+ bool reverse;
+ ArrayType *arrayval;
+ int16 elmlen;
+ bool elmbyval;
+ char elmalign;
+ int num_elems;
+ Datum *elem_values;
+ bool *elem_nulls;
+ int num_nonnulls;
+
+ /* set up next output scan key */
+ cur = &arrayKeyData[numArrayKeyData];
+
+ /* Backfill skip arrays for attrs < or <= input key's attr? */
+ while (numSkipArrayKeys && attno_skip <= inkey->sk_attno)
+ {
+ Oid opfamily = rel->rd_opfamily[attno_skip - 1];
+ Oid opcintype = rel->rd_opcintype[attno_skip - 1];
+ Oid collation = rel->rd_indcollation[attno_skip - 1];
+ Oid eq_op = skip_eq_ops[attno_skip - 1];
+ CompactAttribute *attr;
+ RegProcedure cmp_proc;
+
+ if (!OidIsValid(eq_op))
+ {
+ /*
+ * Attribute already has an = input key, so don't output a
+ * skip array for attno_skip. Just copy attribute's = input
+ * key into arrayKeyData[] once outside this inner loop.
+ *
+ * Note: When we get here there must be a later attribute that
+ * lacks an equality input key, and still needs a skip array
+ * (if there wasn't then numSkipArrayKeys would be 0 by now).
+ */
+ Assert(attno_skip == inkey->sk_attno);
+ /* inkey can't be last input key to be marked required: */
+ Assert(input_ikey < scan->numberOfKeys - 1);
+#if 0
+ /* Could be a redundant input scan key, so can't do this: */
+ Assert(inkey->sk_strategy == BTEqualStrategyNumber ||
+ (inkey->sk_flags & SK_SEARCHNULL));
+#endif
+
+ attno_skip++;
+ break;
+ }
+
+ cmp_proc = get_opcode(eq_op);
+ if (!RegProcedureIsValid(cmp_proc))
+ elog(ERROR, "missing oprcode for skipping equals operator %u", eq_op);
+
+ ScanKeyEntryInitialize(cur,
+ SK_SEARCHARRAY | SK_BT_SKIP, /* flags */
+ attno_skip, /* skipped att number */
+ BTEqualStrategyNumber, /* equality strategy */
+ InvalidOid, /* opclass input subtype */
+ collation, /* index column's collation */
+ cmp_proc, /* equality operator's proc */
+ (Datum) 0); /* constant */
+
+ /* Initialize generic BTArrayKeyInfo fields */
+ so->arrayKeys[numArrayKeys].scan_key = numArrayKeyData;
+ so->arrayKeys[numArrayKeys].num_elems = -1;
+
+ /* Initialize skip array specific BTArrayKeyInfo fields */
+ attr = TupleDescCompactAttr(RelationGetDescr(rel), attno_skip - 1);
+ reverse = (indoption[attno_skip - 1] & INDOPTION_DESC) != 0;
+ so->arrayKeys[numArrayKeys].attlen = attr->attlen;
+ so->arrayKeys[numArrayKeys].attbyval = attr->attbyval;
+ so->arrayKeys[numArrayKeys].null_elem = true; /* for now */
+ so->arrayKeys[numArrayKeys].sksup =
+ PrepareSkipSupportFromOpclass(opfamily, opcintype, reverse);
+ so->arrayKeys[numArrayKeys].low_compare = NULL; /* for now */
+ so->arrayKeys[numArrayKeys].high_compare = NULL; /* for now */
+
+ /*
+ * We'll need a 3-way ORDER proc. Set that up now.
+ */
+ _bt_setup_array_cmp(scan, cur, opcintype,
+ &so->orderProcs[numArrayKeyData], NULL);
+
+ numArrayKeys++;
+ numArrayKeyData++; /* keep this scan key/array */
+
+ /* set up next output scan key */
+ cur = &arrayKeyData[numArrayKeyData];
+
+ /* remember having output this skip array and scan key */
+ numSkipArrayKeys--;
+ attno_skip++;
+ }
+
+ /*
+ * Provisionally copy scan key into arrayKeyData[] array we'll return
+ * to _bt_preprocess_keys caller
+ */
+ *cur = *inkey;
+
+ if (!(cur->sk_flags & SK_SEARCHARRAY))
+ {
+ numArrayKeyData++; /* keep this non-array scan key */
+ continue;
+ }
+
+ /*
+ * Process SAOP array scan key
+ */
+ Assert(!(cur->sk_flags & (SK_ROW_HEADER | SK_SEARCHNULL | SK_SEARCHNOTNULL)));
+
+ /* If array is null as a whole, the scan qual is unsatisfiable */
+ if (cur->sk_flags & SK_ISNULL)
+ {
+ so->qual_ok = false;
+ break;
+ }
+
+ /*
+ * Deconstruct the array into elements
+ */
+ arrayval = DatumGetArrayTypeP(cur->sk_argument);
+ /* We could cache this data, but not clear it's worth it */
+ get_typlenbyvalalign(ARR_ELEMTYPE(arrayval),
+ &elmlen, &elmbyval, &elmalign);
+ deconstruct_array(arrayval,
+ ARR_ELEMTYPE(arrayval),
+ elmlen, elmbyval, elmalign,
+ &elem_values, &elem_nulls, &num_elems);
+
+ /*
+ * Compress out any null elements. We can ignore them since we assume
+ * all btree operators are strict.
+ */
+ num_nonnulls = 0;
+ for (int j = 0; j < num_elems; j++)
+ {
+ if (!elem_nulls[j])
+ elem_values[num_nonnulls++] = elem_values[j];
+ }
+
+ /* We could pfree(elem_nulls) now, but not worth the cycles */
+
+ /* If there's no non-nulls, the scan qual is unsatisfiable */
+ if (num_nonnulls == 0)
+ {
+ so->qual_ok = false;
+ break;
+ }
+
+ /*
+ * Determine the nominal datatype of the array elements. We have to
+ * support the convention that sk_subtype == InvalidOid means the
+ * opclass input type; this is a hack to simplify life for
+ * ScanKeyInit().
+ */
+ elemtype = cur->sk_subtype;
+ if (elemtype == InvalidOid)
+ elemtype = rel->rd_opcintype[cur->sk_attno - 1];
+
+ /*
+ * If the comparison operator is not equality, then the array qual
+ * degenerates to a simple comparison against the smallest or largest
+ * non-null array element, as appropriate.
+ */
+ switch (cur->sk_strategy)
+ {
+ case BTLessStrategyNumber:
+ case BTLessEqualStrategyNumber:
+ cur->sk_argument =
+ _bt_find_extreme_element(scan, cur, elemtype,
+ BTGreaterStrategyNumber,
+ elem_values, num_nonnulls);
+ numArrayKeyData++; /* keep this transformed scan key */
+ continue;
+ case BTEqualStrategyNumber:
+ /* proceed with rest of loop */
+ break;
+ case BTGreaterEqualStrategyNumber:
+ case BTGreaterStrategyNumber:
+ cur->sk_argument =
+ _bt_find_extreme_element(scan, cur, elemtype,
+ BTLessStrategyNumber,
+ elem_values, num_nonnulls);
+ numArrayKeyData++; /* keep this transformed scan key */
+ continue;
+ default:
+ elog(ERROR, "unrecognized StrategyNumber: %d",
+ (int) cur->sk_strategy);
+ break;
+ }
+
+ /*
+ * We'll need a 3-way ORDER proc to perform binary searches for the
+ * next matching array element. Set that up now.
+ *
+ * Array scan keys with cross-type equality operators will require a
+ * separate same-type ORDER proc for sorting their array. Otherwise,
+ * sortproc just points to the same proc used during binary searches.
+ */
+ _bt_setup_array_cmp(scan, cur, elemtype,
+ &so->orderProcs[numArrayKeyData], &sortprocp);
+
+ /*
+ * Sort the non-null elements and eliminate any duplicates. We must
+ * sort in the same ordering used by the index column, so that the
+ * arrays can be advanced in lockstep with the scan's progress through
+ * the index's key space.
+ */
+ reverse = (indoption[cur->sk_attno - 1] & INDOPTION_DESC) != 0;
+ num_elems = _bt_sort_array_elements(cur, sortprocp, reverse,
+ elem_values, num_nonnulls);
+
+ if (origarrayatt == cur->sk_attno)
+ {
+ BTArrayKeyInfo *orig = &so->arrayKeys[origarraykey];
+
+ /*
+ * This array scan key is redundant with a previous equality
+ * operator array scan key. Merge the two arrays together to
+ * eliminate contradictory non-intersecting elements (or try to).
+ *
+ * We merge this next array back into attribute's original array.
+ */
+ Assert(arrayKeyData[orig->scan_key].sk_attno == cur->sk_attno);
+ Assert(arrayKeyData[orig->scan_key].sk_collation ==
+ cur->sk_collation);
+ if (_bt_merge_arrays(scan, cur, sortprocp, reverse,
+ origelemtype, elemtype,
+ orig->elem_values, &orig->num_elems,
+ elem_values, num_elems))
+ {
+ /* Successfully eliminated this array */
+ pfree(elem_values);
+
+ /*
+ * If no intersecting elements remain in the original array,
+ * the scan qual is unsatisfiable
+ */
+ if (orig->num_elems == 0)
+ {
+ so->qual_ok = false;
+ break;
+ }
+
+ /* Throw away this scan key/array */
+ continue;
+ }
+
+ /*
+ * Unable to merge this array with previous array due to a lack of
+ * suitable cross-type opfamily support. Will need to keep both
+ * scan keys/arrays.
+ */
+ }
+ else
+ {
+ /*
+ * This array is the first for current index attribute.
+ *
+ * If it turns out to not be the last array (that is, if the next
+ * array is redundantly applied to this same index attribute),
+ * we'll then treat this array as the attribute's "original" array
+ * when merging.
+ */
+ origarrayatt = cur->sk_attno;
+ origarraykey = numArrayKeys;
+ origelemtype = elemtype;
+ }
+
+ /* Initialize generic BTArrayKeyInfo fields */
+ so->arrayKeys[numArrayKeys].scan_key = numArrayKeyData;
+ so->arrayKeys[numArrayKeys].num_elems = num_elems;
+
+ /* Initialize SAOP array specific BTArrayKeyInfo fields */
+ so->arrayKeys[numArrayKeys].elem_values = elem_values;
+ so->arrayKeys[numArrayKeys].cur_elem = -1; /* i.e. invalid */
+
+ numArrayKeys++;
+ numArrayKeyData++; /* keep this scan key/array */
+ }
+
+ Assert(numSkipArrayKeys == 0 || !so->qual_ok);
+
+ /* Set final number of equality-type array keys */
+ so->numArrayKeys = numArrayKeys;
+ /* Set number of scan keys in arrayKeyData[] */
+ *new_numberOfKeys = numArrayKeyData;
+
+ MemoryContextSwitchTo(oldContext);
+
+ return arrayKeyData;
+}
+
+/*
+ * _bt_preprocess_array_keys_final() -- fix up array scan key references
+ *
+ * When _bt_preprocess_array_keys performed initial array preprocessing, it
+ * set each array's array->scan_key to its scankey's arrayKeyData[] offset.
+ * This function handles translation of the scan key references from the
+ * BTArrayKeyInfo info array, from input scan key references (to the keys in
+ * arrayKeyData[]), into output references (to the keys in so->keyData[]).
+ * Caller's keyDataMap[] array tells us how to perform this remapping.
+ *
+ * Also finalizes so->orderProcs[] for the scan. Arrays already have an ORDER
+ * proc, which might need to be repositioned to its so->keyData[]-wise offset
+ * (very much like the remapping that we apply to array->scan_key references).
+ * Non-array equality strategy scan keys (that survived preprocessing) don't
+ * yet have an so->orderProcs[] entry, so we set one for them here.
+ *
+ * Also converts single-element array scan keys into equivalent non-array
+ * equality scan keys, which decrements so->numArrayKeys. It's possible that
+ * this will leave this new btrescan without any arrays at all. This isn't
+ * necessary for correctness; it's just an optimization. Non-array equality
+ * scan keys are slightly faster than equivalent array scan keys at runtime.
+ */
+static void
+_bt_preprocess_array_keys_final(IndexScanDesc scan, int *keyDataMap)
+{
+ BTScanOpaque so = (BTScanOpaque) scan->opaque;
+ Relation rel = scan->indexRelation;
+ int arrayidx = 0;
+ int last_equal_output_ikey PG_USED_FOR_ASSERTS_ONLY = -1;
+
+ Assert(so->qual_ok);
+
+ /*
+ * Nothing for us to do when _bt_preprocess_array_keys only had to deal
+ * with array inequalities
+ */
+ if (so->numArrayKeys == 0)
+ return;
+
+ for (int output_ikey = 0; output_ikey < so->numberOfKeys; output_ikey++)
+ {
+ ScanKey outkey = so->keyData + output_ikey;
+ int input_ikey;
+ bool found PG_USED_FOR_ASSERTS_ONLY = false;
+
+ Assert(outkey->sk_strategy != InvalidStrategy);
+
+ if (outkey->sk_strategy != BTEqualStrategyNumber)
+ continue;
+
+ input_ikey = keyDataMap[output_ikey];
+
+ Assert(last_equal_output_ikey < output_ikey);
+ Assert(last_equal_output_ikey < input_ikey);
+ last_equal_output_ikey = output_ikey;
+
+ /*
+ * We're lazy about looking up ORDER procs for non-array keys, since
+ * not all input keys become output keys. Take care of it now.
+ */
+ if (!(outkey->sk_flags & SK_SEARCHARRAY))
+ {
+ Oid elemtype;
+
+ /* No need for an ORDER proc given an IS NULL scan key */
+ if (outkey->sk_flags & SK_SEARCHNULL)
+ continue;
+
+ /*
+ * A non-required scan key doesn't need an ORDER proc, either
+ * (unless it's associated with an array, which this one isn't)
+ */
+ if (!(outkey->sk_flags & SK_BT_REQFWD))
+ continue;
+
+ elemtype = outkey->sk_subtype;
+ if (elemtype == InvalidOid)
+ elemtype = rel->rd_opcintype[outkey->sk_attno - 1];
+
+ _bt_setup_array_cmp(scan, outkey, elemtype,
+ &so->orderProcs[output_ikey], NULL);
+ continue;
+ }
+
+ /*
+ * Reorder existing array scan key so->orderProcs[] entries.
+ *
+ * Doing this in-place is safe because preprocessing is required to
+ * output all equality strategy scan keys in original input order
+ * (among each group of entries against the same index attribute).
+ * This is also the order that the arrays themselves appear in.
+ */
+ so->orderProcs[output_ikey] = so->orderProcs[input_ikey];
+
+ /* Fix-up array->scan_key references for arrays */
+ for (; arrayidx < so->numArrayKeys; arrayidx++)
+ {
+ BTArrayKeyInfo *array = &so->arrayKeys[arrayidx];
+
+ /*
+ * All skip arrays must be marked required, and final column can
+ * never have a skip array
+ */
+ Assert(array->num_elems > 0 || array->num_elems == -1);
+ Assert(array->num_elems != -1 || outkey->sk_flags & SK_BT_REQFWD);
+ Assert(array->num_elems != -1 ||
+ outkey->sk_attno < IndexRelationGetNumberOfKeyAttributes(rel));
+
+ if (array->scan_key == input_ikey)
+ {
+ /* found it */
+ array->scan_key = output_ikey;
+ found = true;
+
+ /*
+ * Transform array scan keys that have exactly 1 element
+ * remaining (following all prior preprocessing) into
+ * equivalent non-array scan keys.
+ */
+ if (array->num_elems == 1)
+ {
+ outkey->sk_flags &= ~SK_SEARCHARRAY;
+ outkey->sk_argument = array->elem_values[0];
+ so->numArrayKeys--;
+
+ /* If we're out of array keys, we can quit right away */
+ if (so->numArrayKeys == 0)
+ return;
+
+ /* Shift other arrays forward */
+ memmove(array, array + 1,
+ sizeof(BTArrayKeyInfo) *
+ (so->numArrayKeys - arrayidx));
+
+ /*
+ * Don't increment arrayidx (there was an entry that was
+ * just shifted forward to the offset at arrayidx, which
+ * will still need to be matched)
+ */
+ }
+ else
+ {
+ /*
+ * Any skip array low_compare and high_compare scan keys
+ * are now final. Transform the array's > low_compare key
+ * into a >= key (and < high_compare keys into a <= key).
+ */
+ if (array->num_elems == -1 && array->sksup &&
+ !array->null_elem)
+ _bt_skiparray_strat_adjust(scan, outkey, array);
+
+ /* Match found, so done with this array */
+ arrayidx++;
+ }
+
+ break;
+ }
+ }
+
+ Assert(found);
+ }
+
+ /*
+ * Parallel index scans require space in shared memory to store the
+ * current array elements (for arrays kept by preprocessing) to schedule
+ * the next primitive index scan. The underlying structure is protected
+ * using an LWLock, so defensively limit its size. In practice this can
+ * only affect parallel scans that use an incomplete opfamily.
+ */
+ if (scan->parallel_scan && so->numArrayKeys > INDEX_MAX_KEYS)
+ ereport(ERROR,
+ (errcode(ERRCODE_PROGRAM_LIMIT_EXCEEDED),
+ errmsg_internal("number of array scan keys left by preprocessing (%d) exceeds the maximum allowed by parallel btree index scans (%d)",
+ so->numArrayKeys, INDEX_MAX_KEYS)));
+}
+
+/*
+ * _bt_num_array_keys() -- determine # of BTArrayKeyInfo entries
+ *
+ * _bt_preprocess_array_keys helper function. Returns the estimated size of
+ * the scan's BTArrayKeyInfo array, which is guaranteed to be large enough to
+ * fit every so->arrayKeys[] entry.
+ *
+ * Also sets *numSkipArrayKeys_out to the number of skip arrays caller must
+ * add to the scan keys it'll output. Caller must add this many skip arrays:
+ * one array for each of the most significant attributes that lack a = input
+ * key (IS NULL keys count as = input keys here). The specific attributes
+ * that need skip arrays are indicated by initializing skip_eq_ops_out[] arg
+ * 0-based attribute offset to a valid = op strategy Oid. We'll only ever set
+ * skip_eq_ops_out[] entries to InvalidOid for attributes that already have an
+ * equality key in scan->keyData[] input keys -- and only when there's some
+ * later "attribute gap" for us to "fill-in" with a skip array.
+ *
+ * We're optimistic about skipping working out: we always add exactly the skip
+ * arrays needed to maximize the number of input scan keys that can ultimately
+ * be marked as required to continue the scan (but no more). Given a
+ * multi-column index on (a, b, c, d), we add skip arrays as follows:
+ *
+ * Input keys Output keys (after all preprocessing)
+ * ---------- -------------------------------------
+ * a = 1 a = 1 (no skip arrays)
+ * b = 42 skip a AND b = 42
+ * a = 1 AND b = 42 a = 1 AND b = 42 (no skip arrays)
+ * a >= 1 AND b = 42 range skip a AND b = 42
+ * a = 1 AND b > 42 a = 1 AND b > 42 (no skip arrays)
+ * a >= 1 AND a <= 3 AND b = 42 range skip a AND b = 42
+ * a = 1 AND c <= 27 a = 1 AND skip b AND c <= 27
+ * a = 1 AND d >= 1 a = 1 AND skip b AND skip c AND d >= 1
+ * a = 1 AND b >= 42 AND d > 1 a = 1 AND range skip b AND skip c AND d > 1
+ */
+static int
+_bt_num_array_keys(IndexScanDesc scan, Oid *skip_eq_ops_out,
+ int *numSkipArrayKeys_out)
+{
+ Relation rel = scan->indexRelation;
+ AttrNumber attno_skip = 1,
+ attno_inkey = 1;
+ bool attno_has_equal = false,
+ attno_has_rowcompare = false;
+ int numSAOPArrayKeys,
+ numSkipArrayKeys,
+ prev_numSkipArrayKeys;
+
+ Assert(scan->numberOfKeys);
+
+ /* Initial pass over input scan keys counts the number of SAOP arrays */
+ numSAOPArrayKeys = 0;
+ *numSkipArrayKeys_out = prev_numSkipArrayKeys = numSkipArrayKeys = 0;
+ for (int i = 0; i < scan->numberOfKeys; i++)
+ {
+ ScanKey inkey = scan->keyData + i;
+
+ if (inkey->sk_flags & SK_SEARCHARRAY)
+ numSAOPArrayKeys++;
+ }
+
+#ifdef DEBUG_DISABLE_SKIP_SCAN
+ /* don't attempt to add skip arrays */
+ return numSAOPArrayKeys;
+#endif
+
+ for (int i = 0;; i++)
+ {
+ ScanKey inkey = scan->keyData + i;
+
+ /*
+ * Backfill skip arrays for any wholly omitted attributes prior to
+ * attno_inkey
+ */
+ while (attno_skip < attno_inkey)
+ {
+ Oid opfamily = rel->rd_opfamily[attno_skip - 1];
+ Oid opcintype = rel->rd_opcintype[attno_skip - 1];
+
+ /* Look up input opclass's equality operator (might fail) */
+ skip_eq_ops_out[attno_skip - 1] =
+ get_opfamily_member(opfamily, opcintype, opcintype,
+ BTEqualStrategyNumber);
+ if (!OidIsValid(skip_eq_ops_out[attno_skip - 1]))
+ {
+ /*
+ * Cannot generate a skip array for this or later attributes
+ * (input opclass lacks an equality strategy operator)
+ */
+ *numSkipArrayKeys_out = prev_numSkipArrayKeys;
+ return numSAOPArrayKeys + prev_numSkipArrayKeys;
+ }
+
+ /* plan on adding a backfill skip array for this attribute */
+ numSkipArrayKeys++;
+ attno_skip++;
+ }
+
+ prev_numSkipArrayKeys = numSkipArrayKeys;
+
+ /*
+ * Stop once past the final input scan key. We deliberately never add
+ * a skip array for the last input scan key's attribute -- even when
+ * there are only inequality keys on that attribute.
+ */
+ if (i == scan->numberOfKeys)
+ break;
+
+ /*
+ * Later preprocessing steps cannot merge a RowCompare into a skip
+ * array, so stop adding skip arrays once we see one. (Note that we
+ * can backfill skip arrays before a RowCompare, which will allow keys
+ * up to and including the RowCompare to be marked required.)
+ *
+ * Skip arrays work by maintaining a current array element value,
+ * which anchors lower-order keys via an implied equality constraint.
+ * This is incompatible with the current nbtree row comparison design,
+ * which compares all columns together, as an indivisible group.
+ * Alternative designs that can be used alongside skip arrays are
+ * possible, but it's not clear that they're really worth pursuing.
+ *
+ * A RowCompare qual "(a, b, c) > (10, 'foo', 42)" is equivalent to
+ * "(a=10 AND b='foo' AND c>42) OR (a=10 AND b>'foo') OR (a>10)".
+ * Decomposing this RowCompare into these 3 disjuncts allows each
+ * disjunct to be executed as a separate "single value" index scan.
+ * That'll give all 3 scans the ability to add skip arrays in the
+ * usual way (when there are any scalar keys after the RowCompare).
+ * Under this scheme, a qual "(a, b, c) > (10, 'foo', 42) AND d = 99"
+ * performs 3 separate scans, each of which can mark keys up to and
+ * including its "d = 99" key as required to continue the scan.
+ */
+ if (attno_has_rowcompare)
+ break;
+
+ /*
+ * Now consider next attno_inkey (or keep going if this is an
+ * additional scan key against the same attribute)
+ */
+ if (attno_inkey < inkey->sk_attno)
+ {
+ /*
+ * Now add skip array for previous scan key's attribute, though
+ * only if the attribute has no equality strategy scan keys
+ */
+ if (attno_has_equal)
+ {
+ /* Attributes with an = key must have InvalidOid eq_op set */
+ skip_eq_ops_out[attno_skip - 1] = InvalidOid;
+ }
+ else
+ {
+ Oid opfamily = rel->rd_opfamily[attno_skip - 1];
+ Oid opcintype = rel->rd_opcintype[attno_skip - 1];
+
+ /* Look up input opclass's equality operator (might fail) */
+ skip_eq_ops_out[attno_skip - 1] =
+ get_opfamily_member(opfamily, opcintype, opcintype,
+ BTEqualStrategyNumber);
+
+ if (!OidIsValid(skip_eq_ops_out[attno_skip - 1]))
+ {
+ /*
+ * Input opclass lacks an equality strategy operator, so
+ * don't generate a skip array that definitely won't work
+ */
+ break;
+ }
+
+ /* plan on adding a backfill skip array for this attribute */
+ numSkipArrayKeys++;
+ }
+
+ /* Set things up for this new attribute */
+ attno_skip++;
+ attno_inkey = inkey->sk_attno;
+ attno_has_equal = false;
+ }
+
+ /*
+ * Track if this attribute's scan keys include any equality strategy
+ * scan keys (IS NULL keys count as equality keys here). Also track
+ * if it has any RowCompare keys.
+ */
+ if (inkey->sk_strategy == BTEqualStrategyNumber ||
+ (inkey->sk_flags & SK_SEARCHNULL))
+ attno_has_equal = true;
+ if (inkey->sk_flags & SK_ROW_HEADER)
+ attno_has_rowcompare = true;
+ }
+
+ *numSkipArrayKeys_out = numSkipArrayKeys;
+ return numSAOPArrayKeys + numSkipArrayKeys;
+}
+
+/*
+ * _bt_find_extreme_element() -- get least or greatest array element
+ *
+ * scan and skey identify the index column, whose opfamily determines the
+ * comparison semantics. strat should be BTLessStrategyNumber to get the
+ * least element, or BTGreaterStrategyNumber to get the greatest.
+ */
+static Datum
+_bt_find_extreme_element(IndexScanDesc scan, ScanKey skey, Oid elemtype,
+ StrategyNumber strat,
+ Datum *elems, int nelems)
+{
+ Relation rel = scan->indexRelation;
+ Oid cmp_op;
+ RegProcedure cmp_proc;
+ FmgrInfo flinfo;
+ Datum result;
+ int i;
+
+ /*
+ * Look up the appropriate comparison operator in the opfamily.
+ *
+ * Note: it's possible that this would fail, if the opfamily is
+ * incomplete, but it seems quite unlikely that an opfamily would omit
+ * non-cross-type comparison operators for any datatype that it supports
+ * at all.
+ */
+ Assert(skey->sk_strategy != BTEqualStrategyNumber);
+ Assert(OidIsValid(elemtype));
+ cmp_op = get_opfamily_member(rel->rd_opfamily[skey->sk_attno - 1],
+ elemtype,
+ elemtype,
+ strat);
+ if (!OidIsValid(cmp_op))
+ elog(ERROR, "missing operator %d(%u,%u) in opfamily %u",
+ strat, elemtype, elemtype,
+ rel->rd_opfamily[skey->sk_attno - 1]);
+ cmp_proc = get_opcode(cmp_op);
+ if (!RegProcedureIsValid(cmp_proc))
+ elog(ERROR, "missing oprcode for operator %u", cmp_op);
+
+ fmgr_info(cmp_proc, &flinfo);
+
+ Assert(nelems > 0);
+ result = elems[0];
+ for (i = 1; i < nelems; i++)
+ {
+ if (DatumGetBool(FunctionCall2Coll(&flinfo,
+ skey->sk_collation,
+ elems[i],
+ result)))
+ result = elems[i];
+ }
+
+ return result;
+}
+
+/*
+ * _bt_setup_array_cmp() -- Set up array comparison functions
+ *
+ * Sets ORDER proc in caller's orderproc argument, which is used during binary
+ * searches of arrays during the index scan. Also sets a same-type ORDER proc
+ * in caller's *sortprocp argument, which is used when sorting the array.
+ *
+ * Preprocessing calls here with all equality strategy scan keys (when scan
+ * uses equality array keys), including those not associated with any array.
+ * See _bt_advance_array_keys for an explanation of why it'll need to treat
+ * simple scalar equality scan keys as degenerate single element arrays.
+ *
+ * Caller should pass an orderproc pointing to space that'll store the ORDER
+ * proc for the scan, and a *sortprocp pointing to its own separate space.
+ * When calling here for a non-array scan key, sortprocp arg should be NULL.
+ *
+ * In the common case where we don't need to deal with cross-type operators,
+ * only one ORDER proc is actually required by caller. We'll set *sortprocp
+ * to point to the same memory that caller's orderproc continues to point to.
+ * Otherwise, *sortprocp will continue to point to caller's own space. Either
+ * way, *sortprocp will point to a same-type ORDER proc (since that's the only
+ * safe way to sort/deduplicate the array associated with caller's scan key).
+ */
+static void
+_bt_setup_array_cmp(IndexScanDesc scan, ScanKey skey, Oid elemtype,
+ FmgrInfo *orderproc, FmgrInfo **sortprocp)
+{
+ BTScanOpaque so = (BTScanOpaque) scan->opaque;
+ Relation rel = scan->indexRelation;
+ RegProcedure cmp_proc;
+ Oid opcintype = rel->rd_opcintype[skey->sk_attno - 1];
+
+ Assert(skey->sk_strategy == BTEqualStrategyNumber);
+ Assert(OidIsValid(elemtype));
+
+ /*
+ * If scankey operator is not a cross-type comparison, we can use the
+ * cached comparison function; otherwise gotta look it up in the catalogs
+ */
+ if (elemtype == opcintype)
+ {
+ /* Set same-type ORDER procs for caller */
+ *orderproc = *index_getprocinfo(rel, skey->sk_attno, BTORDER_PROC);
+ if (sortprocp)
+ *sortprocp = orderproc;
+
+ return;
+ }
+
+ /*
+ * Look up the appropriate cross-type comparison function in the opfamily.
+ *
+ * Use the opclass input type as the left hand arg type, and the array
+ * element type as the right hand arg type (since binary searches use an
+ * index tuple's attribute value to search for a matching array element).
+ *
+ * Note: it's possible that this would fail, if the opfamily is
+ * incomplete, but only in cases where it's quite likely that _bt_first
+ * would fail in just the same way (had we not failed before it could).
+ */
+ cmp_proc = get_opfamily_proc(rel->rd_opfamily[skey->sk_attno - 1],
+ opcintype, elemtype, BTORDER_PROC);
+ if (!RegProcedureIsValid(cmp_proc))
+ elog(ERROR, "missing support function %d(%u,%u) for attribute %d of index \"%s\"",
+ BTORDER_PROC, opcintype, elemtype, skey->sk_attno,
+ RelationGetRelationName(rel));
+
+ /* Set cross-type ORDER proc for caller */
+ fmgr_info_cxt(cmp_proc, orderproc, so->arrayContext);
+
+ /* Done if caller doesn't actually have an array they'll need to sort */
+ if (!sortprocp)
+ return;
+
+ /*
+ * Look up the appropriate same-type comparison function in the opfamily.
+ *
+ * Note: it's possible that this would fail, if the opfamily is
+ * incomplete, but it seems quite unlikely that an opfamily would omit
+ * non-cross-type comparison procs for any datatype that it supports at
+ * all.
+ */
+ cmp_proc = get_opfamily_proc(rel->rd_opfamily[skey->sk_attno - 1],
+ elemtype, elemtype, BTORDER_PROC);
+ if (!RegProcedureIsValid(cmp_proc))
+ elog(ERROR, "missing support function %d(%u,%u) for attribute %d of index \"%s\"",
+ BTORDER_PROC, elemtype, elemtype,
+ skey->sk_attno, RelationGetRelationName(rel));
+
+ /* Set same-type ORDER proc for caller */
+ fmgr_info_cxt(cmp_proc, *sortprocp, so->arrayContext);
+}
+
+/*
+ * _bt_sort_array_elements() -- sort and de-dup array elements
+ *
+ * The array elements are sorted in-place, and the new number of elements
+ * after duplicate removal is returned.
+ *
+ * skey identifies the index column whose opfamily determines the comparison
+ * semantics, and sortproc is a corresponding ORDER proc. If reverse is true,
+ * we sort in descending order.
+ */
+static int
+_bt_sort_array_elements(ScanKey skey, FmgrInfo *sortproc, bool reverse,
+ Datum *elems, int nelems)
+{
+ BTSortArrayContext cxt;
+
+ if (nelems <= 1)
+ return nelems; /* no work to do */
+
+ /* Sort the array elements */
+ cxt.sortproc = sortproc;
+ cxt.collation = skey->sk_collation;
+ cxt.reverse = reverse;
+ qsort_arg(elems, nelems, sizeof(Datum),
+ _bt_compare_array_elements, &cxt);
+
+ /* Now scan the sorted elements and remove duplicates */
+ return qunique_arg(elems, nelems, sizeof(Datum),
+ _bt_compare_array_elements, &cxt);
+}
+
+/*
+ * _bt_merge_arrays() -- merge next array's elements into an original array
+ *
+ * Called when preprocessing encounters a pair of array equality scan keys,
+ * both against the same index attribute (during initial array preprocessing).
+ * Merging reorganizes caller's original array (the left hand arg) in-place,
+ * without ever copying elements from one array into the other. (Mixing the
+ * elements together like this would be wrong, since they don't necessarily
+ * use the same underlying element type, despite all the other similarities.)
+ *
+ * Both arrays must have already been sorted and deduplicated by calling
+ * _bt_sort_array_elements. sortproc is the same-type ORDER proc that was
+ * just used to sort and deduplicate caller's "next" array. We'll usually be
+ * able to reuse that order PROC to merge the arrays together now. If not,
+ * then we'll perform a separate ORDER proc lookup.
+ *
+ * If the opfamily doesn't supply a complete set of cross-type ORDER procs we
+ * may not be able to determine which elements are contradictory. If we have
+ * the required ORDER proc then we return true (and validly set *nelems_orig),
+ * guaranteeing that at least the next array can be considered redundant. We
+ * return false if the required comparisons cannot be made (caller must keep
+ * both arrays when this happens).
+ */
+static bool
+_bt_merge_arrays(IndexScanDesc scan, ScanKey skey, FmgrInfo *sortproc,
+ bool reverse, Oid origelemtype, Oid nextelemtype,
+ Datum *elems_orig, int *nelems_orig,
+ Datum *elems_next, int nelems_next)
+{
+ Relation rel = scan->indexRelation;
+ BTScanOpaque so = (BTScanOpaque) scan->opaque;
+ BTSortArrayContext cxt;
+ int nelems_orig_start = *nelems_orig,
+ nelems_orig_merged = 0;
+ FmgrInfo *mergeproc = sortproc;
+ FmgrInfo crosstypeproc;
+
+ Assert(skey->sk_strategy == BTEqualStrategyNumber);
+ Assert(OidIsValid(origelemtype) && OidIsValid(nextelemtype));
+
+ if (origelemtype != nextelemtype)
+ {
+ RegProcedure cmp_proc;
+
+ /*
+ * Cross-array-element-type merging is required, so can't just reuse
+ * sortproc when merging
+ */
+ cmp_proc = get_opfamily_proc(rel->rd_opfamily[skey->sk_attno - 1],
+ origelemtype, nextelemtype, BTORDER_PROC);
+ if (!RegProcedureIsValid(cmp_proc))
+ {
+ /* Can't make the required comparisons */
+ return false;
+ }
+
+ /* We have all we need to determine redundancy/contradictoriness */
+ mergeproc = &crosstypeproc;
+ fmgr_info_cxt(cmp_proc, mergeproc, so->arrayContext);
+ }
+
+ cxt.sortproc = mergeproc;
+ cxt.collation = skey->sk_collation;
+ cxt.reverse = reverse;
+
+ for (int i = 0, j = 0; i < nelems_orig_start && j < nelems_next;)
+ {
+ Datum *oelem = elems_orig + i,
+ *nelem = elems_next + j;
+ int res = _bt_compare_array_elements(oelem, nelem, &cxt);
+
+ if (res == 0)
+ {
+ elems_orig[nelems_orig_merged++] = *oelem;
+ i++;
+ j++;
+ }
+ else if (res < 0)
+ i++;
+ else /* res > 0 */
+ j++;
+ }
+
+ *nelems_orig = nelems_orig_merged;
+
+ return true;
+}
+
+/*
+ * qsort_arg comparator for sorting array elements
+ */
+static int
+_bt_compare_array_elements(const void *a, const void *b, void *arg)
+{
+ Datum da = *((const Datum *) a);
+ Datum db = *((const Datum *) b);
+ BTSortArrayContext *cxt = (BTSortArrayContext *) arg;
+ int32 compare;
+
+ compare = DatumGetInt32(FunctionCall2Coll(cxt->sortproc,
+ cxt->collation,
+ da, db));
+ if (cxt->reverse)
+ INVERT_COMPARE_RESULT(compare);
+ return compare;
+}
diff --git a/src/backend/access/nbtree/nbtree.c b/src/backend/access/nbtree/nbtree.c
index 686a3206f726b..fdff960c13022 100644
--- a/src/backend/access/nbtree/nbtree.c
+++ b/src/backend/access/nbtree/nbtree.c
@@ -8,7 +8,7 @@
* This file contains only the public interface routines.
*
*
- * Portions Copyright (c) 1996-2024, PostgreSQL Global Development Group
+ * Portions Copyright (c) 1996-2025, PostgreSQL Global Development Group
* Portions Copyright (c) 1994, Regents of the University of California
*
* IDENTIFICATION
@@ -20,10 +20,9 @@
#include "access/nbtree.h"
#include "access/relscan.h"
-#include "access/xloginsert.h"
+#include "access/stratnum.h"
#include "commands/progress.h"
#include "commands/vacuum.h"
-#include "miscadmin.h"
#include "nodes/execnodes.h"
#include "pgstat.h"
#include "storage/bulk_write.h"
@@ -31,7 +30,8 @@
#include "storage/indexfsm.h"
#include "storage/ipc.h"
#include "storage/lmgr.h"
-#include "storage/smgr.h"
+#include "storage/read_stream.h"
+#include "utils/datum.h"
#include "utils/fmgrprotos.h"
#include "utils/index_selfuncs.h"
#include "utils/memutils.h"
@@ -66,27 +66,41 @@ typedef enum
*/
typedef struct BTParallelScanDescData
{
- BlockNumber btps_scanPage; /* latest or next page to be scanned */
+ BlockNumber btps_nextScanPage; /* next page to be scanned */
+ BlockNumber btps_lastCurrPage; /* page whose sibling link was copied into
+ * btps_nextScanPage */
BTPS_State btps_pageStatus; /* indicates whether next page is
* available for scan. see above for
* possible states of parallel scan. */
- slock_t btps_mutex; /* protects above variables, btps_arrElems */
+ LWLock btps_lock; /* protects shared parallel state */
ConditionVariable btps_cv; /* used to synchronize parallel scan */
/*
* btps_arrElems is used when scans need to schedule another primitive
- * index scan. Holds BTArrayKeyInfo.cur_elem offsets for scan keys.
+ * index scan with one or more SAOP arrays. Holds BTArrayKeyInfo.cur_elem
+ * offsets for each = scan key associated with a ScalarArrayOp array.
*/
int btps_arrElems[FLEXIBLE_ARRAY_MEMBER];
+
+ /*
+ * Additional space (at the end of the struct) is used when scans need to
+ * schedule another primitive index scan with one or more skip arrays.
+ * Holds a flattened datum representation for each = scan key associated
+ * with a skip array.
+ */
} BTParallelScanDescData;
typedef struct BTParallelScanDescData *BTParallelScanDesc;
+static void _bt_parallel_serialize_arrays(Relation rel, BTParallelScanDesc btscan,
+ BTScanOpaque so);
+static void _bt_parallel_restore_arrays(Relation rel, BTParallelScanDesc btscan,
+ BTScanOpaque so);
static void btvacuumscan(IndexVacuumInfo *info, IndexBulkDeleteResult *stats,
IndexBulkDeleteCallback callback, void *callback_state,
BTCycleId cycleid);
-static void btvacuumpage(BTVacState *vstate, BlockNumber scanblkno);
+static BlockNumber btvacuumpage(BTVacState *vstate, Buffer buf);
static BTVacuumPosting btreevacuumposting(BTVacState *vstate,
IndexTuple posting,
OffsetNumber updatedoffset,
@@ -107,6 +121,9 @@ bthandler(PG_FUNCTION_ARGS)
amroutine->amoptsprocnum = BTOPTIONS_PROC;
amroutine->amcanorder = true;
amroutine->amcanorderbyop = false;
+ amroutine->amcanhash = false;
+ amroutine->amconsistentequality = true;
+ amroutine->amconsistentordering = true;
amroutine->amcanbackward = true;
amroutine->amcanunique = true;
amroutine->amcanmulticol = true;
@@ -133,6 +150,7 @@ bthandler(PG_FUNCTION_ARGS)
amroutine->amvacuumcleanup = btvacuumcleanup;
amroutine->amcanreturn = btcanreturn;
amroutine->amcostestimate = btcostestimate;
+ amroutine->amgettreeheight = btgettreeheight;
amroutine->amoptions = btoptions;
amroutine->amproperty = btproperty;
amroutine->ambuildphasename = btbuildphasename;
@@ -148,6 +166,8 @@ bthandler(PG_FUNCTION_ARGS)
amroutine->amestimateparallelscan = btestimateparallelscan;
amroutine->aminitparallelscan = btinitparallelscan;
amroutine->amparallelrescan = btparallelrescan;
+ amroutine->amtranslatestrategy = bttranslatestrategy;
+ amroutine->amtranslatecmptype = bttranslatecmptype;
PG_RETURN_POINTER(amroutine);
}
@@ -208,6 +228,8 @@ btgettuple(IndexScanDesc scan, ScanDirection dir)
BTScanOpaque so = (BTScanOpaque) scan->opaque;
bool res;
+ Assert(scan->heapRelation != NULL);
+
/* btree indexes are never lossy */
scan->xs_recheck = false;
@@ -269,6 +291,8 @@ btgetbitmap(IndexScanDesc scan, TIDBitmap *tbm)
int64 ntids = 0;
ItemPointer heapTid;
+ Assert(scan->heapRelation == NULL);
+
/* Each loop iteration performs another primitive index scan */
do
{
@@ -329,8 +353,10 @@ btbeginscan(Relation rel, int nkeys, int norderbys)
else
so->keyData = NULL;
+ so->skipScan = false;
so->needPrimScan = false;
so->scanBehind = false;
+ so->oppositeDirCheck = false;
so->arrayKeys = NULL;
so->orderProcs = NULL;
so->arrayContext = NULL;
@@ -371,9 +397,38 @@ btrescan(IndexScanDesc scan, ScanKey scankey, int nscankeys,
BTScanPosInvalidate(so->currPos);
}
+ /*
+ * We prefer to eagerly drop leaf page pins before btgettuple returns.
+ * This avoids making VACUUM wait to acquire a cleanup lock on the page.
+ *
+ * We cannot safely drop leaf page pins during index-only scans due to a
+ * race condition involving VACUUM setting pages all-visible in the VM.
+ * It's also unsafe for plain index scans that use a non-MVCC snapshot.
+ *
+ * When we drop pins eagerly, the mechanism that marks so->killedItems[]
+ * index tuples LP_DEAD has to deal with concurrent TID recycling races.
+ * The scheme used to detect unsafe TID recycling won't work when scanning
+ * unlogged relations (since it involves saving an affected page's LSN).
+ * Opt out of eager pin dropping during unlogged relation scans for now
+ * (this is preferable to opting out of kill_prior_tuple LP_DEAD setting).
+ *
+ * Also opt out of dropping leaf page pins eagerly during bitmap scans.
+ * Pins cannot be held for more than an instant during bitmap scans either
+ * way, so we might as well avoid wasting cycles on acquiring page LSNs.
+ *
+ * See nbtree/README section on making concurrent TID recycling safe.
+ *
+ * Note: so->dropPin should never change across rescans.
+ */
+ so->dropPin = (!scan->xs_want_itup &&
+ IsMVCCSnapshot(scan->xs_snapshot) &&
+ RelationNeedsWAL(scan->indexRelation) &&
+ scan->heapRelation != NULL);
+
so->markItemIndex = -1;
so->needPrimScan = false;
so->scanBehind = false;
+ so->oppositeDirCheck = false;
BTScanPosUnpinIfPinned(so->markPos);
BTScanPosInvalidate(so->markPos);
@@ -403,9 +458,7 @@ btrescan(IndexScanDesc scan, ScanKey scankey, int nscankeys,
* Reset the scan keys
*/
if (scankey && scan->numberOfKeys > 0)
- memmove(scan->keyData,
- scankey,
- scan->numberOfKeys * sizeof(ScanKeyData));
+ memcpy(scan->keyData, scankey, scan->numberOfKeys * sizeof(ScanKeyData));
so->numberOfKeys = 0; /* until _bt_preprocess_keys sets it */
so->numArrayKeys = 0; /* ditto */
}
@@ -534,10 +587,167 @@ btrestrpos(IndexScanDesc scan)
* btestimateparallelscan -- estimate storage for BTParallelScanDescData
*/
Size
-btestimateparallelscan(int nkeys, int norderbys)
+btestimateparallelscan(Relation rel, int nkeys, int norderbys)
{
- /* Pessimistically assume all input scankeys will be output with arrays */
- return offsetof(BTParallelScanDescData, btps_arrElems) + sizeof(int) * nkeys;
+ int16 nkeyatts = IndexRelationGetNumberOfKeyAttributes(rel);
+ Size estnbtreeshared,
+ genericattrspace;
+
+ /*
+ * Pessimistically assume that every input scan key will be output with
+ * its own SAOP array
+ */
+ estnbtreeshared = offsetof(BTParallelScanDescData, btps_arrElems) +
+ sizeof(int) * nkeys;
+
+ /* Single column indexes cannot possibly use a skip array */
+ if (nkeyatts == 1)
+ return estnbtreeshared;
+
+ /*
+ * Pessimistically assume that all attributes prior to the least
+ * significant attribute require a skip array (and an associated key)
+ */
+ genericattrspace = datumEstimateSpace((Datum) 0, false, true,
+ sizeof(Datum));
+ for (int attnum = 1; attnum < nkeyatts; attnum++)
+ {
+ CompactAttribute *attr;
+
+ /*
+ * We make the conservative assumption that every index column will
+ * also require a skip array.
+ *
+ * Every skip array must have space to store its scan key's sk_flags.
+ */
+ estnbtreeshared = add_size(estnbtreeshared, sizeof(int));
+
+ /* Consider space required to store a datum of opclass input type */
+ attr = TupleDescCompactAttr(rel->rd_att, attnum - 1);
+ if (attr->attbyval)
+ {
+ /* This index attribute stores pass-by-value datums */
+ Size estfixed = datumEstimateSpace((Datum) 0, false,
+ true, attr->attlen);
+
+ estnbtreeshared = add_size(estnbtreeshared, estfixed);
+ continue;
+ }
+
+ /*
+ * This index attribute stores pass-by-reference datums.
+ *
+ * Assume that serializing this array will use just as much space as a
+ * pass-by-value datum, in addition to space for the largest possible
+ * whole index tuple (this is not just a per-datum portion of the
+ * largest possible tuple because that'd be almost as large anyway).
+ *
+ * This is quite conservative, but it's not clear how we could do much
+ * better. The executor requires an up-front storage request size
+ * that reliably covers the scan's high watermark memory usage. We
+ * can't be sure of the real high watermark until the scan is over.
+ */
+ estnbtreeshared = add_size(estnbtreeshared, genericattrspace);
+ estnbtreeshared = add_size(estnbtreeshared, BTMaxItemSize);
+ }
+
+ return estnbtreeshared;
+}
+
+/*
+ * _bt_parallel_serialize_arrays() -- Serialize parallel array state.
+ *
+ * Caller must have exclusively locked btscan->btps_lock when called.
+ */
+static void
+_bt_parallel_serialize_arrays(Relation rel, BTParallelScanDesc btscan,
+ BTScanOpaque so)
+{
+ char *datumshared;
+
+ /* Space for serialized datums begins immediately after btps_arrElems[] */
+ datumshared = ((char *) &btscan->btps_arrElems[so->numArrayKeys]);
+ for (int i = 0; i < so->numArrayKeys; i++)
+ {
+ BTArrayKeyInfo *array = &so->arrayKeys[i];
+ ScanKey skey = &so->keyData[array->scan_key];
+
+ if (array->num_elems != -1)
+ {
+ /* Save SAOP array's cur_elem (no need to copy key/datum) */
+ Assert(!(skey->sk_flags & SK_BT_SKIP));
+ btscan->btps_arrElems[i] = array->cur_elem;
+ continue;
+ }
+
+ /* Save all mutable state associated with skip array's key */
+ Assert(skey->sk_flags & SK_BT_SKIP);
+ memcpy(datumshared, &skey->sk_flags, sizeof(int));
+ datumshared += sizeof(int);
+
+ if (skey->sk_flags & (SK_BT_MINVAL | SK_BT_MAXVAL))
+ {
+ /* No sk_argument datum to serialize */
+ Assert(skey->sk_argument == 0);
+ continue;
+ }
+
+ datumSerialize(skey->sk_argument, (skey->sk_flags & SK_ISNULL) != 0,
+ array->attbyval, array->attlen, &datumshared);
+ }
+}
+
+/*
+ * _bt_parallel_restore_arrays() -- Restore serialized parallel array state.
+ *
+ * Caller must have exclusively locked btscan->btps_lock when called.
+ */
+static void
+_bt_parallel_restore_arrays(Relation rel, BTParallelScanDesc btscan,
+ BTScanOpaque so)
+{
+ char *datumshared;
+
+ /* Space for serialized datums begins immediately after btps_arrElems[] */
+ datumshared = ((char *) &btscan->btps_arrElems[so->numArrayKeys]);
+ for (int i = 0; i < so->numArrayKeys; i++)
+ {
+ BTArrayKeyInfo *array = &so->arrayKeys[i];
+ ScanKey skey = &so->keyData[array->scan_key];
+ bool isnull;
+
+ if (array->num_elems != -1)
+ {
+ /* Restore SAOP array using its saved cur_elem */
+ Assert(!(skey->sk_flags & SK_BT_SKIP));
+ array->cur_elem = btscan->btps_arrElems[i];
+ skey->sk_argument = array->elem_values[array->cur_elem];
+ continue;
+ }
+
+ /* Restore skip array by restoring its key directly */
+ if (!array->attbyval && skey->sk_argument)
+ pfree(DatumGetPointer(skey->sk_argument));
+ skey->sk_argument = (Datum) 0;
+ memcpy(&skey->sk_flags, datumshared, sizeof(int));
+ datumshared += sizeof(int);
+
+ Assert(skey->sk_flags & SK_BT_SKIP);
+
+ if (skey->sk_flags & (SK_BT_MINVAL | SK_BT_MAXVAL))
+ {
+ /* No sk_argument datum to restore */
+ continue;
+ }
+
+ skey->sk_argument = datumRestore(&datumshared, &isnull);
+ if (isnull)
+ {
+ Assert(skey->sk_argument == 0);
+ Assert(skey->sk_flags & SK_SEARCHNULL);
+ Assert(skey->sk_flags & SK_ISNULL);
+ }
+ }
}
/*
@@ -548,8 +758,10 @@ btinitparallelscan(void *target)
{
BTParallelScanDesc bt_target = (BTParallelScanDesc) target;
- SpinLockInit(&bt_target->btps_mutex);
- bt_target->btps_scanPage = InvalidBlockNumber;
+ LWLockInitialize(&bt_target->btps_lock,
+ LWTRANCHE_PARALLEL_BTREE_SCAN);
+ bt_target->btps_nextScanPage = InvalidBlockNumber;
+ bt_target->btps_lastCurrPage = InvalidBlockNumber;
bt_target->btps_pageStatus = BTPARALLEL_NOT_INITIALIZED;
ConditionVariableInit(&bt_target->btps_cv);
}
@@ -565,18 +777,19 @@ btparallelrescan(IndexScanDesc scan)
Assert(parallel_scan);
- btscan = (BTParallelScanDesc) OffsetToPointer((void *) parallel_scan,
- parallel_scan->ps_offset);
+ btscan = (BTParallelScanDesc) OffsetToPointer(parallel_scan,
+ parallel_scan->ps_offset_am);
/*
- * In theory, we don't need to acquire the spinlock here, because there
+ * In theory, we don't need to acquire the LWLock here, because there
* shouldn't be any other workers running at this point, but we do so for
* consistency.
*/
- SpinLockAcquire(&btscan->btps_mutex);
- btscan->btps_scanPage = InvalidBlockNumber;
+ LWLockAcquire(&btscan->btps_lock, LW_EXCLUSIVE);
+ btscan->btps_nextScanPage = InvalidBlockNumber;
+ btscan->btps_lastCurrPage = InvalidBlockNumber;
btscan->btps_pageStatus = BTPARALLEL_NOT_INITIALIZED;
- SpinLockRelease(&btscan->btps_mutex);
+ LWLockRelease(&btscan->btps_lock);
}
/*
@@ -585,94 +798,113 @@ btparallelrescan(IndexScanDesc scan)
* or _bt_parallel_done().
*
* The return value is true if we successfully seized the scan and false
- * if we did not. The latter case occurs if no pages remain.
- *
- * If the return value is true, *pageno returns the next or current page
- * of the scan (depending on the scan direction). An invalid block number
- * means the scan hasn't yet started, or that caller needs to start the next
- * primitive index scan (if it's the latter case we'll set so.needPrimScan).
- * The first time a participating process reaches the last page, it will return
- * true and set *pageno to P_NONE; after that, further attempts to seize the
- * scan will return false.
+ * if we did not. The latter case occurs when no pages remain, or when
+ * another primitive index scan is scheduled that caller's backend cannot
+ * start just yet (only backends that call from _bt_first are capable of
+ * starting primitive index scans, which they indicate by passing first=true).
*
- * Callers should ignore the value of pageno if the return value is false.
+ * If the return value is true, *next_scan_page returns the next page of the
+ * scan, and *last_curr_page returns the page that *next_scan_page came from.
+ * An invalid *next_scan_page means the scan hasn't yet started, or that
+ * caller needs to start the next primitive index scan (if it's the latter
+ * case we'll set so.needPrimScan).
*
- * Callers that are in a position to start a new primitive index scan must
- * pass first=true (all other callers pass first=false). We just return false
- * for first=false callers that require another primitive index scan.
+ * Callers should ignore the value of *next_scan_page and *last_curr_page if
+ * the return value is false.
*/
bool
-_bt_parallel_seize(IndexScanDesc scan, BlockNumber *pageno, bool first)
+_bt_parallel_seize(IndexScanDesc scan, BlockNumber *next_scan_page,
+ BlockNumber *last_curr_page, bool first)
{
+ Relation rel = scan->indexRelation;
BTScanOpaque so = (BTScanOpaque) scan->opaque;
- bool exit_loop = false;
- bool status = true;
+ bool exit_loop = false,
+ status = true,
+ endscan = false;
ParallelIndexScanDesc parallel_scan = scan->parallel_scan;
BTParallelScanDesc btscan;
- *pageno = P_NONE;
+ *next_scan_page = InvalidBlockNumber;
+ *last_curr_page = InvalidBlockNumber;
+
+ /*
+ * Reset so->currPos, and initialize moreLeft/moreRight such that the next
+ * call to _bt_readnextpage treats this backend similarly to a serial
+ * backend that steps from *last_curr_page to *next_scan_page (unless this
+ * backend's so->currPos is initialized by _bt_readfirstpage before then).
+ */
+ BTScanPosInvalidate(so->currPos);
+ so->currPos.moreLeft = so->currPos.moreRight = true;
if (first)
{
/*
* Initialize array related state when called from _bt_first, assuming
- * that this will either be the first primitive index scan for the
- * scan, or a previous explicitly scheduled primitive scan.
- *
- * Note: so->needPrimScan is only set when a scheduled primitive index
- * scan is set to be performed in caller's worker process. It should
- * not be set here by us for the first primitive scan, nor should we
- * ever set it for a parallel scan that has no array keys.
+ * that this will be the first primitive index scan for the scan
*/
so->needPrimScan = false;
so->scanBehind = false;
+ so->oppositeDirCheck = false;
}
else
{
/*
- * Don't attempt to seize the scan when backend requires another
- * primitive index scan unless we're in a position to start it now
+ * Don't attempt to seize the scan when it requires another primitive
+ * index scan, since caller's backend cannot start it right now
*/
if (so->needPrimScan)
return false;
}
- btscan = (BTParallelScanDesc) OffsetToPointer((void *) parallel_scan,
- parallel_scan->ps_offset);
+ btscan = (BTParallelScanDesc) OffsetToPointer(parallel_scan,
+ parallel_scan->ps_offset_am);
while (1)
{
- SpinLockAcquire(&btscan->btps_mutex);
+ LWLockAcquire(&btscan->btps_lock, LW_EXCLUSIVE);
if (btscan->btps_pageStatus == BTPARALLEL_DONE)
{
/* We're done with this parallel index scan */
status = false;
}
+ else if (btscan->btps_pageStatus == BTPARALLEL_IDLE &&
+ btscan->btps_nextScanPage == P_NONE)
+ {
+ /* End this parallel index scan */
+ status = false;
+ endscan = true;
+ }
else if (btscan->btps_pageStatus == BTPARALLEL_NEED_PRIMSCAN)
{
Assert(so->numArrayKeys);
- /*
- * If we can start another primitive scan right away, do so.
- * Otherwise just wait.
- */
if (first)
{
+ /* Can start scheduled primitive scan right away, so do so */
btscan->btps_pageStatus = BTPARALLEL_ADVANCING;
- for (int i = 0; i < so->numArrayKeys; i++)
- {
- BTArrayKeyInfo *array = &so->arrayKeys[i];
- ScanKey skey = &so->keyData[array->scan_key];
- array->cur_elem = btscan->btps_arrElems[i];
- skey->sk_argument = array->elem_values[array->cur_elem];
- }
- so->needPrimScan = true;
- so->scanBehind = false;
- *pageno = InvalidBlockNumber;
+ /* Restore scan's array keys from serialized values */
+ _bt_parallel_restore_arrays(rel, btscan, so);
exit_loop = true;
}
+ else
+ {
+ /*
+ * Don't attempt to seize the scan when it requires another
+ * primitive index scan, since caller's backend cannot start
+ * it right now
+ */
+ status = false;
+ }
+
+ /*
+ * Either way, update backend local state to indicate that a
+ * pending primitive scan is required
+ */
+ so->needPrimScan = true;
+ so->scanBehind = false;
+ so->oppositeDirCheck = false;
}
else if (btscan->btps_pageStatus != BTPARALLEL_ADVANCING)
{
@@ -681,43 +913,60 @@ _bt_parallel_seize(IndexScanDesc scan, BlockNumber *pageno, bool first)
* of advancing it to a new page!
*/
btscan->btps_pageStatus = BTPARALLEL_ADVANCING;
- *pageno = btscan->btps_scanPage;
+ Assert(btscan->btps_nextScanPage != P_NONE);
+ *next_scan_page = btscan->btps_nextScanPage;
+ *last_curr_page = btscan->btps_lastCurrPage;
exit_loop = true;
}
- SpinLockRelease(&btscan->btps_mutex);
+ LWLockRelease(&btscan->btps_lock);
if (exit_loop || !status)
break;
ConditionVariableSleep(&btscan->btps_cv, WAIT_EVENT_BTREE_PAGE);
}
ConditionVariableCancelSleep();
+ /* When the scan has reached the rightmost (or leftmost) page, end it */
+ if (endscan)
+ _bt_parallel_done(scan);
+
return status;
}
/*
* _bt_parallel_release() -- Complete the process of advancing the scan to a
- * new page. We now have the new value btps_scanPage; some other backend
+ * new page. We now have the new value btps_nextScanPage; another backend
* can now begin advancing the scan.
*
- * Callers whose scan uses array keys must save their scan_page argument so
+ * Callers whose scan uses array keys must save their curr_page argument so
* that it can be passed to _bt_parallel_primscan_schedule, should caller
- * determine that another primitive index scan is required. If that happens,
- * scan_page won't be scanned by any backend (unless the next primitive index
- * scan lands on scan_page).
+ * determine that another primitive index scan is required.
+ *
+ * If caller's next_scan_page is P_NONE, the scan has reached the index's
+ * rightmost/leftmost page. This is treated as reaching the end of the scan
+ * within _bt_parallel_seize.
+ *
+ * Note: unlike the serial case, parallel scans don't need to remember both
+ * sibling links. next_scan_page is whichever link is next given the scan's
+ * direction. That's all we'll ever need, since the direction of a parallel
+ * scan can never change.
*/
void
-_bt_parallel_release(IndexScanDesc scan, BlockNumber scan_page)
+_bt_parallel_release(IndexScanDesc scan, BlockNumber next_scan_page,
+ BlockNumber curr_page)
{
ParallelIndexScanDesc parallel_scan = scan->parallel_scan;
BTParallelScanDesc btscan;
- btscan = (BTParallelScanDesc) OffsetToPointer((void *) parallel_scan,
- parallel_scan->ps_offset);
+ Assert(BlockNumberIsValid(next_scan_page));
- SpinLockAcquire(&btscan->btps_mutex);
- btscan->btps_scanPage = scan_page;
+ btscan = (BTParallelScanDesc) OffsetToPointer(parallel_scan,
+ parallel_scan->ps_offset_am);
+
+ LWLockAcquire(&btscan->btps_lock, LW_EXCLUSIVE);
+ btscan->btps_nextScanPage = next_scan_page;
+ btscan->btps_lastCurrPage = curr_page;
btscan->btps_pageStatus = BTPARALLEL_IDLE;
- SpinLockRelease(&btscan->btps_mutex);
+ LWLockRelease(&btscan->btps_lock);
ConditionVariableSignal(&btscan->btps_cv);
}
@@ -731,28 +980,39 @@ _bt_parallel_release(IndexScanDesc scan, BlockNumber scan_page)
void
_bt_parallel_done(IndexScanDesc scan)
{
+ BTScanOpaque so = (BTScanOpaque) scan->opaque;
ParallelIndexScanDesc parallel_scan = scan->parallel_scan;
BTParallelScanDesc btscan;
bool status_changed = false;
+ Assert(!BTScanPosIsValid(so->currPos));
+
/* Do nothing, for non-parallel scans */
if (parallel_scan == NULL)
return;
- btscan = (BTParallelScanDesc) OffsetToPointer((void *) parallel_scan,
- parallel_scan->ps_offset);
+ /*
+ * Should not mark parallel scan done when there's still a pending
+ * primitive index scan
+ */
+ if (so->needPrimScan)
+ return;
+
+ btscan = (BTParallelScanDesc) OffsetToPointer(parallel_scan,
+ parallel_scan->ps_offset_am);
/*
* Mark the parallel scan as done, unless some other process did so
* already
*/
- SpinLockAcquire(&btscan->btps_mutex);
+ LWLockAcquire(&btscan->btps_lock, LW_EXCLUSIVE);
+ Assert(btscan->btps_pageStatus != BTPARALLEL_NEED_PRIMSCAN);
if (btscan->btps_pageStatus != BTPARALLEL_DONE)
{
btscan->btps_pageStatus = BTPARALLEL_DONE;
status_changed = true;
}
- SpinLockRelease(&btscan->btps_mutex);
+ LWLockRelease(&btscan->btps_lock);
/* wake up all the workers associated with this parallel scan */
if (status_changed)
@@ -762,39 +1022,36 @@ _bt_parallel_done(IndexScanDesc scan)
/*
* _bt_parallel_primscan_schedule() -- Schedule another primitive index scan.
*
- * Caller passes the block number most recently passed to _bt_parallel_release
+ * Caller passes the curr_page most recently passed to _bt_parallel_release
* by its backend. Caller successfully schedules the next primitive index scan
* if the shared parallel state hasn't been seized since caller's backend last
* advanced the scan.
*/
void
-_bt_parallel_primscan_schedule(IndexScanDesc scan, BlockNumber prev_scan_page)
+_bt_parallel_primscan_schedule(IndexScanDesc scan, BlockNumber curr_page)
{
+ Relation rel = scan->indexRelation;
BTScanOpaque so = (BTScanOpaque) scan->opaque;
ParallelIndexScanDesc parallel_scan = scan->parallel_scan;
BTParallelScanDesc btscan;
Assert(so->numArrayKeys);
- btscan = (BTParallelScanDesc) OffsetToPointer((void *) parallel_scan,
- parallel_scan->ps_offset);
+ btscan = (BTParallelScanDesc) OffsetToPointer(parallel_scan,
+ parallel_scan->ps_offset_am);
- SpinLockAcquire(&btscan->btps_mutex);
- if (btscan->btps_scanPage == prev_scan_page &&
+ LWLockAcquire(&btscan->btps_lock, LW_EXCLUSIVE);
+ if (btscan->btps_lastCurrPage == curr_page &&
btscan->btps_pageStatus == BTPARALLEL_IDLE)
{
- btscan->btps_scanPage = InvalidBlockNumber;
+ btscan->btps_nextScanPage = InvalidBlockNumber;
+ btscan->btps_lastCurrPage = InvalidBlockNumber;
btscan->btps_pageStatus = BTPARALLEL_NEED_PRIMSCAN;
/* Serialize scan's current array keys */
- for (int i = 0; i < so->numArrayKeys; i++)
- {
- BTArrayKeyInfo *array = &so->arrayKeys[i];
-
- btscan->btps_arrElems[i] = array->cur_elem;
- }
+ _bt_parallel_serialize_arrays(rel, btscan, so);
}
- SpinLockRelease(&btscan->btps_mutex);
+ LWLockRelease(&btscan->btps_lock);
}
/*
@@ -930,8 +1187,9 @@ btvacuumscan(IndexVacuumInfo *info, IndexBulkDeleteResult *stats,
Relation rel = info->index;
BTVacState vstate;
BlockNumber num_pages;
- BlockNumber scanblkno;
bool needLock;
+ BlockRangeReadStreamPrivate p;
+ ReadStream *stream = NULL;
/*
* Reset fields that track information about the entire index now. This
@@ -1000,7 +1258,21 @@ btvacuumscan(IndexVacuumInfo *info, IndexBulkDeleteResult *stats,
*/
needLock = !RELATION_IS_LOCAL(rel);
- scanblkno = BTREE_METAPAGE + 1;
+ p.current_blocknum = BTREE_METAPAGE + 1;
+
+ /*
+ * It is safe to use batchmode as block_range_read_stream_cb takes no
+ * locks.
+ */
+ stream = read_stream_begin_relation(READ_STREAM_MAINTENANCE |
+ READ_STREAM_FULL |
+ READ_STREAM_USE_BATCHING,
+ info->strategy,
+ rel,
+ MAIN_FORKNUM,
+ block_range_read_stream_cb,
+ &p,
+ 0);
for (;;)
{
/* Get the current relation length */
@@ -1015,18 +1287,42 @@ btvacuumscan(IndexVacuumInfo *info, IndexBulkDeleteResult *stats,
num_pages);
/* Quit if we've scanned the whole relation */
- if (scanblkno >= num_pages)
+ if (p.current_blocknum >= num_pages)
break;
- /* Iterate over pages, then loop back to recheck length */
- for (; scanblkno < num_pages; scanblkno++)
+
+ p.last_exclusive = num_pages;
+
+ /* Iterate over pages, then loop back to recheck relation length */
+ while (true)
{
- btvacuumpage(&vstate, scanblkno);
+ BlockNumber current_block;
+ Buffer buf;
+
+ /* call vacuum_delay_point while not holding any buffer lock */
+ vacuum_delay_point(false);
+
+ buf = read_stream_next_buffer(stream, NULL);
+
+ if (!BufferIsValid(buf))
+ break;
+
+ current_block = btvacuumpage(&vstate, buf);
+
if (info->report_progress)
pgstat_progress_update_param(PROGRESS_SCAN_BLOCKS_DONE,
- scanblkno);
+ current_block);
}
+
+ /*
+ * We have to reset the read stream to use it again. After returning
+ * InvalidBuffer, the read stream API won't invoke our callback again
+ * until the stream has been reset.
+ */
+ read_stream_reset(stream);
}
+ read_stream_end(stream);
+
/* Set statistics num_pages field to final size of index */
stats->num_pages = num_pages;
@@ -1050,14 +1346,16 @@ btvacuumscan(IndexVacuumInfo *info, IndexBulkDeleteResult *stats,
* btvacuumpage --- VACUUM one page
*
* This processes a single page for btvacuumscan(). In some cases we must
- * backtrack to re-examine and VACUUM pages that were the scanblkno during
+ * backtrack to re-examine and VACUUM pages that were on buf's page during
* a previous call here. This is how we handle page splits (that happened
* after our cycleid was acquired) whose right half page happened to reuse
* a block that we might have processed at some point before it was
* recycled (i.e. before the page split).
+ *
+ * Returns BlockNumber of a scanned page (not backtracked).
*/
-static void
-btvacuumpage(BTVacState *vstate, BlockNumber scanblkno)
+static BlockNumber
+btvacuumpage(BTVacState *vstate, Buffer buf)
{
IndexVacuumInfo *info = vstate->info;
IndexBulkDeleteResult *stats = vstate->stats;
@@ -1068,7 +1366,7 @@ btvacuumpage(BTVacState *vstate, BlockNumber scanblkno)
bool attempt_pagedel;
BlockNumber blkno,
backtrack_to;
- Buffer buf;
+ BlockNumber scanblkno = BufferGetBlockNumber(buf);
Page page;
BTPageOpaque opaque;
@@ -1079,17 +1377,6 @@ btvacuumpage(BTVacState *vstate, BlockNumber scanblkno)
attempt_pagedel = false;
backtrack_to = P_NONE;
- /* call vacuum_delay_point while not holding any buffer lock */
- vacuum_delay_point();
-
- /*
- * We can't use _bt_getbuf() here because it always applies
- * _bt_checkpage(), which will barf on an all-zero page. We want to
- * recycle all-zero pages, not fail. Also, we want to use a nondefault
- * buffer access strategy.
- */
- buf = ReadBufferExtended(rel, MAIN_FORKNUM, blkno, RBM_NORMAL,
- info->strategy);
_bt_lockbuf(rel, buf, BT_READ);
page = BufferGetPage(buf);
opaque = NULL;
@@ -1125,7 +1412,7 @@ btvacuumpage(BTVacState *vstate, BlockNumber scanblkno)
errmsg_internal("right sibling %u of scanblkno %u unexpectedly in an inconsistent state in index \"%s\"",
blkno, scanblkno, RelationGetRelationName(rel))));
_bt_relbuf(rel, buf);
- return;
+ return scanblkno;
}
/*
@@ -1145,7 +1432,7 @@ btvacuumpage(BTVacState *vstate, BlockNumber scanblkno)
{
/* Done with current scanblkno (and all lower split pages) */
_bt_relbuf(rel, buf);
- return;
+ return scanblkno;
}
}
@@ -1376,8 +1663,22 @@ btvacuumpage(BTVacState *vstate, BlockNumber scanblkno)
if (backtrack_to != P_NONE)
{
blkno = backtrack_to;
+
+ /* check for vacuum delay while not holding any buffer lock */
+ vacuum_delay_point(false);
+
+ /*
+ * We can't use _bt_getbuf() here because it always applies
+ * _bt_checkpage(), which will barf on an all-zero page. We want to
+ * recycle all-zero pages, not fail. Also, we want to use a
+ * nondefault buffer access strategy.
+ */
+ buf = ReadBufferExtended(rel, MAIN_FORKNUM, blkno, RBM_NORMAL,
+ info->strategy);
goto backtrack;
}
+
+ return scanblkno;
}
/*
@@ -1445,3 +1746,52 @@ btcanreturn(Relation index, int attno)
{
return true;
}
+
+/*
+ * btgettreeheight() -- Compute tree height for use by btcostestimate().
+ */
+int
+btgettreeheight(Relation rel)
+{
+ return _bt_getrootheight(rel);
+}
+
+CompareType
+bttranslatestrategy(StrategyNumber strategy, Oid opfamily)
+{
+ switch (strategy)
+ {
+ case BTLessStrategyNumber:
+ return COMPARE_LT;
+ case BTLessEqualStrategyNumber:
+ return COMPARE_LE;
+ case BTEqualStrategyNumber:
+ return COMPARE_EQ;
+ case BTGreaterEqualStrategyNumber:
+ return COMPARE_GE;
+ case BTGreaterStrategyNumber:
+ return COMPARE_GT;
+ default:
+ return COMPARE_INVALID;
+ }
+}
+
+StrategyNumber
+bttranslatecmptype(CompareType cmptype, Oid opfamily)
+{
+ switch (cmptype)
+ {
+ case COMPARE_LT:
+ return BTLessStrategyNumber;
+ case COMPARE_LE:
+ return BTLessEqualStrategyNumber;
+ case COMPARE_EQ:
+ return BTEqualStrategyNumber;
+ case COMPARE_GE:
+ return BTGreaterEqualStrategyNumber;
+ case COMPARE_GT:
+ return BTGreaterStrategyNumber;
+ default:
+ return InvalidStrategy;
+ }
+}
diff --git a/src/backend/access/nbtree/nbtsearch.c b/src/backend/access/nbtree/nbtsearch.c
index 57bcfc7e4c642..d69798795b43b 100644
--- a/src/backend/access/nbtree/nbtsearch.c
+++ b/src/backend/access/nbtree/nbtsearch.c
@@ -4,7 +4,7 @@
* Search code for postgres btrees.
*
*
- * Portions Copyright (c) 1996-2024, PostgreSQL Global Development Group
+ * Portions Copyright (c) 1996-2025, PostgreSQL Global Development Group
* Portions Copyright (c) 1994, Regents of the University of California
*
* IDENTIFICATION
@@ -25,12 +25,15 @@
#include "utils/rel.h"
-static void _bt_drop_lock_and_maybe_pin(IndexScanDesc scan, BTScanPos sp);
+static inline void _bt_drop_lock_and_maybe_pin(Relation rel, BTScanOpaque so);
+static Buffer _bt_moveright(Relation rel, Relation heaprel, BTScanInsert key,
+ Buffer buf, bool forupdate, BTStack stack,
+ int access);
static OffsetNumber _bt_binsrch(Relation rel, BTScanInsert key, Buffer buf);
static int _bt_binsrch_posting(BTScanInsert key, Page page,
OffsetNumber offnum);
static bool _bt_readpage(IndexScanDesc scan, ScanDirection dir,
- OffsetNumber offnum, bool firstPage);
+ OffsetNumber offnum, bool firstpage);
static void _bt_saveitem(BTScanOpaque so, int itemIndex,
OffsetNumber offnum, IndexTuple itup);
static int _bt_setuppostingitems(BTScanOpaque so, int itemIndex,
@@ -39,36 +42,44 @@ static int _bt_setuppostingitems(BTScanOpaque so, int itemIndex,
static inline void _bt_savepostingitem(BTScanOpaque so, int itemIndex,
OffsetNumber offnum,
ItemPointer heapTid, int tupleOffset);
+static inline void _bt_returnitem(IndexScanDesc scan, BTScanOpaque so);
static bool _bt_steppage(IndexScanDesc scan, ScanDirection dir);
-static bool _bt_readnextpage(IndexScanDesc scan, BlockNumber blkno, ScanDirection dir);
-static bool _bt_parallel_readpage(IndexScanDesc scan, BlockNumber blkno,
- ScanDirection dir);
-static Buffer _bt_walk_left(Relation rel, Buffer buf);
+static bool _bt_readfirstpage(IndexScanDesc scan, OffsetNumber offnum,
+ ScanDirection dir);
+static bool _bt_readnextpage(IndexScanDesc scan, BlockNumber blkno,
+ BlockNumber lastcurrblkno, ScanDirection dir,
+ bool seized);
+static Buffer _bt_lock_and_validate_left(Relation rel, BlockNumber *blkno,
+ BlockNumber lastcurrblkno);
static bool _bt_endpoint(IndexScanDesc scan, ScanDirection dir);
-static inline void _bt_initialize_more_data(BTScanOpaque so, ScanDirection dir);
/*
* _bt_drop_lock_and_maybe_pin()
*
- * Unlock the buffer; and if it is safe to release the pin, do that, too.
- * This will prevent vacuum from stalling in a blocked state trying to read a
- * page when a cursor is sitting on it.
- *
- * See nbtree/README section on making concurrent TID recycling safe.
+ * Unlock so->currPos.buf. If scan is so->dropPin, drop the pin, too.
+ * Dropping the pin prevents VACUUM from blocking on acquiring a cleanup lock.
*/
-static void
-_bt_drop_lock_and_maybe_pin(IndexScanDesc scan, BTScanPos sp)
+static inline void
+_bt_drop_lock_and_maybe_pin(Relation rel, BTScanOpaque so)
{
- _bt_unlockbuf(scan->indexRelation, sp->buf);
-
- if (IsMVCCSnapshot(scan->xs_snapshot) &&
- RelationNeedsWAL(scan->indexRelation) &&
- !scan->xs_want_itup)
+ if (!so->dropPin)
{
- ReleaseBuffer(sp->buf);
- sp->buf = InvalidBuffer;
+ /* Just drop the lock (not the pin) */
+ _bt_unlockbuf(rel, so->currPos.buf);
+ return;
}
+
+ /*
+ * Drop both the lock and the pin.
+ *
+ * Have to set so->currPos.lsn so that _bt_killitems has a way to detect
+ * when concurrent heap TID recycling by VACUUM might have taken place.
+ */
+ Assert(RelationNeedsWAL(rel));
+ so->currPos.lsn = BufferGetLSNAtomic(so->currPos.buf);
+ _bt_relbuf(rel, so->currPos.buf);
+ so->currPos.buf = InvalidBuffer;
}
/*
@@ -231,7 +242,7 @@ _bt_search(Relation rel, Relation heaprel, BTScanInsert key, Buffer *bufP,
* 'access'. If we move right, we release the buffer and lock and acquire
* the same on the right sibling. Return value is the buffer we stop at.
*/
-Buffer
+static Buffer
_bt_moveright(Relation rel,
Relation heaprel,
BTScanInsert key,
@@ -858,14 +869,14 @@ _bt_compare(Relation rel,
* We need to be clever about the direction of scan, the search
* conditions, and the tree ordering. We find the first item (or,
* if backwards scan, the last item) in the tree that satisfies the
- * qualifications in the scan key. On success exit, the page containing
- * the current index tuple is pinned but not locked, and data about
- * the matching tuple(s) on the page has been loaded into so->currPos.
- * scan->xs_heaptid is set to the heap TID of the current tuple, and if
- * requested, scan->xs_itup points to a copy of the index tuple.
+ * qualifications in the scan key. On success exit, data about the
+ * matching tuple(s) on the page has been loaded into so->currPos. We'll
+ * drop all locks and hold onto a pin on page's buffer, except during
+ * so->dropPin scans, when we drop both the lock and the pin.
+ * _bt_returnitem sets the next item to return to scan on success exit.
*
* If there are no matching items in the index, we return false, with no
- * pins or locks held.
+ * pins or locks held. so->currPos will remain invalid.
*
* Note that scan->keyData[], and the so->keyData[] scankey built from it,
* are both search-type scankeys (see nbtree/README for more about this).
@@ -877,24 +888,18 @@ _bt_first(IndexScanDesc scan, ScanDirection dir)
{
Relation rel = scan->indexRelation;
BTScanOpaque so = (BTScanOpaque) scan->opaque;
- Buffer buf;
BTStack stack;
OffsetNumber offnum;
- StrategyNumber strat;
BTScanInsertData inskey;
ScanKey startKeys[INDEX_MAX_KEYS];
- ScanKeyData notnullkeys[INDEX_MAX_KEYS];
+ ScanKeyData notnullkey;
int keysz = 0;
- int i;
- bool status;
- StrategyNumber strat_total;
- BTScanPosItem *currItem;
- BlockNumber blkno;
+ StrategyNumber strat_total = InvalidStrategy;
+ BlockNumber blkno = InvalidBlockNumber,
+ lastcurrblkno;
Assert(!BTScanPosIsValid(so->currPos));
- pgstat_count_index_scan(rel);
-
/*
* Examine the scan keys and eliminate any redundant keys; also mark the
* keys that must be matched to continue the scan.
@@ -907,87 +912,102 @@ _bt_first(IndexScanDesc scan, ScanDirection dir)
*/
if (!so->qual_ok)
{
+ Assert(!so->needPrimScan);
_bt_parallel_done(scan);
return false;
}
/*
- * For parallel scans, get the starting page from shared state. If the
- * scan has not started, proceed to find out first leaf page in the usual
- * way while keeping other participating processes waiting. If the scan
- * has already begun, use the page number from the shared structure.
- *
- * When a parallel scan has another primitive index scan scheduled, a
- * parallel worker will seize the scan for that purpose now. This is
- * similar to the case where the top-level scan hasn't started.
+ * If this is a parallel scan, we must seize the scan. _bt_readfirstpage
+ * will likely release the parallel scan later on.
*/
- if (scan->parallel_scan != NULL)
- {
- status = _bt_parallel_seize(scan, &blkno, true);
+ if (scan->parallel_scan != NULL &&
+ !_bt_parallel_seize(scan, &blkno, &lastcurrblkno, true))
+ return false;
- /*
- * Initialize arrays (when _bt_parallel_seize didn't already set up
- * the next primitive index scan)
- */
- if (so->numArrayKeys && !so->needPrimScan)
- _bt_start_array_keys(scan, dir);
+ /*
+ * Initialize the scan's arrays (if any) for the current scan direction
+ * (except when they were already set to later values as part of
+ * scheduling the primitive index scan that is now underway)
+ */
+ if (so->numArrayKeys && !so->needPrimScan)
+ _bt_start_array_keys(scan, dir);
- if (!status)
- return false;
- else if (blkno == P_NONE)
- {
- _bt_parallel_done(scan);
- return false;
- }
- else if (blkno != InvalidBlockNumber)
- {
- if (!_bt_parallel_readpage(scan, blkno, dir))
- return false;
- goto readcomplete;
- }
- }
- else if (so->numArrayKeys && !so->needPrimScan)
+ if (blkno != InvalidBlockNumber)
{
/*
- * First _bt_first call (for current btrescan) without parallelism.
- *
- * Initialize arrays, and the corresponding scan keys that were just
- * output by _bt_preprocess_keys.
+ * We anticipated calling _bt_search, but another worker bet us to it.
+ * _bt_readnextpage releases the scan for us (not _bt_readfirstpage).
*/
- _bt_start_array_keys(scan, dir);
+ Assert(scan->parallel_scan != NULL);
+ Assert(!so->needPrimScan);
+ Assert(blkno != P_NONE);
+
+ if (!_bt_readnextpage(scan, blkno, lastcurrblkno, dir, true))
+ return false;
+
+ _bt_returnitem(scan, so);
+ return true;
}
+ /*
+ * Count an indexscan for stats, now that we know that we'll call
+ * _bt_search/_bt_endpoint below
+ */
+ pgstat_count_index_scan(rel);
+ if (scan->instrument)
+ scan->instrument->nsearches++;
+
/*----------
* Examine the scan keys to discover where we need to start the scan.
+ * The selected scan keys (at most one per index column) are remembered by
+ * storing their addresses into the local startKeys[] array. The final
+ * startKeys[] entry's strategy is set in strat_total. (Actually, there
+ * are a couple of cases where we force a less/more restrictive strategy.)
*
- * We want to identify the keys that can be used as starting boundaries;
- * these are =, >, or >= keys for a forward scan or =, <, <= keys for
- * a backwards scan. We can use keys for multiple attributes so long as
- * the prior attributes had only =, >= (resp. =, <=) keys. Once we accept
- * a > or < boundary or find an attribute with no boundary (which can be
- * thought of as the same as "> -infinity"), we can't use keys for any
- * attributes to its right, because it would break our simplistic notion
- * of what initial positioning strategy to use.
+ * We must use the key that was marked required (in the direction opposite
+ * our own scan's) during preprocessing. Each index attribute can only
+ * have one such required key. In general, the keys that we use to find
+ * an initial position when scanning forwards are the same keys that end
+ * the scan on the leaf level when scanning backwards (and vice-versa).
*
* When the scan keys include cross-type operators, _bt_preprocess_keys
- * may not be able to eliminate redundant keys; in such cases we will
- * arbitrarily pick a usable one for each attribute. This is correct
- * but possibly not optimal behavior. (For example, with keys like
- * "x >= 4 AND x >= 5" we would elect to scan starting at x=4 when
- * x=5 would be more efficient.) Since the situation only arises given
- * a poorly-worded query plus an incomplete opfamily, live with it.
+ * may not be able to eliminate redundant keys; in such cases it will
+ * arbitrarily pick a usable key for each attribute (and scan direction),
+ * ensuring that there is no more than one key required in each direction.
+ * We stop considering further keys once we reach the first nonrequired
+ * key (which must come after all required keys), so this can't affect us.
+ *
+ * The required keys that we use as starting boundaries have to be =, >,
+ * or >= keys for a forward scan or =, <, <= keys for a backwards scan.
+ * We can use keys for multiple attributes so long as the prior attributes
+ * had only =, >= (resp. =, <=) keys. These rules are very similar to the
+ * rules that preprocessing used to determine which keys to mark required.
+ * We cannot always use every required key as a positioning key, though.
+ * Skip arrays necessitate independently applying our own rules here.
+ * Skip arrays are always generally considered = array keys, but we'll
+ * nevertheless treat them as inequalities at certain points of the scan.
+ * When that happens, it _might_ have implications for the number of
+ * required keys that we can safely use for initial positioning purposes.
+ *
+ * For example, a forward scan with a skip array on its leading attribute
+ * (with no low_compare/high_compare) will have at least two required scan
+ * keys, but we won't use any of them as boundary keys during the scan's
+ * initial call here. Our positioning key during the first call here can
+ * be thought of as representing "> -infinity". Similarly, if such a skip
+ * array's low_compare is "a > 'foo'", then we position using "a > 'foo'"
+ * during the scan's initial call here; a lower-order key such as "b = 42"
+ * can't be used until the "a" array advances beyond MINVAL/low_compare.
*
- * When both equality and inequality keys appear for a single attribute
- * (again, only possible when cross-type operators appear), we *must*
- * select one of the equality keys for the starting point, because
- * _bt_checkkeys() will stop the scan as soon as an equality qual fails.
- * For example, if we have keys like "x >= 4 AND x = 10" and we elect to
- * start at x=4, we will fail and stop before reaching x=10. If multiple
- * equality quals survive preprocessing, however, it doesn't matter which
- * one we use --- by definition, they are either redundant or
- * contradictory.
+ * On the other hand, if such a skip array's low_compare was "a >= 'foo'",
+ * then we _can_ use "a >= 'foo' AND b = 42" during the initial call here.
+ * A subsequent call here might have us use "a = 'fop' AND b = 42". Note
+ * that we treat = and >= as equivalent when scanning forwards (just as we
+ * treat = and <= as equivalent when scanning backwards). We effectively
+ * do the same thing (though with a distinct "a" element/value) each time.
*
- * Any regular (not SK_SEARCHNULL) key implies a NOT NULL qualifier.
+ * All keys (with the exception of SK_SEARCHNULL keys and SK_BT_SKIP
+ * array keys whose array is "null_elem=true") imply a NOT NULL qualifier.
* If the index stores nulls at the end of the index we'll be starting
* from, and we have no boundary key for the column (which means the key
* we deduced NOT NULL from is an inequality key that constrains the other
@@ -996,40 +1016,38 @@ _bt_first(IndexScanDesc scan, ScanDirection dir)
* traversing a lot of null entries at the start of the scan.
*
* In this loop, row-comparison keys are treated the same as keys on their
- * first (leftmost) columns. We'll add on lower-order columns of the row
- * comparison below, if possible.
+ * first (leftmost) columns. We'll add all lower-order columns of the row
+ * comparison that were marked required during preprocessing below.
*
- * The selected scan keys (at most one per index column) are remembered by
- * storing their addresses into the local startKeys[] array.
- *
- * _bt_checkkeys/_bt_advance_array_keys decide whether and when to start
- * the next primitive index scan (for scans with array keys) based in part
- * on an understanding of how it'll enable us to reposition the scan.
- * They're directly aware of how we'll sometimes cons up an explicit
- * SK_SEARCHNOTNULL key. They'll even end primitive scans by applying a
- * symmetric "deduce NOT NULL" rule of their own. This allows top-level
- * scans to skip large groups of NULLs through repeated deductions about
- * key strictness (for a required inequality key) and whether NULLs in the
- * key's index column are stored last or first (relative to non-NULLs).
+ * _bt_advance_array_keys needs to know exactly how we'll reposition the
+ * scan (should it opt to schedule another primitive index scan). It is
+ * critical that primscans only be scheduled when they'll definitely make
+ * some useful progress. _bt_advance_array_keys does this by calling
+ * _bt_checkkeys routines that report whether a tuple is past the end of
+ * matches for the scan's keys (given the scan's current array elements).
+ * If the page's final tuple is "after the end of matches" for a scan that
+ * uses the *opposite* scan direction, then it must follow that it's also
+ * "before the start of matches" for the actual current scan direction.
+ * It is therefore essential that all of our initial positioning rules are
+ * symmetric with _bt_checkkeys's corresponding continuescan=false rule.
* If you update anything here, _bt_checkkeys/_bt_advance_array_keys might
* need to be kept in sync.
*----------
*/
- strat_total = BTEqualStrategyNumber;
if (so->numberOfKeys > 0)
{
AttrNumber curattr;
- ScanKey chosen;
+ ScanKey bkey;
ScanKey impliesNN;
ScanKey cur;
/*
- * chosen is the so-far-chosen key for the current attribute, if any.
- * We don't cast the decision in stone until we reach keys for the
- * next attribute.
+ * bkey will be set to the key that preprocessing left behind as the
+ * boundary key for this attribute, in this scan direction (if any)
*/
+ cur = so->keyData;
curattr = 1;
- chosen = NULL;
+ bkey = NULL;
/* Also remember any scankey that implies a NOT NULL constraint */
impliesNN = NULL;
@@ -1038,29 +1056,80 @@ _bt_first(IndexScanDesc scan, ScanDirection dir)
* pass to handle after-last-key processing. Actual exit from the
* loop is at one of the "break" statements below.
*/
- for (cur = so->keyData, i = 0;; cur++, i++)
+ for (int i = 0;; cur++, i++)
{
if (i >= so->numberOfKeys || cur->sk_attno != curattr)
{
+ /* Done looking for the curattr boundary key */
+ Assert(bkey == NULL ||
+ (bkey->sk_attno == curattr &&
+ (bkey->sk_flags & (SK_BT_REQFWD | SK_BT_REQBKWD))));
+ Assert(impliesNN == NULL ||
+ (impliesNN->sk_attno == curattr &&
+ (impliesNN->sk_flags & (SK_BT_REQFWD | SK_BT_REQBKWD))));
+
+ /*
+ * If this is a scan key for a skip array whose current
+ * element is MINVAL, choose low_compare (when scanning
+ * backwards it'll be MAXVAL, and we'll choose high_compare).
+ *
+ * Note: if the array's low_compare key makes 'bkey' NULL,
+ * then we behave as if the array's first element is -inf,
+ * except when !array->null_elem implies a usable NOT NULL
+ * constraint.
+ */
+ if (bkey != NULL &&
+ (bkey->sk_flags & (SK_BT_MINVAL | SK_BT_MAXVAL)))
+ {
+ int ikey = bkey - so->keyData;
+ ScanKey skipequalitykey = bkey;
+ BTArrayKeyInfo *array = NULL;
+
+ for (int arridx = 0; arridx < so->numArrayKeys; arridx++)
+ {
+ array = &so->arrayKeys[arridx];
+ if (array->scan_key == ikey)
+ break;
+ }
+
+ if (ScanDirectionIsForward(dir))
+ {
+ Assert(!(skipequalitykey->sk_flags & SK_BT_MAXVAL));
+ bkey = array->low_compare;
+ }
+ else
+ {
+ Assert(!(skipequalitykey->sk_flags & SK_BT_MINVAL));
+ bkey = array->high_compare;
+ }
+
+ Assert(bkey == NULL ||
+ bkey->sk_attno == skipequalitykey->sk_attno);
+
+ if (!array->null_elem)
+ impliesNN = skipequalitykey;
+ else
+ Assert(bkey == NULL && impliesNN == NULL);
+ }
+
/*
- * Done looking at keys for curattr. If we didn't find a
- * usable boundary key, see if we can deduce a NOT NULL key.
+ * If we didn't find a usable boundary key, see if we can
+ * deduce a NOT NULL key
*/
- if (chosen == NULL && impliesNN != NULL &&
+ if (bkey == NULL && impliesNN != NULL &&
((impliesNN->sk_flags & SK_BT_NULLS_FIRST) ?
ScanDirectionIsForward(dir) :
ScanDirectionIsBackward(dir)))
{
- /* Yes, so build the key in notnullkeys[keysz] */
- chosen = ¬nullkeys[keysz];
- ScanKeyEntryInitialize(chosen,
+ /* Final startKeys[] entry will be deduced NOT NULL key */
+ bkey = ¬nullkey;
+ ScanKeyEntryInitialize(bkey,
(SK_SEARCHNOTNULL | SK_ISNULL |
(impliesNN->sk_flags &
(SK_BT_DESC | SK_BT_NULLS_FIRST))),
curattr,
- ((impliesNN->sk_flags & SK_BT_NULLS_FIRST) ?
- BTGreaterStrategyNumber :
- BTLessStrategyNumber),
+ ScanDirectionIsForward(dir) ?
+ BTGreaterStrategyNumber : BTLessStrategyNumber,
InvalidOid,
InvalidOid,
InvalidOid,
@@ -1068,45 +1137,80 @@ _bt_first(IndexScanDesc scan, ScanDirection dir)
}
/*
- * If we still didn't find a usable boundary key, quit; else
- * save the boundary key pointer in startKeys.
+ * If preprocessing didn't leave a usable boundary key, quit;
+ * else save the boundary key pointer in startKeys[]
+ */
+ if (bkey == NULL)
+ break;
+ startKeys[keysz++] = bkey;
+
+ /*
+ * We can only consider adding more boundary keys when the one
+ * that we just chose to add uses either the = or >= strategy
+ * (during backwards scans we can only do so when the key that
+ * we just added to startKeys[] uses the = or <= strategy)
*/
- if (chosen == NULL)
+ strat_total = bkey->sk_strategy;
+ if (strat_total == BTGreaterStrategyNumber ||
+ strat_total == BTLessStrategyNumber)
break;
- startKeys[keysz++] = chosen;
/*
- * Adjust strat_total, and quit if we have stored a > or <
- * key.
+ * If the key that we just added to startKeys[] is a skip
+ * array = key whose current element is marked NEXT or PRIOR,
+ * make strat_total > or < (and stop adding boundary keys).
+ * This can only happen with opclasses that lack skip support.
*/
- strat = chosen->sk_strategy;
- if (strat != BTEqualStrategyNumber)
+ if (bkey->sk_flags & (SK_BT_NEXT | SK_BT_PRIOR))
{
- strat_total = strat;
- if (strat == BTGreaterStrategyNumber ||
- strat == BTLessStrategyNumber)
- break;
+ Assert(bkey->sk_flags & SK_BT_SKIP);
+ Assert(strat_total == BTEqualStrategyNumber);
+
+ if (ScanDirectionIsForward(dir))
+ {
+ Assert(!(bkey->sk_flags & SK_BT_PRIOR));
+ strat_total = BTGreaterStrategyNumber;
+ }
+ else
+ {
+ Assert(!(bkey->sk_flags & SK_BT_NEXT));
+ strat_total = BTLessStrategyNumber;
+ }
+
+ /*
+ * We're done. We'll never find an exact = match for a
+ * NEXT or PRIOR sentinel sk_argument value. There's no
+ * sense in trying to add more keys to startKeys[].
+ */
+ break;
}
/*
- * Done if that was the last attribute, or if next key is not
- * in sequence (implying no boundary key is available for the
- * next attribute).
+ * Done if that was the last scan key output by preprocessing.
+ * Also done if we've now examined all keys marked required.
*/
if (i >= so->numberOfKeys ||
- cur->sk_attno != curattr + 1)
+ !(cur->sk_flags & (SK_BT_REQFWD | SK_BT_REQBKWD)))
break;
/*
* Reset for next attr.
*/
+ Assert(cur->sk_attno == curattr + 1);
curattr = cur->sk_attno;
- chosen = NULL;
+ bkey = NULL;
impliesNN = NULL;
}
/*
- * Can we use this key as a starting boundary for this attr?
+ * If we've located the starting boundary key for curattr, we have
+ * no interest in curattr's other required key
+ */
+ if (bkey != NULL)
+ continue;
+
+ /*
+ * Is this key the starting boundary key for curattr?
*
* If not, does it imply a NOT NULL constraint? (Because
* SK_SEARCHNULL keys are always assigned BTEqualStrategyNumber,
@@ -1116,27 +1220,20 @@ _bt_first(IndexScanDesc scan, ScanDirection dir)
{
case BTLessStrategyNumber:
case BTLessEqualStrategyNumber:
- if (chosen == NULL)
- {
- if (ScanDirectionIsBackward(dir))
- chosen = cur;
- else
- impliesNN = cur;
- }
+ if (ScanDirectionIsBackward(dir))
+ bkey = cur;
+ else if (impliesNN == NULL)
+ impliesNN = cur;
break;
case BTEqualStrategyNumber:
- /* override any non-equality choice */
- chosen = cur;
+ bkey = cur;
break;
case BTGreaterEqualStrategyNumber:
case BTGreaterStrategyNumber:
- if (chosen == NULL)
- {
- if (ScanDirectionIsForward(dir))
- chosen = cur;
- else
- impliesNN = cur;
- }
+ if (ScanDirectionIsForward(dir))
+ bkey = cur;
+ else if (impliesNN == NULL)
+ impliesNN = cur;
break;
}
}
@@ -1146,164 +1243,195 @@ _bt_first(IndexScanDesc scan, ScanDirection dir)
* If we found no usable boundary keys, we have to start from one end of
* the tree. Walk down that edge to the first or last key, and scan from
* there.
+ *
+ * Note: calls _bt_readfirstpage for us, which releases the parallel scan.
*/
if (keysz == 0)
- {
- bool match;
-
- match = _bt_endpoint(scan, dir);
-
- if (!match)
- {
- /* No match, so mark (parallel) scan finished */
- _bt_parallel_done(scan);
- }
-
- return match;
- }
+ return _bt_endpoint(scan, dir);
/*
* We want to start the scan somewhere within the index. Set up an
* insertion scankey we can use to search for the boundary point we
* identified above. The insertion scankey is built using the keys
* identified by startKeys[]. (Remaining insertion scankey fields are
- * initialized after initial-positioning strategy is finalized.)
+ * initialized after initial-positioning scan keys are finalized.)
*/
Assert(keysz <= INDEX_MAX_KEYS);
- for (i = 0; i < keysz; i++)
+ for (int i = 0; i < keysz; i++)
{
- ScanKey cur = startKeys[i];
+ ScanKey bkey = startKeys[i];
- Assert(cur->sk_attno == i + 1);
+ Assert(bkey->sk_attno == i + 1);
- if (cur->sk_flags & SK_ROW_HEADER)
+ if (bkey->sk_flags & SK_ROW_HEADER)
{
/*
- * Row comparison header: look to the first row member instead.
- *
- * The member scankeys are already in insertion format (ie, they
- * have sk_func = 3-way-comparison function), but we have to watch
- * out for nulls, which _bt_preprocess_keys didn't check. A null
- * in the first row member makes the condition unmatchable, just
- * like qual_ok = false.
+ * Row comparison header: look to the first row member instead
*/
- ScanKey subkey = (ScanKey) DatumGetPointer(cur->sk_argument);
+ ScanKey subkey = (ScanKey) DatumGetPointer(bkey->sk_argument);
+ bool loosen_strat = false,
+ tighten_strat = false;
+ /*
+ * Cannot be a NULL in the first row member: _bt_preprocess_keys
+ * would've marked the qual as unsatisfiable, preventing us from
+ * ever getting this far
+ */
Assert(subkey->sk_flags & SK_ROW_MEMBER);
- if (subkey->sk_flags & SK_ISNULL)
- {
- _bt_parallel_done(scan);
- return false;
- }
+ Assert(subkey->sk_attno == bkey->sk_attno);
+ Assert(!(subkey->sk_flags & SK_ISNULL));
+
+ /*
+ * This is either a > or >= key (during backwards scans it is
+ * either < or <=) that was marked required during preprocessing.
+ * Later so->keyData[] keys can't have been marked required, so
+ * our row compare header key must be the final startKeys[] entry.
+ */
+ Assert(subkey->sk_flags & (SK_BT_REQFWD | SK_BT_REQBKWD));
+ Assert(i == keysz - 1);
+
+ /*
+ * The member scankeys are already in insertion format (ie, they
+ * have sk_func = 3-way-comparison function)
+ */
memcpy(inskey.scankeys + i, subkey, sizeof(ScanKeyData));
/*
- * If the row comparison is the last positioning key we accepted,
- * try to add additional keys from the lower-order row members.
- * (If we accepted independent conditions on additional index
- * columns, we use those instead --- doesn't seem worth trying to
- * determine which is more restrictive.) Note that this is OK
- * even if the row comparison is of ">" or "<" type, because the
- * condition applied to all but the last row member is effectively
- * ">=" or "<=", and so the extra keys don't break the positioning
- * scheme. But, by the same token, if we aren't able to use all
- * the row members, then the part of the row comparison that we
- * did use has to be treated as just a ">=" or "<=" condition, and
- * so we'd better adjust strat_total accordingly.
+ * Now look to later row compare members.
+ *
+ * If there's an "index attribute gap" between two row compare
+ * members, the second member won't have been marked required, and
+ * so can't be used as a starting boundary key here. The part of
+ * the row comparison that we do still use has to be treated as a
+ * ">=" or "<=" condition. For example, a qual "(a, c) > (1, 42)"
+ * with an omitted intervening index attribute "b" will use an
+ * insertion scan key "a >= 1". Even the first "a = 1" tuple on
+ * the leaf level might satisfy the row compare qual.
+ *
+ * We're able to use a _more_ restrictive strategy when we reach a
+ * NULL row compare member, since they're always unsatisfiable.
+ * For example, a qual "(a, b, c) >= (1, NULL, 77)" will use an
+ * insertion scan key "a > 1". All tuples where "a = 1" cannot
+ * possibly satisfy the row compare qual, so this is safe.
*/
- if (i == keysz - 1)
+ Assert(!(subkey->sk_flags & SK_ROW_END));
+ for (;;)
{
- bool used_all_subkeys = false;
+ subkey++;
+ Assert(subkey->sk_flags & SK_ROW_MEMBER);
- Assert(!(subkey->sk_flags & SK_ROW_END));
- for (;;)
+ if (subkey->sk_flags & SK_ISNULL)
{
- subkey++;
- Assert(subkey->sk_flags & SK_ROW_MEMBER);
- if (subkey->sk_attno != keysz + 1)
- break; /* out-of-sequence, can't use it */
- if (subkey->sk_strategy != cur->sk_strategy)
- break; /* wrong direction, can't use it */
- if (subkey->sk_flags & SK_ISNULL)
- break; /* can't use null keys */
- Assert(keysz < INDEX_MAX_KEYS);
- memcpy(inskey.scankeys + keysz, subkey,
- sizeof(ScanKeyData));
- keysz++;
- if (subkey->sk_flags & SK_ROW_END)
- {
- used_all_subkeys = true;
- break;
- }
+ /*
+ * NULL member key, can only use earlier keys.
+ *
+ * We deliberately avoid checking if this key is marked
+ * required. All earlier keys are required, and this key
+ * is unsatisfiable either way, so we can't miss anything.
+ */
+ tighten_strat = true;
+ break;
}
- if (!used_all_subkeys)
+
+ if (!(subkey->sk_flags & (SK_BT_REQFWD | SK_BT_REQBKWD)))
{
- switch (strat_total)
- {
- case BTLessStrategyNumber:
- strat_total = BTLessEqualStrategyNumber;
- break;
- case BTGreaterStrategyNumber:
- strat_total = BTGreaterEqualStrategyNumber;
- break;
- }
+ /* nonrequired member key, can only use earlier keys */
+ loosen_strat = true;
+ break;
}
- break; /* done with outer loop */
+
+ Assert(subkey->sk_attno == keysz + 1);
+ Assert(subkey->sk_strategy == bkey->sk_strategy);
+ Assert(keysz < INDEX_MAX_KEYS);
+
+ memcpy(inskey.scankeys + keysz, subkey,
+ sizeof(ScanKeyData));
+ keysz++;
+ if (subkey->sk_flags & SK_ROW_END)
+ break;
}
- }
- else
- {
- /*
- * Ordinary comparison key. Transform the search-style scan key
- * to an insertion scan key by replacing the sk_func with the
- * appropriate btree comparison function.
- *
- * If scankey operator is not a cross-type comparison, we can use
- * the cached comparison function; otherwise gotta look it up in
- * the catalogs. (That can't lead to infinite recursion, since no
- * indexscan initiated by syscache lookup will use cross-data-type
- * operators.)
- *
- * We support the convention that sk_subtype == InvalidOid means
- * the opclass input type; this is a hack to simplify life for
- * ScanKeyInit().
- */
- if (cur->sk_subtype == rel->rd_opcintype[i] ||
- cur->sk_subtype == InvalidOid)
+ Assert(!(loosen_strat && tighten_strat));
+ if (loosen_strat)
{
- FmgrInfo *procinfo;
-
- procinfo = index_getprocinfo(rel, cur->sk_attno, BTORDER_PROC);
- ScanKeyEntryInitializeWithInfo(inskey.scankeys + i,
- cur->sk_flags,
- cur->sk_attno,
- InvalidStrategy,
- cur->sk_subtype,
- cur->sk_collation,
- procinfo,
- cur->sk_argument);
+ /* Use less restrictive strategy (and fewer member keys) */
+ switch (strat_total)
+ {
+ case BTLessStrategyNumber:
+ strat_total = BTLessEqualStrategyNumber;
+ break;
+ case BTGreaterStrategyNumber:
+ strat_total = BTGreaterEqualStrategyNumber;
+ break;
+ }
}
- else
+ if (tighten_strat)
{
- RegProcedure cmp_proc;
-
- cmp_proc = get_opfamily_proc(rel->rd_opfamily[i],
- rel->rd_opcintype[i],
- cur->sk_subtype,
- BTORDER_PROC);
- if (!RegProcedureIsValid(cmp_proc))
- elog(ERROR, "missing support function %d(%u,%u) for attribute %d of index \"%s\"",
- BTORDER_PROC, rel->rd_opcintype[i], cur->sk_subtype,
- cur->sk_attno, RelationGetRelationName(rel));
- ScanKeyEntryInitialize(inskey.scankeys + i,
- cur->sk_flags,
- cur->sk_attno,
- InvalidStrategy,
- cur->sk_subtype,
- cur->sk_collation,
- cmp_proc,
- cur->sk_argument);
+ /* Use more restrictive strategy (and fewer member keys) */
+ switch (strat_total)
+ {
+ case BTLessEqualStrategyNumber:
+ strat_total = BTLessStrategyNumber;
+ break;
+ case BTGreaterEqualStrategyNumber:
+ strat_total = BTGreaterStrategyNumber;
+ break;
+ }
}
+
+ /* done adding to inskey (row comparison keys always come last) */
+ break;
+ }
+
+ /*
+ * Ordinary comparison key/search-style key.
+ *
+ * Transform the search-style scan key to an insertion scan key by
+ * replacing the sk_func with the appropriate btree 3-way-comparison
+ * function.
+ *
+ * If scankey operator is not a cross-type comparison, we can use the
+ * cached comparison function; otherwise gotta look it up in the
+ * catalogs. (That can't lead to infinite recursion, since no
+ * indexscan initiated by syscache lookup will use cross-data-type
+ * operators.)
+ *
+ * We support the convention that sk_subtype == InvalidOid means the
+ * opclass input type; this hack simplifies life for ScanKeyInit().
+ */
+ if (bkey->sk_subtype == rel->rd_opcintype[i] ||
+ bkey->sk_subtype == InvalidOid)
+ {
+ FmgrInfo *procinfo;
+
+ procinfo = index_getprocinfo(rel, bkey->sk_attno, BTORDER_PROC);
+ ScanKeyEntryInitializeWithInfo(inskey.scankeys + i,
+ bkey->sk_flags,
+ bkey->sk_attno,
+ InvalidStrategy,
+ bkey->sk_subtype,
+ bkey->sk_collation,
+ procinfo,
+ bkey->sk_argument);
+ }
+ else
+ {
+ RegProcedure cmp_proc;
+
+ cmp_proc = get_opfamily_proc(rel->rd_opfamily[i],
+ rel->rd_opcintype[i],
+ bkey->sk_subtype, BTORDER_PROC);
+ if (!RegProcedureIsValid(cmp_proc))
+ elog(ERROR, "missing support function %d(%u,%u) for attribute %d of index \"%s\"",
+ BTORDER_PROC, rel->rd_opcintype[i], bkey->sk_subtype,
+ bkey->sk_attno, RelationGetRelationName(rel));
+ ScanKeyEntryInitialize(inskey.scankeys + i,
+ bkey->sk_flags,
+ bkey->sk_attno,
+ InvalidStrategy,
+ bkey->sk_subtype,
+ bkey->sk_collation,
+ cmp_proc,
+ bkey->sk_argument);
}
}
@@ -1385,13 +1513,15 @@ _bt_first(IndexScanDesc scan, ScanDirection dir)
* position ourselves on the target leaf page.
*/
Assert(ScanDirectionIsBackward(dir) == inskey.backward);
- stack = _bt_search(rel, NULL, &inskey, &buf, BT_READ);
+ stack = _bt_search(rel, NULL, &inskey, &so->currPos.buf, BT_READ);
/* don't need to keep the stack around... */
_bt_freestack(stack);
- if (!BufferIsValid(buf))
+ if (!BufferIsValid(so->currPos.buf))
{
+ Assert(!so->needPrimScan);
+
/*
* We only get here if the index is completely empty. Lock relation
* because nothing finer to lock exists. Without a buffer lock, it's
@@ -1404,33 +1534,23 @@ _bt_first(IndexScanDesc scan, ScanDirection dir)
if (IsolationIsSerializable())
{
PredicateLockRelation(rel, scan->xs_snapshot);
- stack = _bt_search(rel, NULL, &inskey, &buf, BT_READ);
+ stack = _bt_search(rel, NULL, &inskey, &so->currPos.buf, BT_READ);
_bt_freestack(stack);
}
- if (!BufferIsValid(buf))
+ if (!BufferIsValid(so->currPos.buf))
{
- /*
- * Mark parallel scan as done, so that all the workers can finish
- * their scan.
- */
_bt_parallel_done(scan);
- BTScanPosInvalidate(so->currPos);
return false;
}
}
- PredicateLockPage(rel, BufferGetBlockNumber(buf), scan->xs_snapshot);
-
- _bt_initialize_more_data(so, dir);
-
/* position to the precise item on the page */
- offnum = _bt_binsrch(rel, &inskey, buf);
- Assert(!BTScanPosIsValid(so->currPos));
- so->currPos.buf = buf;
+ offnum = _bt_binsrch(rel, &inskey, so->currPos.buf);
/*
- * Now load data from the first page of the scan.
+ * Now load data from the first page of the scan (usually the page
+ * currently in so->currPos.buf).
*
* If inskey.nextkey = false and inskey.backward = false, offnum is
* positioned at the first non-pivot tuple >= inskey.scankeys.
@@ -1448,29 +1568,10 @@ _bt_first(IndexScanDesc scan, ScanDirection dir)
* for the page. For example, when inskey is both < the leaf page's high
* key and > all of its non-pivot tuples, offnum will be "maxoff + 1".
*/
- if (!_bt_readpage(scan, dir, offnum, true))
- {
- /*
- * There's no actually-matching data on this page. Try to advance to
- * the next page. Return false if there's no matching data at all.
- */
- _bt_unlockbuf(scan->indexRelation, so->currPos.buf);
- if (!_bt_steppage(scan, dir))
- return false;
- }
- else
- {
- /* We have at least one item to return as scan's first item */
- _bt_drop_lock_and_maybe_pin(scan, &so->currPos);
- }
-
-readcomplete:
- /* OK, itemIndex says what to return */
- currItem = &so->currPos.items[so->currPos.itemIndex];
- scan->xs_heaptid = currItem->heapTid;
- if (scan->xs_want_itup)
- scan->xs_itup = (IndexTuple) (so->currTuples + currItem->tupleOffset);
+ if (!_bt_readfirstpage(scan, offnum, dir))
+ return false;
+ _bt_returnitem(scan, so);
return true;
}
@@ -1481,18 +1582,19 @@ _bt_first(IndexScanDesc scan, ScanDirection dir)
* but is not locked, and so->currPos.itemIndex identifies which item was
* previously returned.
*
- * On successful exit, scan->xs_heaptid is set to the TID of the next
- * heap tuple, and if requested, scan->xs_itup points to a copy of the
- * index tuple. so->currPos is updated as needed.
+ * On success exit, so->currPos is updated as needed, and _bt_returnitem
+ * sets the next item to return to the scan. so->currPos remains valid.
*
- * On failure exit (no more tuples), we release pin and set
- * so->currPos.buf to InvalidBuffer.
+ * On failure exit (no more tuples), we invalidate so->currPos. It'll
+ * still be possible for the scan to return tuples by changing direction,
+ * though we'll need to call _bt_first anew in that other direction.
*/
bool
_bt_next(IndexScanDesc scan, ScanDirection dir)
{
BTScanOpaque so = (BTScanOpaque) scan->opaque;
- BTScanPosItem *currItem;
+
+ Assert(BTScanPosIsValid(so->currPos));
/*
* Advance to next tuple on current page; or if there's no more, try to
@@ -1515,12 +1617,7 @@ _bt_next(IndexScanDesc scan, ScanDirection dir)
}
}
- /* OK, itemIndex says what to return */
- currItem = &so->currPos.items[so->currPos.itemIndex];
- scan->xs_heaptid = currItem->heapTid;
- if (scan->xs_want_itup)
- scan->xs_itup = (IndexTuple) (so->currTuples + currItem->tupleOffset);
-
+ _bt_returnitem(scan, so);
return true;
}
@@ -1538,14 +1635,6 @@ _bt_next(IndexScanDesc scan, ScanDirection dir)
* that there can be no more matching tuples in the current scan direction
* (could just be for the current primitive index scan when scan has arrays).
*
- * _bt_first caller passes us an offnum returned by _bt_binsrch, which might
- * be an out of bounds offnum such as "maxoff + 1" in certain corner cases.
- * _bt_checkkeys will stop the scan as soon as an equality qual fails (when
- * its scan key was marked required), so _bt_first _must_ pass us an offnum
- * exactly at the beginning of where equal tuples are to be found. When we're
- * passed an offnum past the end of the page, we might still manage to stop
- * the scan on this page by calling _bt_checkkeys against the high key.
- *
* In the case of a parallel scan, caller must have called _bt_parallel_seize
* prior to calling this function; this function will invoke
* _bt_parallel_release before returning.
@@ -1554,8 +1643,9 @@ _bt_next(IndexScanDesc scan, ScanDirection dir)
*/
static bool
_bt_readpage(IndexScanDesc scan, ScanDirection dir, OffsetNumber offnum,
- bool firstPage)
+ bool firstpage)
{
+ Relation rel = scan->indexRelation;
BTScanOpaque so = (BTScanOpaque) scan->opaque;
Page page;
BTPageOpaque opaque;
@@ -1566,138 +1656,91 @@ _bt_readpage(IndexScanDesc scan, ScanDirection dir, OffsetNumber offnum,
int itemIndex,
indnatts;
- /*
- * We must have the buffer pinned and locked, but the usual macro can't be
- * used here; this function is what makes it good for currPos.
- */
- Assert(BufferIsValid(so->currPos.buf));
-
+ /* save the page/buffer block number, along with its sibling links */
page = BufferGetPage(so->currPos.buf);
opaque = BTPageGetOpaque(page);
+ so->currPos.currPage = BufferGetBlockNumber(so->currPos.buf);
+ so->currPos.prevPage = opaque->btpo_prev;
+ so->currPos.nextPage = opaque->btpo_next;
+ /* delay setting so->currPos.lsn until _bt_drop_lock_and_maybe_pin */
+ so->currPos.dir = dir;
+ so->currPos.nextTupleOffset = 0;
+
+ /* either moreRight or moreLeft should be set now (may be unset later) */
+ Assert(ScanDirectionIsForward(dir) ? so->currPos.moreRight :
+ so->currPos.moreLeft);
+ Assert(!P_IGNORE(opaque));
+ Assert(BTScanPosIsPinned(so->currPos));
+ Assert(!so->needPrimScan);
- /* allow next page be processed by parallel worker */
if (scan->parallel_scan)
{
+ /* allow next/prev page to be read by other worker without delay */
if (ScanDirectionIsForward(dir))
- pstate.prev_scan_page = opaque->btpo_next;
+ _bt_parallel_release(scan, so->currPos.nextPage,
+ so->currPos.currPage);
else
- pstate.prev_scan_page = BufferGetBlockNumber(so->currPos.buf);
-
- _bt_parallel_release(scan, pstate.prev_scan_page);
+ _bt_parallel_release(scan, so->currPos.prevPage,
+ so->currPos.currPage);
}
- indnatts = IndexRelationGetNumberOfAttributes(scan->indexRelation);
+ PredicateLockPage(rel, so->currPos.currPage, scan->xs_snapshot);
+
+ /* initialize local variables */
+ indnatts = IndexRelationGetNumberOfAttributes(rel);
arrayKeys = so->numArrayKeys != 0;
minoff = P_FIRSTDATAKEY(opaque);
maxoff = PageGetMaxOffsetNumber(page);
/* initialize page-level state that we'll pass to _bt_checkkeys */
- pstate.dir = dir;
pstate.minoff = minoff;
pstate.maxoff = maxoff;
pstate.finaltup = NULL;
pstate.page = page;
+ pstate.firstpage = firstpage;
+ pstate.forcenonrequired = false;
+ pstate.startikey = 0;
pstate.offnum = InvalidOffsetNumber;
pstate.skip = InvalidOffsetNumber;
pstate.continuescan = true; /* default assumption */
- pstate.prechecked = false;
- pstate.firstmatch = false;
pstate.rechecks = 0;
pstate.targetdistance = 0;
-
- /*
- * We note the buffer's block number so that we can release the pin later.
- * This allows us to re-read the buffer if it is needed again for hinting.
- */
- so->currPos.currPage = BufferGetBlockNumber(so->currPos.buf);
-
- /*
- * We save the LSN of the page as we read it, so that we know whether it
- * safe to apply LP_DEAD hints to the page later. This allows us to drop
- * the pin for MVCC scans, which allows vacuum to avoid blocking.
- */
- so->currPos.lsn = BufferGetLSNAtomic(so->currPos.buf);
-
- /*
- * we must save the page's right-link while scanning it; this tells us
- * where to step right to after we're done with these items. There is no
- * corresponding need for the left-link, since splits always go right.
- */
- so->currPos.nextPage = opaque->btpo_next;
-
- /* initialize tuple workspace to empty */
- so->currPos.nextTupleOffset = 0;
-
- /*
- * Now that the current page has been made consistent, the macro should be
- * good.
- */
- Assert(BTScanPosIsPinned(so->currPos));
-
- /*
- * Prechecking the value of the continuescan flag for the last item on the
- * page (for backwards scan it will be the first item on a page). If we
- * observe it to be true, then it should be true for all other items. This
- * allows us to do significant optimizations in the _bt_checkkeys()
- * function for all the items on the page.
- *
- * With the forward scan, we do this check for the last item on the page
- * instead of the high key. It's relatively likely that the most
- * significant column in the high key will be different from the
- * corresponding value from the last item on the page. So checking with
- * the last item on the page would give a more precise answer.
- *
- * We skip this for the first page read by each (primitive) scan, to avoid
- * slowing down point queries. They typically don't stand to gain much
- * when the optimization can be applied, and are more likely to notice the
- * overhead of the precheck.
- *
- * The optimization is unsafe and must be avoided whenever _bt_checkkeys
- * just set a low-order required array's key to the best available match
- * for a truncated -inf attribute value from the prior page's high key
- * (array element 0 is always the best available match in this scenario).
- * It's quite likely that matches for array element 0 begin on this page,
- * but the start of matches won't necessarily align with page boundaries.
- * When the start of matches is somewhere in the middle of this page, it
- * would be wrong to treat page's final non-pivot tuple as representative.
- * Doing so might lead us to treat some of the page's earlier tuples as
- * being part of a group of tuples thought to satisfy the required keys.
- *
- * Note: Conversely, in the case where the scan's arrays just advanced
- * using the prior page's HIKEY _without_ advancement setting scanBehind,
- * the start of matches must be aligned with page boundaries, which makes
- * it safe to attempt the optimization here now. It's also safe when the
- * prior page's HIKEY simply didn't need to advance any required array. In
- * both cases we can safely assume that the _first_ tuple from this page
- * must be >= the current set of array keys/equality constraints. And so
- * if the final tuple is == those same keys (and also satisfies any
- * required < or <= strategy scan keys) during the precheck, we can safely
- * assume that this must also be true of all earlier tuples from the page.
- */
- if (!firstPage && !so->scanBehind && minoff < maxoff)
- {
- ItemId iid;
- IndexTuple itup;
-
- iid = PageGetItemId(page, ScanDirectionIsForward(dir) ? maxoff : minoff);
- itup = (IndexTuple) PageGetItem(page, iid);
-
- /* Call with arrayKeys=false to avoid undesirable side-effects */
- _bt_checkkeys(scan, &pstate, false, itup, indnatts);
- pstate.prechecked = pstate.continuescan;
- pstate.continuescan = true; /* reset */
- }
+ pstate.nskipadvances = 0;
if (ScanDirectionIsForward(dir))
{
/* SK_SEARCHARRAY forward scans must provide high key up front */
- if (arrayKeys && !P_RIGHTMOST(opaque))
+ if (arrayKeys)
{
- ItemId iid = PageGetItemId(page, P_HIKEY);
+ if (!P_RIGHTMOST(opaque))
+ {
+ ItemId iid = PageGetItemId(page, P_HIKEY);
+
+ pstate.finaltup = (IndexTuple) PageGetItem(page, iid);
+
+ if (so->scanBehind &&
+ !_bt_scanbehind_checkkeys(scan, dir, pstate.finaltup))
+ {
+ /* Schedule another primitive index scan after all */
+ so->currPos.moreRight = false;
+ so->needPrimScan = true;
+ if (scan->parallel_scan)
+ _bt_parallel_primscan_schedule(scan,
+ so->currPos.currPage);
+ return false;
+ }
+ }
- pstate.finaltup = (IndexTuple) PageGetItem(page, iid);
+ so->scanBehind = so->oppositeDirCheck = false; /* reset */
}
+ /*
+ * Consider pstate.startikey optimization once the ongoing primitive
+ * index scan has already read at least one page
+ */
+ if (!pstate.firstpage && minoff < maxoff)
+ _bt_set_startikey(scan, &pstate);
+
/* load items[] in ascending order */
itemIndex = 0;
@@ -1734,6 +1777,7 @@ _bt_readpage(IndexScanDesc scan, ScanDirection dir, OffsetNumber offnum,
{
Assert(!passes_quals && pstate.continuescan);
Assert(offnum < pstate.skip);
+ Assert(!pstate.forcenonrequired);
offnum = pstate.skip;
pstate.skip = InvalidOffsetNumber;
@@ -1743,7 +1787,6 @@ _bt_readpage(IndexScanDesc scan, ScanDirection dir, OffsetNumber offnum,
if (passes_quals)
{
/* tuple passes all scan key conditions */
- pstate.firstmatch = true;
if (!BTreeTupleIsPosting(itup))
{
/* Remember it */
@@ -1791,14 +1834,19 @@ _bt_readpage(IndexScanDesc scan, ScanDirection dir, OffsetNumber offnum,
* only appear on non-pivot tuples on the right sibling page are
* common.
*/
- if (pstate.continuescan && !P_RIGHTMOST(opaque))
+ if (pstate.continuescan && !so->scanBehind && !P_RIGHTMOST(opaque))
{
ItemId iid = PageGetItemId(page, P_HIKEY);
IndexTuple itup = (IndexTuple) PageGetItem(page, iid);
int truncatt;
- truncatt = BTreeTupleGetNAtts(itup, scan->indexRelation);
- pstate.prechecked = false; /* precheck didn't cover HIKEY */
+ /* Reset arrays, per _bt_set_startikey contract */
+ if (pstate.forcenonrequired)
+ _bt_start_array_keys(scan, dir);
+ pstate.forcenonrequired = false;
+ pstate.startikey = 0; /* _bt_set_startikey ignores P_HIKEY */
+
+ truncatt = BTreeTupleGetNAtts(itup, rel);
_bt_checkkeys(scan, &pstate, arrayKeys, itup, truncatt);
}
@@ -1813,13 +1861,37 @@ _bt_readpage(IndexScanDesc scan, ScanDirection dir, OffsetNumber offnum,
else
{
/* SK_SEARCHARRAY backward scans must provide final tuple up front */
- if (arrayKeys && minoff <= maxoff && !P_LEFTMOST(opaque))
+ if (arrayKeys)
{
- ItemId iid = PageGetItemId(page, minoff);
+ if (minoff <= maxoff && !P_LEFTMOST(opaque))
+ {
+ ItemId iid = PageGetItemId(page, minoff);
+
+ pstate.finaltup = (IndexTuple) PageGetItem(page, iid);
+
+ if (so->scanBehind &&
+ !_bt_scanbehind_checkkeys(scan, dir, pstate.finaltup))
+ {
+ /* Schedule another primitive index scan after all */
+ so->currPos.moreLeft = false;
+ so->needPrimScan = true;
+ if (scan->parallel_scan)
+ _bt_parallel_primscan_schedule(scan,
+ so->currPos.currPage);
+ return false;
+ }
+ }
- pstate.finaltup = (IndexTuple) PageGetItem(page, iid);
+ so->scanBehind = so->oppositeDirCheck = false; /* reset */
}
+ /*
+ * Consider pstate.startikey optimization once the ongoing primitive
+ * index scan has already read at least one page
+ */
+ if (!pstate.firstpage && minoff < maxoff)
+ _bt_set_startikey(scan, &pstate);
+
/* load items[] in descending order */
itemIndex = MaxTIDsPerBTreePage;
@@ -1844,8 +1916,7 @@ _bt_readpage(IndexScanDesc scan, ScanDirection dir, OffsetNumber offnum,
*/
if (scan->ignore_killed_tuples && ItemIdIsDead(iid))
{
- Assert(offnum >= P_FIRSTDATAKEY(opaque));
- if (offnum > P_FIRSTDATAKEY(opaque))
+ if (offnum > minoff)
{
offnum = OffsetNumberPrev(offnum);
continue;
@@ -1860,9 +1931,31 @@ _bt_readpage(IndexScanDesc scan, ScanDirection dir, OffsetNumber offnum,
Assert(!BTreeTupleIsPivot(itup));
pstate.offnum = offnum;
- passes_quals = _bt_checkkeys(scan, &pstate, arrayKeys,
+ if (arrayKeys && offnum == minoff && pstate.forcenonrequired)
+ {
+ /* Reset arrays, per _bt_set_startikey contract */
+ pstate.forcenonrequired = false;
+ pstate.startikey = 0;
+ _bt_start_array_keys(scan, dir);
+ }
+ passes_quals = _bt_checkkeys(scan, &pstate, arrayKeys,
itup, indnatts);
+ if (arrayKeys && so->scanBehind)
+ {
+ /*
+ * Done scanning this page, but not done with the current
+ * primscan.
+ *
+ * Note: Forward scans don't check this explicitly, since they
+ * prefer to reuse pstate.skip for this instead.
+ */
+ Assert(!passes_quals && pstate.continuescan);
+ Assert(!pstate.forcenonrequired);
+
+ break;
+ }
+
/*
* Check if we need to skip ahead to a later tuple (only possible
* when the scan uses array keys)
@@ -1871,6 +1964,7 @@ _bt_readpage(IndexScanDesc scan, ScanDirection dir, OffsetNumber offnum,
{
Assert(!passes_quals && pstate.continuescan);
Assert(offnum > pstate.skip);
+ Assert(!pstate.forcenonrequired);
offnum = pstate.skip;
pstate.skip = InvalidOffsetNumber;
@@ -1880,7 +1974,6 @@ _bt_readpage(IndexScanDesc scan, ScanDirection dir, OffsetNumber offnum,
if (passes_quals && tuple_alive)
{
/* tuple passes all scan key conditions */
- pstate.firstmatch = true;
if (!BTreeTupleIsPosting(itup))
{
/* Remember it */
@@ -1916,22 +2009,40 @@ _bt_readpage(IndexScanDesc scan, ScanDirection dir, OffsetNumber offnum,
}
}
}
+ /* When !continuescan, there can't be any more matches, so stop */
if (!pstate.continuescan)
- {
- /* there can't be any more matches, so stop */
- so->currPos.moreLeft = false;
break;
- }
offnum = OffsetNumberPrev(offnum);
}
+ /*
+ * We don't need to visit page to the left when no more matches will
+ * be found there
+ */
+ if (!pstate.continuescan)
+ so->currPos.moreLeft = false;
+
Assert(itemIndex >= 0);
so->currPos.firstItem = itemIndex;
so->currPos.lastItem = MaxTIDsPerBTreePage - 1;
so->currPos.itemIndex = MaxTIDsPerBTreePage - 1;
}
+ /*
+ * If _bt_set_startikey told us to temporarily treat the scan's keys as
+ * nonrequired (possible only during scans with array keys), there must be
+ * no lasting consequences for the scan's array keys. The scan's arrays
+ * should now have exactly the same elements as they would have had if the
+ * nonrequired behavior had never been used. (In general, a scan's arrays
+ * are expected to track its progress through the index's key space.)
+ *
+ * We are required (by _bt_set_startikey) to call _bt_checkkeys against
+ * pstate.finaltup with pstate.forcenonrequired=false to allow the scan's
+ * arrays to recover. Assert that that step hasn't been missed.
+ */
+ Assert(!pstate.forcenonrequired);
+
return (so->currPos.firstItem <= so->currPos.lastItem);
}
@@ -2021,23 +2132,41 @@ _bt_savepostingitem(BTScanOpaque so, int itemIndex, OffsetNumber offnum,
currItem->tupleOffset = tupleOffset;
}
+/*
+ * Return the index item from so->currPos.items[so->currPos.itemIndex] to the
+ * index scan by setting the relevant fields in caller's index scan descriptor
+ */
+static inline void
+_bt_returnitem(IndexScanDesc scan, BTScanOpaque so)
+{
+ BTScanPosItem *currItem = &so->currPos.items[so->currPos.itemIndex];
+
+ /* Most recent _bt_readpage must have succeeded */
+ Assert(BTScanPosIsValid(so->currPos));
+ Assert(so->currPos.itemIndex >= so->currPos.firstItem);
+ Assert(so->currPos.itemIndex <= so->currPos.lastItem);
+
+ /* Return next item, per amgettuple contract */
+ scan->xs_heaptid = currItem->heapTid;
+ if (so->currTuples)
+ scan->xs_itup = (IndexTuple) (so->currTuples + currItem->tupleOffset);
+}
+
/*
* _bt_steppage() -- Step to next page containing valid data for scan
*
- * On entry, if so->currPos.buf is valid the buffer is pinned but not locked;
- * if pinned, we'll drop the pin before moving to next page. The buffer is
- * not locked on entry.
+ * Wrapper on _bt_readnextpage that performs final steps for the current page.
*
- * For success on a scan using a non-MVCC snapshot we hold a pin, but not a
- * read lock, on that page. If we do not hold the pin, we set so->currPos.buf
- * to InvalidBuffer. We return true to indicate success.
+ * On entry, so->currPos must be valid. Its buffer will be pinned, though
+ * never locked. (Actually, when so->dropPin there won't even be a pin held,
+ * though so->currPos.currPage must still be set to a valid block number.)
*/
static bool
_bt_steppage(IndexScanDesc scan, ScanDirection dir)
{
BTScanOpaque so = (BTScanOpaque) scan->opaque;
- BlockNumber blkno = InvalidBlockNumber;
- bool status;
+ BlockNumber blkno,
+ lastcurrblkno;
Assert(BTScanPosIsValid(so->currPos));
@@ -2075,322 +2204,310 @@ _bt_steppage(IndexScanDesc scan, ScanDirection dir)
* markPos state. But depending on the current array state like this
* would add complexity. Instead, we just unset markPos's copy of
* moreRight or moreLeft (whichever might be affected), while making
- * btrestpos reset the scan's arrays to their initial scan positions.
- * In effect, btrestpos leaves advancing the arrays up to the first
+ * btrestrpos reset the scan's arrays to their initial scan positions.
+ * In effect, btrestrpos leaves advancing the arrays up to the first
* _bt_readpage call (that takes place after it has restored markPos).
*/
- Assert(so->markPos.dir == dir);
if (so->needPrimScan)
{
- if (ScanDirectionIsForward(dir))
+ if (ScanDirectionIsForward(so->currPos.dir))
so->markPos.moreRight = true;
else
so->markPos.moreLeft = true;
}
+
+ /* mark/restore not supported by parallel scans */
+ Assert(!scan->parallel_scan);
}
+ BTScanPosUnpinIfPinned(so->currPos);
+
+ /* Walk to the next page with data */
if (ScanDirectionIsForward(dir))
+ blkno = so->currPos.nextPage;
+ else
+ blkno = so->currPos.prevPage;
+ lastcurrblkno = so->currPos.currPage;
+
+ /*
+ * Cancel primitive index scans that were scheduled when the call to
+ * _bt_readpage for currPos happened to use the opposite direction to the
+ * one that we're stepping in now. (It's okay to leave the scan's array
+ * keys as-is, since the next _bt_readpage will advance them.)
+ */
+ if (so->currPos.dir != dir)
+ so->needPrimScan = false;
+
+ return _bt_readnextpage(scan, blkno, lastcurrblkno, dir, false);
+}
+
+/*
+ * _bt_readfirstpage() -- Read first page containing valid data for _bt_first
+ *
+ * _bt_first caller passes us an offnum returned by _bt_binsrch, which might
+ * be an out of bounds offnum such as "maxoff + 1" in certain corner cases.
+ * _bt_checkkeys will stop the scan as soon as an equality qual fails (when
+ * its scan key was marked required), so _bt_first _must_ pass us an offnum
+ * exactly at the beginning of where equal tuples are to be found. When we're
+ * passed an offnum past the end of the page, we might still manage to stop
+ * the scan on this page by calling _bt_checkkeys against the high key. See
+ * _bt_readpage for full details.
+ *
+ * On entry, so->currPos must be pinned and locked (so offnum stays valid).
+ * Parallel scan callers must have seized the scan before calling here.
+ *
+ * On exit, we'll have updated so->currPos and retained locks and pins
+ * according to the same rules as those laid out for _bt_readnextpage exit.
+ * Like _bt_readnextpage, our return value indicates if there are any matching
+ * records in the given direction.
+ *
+ * We always release the scan for a parallel scan caller, regardless of
+ * success or failure; we'll call _bt_parallel_release as soon as possible.
+ */
+static bool
+_bt_readfirstpage(IndexScanDesc scan, OffsetNumber offnum, ScanDirection dir)
+{
+ BTScanOpaque so = (BTScanOpaque) scan->opaque;
+
+ so->numKilled = 0; /* just paranoia */
+ so->markItemIndex = -1; /* ditto */
+
+ /* Initialize so->currPos for the first page (page in so->currPos.buf) */
+ if (so->needPrimScan)
{
- /* Walk right to the next page with data */
- if (scan->parallel_scan != NULL)
- {
- /*
- * Seize the scan to get the next block number; if the scan has
- * ended already, bail out.
- */
- status = _bt_parallel_seize(scan, &blkno, false);
- if (!status)
- {
- /* release the previous buffer, if pinned */
- BTScanPosUnpinIfPinned(so->currPos);
- BTScanPosInvalidate(so->currPos);
- return false;
- }
- }
- else
- {
- /* Not parallel, so use the previously-saved nextPage link. */
- blkno = so->currPos.nextPage;
- }
+ Assert(so->numArrayKeys);
- /* Remember we left a page with data */
so->currPos.moreLeft = true;
-
- /* release the previous buffer, if pinned */
- BTScanPosUnpinIfPinned(so->currPos);
+ so->currPos.moreRight = true;
+ so->needPrimScan = false;
}
- else
+ else if (ScanDirectionIsForward(dir))
{
- /* Remember we left a page with data */
+ so->currPos.moreLeft = false;
so->currPos.moreRight = true;
+ }
+ else
+ {
+ so->currPos.moreLeft = true;
+ so->currPos.moreRight = false;
+ }
- if (scan->parallel_scan != NULL)
- {
- /*
- * Seize the scan to get the current block number; if the scan has
- * ended already, bail out.
- */
- status = _bt_parallel_seize(scan, &blkno, false);
- BTScanPosUnpinIfPinned(so->currPos);
- if (!status)
- {
- BTScanPosInvalidate(so->currPos);
- return false;
- }
- }
- else
- {
- /* Not parallel, so just use our own notion of the current page */
- blkno = so->currPos.currPage;
- }
+ /*
+ * Attempt to load matching tuples from the first page.
+ *
+ * Note that _bt_readpage will finish initializing the so->currPos fields.
+ * _bt_readpage also releases parallel scan (even when it returns false).
+ */
+ if (_bt_readpage(scan, dir, offnum, true))
+ {
+ Relation rel = scan->indexRelation;
+
+ /*
+ * _bt_readpage succeeded. Drop the lock (and maybe the pin) on
+ * so->currPos.buf in preparation for btgettuple returning tuples.
+ */
+ Assert(BTScanPosIsPinned(so->currPos));
+ _bt_drop_lock_and_maybe_pin(rel, so);
+ return true;
}
- if (!_bt_readnextpage(scan, blkno, dir))
- return false;
+ /* There's no actually-matching data on the page in so->currPos.buf */
+ _bt_unlockbuf(scan->indexRelation, so->currPos.buf);
- /* We have at least one item to return as scan's next item */
- _bt_drop_lock_and_maybe_pin(scan, &so->currPos);
+ /* Call _bt_readnextpage using its _bt_steppage wrapper function */
+ if (!_bt_steppage(scan, dir))
+ return false;
+ /* _bt_readpage for a later page (now in so->currPos) succeeded */
return true;
}
/*
- * _bt_readnextpage() -- Read next page containing valid data for scan
+ * _bt_readnextpage() -- Read next page containing valid data for _bt_next
+ *
+ * Caller's blkno is the next interesting page's link, taken from either the
+ * previously-saved right link or left link. lastcurrblkno is the page that
+ * was current at the point where the blkno link was saved, which we use to
+ * reason about concurrent page splits/page deletions during backwards scans.
+ * In the common case where seized=false, blkno is either so->currPos.nextPage
+ * or so->currPos.prevPage, and lastcurrblkno is so->currPos.currPage.
+ *
+ * On entry, so->currPos shouldn't be locked by caller. so->currPos.buf must
+ * be InvalidBuffer/unpinned as needed by caller (note that lastcurrblkno
+ * won't need to be read again in almost all cases). Parallel scan callers
+ * that seized the scan before calling here should pass seized=true; such a
+ * caller's blkno and lastcurrblkno arguments come from the seized scan.
+ * seized=false callers just pass us the blkno/lastcurrblkno taken from their
+ * so->currPos, which (along with so->currPos itself) can be used to end the
+ * scan. A seized=false caller's blkno can never be assumed to be the page
+ * that must be read next during a parallel scan, though. We must figure that
+ * part out for ourselves by seizing the scan (the correct page to read might
+ * already be beyond the seized=false caller's blkno during a parallel scan,
+ * unless blkno/so->currPos.nextPage/so->currPos.prevPage is already P_NONE,
+ * or unless so->currPos.moreRight/so->currPos.moreLeft is already unset).
*
* On success exit, so->currPos is updated to contain data from the next
- * interesting page, and we return true. Caller must release the lock (and
- * maybe the pin) on the buffer on success exit.
+ * interesting page, and we return true. We hold a pin on the buffer on
+ * success exit (except during so->dropPin index scans, when we drop the pin
+ * eagerly to avoid blocking VACUUM).
*
- * If there are no more matching records in the given direction, we drop all
- * locks and pins, set so->currPos.buf to InvalidBuffer, and return false.
+ * If there are no more matching records in the given direction, we invalidate
+ * so->currPos (while ensuring it retains no locks or pins), and return false.
+ *
+ * We always release the scan for a parallel scan caller, regardless of
+ * success or failure; we'll call _bt_parallel_release as soon as possible.
*/
static bool
-_bt_readnextpage(IndexScanDesc scan, BlockNumber blkno, ScanDirection dir)
+_bt_readnextpage(IndexScanDesc scan, BlockNumber blkno,
+ BlockNumber lastcurrblkno, ScanDirection dir, bool seized)
{
+ Relation rel = scan->indexRelation;
BTScanOpaque so = (BTScanOpaque) scan->opaque;
- Relation rel;
- Page page;
- BTPageOpaque opaque;
- bool status;
- rel = scan->indexRelation;
+ Assert(so->currPos.currPage == lastcurrblkno || seized);
+ Assert(!(blkno == P_NONE && seized));
+ Assert(!BTScanPosIsPinned(so->currPos));
+ /*
+ * Remember that the scan already read lastcurrblkno, a page to the left
+ * of blkno (or remember reading a page to the right, for backwards scans)
+ */
if (ScanDirectionIsForward(dir))
- {
- for (;;)
- {
- /*
- * if we're at end of scan, give up and mark parallel scan as
- * done, so that all the workers can finish their scan
- */
- if (blkno == P_NONE || !so->currPos.moreRight)
- {
- _bt_parallel_done(scan);
- BTScanPosInvalidate(so->currPos);
- return false;
- }
- /* check for interrupts while we're not holding any buffer lock */
- CHECK_FOR_INTERRUPTS();
- /* step right one page */
- so->currPos.buf = _bt_getbuf(rel, blkno, BT_READ);
- page = BufferGetPage(so->currPos.buf);
- opaque = BTPageGetOpaque(page);
- /* check for deleted page */
- if (!P_IGNORE(opaque))
- {
- PredicateLockPage(rel, blkno, scan->xs_snapshot);
- /* see if there are any matches on this page */
- /* note that this will clear moreRight if we can stop */
- if (_bt_readpage(scan, dir, P_FIRSTDATAKEY(opaque), false))
- break;
- }
- else if (scan->parallel_scan != NULL)
- {
- /* allow next page be processed by parallel worker */
- _bt_parallel_release(scan, opaque->btpo_next);
- }
-
- /* nope, keep going */
- if (scan->parallel_scan != NULL)
- {
- _bt_relbuf(rel, so->currPos.buf);
- status = _bt_parallel_seize(scan, &blkno, false);
- if (!status)
- {
- BTScanPosInvalidate(so->currPos);
- return false;
- }
- }
- else
- {
- blkno = opaque->btpo_next;
- _bt_relbuf(rel, so->currPos.buf);
- }
- }
- }
+ so->currPos.moreLeft = true;
else
+ so->currPos.moreRight = true;
+
+ for (;;)
{
- /*
- * Should only happen in parallel cases, when some other backend
- * advanced the scan.
- */
- if (so->currPos.currPage != blkno)
+ Page page;
+ BTPageOpaque opaque;
+
+ if (blkno == P_NONE ||
+ (ScanDirectionIsForward(dir) ?
+ !so->currPos.moreRight : !so->currPos.moreLeft))
{
- BTScanPosUnpinIfPinned(so->currPos);
- so->currPos.currPage = blkno;
+ /* most recent _bt_readpage call (for lastcurrblkno) ended scan */
+ Assert(so->currPos.currPage == lastcurrblkno && !seized);
+ BTScanPosInvalidate(so->currPos);
+ _bt_parallel_done(scan); /* iff !so->needPrimScan */
+ return false;
}
- /*
- * Walk left to the next page with data. This is much more complex
- * than the walk-right case because of the possibility that the page
- * to our left splits while we are in flight to it, plus the
- * possibility that the page we were on gets deleted after we leave
- * it. See nbtree/README for details.
- *
- * It might be possible to rearrange this code to have less overhead
- * in pinning and locking, but that would require capturing the left
- * sibling block number when the page is initially read, and then
- * optimistically starting there (rather than pinning the page twice).
- * It is not clear that this would be worth the complexity.
- */
- if (BTScanPosIsPinned(so->currPos))
- _bt_lockbuf(rel, so->currPos.buf, BT_READ);
- else
- so->currPos.buf = _bt_getbuf(rel, so->currPos.currPage, BT_READ);
+ Assert(!so->needPrimScan);
- for (;;)
+ /* parallel scan must never actually visit so->currPos blkno */
+ if (!seized && scan->parallel_scan != NULL &&
+ !_bt_parallel_seize(scan, &blkno, &lastcurrblkno, false))
{
- /* Done if we know there are no matching keys to the left */
- if (!so->currPos.moreLeft)
- {
- _bt_relbuf(rel, so->currPos.buf);
- _bt_parallel_done(scan);
- BTScanPosInvalidate(so->currPos);
- return false;
- }
-
- /* Step to next physical page */
- so->currPos.buf = _bt_walk_left(rel, so->currPos.buf);
+ /* whole scan is now done (or another primitive scan required) */
+ BTScanPosInvalidate(so->currPos);
+ return false;
+ }
- /* if we're physically at end of index, return failure */
+ if (ScanDirectionIsForward(dir))
+ {
+ /* read blkno, but check for interrupts first */
+ CHECK_FOR_INTERRUPTS();
+ so->currPos.buf = _bt_getbuf(rel, blkno, BT_READ);
+ }
+ else
+ {
+ /* read blkno, avoiding race (also checks for interrupts) */
+ so->currPos.buf = _bt_lock_and_validate_left(rel, &blkno,
+ lastcurrblkno);
if (so->currPos.buf == InvalidBuffer)
{
- _bt_parallel_done(scan);
+ /* must have been a concurrent deletion of leftmost page */
BTScanPosInvalidate(so->currPos);
+ _bt_parallel_done(scan);
return false;
}
+ }
- /*
- * Okay, we managed to move left to a non-deleted page. Done if
- * it's not half-dead and contains matching tuples. Else loop back
- * and do it all again.
- */
- page = BufferGetPage(so->currPos.buf);
- opaque = BTPageGetOpaque(page);
- if (!P_IGNORE(opaque))
+ page = BufferGetPage(so->currPos.buf);
+ opaque = BTPageGetOpaque(page);
+ lastcurrblkno = blkno;
+ if (likely(!P_IGNORE(opaque)))
+ {
+ /* see if there are any matches on this page */
+ if (ScanDirectionIsForward(dir))
{
- PredicateLockPage(rel, BufferGetBlockNumber(so->currPos.buf), scan->xs_snapshot);
- /* see if there are any matches on this page */
- /* note that this will clear moreLeft if we can stop */
- if (_bt_readpage(scan, dir, PageGetMaxOffsetNumber(page), false))
+ /* note that this will clear moreRight if we can stop */
+ if (_bt_readpage(scan, dir, P_FIRSTDATAKEY(opaque), seized))
break;
+ blkno = so->currPos.nextPage;
}
- else if (scan->parallel_scan != NULL)
+ else
{
- /* allow next page be processed by parallel worker */
- _bt_parallel_release(scan, BufferGetBlockNumber(so->currPos.buf));
+ /* note that this will clear moreLeft if we can stop */
+ if (_bt_readpage(scan, dir, PageGetMaxOffsetNumber(page), seized))
+ break;
+ blkno = so->currPos.prevPage;
}
-
- /*
- * For parallel scans, get the last page scanned as it is quite
- * possible that by the time we try to seize the scan, some other
- * worker has already advanced the scan to a different page. We
- * must continue based on the latest page scanned by any worker.
- */
+ }
+ else
+ {
+ /* _bt_readpage not called, so do all this for ourselves */
+ if (ScanDirectionIsForward(dir))
+ blkno = opaque->btpo_next;
+ else
+ blkno = opaque->btpo_prev;
if (scan->parallel_scan != NULL)
- {
- _bt_relbuf(rel, so->currPos.buf);
- status = _bt_parallel_seize(scan, &blkno, false);
- if (!status)
- {
- BTScanPosInvalidate(so->currPos);
- return false;
- }
- so->currPos.buf = _bt_getbuf(rel, blkno, BT_READ);
- }
+ _bt_parallel_release(scan, blkno, lastcurrblkno);
}
- }
-
- return true;
-}
-/*
- * _bt_parallel_readpage() -- Read current page containing valid data for scan
- *
- * On success, release lock and maybe pin on buffer. We return true to
- * indicate success.
- */
-static bool
-_bt_parallel_readpage(IndexScanDesc scan, BlockNumber blkno, ScanDirection dir)
-{
- BTScanOpaque so = (BTScanOpaque) scan->opaque;
-
- Assert(!so->needPrimScan);
-
- _bt_initialize_more_data(so, dir);
-
- if (!_bt_readnextpage(scan, blkno, dir))
- return false;
+ /* no matching tuples on this page */
+ _bt_relbuf(rel, so->currPos.buf);
+ seized = false; /* released by _bt_readpage (or by us) */
+ }
- /* We have at least one item to return as scan's next item */
- _bt_drop_lock_and_maybe_pin(scan, &so->currPos);
+ /*
+ * _bt_readpage succeeded. Drop the lock (and maybe the pin) on
+ * so->currPos.buf in preparation for btgettuple returning tuples.
+ */
+ Assert(so->currPos.currPage == blkno);
+ Assert(BTScanPosIsPinned(so->currPos));
+ _bt_drop_lock_and_maybe_pin(rel, so);
return true;
}
/*
- * _bt_walk_left() -- step left one page, if possible
+ * _bt_lock_and_validate_left() -- lock caller's left sibling blkno,
+ * recovering from concurrent page splits/page deletions when necessary
*
- * The given buffer must be pinned and read-locked. This will be dropped
- * before stepping left. On return, we have pin and read lock on the
- * returned page, instead.
+ * Called during backwards scans, to deal with their unique concurrency rules.
*
- * Returns InvalidBuffer if there is no page to the left (no lock is held
- * in that case).
+ * blkno points to the block number of the page that we expect to move the
+ * scan to. We'll successfully move the scan there when we find that its
+ * right sibling link still points to lastcurrblkno (the page we just read).
+ * Otherwise, we have to figure out which page is the correct one for the scan
+ * to now read the hard way, reasoning about concurrent splits and deletions.
+ * See nbtree/README.
+ *
+ * On return, we have both a pin and a read lock on the returned page, whose
+ * block number will be set in *blkno. Returns InvalidBuffer if there is no
+ * page to the left (no lock or pin is held in that case).
*
* It is possible for the returned leaf page to be half-dead; caller must
* check that condition and step left again when required.
*/
static Buffer
-_bt_walk_left(Relation rel, Buffer buf)
+_bt_lock_and_validate_left(Relation rel, BlockNumber *blkno,
+ BlockNumber lastcurrblkno)
{
- Page page;
- BTPageOpaque opaque;
-
- page = BufferGetPage(buf);
- opaque = BTPageGetOpaque(page);
+ BlockNumber origblkno = *blkno; /* detects circular links */
for (;;)
{
- BlockNumber obknum;
- BlockNumber lblkno;
- BlockNumber blkno;
+ Buffer buf;
+ Page page;
+ BTPageOpaque opaque;
int tries;
- /* if we're at end of tree, release buf and return failure */
- if (P_LEFTMOST(opaque))
- {
- _bt_relbuf(rel, buf);
- break;
- }
- /* remember original page we are stepping left from */
- obknum = BufferGetBlockNumber(buf);
- /* step left */
- blkno = lblkno = opaque->btpo_prev;
- _bt_relbuf(rel, buf);
/* check for interrupts while we're not holding any buffer lock */
CHECK_FOR_INTERRUPTS();
- buf = _bt_getbuf(rel, blkno, BT_READ);
+ buf = _bt_getbuf(rel, *blkno, BT_READ);
page = BufferGetPage(buf);
opaque = BTPageGetOpaque(page);
@@ -2398,7 +2515,7 @@ _bt_walk_left(Relation rel, Buffer buf)
* If this isn't the page we want, walk right till we find what we
* want --- but go no more than four hops (an arbitrary limit). If we
* don't find the correct page by then, the most likely bet is that
- * the original page got deleted and isn't in the sibling chain at all
+ * lastcurrblkno got deleted and isn't in the sibling chain at all
* anymore, not that its left sibling got split more than four times.
*
* Note that it is correct to test P_ISDELETED not P_IGNORE here,
@@ -2407,21 +2524,27 @@ _bt_walk_left(Relation rel, Buffer buf)
tries = 0;
for (;;)
{
- if (!P_ISDELETED(opaque) && opaque->btpo_next == obknum)
+ if (likely(!P_ISDELETED(opaque) &&
+ opaque->btpo_next == lastcurrblkno))
{
/* Found desired page, return it */
return buf;
}
if (P_RIGHTMOST(opaque) || ++tries > 4)
break;
- blkno = opaque->btpo_next;
- buf = _bt_relandgetbuf(rel, buf, blkno, BT_READ);
+ /* step right */
+ *blkno = opaque->btpo_next;
+ buf = _bt_relandgetbuf(rel, buf, *blkno, BT_READ);
page = BufferGetPage(buf);
opaque = BTPageGetOpaque(page);
}
- /* Return to the original page to see what's up */
- buf = _bt_relandgetbuf(rel, buf, obknum, BT_READ);
+ /*
+ * Return to the original page (usually the page most recently read by
+ * _bt_readpage, which is passed by caller as lastcurrblkno) to see
+ * what's up with its prev sibling link
+ */
+ buf = _bt_relandgetbuf(rel, buf, lastcurrblkno, BT_READ);
page = BufferGetPage(buf);
opaque = BTPageGetOpaque(page);
if (P_ISDELETED(opaque))
@@ -2437,31 +2560,42 @@ _bt_walk_left(Relation rel, Buffer buf)
if (P_RIGHTMOST(opaque))
elog(ERROR, "fell off the end of index \"%s\"",
RelationGetRelationName(rel));
- blkno = opaque->btpo_next;
- buf = _bt_relandgetbuf(rel, buf, blkno, BT_READ);
+ lastcurrblkno = opaque->btpo_next;
+ buf = _bt_relandgetbuf(rel, buf, lastcurrblkno, BT_READ);
page = BufferGetPage(buf);
opaque = BTPageGetOpaque(page);
if (!P_ISDELETED(opaque))
break;
}
-
- /*
- * Now return to top of loop, resetting obknum to point to this
- * nondeleted page, and try again.
- */
}
else
{
/*
- * It wasn't deleted; the explanation had better be that the page
- * to the left got split or deleted. Without this check, we'd go
- * into an infinite loop if there's anything wrong.
+ * Original lastcurrblkno wasn't deleted; the explanation had
+ * better be that the page to the left got split or deleted.
+ * Without this check, we risk going into an infinite loop.
*/
- if (opaque->btpo_prev == lblkno)
+ if (opaque->btpo_prev == origblkno)
elog(ERROR, "could not find left sibling of block %u in index \"%s\"",
- obknum, RelationGetRelationName(rel));
- /* Okay to try again with new lblkno value */
+ lastcurrblkno, RelationGetRelationName(rel));
+ /* Okay to try again, since left sibling link changed */
}
+
+ /*
+ * Original lastcurrblkno from caller was concurrently deleted (could
+ * also have been a great many concurrent left sibling page splits).
+ * Found a non-deleted page that should now act as our lastcurrblkno.
+ */
+ if (P_LEFTMOST(opaque))
+ {
+ /* New lastcurrblkno has no left sibling (concurrently deleted) */
+ _bt_relbuf(rel, buf);
+ break;
+ }
+
+ /* Start from scratch with new lastcurrblkno's blkno/prev link */
+ *blkno = origblkno = opaque->btpo_prev;
+ _bt_relbuf(rel, buf);
}
return InvalidBuffer;
@@ -2553,40 +2687,41 @@ _bt_get_endpoint(Relation rel, uint32 level, bool rightmost)
*
* This is used by _bt_first() to set up a scan when we've determined
* that the scan must start at the beginning or end of the index (for
- * a forward or backward scan respectively). Exit conditions are the
- * same as for _bt_first().
+ * a forward or backward scan respectively).
+ *
+ * Parallel scan callers must have seized the scan before calling here.
+ * Exit conditions are the same as for _bt_first().
*/
static bool
_bt_endpoint(IndexScanDesc scan, ScanDirection dir)
{
Relation rel = scan->indexRelation;
BTScanOpaque so = (BTScanOpaque) scan->opaque;
- Buffer buf;
Page page;
BTPageOpaque opaque;
OffsetNumber start;
- BTScanPosItem *currItem;
+
+ Assert(!BTScanPosIsValid(so->currPos));
+ Assert(!so->needPrimScan);
/*
* Scan down to the leftmost or rightmost leaf page. This is a simplified
- * version of _bt_search(). We don't maintain a stack since we know we
- * won't need it.
+ * version of _bt_search().
*/
- buf = _bt_get_endpoint(rel, 0, ScanDirectionIsBackward(dir));
+ so->currPos.buf = _bt_get_endpoint(rel, 0, ScanDirectionIsBackward(dir));
- if (!BufferIsValid(buf))
+ if (!BufferIsValid(so->currPos.buf))
{
/*
* Empty index. Lock the whole relation, as nothing finer to lock
* exists.
*/
PredicateLockRelation(rel, scan->xs_snapshot);
- BTScanPosInvalidate(so->currPos);
+ _bt_parallel_done(scan);
return false;
}
- PredicateLockPage(rel, BufferGetBlockNumber(buf), scan->xs_snapshot);
- page = BufferGetPage(buf);
+ page = BufferGetPage(so->currPos.buf);
opaque = BTPageGetOpaque(page);
Assert(P_ISLEAF(opaque));
@@ -2609,65 +2744,12 @@ _bt_endpoint(IndexScanDesc scan, ScanDirection dir)
start = 0; /* keep compiler quiet */
}
- /* remember which buffer we have pinned */
- so->currPos.buf = buf;
-
- _bt_initialize_more_data(so, dir);
-
/*
* Now load data from the first page of the scan.
*/
- if (!_bt_readpage(scan, dir, start, true))
- {
- /*
- * There's no actually-matching data on this page. Try to advance to
- * the next page. Return false if there's no matching data at all.
- */
- _bt_unlockbuf(scan->indexRelation, so->currPos.buf);
- if (!_bt_steppage(scan, dir))
- return false;
- }
- else
- {
- /* We have at least one item to return as scan's first item */
- _bt_drop_lock_and_maybe_pin(scan, &so->currPos);
- }
-
- /* OK, itemIndex says what to return */
- currItem = &so->currPos.items[so->currPos.itemIndex];
- scan->xs_heaptid = currItem->heapTid;
- if (scan->xs_want_itup)
- scan->xs_itup = (IndexTuple) (so->currTuples + currItem->tupleOffset);
+ if (!_bt_readfirstpage(scan, start, dir))
+ return false;
+ _bt_returnitem(scan, so);
return true;
}
-
-/*
- * _bt_initialize_more_data() -- initialize moreLeft, moreRight and scan dir
- * from currPos
- */
-static inline void
-_bt_initialize_more_data(BTScanOpaque so, ScanDirection dir)
-{
- so->currPos.dir = dir;
- if (so->needPrimScan)
- {
- Assert(so->numArrayKeys);
-
- so->currPos.moreLeft = true;
- so->currPos.moreRight = true;
- so->needPrimScan = false;
- }
- else if (ScanDirectionIsForward(dir))
- {
- so->currPos.moreLeft = false;
- so->currPos.moreRight = true;
- }
- else
- {
- so->currPos.moreLeft = true;
- so->currPos.moreRight = false;
- }
- so->numKilled = 0; /* just paranoia */
- so->markItemIndex = -1; /* ditto */
-}
diff --git a/src/backend/access/nbtree/nbtsort.c b/src/backend/access/nbtree/nbtsort.c
index f5d7b3b0c3014..8828a7a8f8952 100644
--- a/src/backend/access/nbtree/nbtsort.c
+++ b/src/backend/access/nbtree/nbtsort.c
@@ -29,7 +29,7 @@
* This code isn't concerned about the FSM at all. The caller is responsible
* for initializing that.
*
- * Portions Copyright (c) 1996-2024, PostgreSQL Global Development Group
+ * Portions Copyright (c) 1996-2025, PostgreSQL Global Development Group
* Portions Copyright (c) 1994, Regents of the University of California
*
* IDENTIFICATION
@@ -44,15 +44,15 @@
#include "access/parallel.h"
#include "access/relscan.h"
#include "access/table.h"
+#include "access/tableam.h"
#include "access/xact.h"
-#include "access/xloginsert.h"
#include "catalog/index.h"
#include "commands/progress.h"
#include "executor/instrument.h"
#include "miscadmin.h"
#include "pgstat.h"
#include "storage/bulk_write.h"
-#include "tcop/tcopprot.h" /* pgrminclude ignore */
+#include "tcop/tcopprot.h"
#include "utils/rel.h"
#include "utils/sortsupport.h"
#include "utils/tuplesort.h"
@@ -105,6 +105,9 @@ typedef struct BTShared
bool isconcurrent;
int scantuplesortstates;
+ /* Query ID, for report in worker processes */
+ int64 queryid;
+
/*
* workersdonecv is used to monitor the progress of workers. All parallel
* participants must indicate that they are done before leader can use
@@ -473,7 +476,7 @@ _bt_spools_heapscan(Relation heap, Relation index, BTBuildState *buildstate,
/* Fill spool using either serial or parallel heap scan */
if (!buildstate->btleader)
reltuples = table_index_build_scan(heap, index, indexInfo, true, true,
- _bt_build_callback, (void *) buildstate,
+ _bt_build_callback, buildstate,
NULL);
else
reltuples = _bt_parallel_heapscan(buildstate,
@@ -827,7 +830,7 @@ _bt_buildadd(BTWriteState *wstate, BTPageState *state, IndexTuple itup,
* make use of the reserved space. This should never fail on internal
* pages.
*/
- if (unlikely(itupsz > BTMaxItemSize(npage)))
+ if (unlikely(itupsz > BTMaxItemSize))
_bt_check_third_page(wstate->index, wstate->heap, isleaf, npage,
itup);
@@ -1169,7 +1172,7 @@ _bt_load(BTWriteState *wstate, BTSpool *btspool, BTSpool *btspool2)
{
SortSupport sortKey = sortKeys + i;
ScanKey scanKey = wstate->inskey->scankeys + i;
- int16 strategy;
+ bool reverse;
sortKey->ssup_cxt = CurrentMemoryContext;
sortKey->ssup_collation = scanKey->sk_collation;
@@ -1181,10 +1184,9 @@ _bt_load(BTWriteState *wstate, BTSpool *btspool, BTSpool *btspool2)
Assert(sortKey->ssup_attno != 0);
- strategy = (scanKey->sk_flags & SK_BT_DESC) != 0 ?
- BTGreaterStrategyNumber : BTLessStrategyNumber;
+ reverse = (scanKey->sk_flags & SK_BT_DESC) != 0;
- PrepareSortSupportFromIndexRel(wstate->index, strategy, sortKey);
+ PrepareSortSupportFromIndexRel(wstate->index, reverse, sortKey);
}
for (;;)
@@ -1303,7 +1305,7 @@ _bt_load(BTWriteState *wstate, BTSpool *btspool, BTSpool *btspool2)
*/
dstate->maxpostingsize = MAXALIGN_DOWN((BLCKSZ * 10 / 100)) -
sizeof(ItemIdData);
- Assert(dstate->maxpostingsize <= BTMaxItemSize((Page) state->btps_buf) &&
+ Assert(dstate->maxpostingsize <= BTMaxItemSize &&
dstate->maxpostingsize <= INDEX_SIZE_MASK);
dstate->htids = palloc(dstate->maxpostingsize);
@@ -1505,6 +1507,7 @@ _bt_begin_parallel(BTBuildState *buildstate, bool isconcurrent, int request)
btshared->nulls_not_distinct = btspool->nulls_not_distinct;
btshared->isconcurrent = isconcurrent;
btshared->scantuplesortstates = scantuplesortstates;
+ btshared->queryid = pgstat_get_my_query_id();
ConditionVariableInit(&btshared->workersdonecv);
SpinLockInit(&btshared->mutex);
/* Initialize mutable state */
@@ -1787,6 +1790,9 @@ _bt_parallel_build_main(dsm_segment *seg, shm_toc *toc)
indexLockmode = RowExclusiveLock;
}
+ /* Track query ID */
+ pgstat_report_query_id(btshared->queryid, false);
+
/* Open relations within worker */
heapRel = table_open(btshared->heaprelid, heapLockmode);
indexRel = index_open(btshared->indexrelid, indexLockmode);
@@ -1924,7 +1930,7 @@ _bt_parallel_scan_and_sort(BTSpool *btspool, BTSpool *btspool2,
ParallelTableScanFromBTShared(btshared));
reltuples = table_index_build_scan(btspool->heap, btspool->index, indexInfo,
true, progress, _bt_build_callback,
- (void *) &buildstate, scan);
+ &buildstate, scan);
/* Execute this worker's part of the sort */
if (progress)
diff --git a/src/backend/access/nbtree/nbtsplitloc.c b/src/backend/access/nbtree/nbtsplitloc.c
index 1f40d40263e93..b88c396195a42 100644
--- a/src/backend/access/nbtree/nbtsplitloc.c
+++ b/src/backend/access/nbtree/nbtsplitloc.c
@@ -3,7 +3,7 @@
* nbtsplitloc.c
* Choose split point code for Postgres btree implementation.
*
- * Portions Copyright (c) 1996-2024, PostgreSQL Global Development Group
+ * Portions Copyright (c) 1996-2025, PostgreSQL Global Development Group
* Portions Copyright (c) 1994, Regents of the University of California
*
*
@@ -15,6 +15,7 @@
#include "postgres.h"
#include "access/nbtree.h"
+#include "access/tableam.h"
#include "common/int.h"
typedef enum
diff --git a/src/backend/access/nbtree/nbtutils.c b/src/backend/access/nbtree/nbtutils.c
index 05f0d23dc0b23..edfea2acaff66 100644
--- a/src/backend/access/nbtree/nbtutils.c
+++ b/src/backend/access/nbtree/nbtutils.c
@@ -3,7 +3,7 @@
* nbtutils.c
* Utility code for Postgres btree implementation.
*
- * Portions Copyright (c) 1996-2024, PostgreSQL Global Development Group
+ * Portions Copyright (c) 1996-2025, PostgreSQL Global Development Group
* Portions Copyright (c) 1994, Regents of the University of California
*
*
@@ -21,60 +21,32 @@
#include "access/reloptions.h"
#include "access/relscan.h"
#include "commands/progress.h"
-#include "lib/qunique.h"
#include "miscadmin.h"
-#include "utils/array.h"
#include "utils/datum.h"
#include "utils/lsyscache.h"
-#include "utils/memutils.h"
#include "utils/rel.h"
+
#define LOOK_AHEAD_REQUIRED_RECHECKS 3
#define LOOK_AHEAD_DEFAULT_DISTANCE 5
+#define NSKIPADVANCES_THRESHOLD 3
-typedef struct BTSortArrayContext
-{
- FmgrInfo *sortproc;
- Oid collation;
- bool reverse;
-} BTSortArrayContext;
-
-typedef struct BTScanKeyPreproc
-{
- ScanKey skey;
- int ikey;
- int arrayidx;
-} BTScanKeyPreproc;
-
-static void _bt_setup_array_cmp(IndexScanDesc scan, ScanKey skey, Oid elemtype,
- FmgrInfo *orderproc, FmgrInfo **sortprocp);
-static Datum _bt_find_extreme_element(IndexScanDesc scan, ScanKey skey,
- Oid elemtype, StrategyNumber strat,
- Datum *elems, int nelems);
-static int _bt_sort_array_elements(ScanKey skey, FmgrInfo *sortproc,
- bool reverse, Datum *elems, int nelems);
-static bool _bt_merge_arrays(IndexScanDesc scan, ScanKey skey,
- FmgrInfo *sortproc, bool reverse,
- Oid origelemtype, Oid nextelemtype,
- Datum *elems_orig, int *nelems_orig,
- Datum *elems_next, int nelems_next);
-static bool _bt_compare_array_scankey_args(IndexScanDesc scan,
- ScanKey arraysk, ScanKey skey,
- FmgrInfo *orderproc, BTArrayKeyInfo *array,
- bool *qual_ok);
-static ScanKey _bt_preprocess_array_keys(IndexScanDesc scan);
-static void _bt_preprocess_array_keys_final(IndexScanDesc scan, int *keyDataMap);
-static int _bt_compare_array_elements(const void *a, const void *b, void *arg);
static inline int32 _bt_compare_array_skey(FmgrInfo *orderproc,
Datum tupdatum, bool tupnull,
Datum arrdatum, ScanKey cur);
-static int _bt_binsrch_array_skey(FmgrInfo *orderproc,
- bool cur_elem_trig, ScanDirection dir,
- Datum tupdatum, bool tupnull,
- BTArrayKeyInfo *array, ScanKey cur,
- int32 *set_elem_result);
-static bool _bt_advance_array_keys_increment(IndexScanDesc scan, ScanDirection dir);
-static void _bt_rewind_nonrequired_arrays(IndexScanDesc scan, ScanDirection dir);
+static void _bt_binsrch_skiparray_skey(bool cur_elem_trig, ScanDirection dir,
+ Datum tupdatum, bool tupnull,
+ BTArrayKeyInfo *array, ScanKey cur,
+ int32 *set_elem_result);
+static void _bt_skiparray_set_element(Relation rel, ScanKey skey, BTArrayKeyInfo *array,
+ int32 set_elem_result, Datum tupdatum, bool tupnull);
+static void _bt_skiparray_set_isnull(Relation rel, ScanKey skey, BTArrayKeyInfo *array);
+static void _bt_array_set_low_or_high(Relation rel, ScanKey skey,
+ BTArrayKeyInfo *array, bool low_not_high);
+static bool _bt_array_decrement(Relation rel, ScanKey skey, BTArrayKeyInfo *array);
+static bool _bt_array_increment(Relation rel, ScanKey skey, BTArrayKeyInfo *array);
+static bool _bt_advance_array_keys_increment(IndexScanDesc scan, ScanDirection dir,
+ bool *skip_array_set);
static bool _bt_tuple_before_array_skeys(IndexScanDesc scan, ScanDirection dir,
IndexTuple tuple, TupleDesc tupdesc, int tupnatts,
bool readpagetup, int sktrig, bool *scanBehind);
@@ -82,22 +54,17 @@ static bool _bt_advance_array_keys(IndexScanDesc scan, BTReadPageState *pstate,
IndexTuple tuple, int tupnatts, TupleDesc tupdesc,
int sktrig, bool sktrig_required);
#ifdef USE_ASSERT_CHECKING
-static bool _bt_verify_arrays_bt_first(IndexScanDesc scan, ScanDirection dir);
static bool _bt_verify_keys_with_arraykeys(IndexScanDesc scan);
#endif
-static bool _bt_compare_scankey_args(IndexScanDesc scan, ScanKey op,
- ScanKey leftarg, ScanKey rightarg,
- BTArrayKeyInfo *array, FmgrInfo *orderproc,
- bool *result);
-static bool _bt_fix_scankey_strategy(ScanKey skey, int16 *indoption);
-static void _bt_mark_scankey_required(ScanKey skey);
+static bool _bt_oppodir_checkkeys(IndexScanDesc scan, ScanDirection dir,
+ IndexTuple finaltup);
static bool _bt_check_compare(IndexScanDesc scan, ScanDirection dir,
IndexTuple tuple, int tupnatts, TupleDesc tupdesc,
- bool advancenonrequired, bool prechecked, bool firstmatch,
+ bool advancenonrequired, bool forcenonrequired,
bool *continuescan, int *ikey);
static bool _bt_check_rowcompare(ScanKey skey,
IndexTuple tuple, int tupnatts, TupleDesc tupdesc,
- ScanDirection dir, bool *continuescan);
+ ScanDirection dir, bool forcenonrequired, bool *continuescan);
static void _bt_checkkeys_look_ahead(IndexScanDesc scan, BTReadPageState *pstate,
int tupnatts, TupleDesc tupdesc);
static int _bt_keep_natts(Relation rel, IndexTuple lastleft,
@@ -230,1139 +197,767 @@ _bt_freestack(BTStack stack)
}
}
-
/*
- * _bt_preprocess_array_keys() -- Preprocess SK_SEARCHARRAY scan keys
- *
- * If there are any SK_SEARCHARRAY scan keys, deconstruct the array(s) and
- * set up BTArrayKeyInfo info for each one that is an equality-type key.
- * Returns modified scan keys as input for further, standard preprocessing.
- *
- * Currently we perform two kinds of preprocessing to deal with redundancies.
- * For inequality array keys, it's sufficient to find the extreme element
- * value and replace the whole array with that scalar value. This eliminates
- * all but one array element as redundant. Similarly, we are capable of
- * "merging together" multiple equality array keys (from two or more input
- * scan keys) into a single output scan key containing only the intersecting
- * array elements. This can eliminate many redundant array elements, as well
- * as eliminating whole array scan keys as redundant. It can also allow us to
- * detect contradictory quals.
+ * _bt_compare_array_skey() -- apply array comparison function
*
- * It is convenient for _bt_preprocess_keys caller to have to deal with no
- * more than one equality strategy array scan key per index attribute. We'll
- * always be able to set things up that way when complete opfamilies are used.
- * Eliminated array scan keys can be recognized as those that have had their
- * sk_strategy field set to InvalidStrategy here by us. Caller should avoid
- * including these in the scan's so->keyData[] output array.
+ * Compares caller's tuple attribute value to a scan key/array element.
+ * Helper function used during binary searches of SK_SEARCHARRAY arrays.
*
- * We set the scan key references from the scan's BTArrayKeyInfo info array to
- * offsets into the temp modified input array returned to caller. Scans that
- * have array keys should call _bt_preprocess_array_keys_final when standard
- * preprocessing steps are complete. This will convert the scan key offset
- * references into references to the scan's so->keyData[] output scan keys.
+ * This routine returns:
+ * <0 if tupdatum < arrdatum;
+ * 0 if tupdatum == arrdatum;
+ * >0 if tupdatum > arrdatum.
*
- * Note: the reason we need to return a temp scan key array, rather than just
- * scribbling on scan->keyData, is that callers are permitted to call btrescan
- * without supplying a new set of scankey data.
- */
-static ScanKey
-_bt_preprocess_array_keys(IndexScanDesc scan)
+ * This is essentially the same interface as _bt_compare: both functions
+ * compare the value that they're searching for to a binary search pivot.
+ * However, unlike _bt_compare, this function's "tuple argument" comes first,
+ * while its "array/scankey argument" comes second.
+*/
+static inline int32
+_bt_compare_array_skey(FmgrInfo *orderproc,
+ Datum tupdatum, bool tupnull,
+ Datum arrdatum, ScanKey cur)
{
- BTScanOpaque so = (BTScanOpaque) scan->opaque;
- Relation rel = scan->indexRelation;
- int numberOfKeys = scan->numberOfKeys;
- int16 *indoption = rel->rd_indoption;
- int numArrayKeys;
- int origarrayatt = InvalidAttrNumber,
- origarraykey = -1;
- Oid origelemtype = InvalidOid;
- ScanKey cur;
- MemoryContext oldContext;
- ScanKey arrayKeyData; /* modified copy of scan->keyData */
-
- Assert(numberOfKeys);
-
- /* Quick check to see if there are any array keys */
- numArrayKeys = 0;
- for (int i = 0; i < numberOfKeys; i++)
- {
- cur = &scan->keyData[i];
- if (cur->sk_flags & SK_SEARCHARRAY)
- {
- numArrayKeys++;
- Assert(!(cur->sk_flags & (SK_ROW_HEADER | SK_SEARCHNULL | SK_SEARCHNOTNULL)));
- /* If any arrays are null as a whole, we can quit right now. */
- if (cur->sk_flags & SK_ISNULL)
- {
- so->qual_ok = false;
- return NULL;
- }
- }
- }
+ int32 result = 0;
- /* Quit if nothing to do. */
- if (numArrayKeys == 0)
- return NULL;
+ Assert(cur->sk_strategy == BTEqualStrategyNumber);
+ Assert(!(cur->sk_flags & (SK_BT_MINVAL | SK_BT_MAXVAL)));
- /*
- * Make a scan-lifespan context to hold array-associated data, or reset it
- * if we already have one from a previous rescan cycle.
- */
- if (so->arrayContext == NULL)
- so->arrayContext = AllocSetContextCreate(CurrentMemoryContext,
- "BTree array context",
- ALLOCSET_SMALL_SIZES);
+ if (tupnull) /* NULL tupdatum */
+ {
+ if (cur->sk_flags & SK_ISNULL)
+ result = 0; /* NULL "=" NULL */
+ else if (cur->sk_flags & SK_BT_NULLS_FIRST)
+ result = -1; /* NULL "<" NOT_NULL */
+ else
+ result = 1; /* NULL ">" NOT_NULL */
+ }
+ else if (cur->sk_flags & SK_ISNULL) /* NOT_NULL tupdatum, NULL arrdatum */
+ {
+ if (cur->sk_flags & SK_BT_NULLS_FIRST)
+ result = 1; /* NOT_NULL ">" NULL */
+ else
+ result = -1; /* NOT_NULL "<" NULL */
+ }
else
- MemoryContextReset(so->arrayContext);
-
- oldContext = MemoryContextSwitchTo(so->arrayContext);
-
- /* Create modifiable copy of scan->keyData in the workspace context */
- arrayKeyData = (ScanKey) palloc(numberOfKeys * sizeof(ScanKeyData));
- memcpy(arrayKeyData, scan->keyData, numberOfKeys * sizeof(ScanKeyData));
-
- /* Allocate space for per-array data in the workspace context */
- so->arrayKeys = (BTArrayKeyInfo *) palloc(numArrayKeys * sizeof(BTArrayKeyInfo));
-
- /* Allocate space for ORDER procs used to help _bt_checkkeys */
- so->orderProcs = (FmgrInfo *) palloc(numberOfKeys * sizeof(FmgrInfo));
-
- /* Now process each array key */
- numArrayKeys = 0;
- for (int i = 0; i < numberOfKeys; i++)
{
- FmgrInfo sortproc;
- FmgrInfo *sortprocp = &sortproc;
- Oid elemtype;
- bool reverse;
- ArrayType *arrayval;
- int16 elmlen;
- bool elmbyval;
- char elmalign;
- int num_elems;
- Datum *elem_values;
- bool *elem_nulls;
- int num_nonnulls;
- int j;
-
- cur = &arrayKeyData[i];
- if (!(cur->sk_flags & SK_SEARCHARRAY))
- continue;
-
/*
- * First, deconstruct the array into elements. Anything allocated
- * here (including a possibly detoasted array value) is in the
- * workspace context.
+ * Like _bt_compare, we need to be careful of cross-type comparisons,
+ * so the left value has to be the value that came from an index tuple
*/
- arrayval = DatumGetArrayTypeP(cur->sk_argument);
- /* We could cache this data, but not clear it's worth it */
- get_typlenbyvalalign(ARR_ELEMTYPE(arrayval),
- &elmlen, &elmbyval, &elmalign);
- deconstruct_array(arrayval,
- ARR_ELEMTYPE(arrayval),
- elmlen, elmbyval, elmalign,
- &elem_values, &elem_nulls, &num_elems);
+ result = DatumGetInt32(FunctionCall2Coll(orderproc, cur->sk_collation,
+ tupdatum, arrdatum));
/*
- * Compress out any null elements. We can ignore them since we assume
- * all btree operators are strict.
+ * We flip the sign by following the obvious rule: flip whenever the
+ * column is a DESC column.
+ *
+ * _bt_compare does it the wrong way around (flip when *ASC*) in order
+ * to compensate for passing its orderproc arguments backwards. We
+ * don't need to play these games because we find it natural to pass
+ * tupdatum as the left value (and arrdatum as the right value).
*/
- num_nonnulls = 0;
- for (j = 0; j < num_elems; j++)
- {
- if (!elem_nulls[j])
- elem_values[num_nonnulls++] = elem_values[j];
- }
+ if (cur->sk_flags & SK_BT_DESC)
+ INVERT_COMPARE_RESULT(result);
+ }
- /* We could pfree(elem_nulls) now, but not worth the cycles */
+ return result;
+}
- /* If there's no non-nulls, the scan qual is unsatisfiable */
- if (num_nonnulls == 0)
- {
- so->qual_ok = false;
- break;
- }
+/*
+ * _bt_binsrch_array_skey() -- Binary search for next matching array key
+ *
+ * Returns an index to the first array element >= caller's tupdatum argument.
+ * This convention is more natural for forwards scan callers, but that can't
+ * really matter to backwards scan callers. Both callers require handling for
+ * the case where the match we return is < tupdatum, and symmetric handling
+ * for the case where our best match is > tupdatum.
+ *
+ * Also sets *set_elem_result to the result _bt_compare_array_skey returned
+ * when we used it to compare the matching array element to tupdatum/tupnull.
+ *
+ * cur_elem_trig indicates if array advancement was triggered by this array's
+ * scan key, and that the array is for a required scan key. We can apply this
+ * information to find the next matching array element in the current scan
+ * direction using far fewer comparisons (fewer on average, compared to naive
+ * binary search). This scheme takes advantage of an important property of
+ * required arrays: required arrays always advance in lockstep with the index
+ * scan's progress through the index's key space.
+ */
+int
+_bt_binsrch_array_skey(FmgrInfo *orderproc,
+ bool cur_elem_trig, ScanDirection dir,
+ Datum tupdatum, bool tupnull,
+ BTArrayKeyInfo *array, ScanKey cur,
+ int32 *set_elem_result)
+{
+ int low_elem = 0,
+ mid_elem = -1,
+ high_elem = array->num_elems - 1,
+ result = 0;
+ Datum arrdatum;
- /*
- * Determine the nominal datatype of the array elements. We have to
- * support the convention that sk_subtype == InvalidOid means the
- * opclass input type; this is a hack to simplify life for
- * ScanKeyInit().
- */
- elemtype = cur->sk_subtype;
- if (elemtype == InvalidOid)
- elemtype = rel->rd_opcintype[cur->sk_attno - 1];
+ Assert(cur->sk_flags & SK_SEARCHARRAY);
+ Assert(!(cur->sk_flags & SK_BT_SKIP));
+ Assert(!(cur->sk_flags & SK_ISNULL)); /* SAOP arrays never have NULLs */
+ Assert(cur->sk_strategy == BTEqualStrategyNumber);
- /*
- * If the comparison operator is not equality, then the array qual
- * degenerates to a simple comparison against the smallest or largest
- * non-null array element, as appropriate.
- */
- switch (cur->sk_strategy)
- {
- case BTLessStrategyNumber:
- case BTLessEqualStrategyNumber:
- cur->sk_argument =
- _bt_find_extreme_element(scan, cur, elemtype,
- BTGreaterStrategyNumber,
- elem_values, num_nonnulls);
- continue;
- case BTEqualStrategyNumber:
- /* proceed with rest of loop */
- break;
- case BTGreaterEqualStrategyNumber:
- case BTGreaterStrategyNumber:
- cur->sk_argument =
- _bt_find_extreme_element(scan, cur, elemtype,
- BTLessStrategyNumber,
- elem_values, num_nonnulls);
- continue;
- default:
- elog(ERROR, "unrecognized StrategyNumber: %d",
- (int) cur->sk_strategy);
- break;
- }
+ if (cur_elem_trig)
+ {
+ Assert(!ScanDirectionIsNoMovement(dir));
+ Assert(cur->sk_flags & SK_BT_REQFWD);
/*
- * We'll need a 3-way ORDER proc to perform binary searches for the
- * next matching array element. Set that up now.
+ * When the scan key that triggered array advancement is a required
+ * array scan key, it is now certain that the current array element
+ * (plus all prior elements relative to the current scan direction)
+ * cannot possibly be at or ahead of the corresponding tuple value.
+ * (_bt_checkkeys must have called _bt_tuple_before_array_skeys, which
+ * makes sure this is true as a condition of advancing the arrays.)
+ *
+ * This makes it safe to exclude array elements up to and including
+ * the former-current array element from our search.
*
- * Array scan keys with cross-type equality operators will require a
- * separate same-type ORDER proc for sorting their array. Otherwise,
- * sortproc just points to the same proc used during binary searches.
+ * Separately, when array advancement was triggered by a required scan
+ * key, the array element immediately after the former-current element
+ * is often either an exact tupdatum match, or a "close by" near-match
+ * (a near-match tupdatum is one whose key space falls _between_ the
+ * former-current and new-current array elements). We'll detect both
+ * cases via an optimistic comparison of the new search lower bound
+ * (or new search upper bound in the case of backwards scans).
*/
- _bt_setup_array_cmp(scan, cur, elemtype,
- &so->orderProcs[i], &sortprocp);
+ if (ScanDirectionIsForward(dir))
+ {
+ low_elem = array->cur_elem + 1; /* old cur_elem exhausted */
- /*
- * Sort the non-null elements and eliminate any duplicates. We must
- * sort in the same ordering used by the index column, so that the
- * arrays can be advanced in lockstep with the scan's progress through
- * the index's key space.
- */
- reverse = (indoption[cur->sk_attno - 1] & INDOPTION_DESC) != 0;
- num_elems = _bt_sort_array_elements(cur, sortprocp, reverse,
- elem_values, num_nonnulls);
+ /* Compare prospective new cur_elem (also the new lower bound) */
+ if (high_elem >= low_elem)
+ {
+ arrdatum = array->elem_values[low_elem];
+ result = _bt_compare_array_skey(orderproc, tupdatum, tupnull,
+ arrdatum, cur);
+
+ if (result <= 0)
+ {
+ /* Optimistic comparison optimization worked out */
+ *set_elem_result = result;
+ return low_elem;
+ }
+ mid_elem = low_elem;
+ low_elem++; /* this cur_elem exhausted, too */
+ }
- if (origarrayatt == cur->sk_attno)
+ if (high_elem < low_elem)
+ {
+ /* Caller needs to perform "beyond end" array advancement */
+ *set_elem_result = 1;
+ return high_elem;
+ }
+ }
+ else
{
- BTArrayKeyInfo *orig = &so->arrayKeys[origarraykey];
+ high_elem = array->cur_elem - 1; /* old cur_elem exhausted */
- /*
- * This array scan key is redundant with a previous equality
- * operator array scan key. Merge the two arrays together to
- * eliminate contradictory non-intersecting elements (or try to).
- *
- * We merge this next array back into attribute's original array.
- */
- Assert(arrayKeyData[orig->scan_key].sk_attno == cur->sk_attno);
- Assert(arrayKeyData[orig->scan_key].sk_collation ==
- cur->sk_collation);
- if (_bt_merge_arrays(scan, cur, sortprocp, reverse,
- origelemtype, elemtype,
- orig->elem_values, &orig->num_elems,
- elem_values, num_elems))
+ /* Compare prospective new cur_elem (also the new upper bound) */
+ if (high_elem >= low_elem)
{
- /* Successfully eliminated this array */
- pfree(elem_values);
+ arrdatum = array->elem_values[high_elem];
+ result = _bt_compare_array_skey(orderproc, tupdatum, tupnull,
+ arrdatum, cur);
- /*
- * If no intersecting elements remain in the original array,
- * the scan qual is unsatisfiable
- */
- if (orig->num_elems == 0)
+ if (result >= 0)
{
- so->qual_ok = false;
- break;
+ /* Optimistic comparison optimization worked out */
+ *set_elem_result = result;
+ return high_elem;
}
-
- /*
- * Indicate to _bt_preprocess_keys caller that it must ignore
- * this scan key
- */
- cur->sk_strategy = InvalidStrategy;
- continue;
+ mid_elem = high_elem;
+ high_elem--; /* this cur_elem exhausted, too */
}
- /*
- * Unable to merge this array with previous array due to a lack of
- * suitable cross-type opfamily support. Will need to keep both
- * scan keys/arrays.
- */
+ if (high_elem < low_elem)
+ {
+ /* Caller needs to perform "beyond end" array advancement */
+ *set_elem_result = -1;
+ return low_elem;
+ }
}
- else
+ }
+
+ while (high_elem > low_elem)
+ {
+ mid_elem = low_elem + ((high_elem - low_elem) / 2);
+ arrdatum = array->elem_values[mid_elem];
+
+ result = _bt_compare_array_skey(orderproc, tupdatum, tupnull,
+ arrdatum, cur);
+
+ if (result == 0)
{
/*
- * This array is the first for current index attribute.
- *
- * If it turns out to not be the last array (that is, if the next
- * array is redundantly applied to this same index attribute),
- * we'll then treat this array as the attribute's "original" array
- * when merging.
+ * It's safe to quit as soon as we see an equal array element.
+ * This often saves an extra comparison or two...
*/
- origarrayatt = cur->sk_attno;
- origarraykey = numArrayKeys;
- origelemtype = elemtype;
+ low_elem = mid_elem;
+ break;
}
- /*
- * And set up the BTArrayKeyInfo data.
- *
- * Note: _bt_preprocess_array_keys_final will fix-up each array's
- * scan_key field later on, after so->keyData[] has been finalized.
- */
- so->arrayKeys[numArrayKeys].scan_key = i;
- so->arrayKeys[numArrayKeys].num_elems = num_elems;
- so->arrayKeys[numArrayKeys].elem_values = elem_values;
- numArrayKeys++;
+ if (result > 0)
+ low_elem = mid_elem + 1;
+ else
+ high_elem = mid_elem;
}
- so->numArrayKeys = numArrayKeys;
+ /*
+ * ...but our caller also cares about how its searched-for tuple datum
+ * compares to the low_elem datum. Must always set *set_elem_result with
+ * the result of that comparison specifically.
+ */
+ if (low_elem != mid_elem)
+ result = _bt_compare_array_skey(orderproc, tupdatum, tupnull,
+ array->elem_values[low_elem], cur);
- MemoryContextSwitchTo(oldContext);
+ *set_elem_result = result;
- return arrayKeyData;
+ return low_elem;
}
/*
- * _bt_preprocess_array_keys_final() -- fix up array scan key references
+ * _bt_binsrch_skiparray_skey() -- "Binary search" within a skip array
*
- * When _bt_preprocess_array_keys performed initial array preprocessing, it
- * set each array's array->scan_key to the array's arrayKeys[] entry offset
- * (that also work as references into the original scan->keyData[] array).
- * This function handles translation of the scan key references from the
- * BTArrayKeyInfo info array, from input scan key references (to the keys in
- * scan->keyData[]), into output references (to the keys in so->keyData[]).
- * Caller's keyDataMap[] array tells us how to perform this remapping.
+ * Does not return an index into the array, since skip arrays don't really
+ * contain elements (they generate their array elements procedurally instead).
+ * Our interface matches that of _bt_binsrch_array_skey in every other way.
*
- * Also finalizes so->orderProcs[] for the scan. Arrays already have an ORDER
- * proc, which might need to be repositioned to its so->keyData[]-wise offset
- * (very much like the remapping that we apply to array->scan_key references).
- * Non-array equality strategy scan keys (that survived preprocessing) don't
- * yet have an so->orderProcs[] entry, so we set one for them here.
+ * Sets *set_elem_result just like _bt_binsrch_array_skey would with a true
+ * array. The value 0 indicates that tupdatum/tupnull is within the range of
+ * the skip array. We return -1 when tupdatum/tupnull is lower that any value
+ * within the range of the array, and 1 when it is higher than every value.
+ * Caller should pass *set_elem_result to _bt_skiparray_set_element to advance
+ * the array.
*
- * Also converts single-element array scan keys into equivalent non-array
- * equality scan keys, which decrements so->numArrayKeys. It's possible that
- * this will leave this new btrescan without any arrays at all. This isn't
- * necessary for correctness; it's just an optimization. Non-array equality
- * scan keys are slightly faster than equivalent array scan keys at runtime.
+ * cur_elem_trig indicates if array advancement was triggered by this array's
+ * scan key. We use this to optimize-away comparisons that are known by our
+ * caller to be unnecessary from context, just like _bt_binsrch_array_skey.
*/
static void
-_bt_preprocess_array_keys_final(IndexScanDesc scan, int *keyDataMap)
+_bt_binsrch_skiparray_skey(bool cur_elem_trig, ScanDirection dir,
+ Datum tupdatum, bool tupnull,
+ BTArrayKeyInfo *array, ScanKey cur,
+ int32 *set_elem_result)
{
- BTScanOpaque so = (BTScanOpaque) scan->opaque;
- Relation rel = scan->indexRelation;
- int arrayidx = 0;
- int last_equal_output_ikey PG_USED_FOR_ASSERTS_ONLY = -1;
+ Assert(cur->sk_flags & SK_BT_SKIP);
+ Assert(cur->sk_flags & SK_SEARCHARRAY);
+ Assert(cur->sk_flags & SK_BT_REQFWD);
+ Assert(array->num_elems == -1);
+ Assert(!ScanDirectionIsNoMovement(dir));
- Assert(so->qual_ok);
+ if (array->null_elem)
+ {
+ Assert(!array->low_compare && !array->high_compare);
- /*
- * Nothing for us to do when _bt_preprocess_array_keys only had to deal
- * with array inequalities
- */
- if (so->numArrayKeys == 0)
+ *set_elem_result = 0;
return;
+ }
- for (int output_ikey = 0; output_ikey < so->numberOfKeys; output_ikey++)
+ if (tupnull) /* NULL tupdatum */
{
- ScanKey outkey = so->keyData + output_ikey;
- int input_ikey;
- bool found PG_USED_FOR_ASSERTS_ONLY = false;
-
- Assert(outkey->sk_strategy != InvalidStrategy);
-
- if (outkey->sk_strategy != BTEqualStrategyNumber)
- continue;
-
- input_ikey = keyDataMap[output_ikey];
-
- Assert(last_equal_output_ikey < output_ikey);
- Assert(last_equal_output_ikey < input_ikey);
- last_equal_output_ikey = output_ikey;
+ if (cur->sk_flags & SK_BT_NULLS_FIRST)
+ *set_elem_result = -1; /* NULL "<" NOT_NULL */
+ else
+ *set_elem_result = 1; /* NULL ">" NOT_NULL */
+ return;
+ }
+ /*
+ * Array inequalities determine whether tupdatum is within the range of
+ * caller's skip array
+ */
+ *set_elem_result = 0;
+ if (ScanDirectionIsForward(dir))
+ {
/*
- * We're lazy about looking up ORDER procs for non-array keys, since
- * not all input keys become output keys. Take care of it now.
+ * Evaluate low_compare first (unless cur_elem_trig tells us that it
+ * cannot possibly fail to be satisfied), then evaluate high_compare
*/
- if (!(outkey->sk_flags & SK_SEARCHARRAY))
- {
- Oid elemtype;
-
- /* No need for an ORDER proc given an IS NULL scan key */
- if (outkey->sk_flags & SK_SEARCHNULL)
- continue;
-
- /*
- * A non-required scan key doesn't need an ORDER proc, either
- * (unless it's associated with an array, which this one isn't)
- */
- if (!(outkey->sk_flags & SK_BT_REQFWD))
- continue;
-
- elemtype = outkey->sk_subtype;
- if (elemtype == InvalidOid)
- elemtype = rel->rd_opcintype[outkey->sk_attno - 1];
-
- _bt_setup_array_cmp(scan, outkey, elemtype,
- &so->orderProcs[output_ikey], NULL);
- continue;
- }
-
+ if (!cur_elem_trig && array->low_compare &&
+ !DatumGetBool(FunctionCall2Coll(&array->low_compare->sk_func,
+ array->low_compare->sk_collation,
+ tupdatum,
+ array->low_compare->sk_argument)))
+ *set_elem_result = -1;
+ else if (array->high_compare &&
+ !DatumGetBool(FunctionCall2Coll(&array->high_compare->sk_func,
+ array->high_compare->sk_collation,
+ tupdatum,
+ array->high_compare->sk_argument)))
+ *set_elem_result = 1;
+ }
+ else
+ {
/*
- * Reorder existing array scan key so->orderProcs[] entries.
- *
- * Doing this in-place is safe because preprocessing is required to
- * output all equality strategy scan keys in original input order
- * (among each group of entries against the same index attribute).
- * This is also the order that the arrays themselves appear in.
+ * Evaluate high_compare first (unless cur_elem_trig tells us that it
+ * cannot possibly fail to be satisfied), then evaluate low_compare
*/
- so->orderProcs[output_ikey] = so->orderProcs[input_ikey];
-
- /* Fix-up array->scan_key references for arrays */
- for (; arrayidx < so->numArrayKeys; arrayidx++)
- {
- BTArrayKeyInfo *array = &so->arrayKeys[arrayidx];
-
- Assert(array->num_elems > 0);
-
- if (array->scan_key == input_ikey)
- {
- /* found it */
- array->scan_key = output_ikey;
- found = true;
-
- /*
- * Transform array scan keys that have exactly 1 element
- * remaining (following all prior preprocessing) into
- * equivalent non-array scan keys.
- */
- if (array->num_elems == 1)
- {
- outkey->sk_flags &= ~SK_SEARCHARRAY;
- outkey->sk_argument = array->elem_values[0];
- so->numArrayKeys--;
-
- /* If we're out of array keys, we can quit right away */
- if (so->numArrayKeys == 0)
- return;
-
- /* Shift other arrays forward */
- memmove(array, array + 1,
- sizeof(BTArrayKeyInfo) *
- (so->numArrayKeys - arrayidx));
-
- /*
- * Don't increment arrayidx (there was an entry that was
- * just shifted forward to the offset at arrayidx, which
- * will still need to be matched)
- */
- }
- else
- {
- /* Match found, so done with this array */
- arrayidx++;
- }
-
- break;
- }
- }
-
- Assert(found);
+ if (!cur_elem_trig && array->high_compare &&
+ !DatumGetBool(FunctionCall2Coll(&array->high_compare->sk_func,
+ array->high_compare->sk_collation,
+ tupdatum,
+ array->high_compare->sk_argument)))
+ *set_elem_result = 1;
+ else if (array->low_compare &&
+ !DatumGetBool(FunctionCall2Coll(&array->low_compare->sk_func,
+ array->low_compare->sk_collation,
+ tupdatum,
+ array->low_compare->sk_argument)))
+ *set_elem_result = -1;
}
/*
- * Parallel index scans require space in shared memory to store the
- * current array elements (for arrays kept by preprocessing) to schedule
- * the next primitive index scan. The underlying structure is protected
- * using a spinlock, so defensively limit its size. In practice this can
- * only affect parallel scans that use an incomplete opfamily.
+ * Assert that any keys that were assumed to be satisfied already (due to
+ * caller passing cur_elem_trig=true) really are satisfied as expected
*/
- if (scan->parallel_scan && so->numArrayKeys > INDEX_MAX_KEYS)
- ereport(ERROR,
- (errcode(ERRCODE_PROGRAM_LIMIT_EXCEEDED),
- errmsg_internal("number of array scan keys left by preprocessing (%d) exceeds the maximum allowed by parallel btree index scans (%d)",
- so->numArrayKeys, INDEX_MAX_KEYS)));
+#ifdef USE_ASSERT_CHECKING
+ if (cur_elem_trig)
+ {
+ if (ScanDirectionIsForward(dir) && array->low_compare)
+ Assert(DatumGetBool(FunctionCall2Coll(&array->low_compare->sk_func,
+ array->low_compare->sk_collation,
+ tupdatum,
+ array->low_compare->sk_argument)));
+
+ if (ScanDirectionIsBackward(dir) && array->high_compare)
+ Assert(DatumGetBool(FunctionCall2Coll(&array->high_compare->sk_func,
+ array->high_compare->sk_collation,
+ tupdatum,
+ array->high_compare->sk_argument)));
+ }
+#endif
}
/*
- * _bt_setup_array_cmp() -- Set up array comparison functions
- *
- * Sets ORDER proc in caller's orderproc argument, which is used during binary
- * searches of arrays during the index scan. Also sets a same-type ORDER proc
- * in caller's *sortprocp argument, which is used when sorting the array.
- *
- * Preprocessing calls here with all equality strategy scan keys (when scan
- * uses equality array keys), including those not associated with any array.
- * See _bt_advance_array_keys for an explanation of why it'll need to treat
- * simple scalar equality scan keys as degenerate single element arrays.
+ * _bt_skiparray_set_element() -- Set skip array scan key's sk_argument
*
- * Caller should pass an orderproc pointing to space that'll store the ORDER
- * proc for the scan, and a *sortprocp pointing to its own separate space.
- * When calling here for a non-array scan key, sortprocp arg should be NULL.
+ * Caller passes set_elem_result returned by _bt_binsrch_skiparray_skey for
+ * caller's tupdatum/tupnull.
*
- * In the common case where we don't need to deal with cross-type operators,
- * only one ORDER proc is actually required by caller. We'll set *sortprocp
- * to point to the same memory that caller's orderproc continues to point to.
- * Otherwise, *sortprocp will continue to point to caller's own space. Either
- * way, *sortprocp will point to a same-type ORDER proc (since that's the only
- * safe way to sort/deduplicate the array associated with caller's scan key).
+ * We copy tupdatum/tupnull into skey's sk_argument iff set_elem_result == 0.
+ * Otherwise, we set skey to either the lowest or highest value that's within
+ * the range of caller's skip array (whichever is the best available match to
+ * tupdatum/tupnull that is still within the range of the skip array according
+ * to _bt_binsrch_skiparray_skey/set_elem_result).
*/
static void
-_bt_setup_array_cmp(IndexScanDesc scan, ScanKey skey, Oid elemtype,
- FmgrInfo *orderproc, FmgrInfo **sortprocp)
+_bt_skiparray_set_element(Relation rel, ScanKey skey, BTArrayKeyInfo *array,
+ int32 set_elem_result, Datum tupdatum, bool tupnull)
{
- BTScanOpaque so = (BTScanOpaque) scan->opaque;
- Relation rel = scan->indexRelation;
- RegProcedure cmp_proc;
- Oid opcintype = rel->rd_opcintype[skey->sk_attno - 1];
+ Assert(skey->sk_flags & SK_BT_SKIP);
+ Assert(skey->sk_flags & SK_SEARCHARRAY);
- Assert(skey->sk_strategy == BTEqualStrategyNumber);
- Assert(OidIsValid(elemtype));
-
- /*
- * If scankey operator is not a cross-type comparison, we can use the
- * cached comparison function; otherwise gotta look it up in the catalogs
- */
- if (elemtype == opcintype)
+ if (set_elem_result)
{
- /* Set same-type ORDER procs for caller */
- *orderproc = *index_getprocinfo(rel, skey->sk_attno, BTORDER_PROC);
- if (sortprocp)
- *sortprocp = orderproc;
+ /* tupdatum/tupnull is out of the range of the skip array */
+ Assert(!array->null_elem);
+ _bt_array_set_low_or_high(rel, skey, array, set_elem_result < 0);
return;
}
- /*
- * Look up the appropriate cross-type comparison function in the opfamily.
- *
- * Use the opclass input type as the left hand arg type, and the array
- * element type as the right hand arg type (since binary searches use an
- * index tuple's attribute value to search for a matching array element).
- *
- * Note: it's possible that this would fail, if the opfamily is
- * incomplete, but only in cases where it's quite likely that _bt_first
- * would fail in just the same way (had we not failed before it could).
- */
- cmp_proc = get_opfamily_proc(rel->rd_opfamily[skey->sk_attno - 1],
- opcintype, elemtype, BTORDER_PROC);
- if (!RegProcedureIsValid(cmp_proc))
- elog(ERROR, "missing support function %d(%u,%u) for attribute %d of index \"%s\"",
- BTORDER_PROC, opcintype, elemtype, skey->sk_attno,
- RelationGetRelationName(rel));
-
- /* Set cross-type ORDER proc for caller */
- fmgr_info_cxt(cmp_proc, orderproc, so->arrayContext);
-
- /* Done if caller doesn't actually have an array they'll need to sort */
- if (!sortprocp)
+ /* Advance skip array to tupdatum (or tupnull) value */
+ if (unlikely(tupnull))
+ {
+ _bt_skiparray_set_isnull(rel, skey, array);
return;
+ }
- /*
- * Look up the appropriate same-type comparison function in the opfamily.
- *
- * Note: it's possible that this would fail, if the opfamily is
- * incomplete, but it seems quite unlikely that an opfamily would omit
- * non-cross-type comparison procs for any datatype that it supports at
- * all.
- */
- cmp_proc = get_opfamily_proc(rel->rd_opfamily[skey->sk_attno - 1],
- elemtype, elemtype, BTORDER_PROC);
- if (!RegProcedureIsValid(cmp_proc))
- elog(ERROR, "missing support function %d(%u,%u) for attribute %d of index \"%s\"",
- BTORDER_PROC, elemtype, elemtype,
- skey->sk_attno, RelationGetRelationName(rel));
-
- /* Set same-type ORDER proc for caller */
- fmgr_info_cxt(cmp_proc, *sortprocp, so->arrayContext);
+ /* Free memory previously allocated for sk_argument if needed */
+ if (!array->attbyval && skey->sk_argument)
+ pfree(DatumGetPointer(skey->sk_argument));
+
+ /* tupdatum becomes new sk_argument/new current element */
+ skey->sk_flags &= ~(SK_SEARCHNULL | SK_ISNULL |
+ SK_BT_MINVAL | SK_BT_MAXVAL |
+ SK_BT_NEXT | SK_BT_PRIOR);
+ skey->sk_argument = datumCopy(tupdatum, array->attbyval, array->attlen);
}
/*
- * _bt_find_extreme_element() -- get least or greatest array element
- *
- * scan and skey identify the index column, whose opfamily determines the
- * comparison semantics. strat should be BTLessStrategyNumber to get the
- * least element, or BTGreaterStrategyNumber to get the greatest.
+ * _bt_skiparray_set_isnull() -- set skip array scan key to NULL
*/
-static Datum
-_bt_find_extreme_element(IndexScanDesc scan, ScanKey skey, Oid elemtype,
- StrategyNumber strat,
- Datum *elems, int nelems)
+static void
+_bt_skiparray_set_isnull(Relation rel, ScanKey skey, BTArrayKeyInfo *array)
{
- Relation rel = scan->indexRelation;
- Oid cmp_op;
- RegProcedure cmp_proc;
- FmgrInfo flinfo;
- Datum result;
- int i;
-
- /*
- * Look up the appropriate comparison operator in the opfamily.
- *
- * Note: it's possible that this would fail, if the opfamily is
- * incomplete, but it seems quite unlikely that an opfamily would omit
- * non-cross-type comparison operators for any datatype that it supports
- * at all.
- */
- Assert(skey->sk_strategy != BTEqualStrategyNumber);
- Assert(OidIsValid(elemtype));
- cmp_op = get_opfamily_member(rel->rd_opfamily[skey->sk_attno - 1],
- elemtype,
- elemtype,
- strat);
- if (!OidIsValid(cmp_op))
- elog(ERROR, "missing operator %d(%u,%u) in opfamily %u",
- strat, elemtype, elemtype,
- rel->rd_opfamily[skey->sk_attno - 1]);
- cmp_proc = get_opcode(cmp_op);
- if (!RegProcedureIsValid(cmp_proc))
- elog(ERROR, "missing oprcode for operator %u", cmp_op);
-
- fmgr_info(cmp_proc, &flinfo);
-
- Assert(nelems > 0);
- result = elems[0];
- for (i = 1; i < nelems; i++)
- {
- if (DatumGetBool(FunctionCall2Coll(&flinfo,
- skey->sk_collation,
- elems[i],
- result)))
- result = elems[i];
- }
-
- return result;
+ Assert(skey->sk_flags & SK_BT_SKIP);
+ Assert(skey->sk_flags & SK_SEARCHARRAY);
+ Assert(array->null_elem && !array->low_compare && !array->high_compare);
+
+ /* Free memory previously allocated for sk_argument if needed */
+ if (!array->attbyval && skey->sk_argument)
+ pfree(DatumGetPointer(skey->sk_argument));
+
+ /* NULL becomes new sk_argument/new current element */
+ skey->sk_argument = (Datum) 0;
+ skey->sk_flags &= ~(SK_BT_MINVAL | SK_BT_MAXVAL |
+ SK_BT_NEXT | SK_BT_PRIOR);
+ skey->sk_flags |= (SK_SEARCHNULL | SK_ISNULL);
}
/*
- * _bt_sort_array_elements() -- sort and de-dup array elements
- *
- * The array elements are sorted in-place, and the new number of elements
- * after duplicate removal is returned.
+ * _bt_start_array_keys() -- Initialize array keys at start of a scan
*
- * skey identifies the index column whose opfamily determines the comparison
- * semantics, and sortproc is a corresponding ORDER proc. If reverse is true,
- * we sort in descending order.
+ * Set up the cur_elem counters and fill in the first sk_argument value for
+ * each array scankey.
*/
-static int
-_bt_sort_array_elements(ScanKey skey, FmgrInfo *sortproc, bool reverse,
- Datum *elems, int nelems)
+void
+_bt_start_array_keys(IndexScanDesc scan, ScanDirection dir)
{
- BTSortArrayContext cxt;
+ Relation rel = scan->indexRelation;
+ BTScanOpaque so = (BTScanOpaque) scan->opaque;
- if (nelems <= 1)
- return nelems; /* no work to do */
+ Assert(so->numArrayKeys);
+ Assert(so->qual_ok);
- /* Sort the array elements */
- cxt.sortproc = sortproc;
- cxt.collation = skey->sk_collation;
- cxt.reverse = reverse;
- qsort_arg(elems, nelems, sizeof(Datum),
- _bt_compare_array_elements, &cxt);
+ for (int i = 0; i < so->numArrayKeys; i++)
+ {
+ BTArrayKeyInfo *array = &so->arrayKeys[i];
+ ScanKey skey = &so->keyData[array->scan_key];
- /* Now scan the sorted elements and remove duplicates */
- return qunique_arg(elems, nelems, sizeof(Datum),
- _bt_compare_array_elements, &cxt);
+ Assert(skey->sk_flags & SK_SEARCHARRAY);
+
+ _bt_array_set_low_or_high(rel, skey, array,
+ ScanDirectionIsForward(dir));
+ }
+ so->scanBehind = so->oppositeDirCheck = false; /* reset */
}
/*
- * _bt_merge_arrays() -- merge next array's elements into an original array
+ * _bt_array_set_low_or_high() -- Set array scan key to lowest/highest element
*
- * Called when preprocessing encounters a pair of array equality scan keys,
- * both against the same index attribute (during initial array preprocessing).
- * Merging reorganizes caller's original array (the left hand arg) in-place,
- * without ever copying elements from one array into the other. (Mixing the
- * elements together like this would be wrong, since they don't necessarily
- * use the same underlying element type, despite all the other similarities.)
- *
- * Both arrays must have already been sorted and deduplicated by calling
- * _bt_sort_array_elements. sortproc is the same-type ORDER proc that was
- * just used to sort and deduplicate caller's "next" array. We'll usually be
- * able to reuse that order PROC to merge the arrays together now. If not,
- * then we'll perform a separate ORDER proc lookup.
- *
- * If the opfamily doesn't supply a complete set of cross-type ORDER procs we
- * may not be able to determine which elements are contradictory. If we have
- * the required ORDER proc then we return true (and validly set *nelems_orig),
- * guaranteeing that at least the next array can be considered redundant. We
- * return false if the required comparisons cannot not be made (caller must
- * keep both arrays when this happens).
+ * Caller also passes associated scan key, which will have its argument set to
+ * the lowest/highest array value in passing.
*/
-static bool
-_bt_merge_arrays(IndexScanDesc scan, ScanKey skey, FmgrInfo *sortproc,
- bool reverse, Oid origelemtype, Oid nextelemtype,
- Datum *elems_orig, int *nelems_orig,
- Datum *elems_next, int nelems_next)
+static void
+_bt_array_set_low_or_high(Relation rel, ScanKey skey, BTArrayKeyInfo *array,
+ bool low_not_high)
{
- Relation rel = scan->indexRelation;
- BTScanOpaque so = (BTScanOpaque) scan->opaque;
- BTSortArrayContext cxt;
- int nelems_orig_start = *nelems_orig,
- nelems_orig_merged = 0;
- FmgrInfo *mergeproc = sortproc;
- FmgrInfo crosstypeproc;
+ Assert(skey->sk_flags & SK_SEARCHARRAY);
- Assert(skey->sk_strategy == BTEqualStrategyNumber);
- Assert(OidIsValid(origelemtype) && OidIsValid(nextelemtype));
-
- if (origelemtype != nextelemtype)
+ if (array->num_elems != -1)
{
- RegProcedure cmp_proc;
+ /* set low or high element for SAOP array */
+ int set_elem = 0;
+
+ Assert(!(skey->sk_flags & SK_BT_SKIP));
+
+ if (!low_not_high)
+ set_elem = array->num_elems - 1;
/*
- * Cross-array-element-type merging is required, so can't just reuse
- * sortproc when merging
+ * Just copy over array datum (only skip arrays require freeing and
+ * allocating memory for sk_argument)
*/
- cmp_proc = get_opfamily_proc(rel->rd_opfamily[skey->sk_attno - 1],
- origelemtype, nextelemtype, BTORDER_PROC);
- if (!RegProcedureIsValid(cmp_proc))
- {
- /* Can't make the required comparisons */
- return false;
- }
+ array->cur_elem = set_elem;
+ skey->sk_argument = array->elem_values[set_elem];
- /* We have all we need to determine redundancy/contradictoriness */
- mergeproc = &crosstypeproc;
- fmgr_info_cxt(cmp_proc, mergeproc, so->arrayContext);
+ return;
}
- cxt.sortproc = mergeproc;
- cxt.collation = skey->sk_collation;
- cxt.reverse = reverse;
+ /* set low or high element for skip array */
+ Assert(skey->sk_flags & SK_BT_SKIP);
+ Assert(array->num_elems == -1);
- for (int i = 0, j = 0; i < nelems_orig_start && j < nelems_next;)
- {
- Datum *oelem = elems_orig + i,
- *nelem = elems_next + j;
- int res = _bt_compare_array_elements(oelem, nelem, &cxt);
+ /* Free memory previously allocated for sk_argument if needed */
+ if (!array->attbyval && skey->sk_argument)
+ pfree(DatumGetPointer(skey->sk_argument));
- if (res == 0)
- {
- elems_orig[nelems_orig_merged++] = *oelem;
- i++;
- j++;
- }
- else if (res < 0)
- i++;
- else /* res > 0 */
- j++;
- }
+ /* Reset flags */
+ skey->sk_argument = (Datum) 0;
+ skey->sk_flags &= ~(SK_SEARCHNULL | SK_ISNULL |
+ SK_BT_MINVAL | SK_BT_MAXVAL |
+ SK_BT_NEXT | SK_BT_PRIOR);
- *nelems_orig = nelems_orig_merged;
-
- return true;
+ if (array->null_elem &&
+ (low_not_high == ((skey->sk_flags & SK_BT_NULLS_FIRST) != 0)))
+ {
+ /* Requested element (either lowest or highest) has the value NULL */
+ skey->sk_flags |= (SK_SEARCHNULL | SK_ISNULL);
+ }
+ else if (low_not_high)
+ {
+ /* Setting array to lowest element (according to low_compare) */
+ skey->sk_flags |= SK_BT_MINVAL;
+ }
+ else
+ {
+ /* Setting array to highest element (according to high_compare) */
+ skey->sk_flags |= SK_BT_MAXVAL;
+ }
}
/*
- * Compare an array scan key to a scalar scan key, eliminating contradictory
- * array elements such that the scalar scan key becomes redundant.
- *
- * Array elements can be eliminated as contradictory when excluded by some
- * other operator on the same attribute. For example, with an index scan qual
- * "WHERE a IN (1, 2, 3) AND a < 2", all array elements except the value "1"
- * are eliminated, and the < scan key is eliminated as redundant. Cases where
- * every array element is eliminated by a redundant scalar scan key have an
- * unsatisfiable qual, which we handle by setting *qual_ok=false for caller.
+ * _bt_array_decrement() -- decrement array scan key's sk_argument
*
- * If the opfamily doesn't supply a complete set of cross-type ORDER procs we
- * may not be able to determine which elements are contradictory. If we have
- * the required ORDER proc then we return true (and validly set *qual_ok),
- * guaranteeing that at least the scalar scan key can be considered redundant.
- * We return false if the comparison could not be made (caller must keep both
- * scan keys when this happens).
+ * Return value indicates whether caller's array was successfully decremented.
+ * Cannot decrement an array whose current element is already the first one.
*/
static bool
-_bt_compare_array_scankey_args(IndexScanDesc scan, ScanKey arraysk, ScanKey skey,
- FmgrInfo *orderproc, BTArrayKeyInfo *array,
- bool *qual_ok)
+_bt_array_decrement(Relation rel, ScanKey skey, BTArrayKeyInfo *array)
{
- Relation rel = scan->indexRelation;
- Oid opcintype = rel->rd_opcintype[arraysk->sk_attno - 1];
- int cmpresult = 0,
- cmpexact = 0,
- matchelem,
- new_nelems = 0;
- FmgrInfo crosstypeproc;
- FmgrInfo *orderprocp = orderproc;
-
- Assert(arraysk->sk_attno == skey->sk_attno);
- Assert(array->num_elems > 0);
- Assert(!(arraysk->sk_flags & (SK_ISNULL | SK_ROW_HEADER | SK_ROW_MEMBER)));
- Assert((arraysk->sk_flags & SK_SEARCHARRAY) &&
- arraysk->sk_strategy == BTEqualStrategyNumber);
- Assert(!(skey->sk_flags & (SK_ISNULL | SK_ROW_HEADER | SK_ROW_MEMBER)));
- Assert(!(skey->sk_flags & SK_SEARCHARRAY) ||
- skey->sk_strategy != BTEqualStrategyNumber);
+ bool uflow = false;
+ Datum dec_sk_argument;
- /*
- * _bt_binsrch_array_skey searches an array for the entry best matching a
- * datum of opclass input type for the index's attribute (on-disk type).
- * We can reuse the array's ORDER proc whenever the non-array scan key's
- * type is a match for the corresponding attribute's input opclass type.
- * Otherwise, we have to do another ORDER proc lookup so that our call to
- * _bt_binsrch_array_skey applies the correct comparator.
- *
- * Note: we have to support the convention that sk_subtype == InvalidOid
- * means the opclass input type; this is a hack to simplify life for
- * ScanKeyInit().
- */
- if (skey->sk_subtype != opcintype && skey->sk_subtype != InvalidOid)
- {
- RegProcedure cmp_proc;
- Oid arraysk_elemtype;
+ Assert(skey->sk_flags & SK_SEARCHARRAY);
+ Assert(!(skey->sk_flags & (SK_BT_MAXVAL | SK_BT_NEXT | SK_BT_PRIOR)));
- /*
- * Need an ORDER proc lookup to detect redundancy/contradictoriness
- * with this pair of scankeys.
- *
- * Scalar scan key's argument will be passed to _bt_compare_array_skey
- * as its tupdatum/lefthand argument (rhs arg is for array elements).
- */
- arraysk_elemtype = arraysk->sk_subtype;
- if (arraysk_elemtype == InvalidOid)
- arraysk_elemtype = rel->rd_opcintype[arraysk->sk_attno - 1];
- cmp_proc = get_opfamily_proc(rel->rd_opfamily[arraysk->sk_attno - 1],
- skey->sk_subtype, arraysk_elemtype,
- BTORDER_PROC);
- if (!RegProcedureIsValid(cmp_proc))
+ /* SAOP array? */
+ if (array->num_elems != -1)
+ {
+ Assert(!(skey->sk_flags & (SK_BT_SKIP | SK_BT_MINVAL | SK_BT_MAXVAL)));
+ if (array->cur_elem > 0)
{
- /* Can't make the comparison */
- *qual_ok = false; /* suppress compiler warnings */
- return false;
+ /*
+ * Just decrement current element, and assign its datum to skey
+ * (only skip arrays need us to free existing sk_argument memory)
+ */
+ array->cur_elem--;
+ skey->sk_argument = array->elem_values[array->cur_elem];
+
+ /* Successfully decremented array */
+ return true;
}
- /* We have all we need to determine redundancy/contradictoriness */
- orderprocp = &crosstypeproc;
- fmgr_info(cmp_proc, orderprocp);
+ /* Cannot decrement to before first array element */
+ return false;
}
- matchelem = _bt_binsrch_array_skey(orderprocp, false,
- NoMovementScanDirection,
- skey->sk_argument, false, array,
- arraysk, &cmpresult);
+ /* Nope, this is a skip array */
+ Assert(skey->sk_flags & SK_BT_SKIP);
- switch (skey->sk_strategy)
- {
- case BTLessStrategyNumber:
- cmpexact = 1; /* exclude exact match, if any */
- /* FALL THRU */
- case BTLessEqualStrategyNumber:
- if (cmpresult >= cmpexact)
- matchelem++;
- /* Resize, keeping elements from the start of the array */
- new_nelems = matchelem;
- break;
- case BTEqualStrategyNumber:
- if (cmpresult != 0)
- {
- /* qual is unsatisfiable */
- new_nelems = 0;
- }
- else
- {
- /* Shift matching element to the start of the array, resize */
- array->elem_values[0] = array->elem_values[matchelem];
- new_nelems = 1;
- }
- break;
- case BTGreaterEqualStrategyNumber:
- cmpexact = 1; /* include exact match, if any */
- /* FALL THRU */
- case BTGreaterStrategyNumber:
- if (cmpresult >= cmpexact)
- matchelem++;
- /* Shift matching elements to the start of the array, resize */
- new_nelems = array->num_elems - matchelem;
- memmove(array->elem_values, array->elem_values + matchelem,
- sizeof(Datum) * new_nelems);
- break;
- default:
- elog(ERROR, "unrecognized StrategyNumber: %d",
- (int) skey->sk_strategy);
- break;
- }
+ /*
+ * The sentinel value that represents the minimum value within the range
+ * of a skip array (often just -inf) is never decrementable
+ */
+ if (skey->sk_flags & SK_BT_MINVAL)
+ return false;
- Assert(new_nelems >= 0);
- Assert(new_nelems <= array->num_elems);
+ /*
+ * When the current array element is NULL, and the lowest sorting value in
+ * the index is also NULL, we cannot decrement before first array element
+ */
+ if ((skey->sk_flags & SK_ISNULL) && (skey->sk_flags & SK_BT_NULLS_FIRST))
+ return false;
- array->num_elems = new_nelems;
- *qual_ok = new_nelems > 0;
+ /*
+ * Opclasses without skip support "decrement" the scan key's current
+ * element by setting the PRIOR flag. The true prior value is determined
+ * by repositioning to the last index tuple < existing sk_argument/current
+ * array element. Note that this works in the usual way when the scan key
+ * is already marked ISNULL (i.e. when the current element is NULL).
+ */
+ if (!array->sksup)
+ {
+ /* Successfully "decremented" array */
+ skey->sk_flags |= SK_BT_PRIOR;
+ return true;
+ }
- return true;
-}
+ /*
+ * Opclasses with skip support directly decrement sk_argument
+ */
+ if (skey->sk_flags & SK_ISNULL)
+ {
+ Assert(!(skey->sk_flags & SK_BT_NULLS_FIRST));
-/*
- * qsort_arg comparator for sorting array elements
- */
-static int
-_bt_compare_array_elements(const void *a, const void *b, void *arg)
-{
- Datum da = *((const Datum *) a);
- Datum db = *((const Datum *) b);
- BTSortArrayContext *cxt = (BTSortArrayContext *) arg;
- int32 compare;
-
- compare = DatumGetInt32(FunctionCall2Coll(cxt->sortproc,
- cxt->collation,
- da, db));
- if (cxt->reverse)
- INVERT_COMPARE_RESULT(compare);
- return compare;
-}
+ /*
+ * Existing sk_argument/array element is NULL (for an IS NULL qual).
+ *
+ * "Decrement" from NULL to the high_elem value provided by opclass
+ * skip support routine.
+ */
+ skey->sk_flags &= ~(SK_SEARCHNULL | SK_ISNULL);
+ skey->sk_argument = datumCopy(array->sksup->high_elem,
+ array->attbyval, array->attlen);
+ return true;
+ }
-/*
- * _bt_compare_array_skey() -- apply array comparison function
- *
- * Compares caller's tuple attribute value to a scan key/array element.
- * Helper function used during binary searches of SK_SEARCHARRAY arrays.
- *
- * This routine returns:
- * <0 if tupdatum < arrdatum;
- * 0 if tupdatum == arrdatum;
- * >0 if tupdatum > arrdatum.
- *
- * This is essentially the same interface as _bt_compare: both functions
- * compare the value that they're searching for to a binary search pivot.
- * However, unlike _bt_compare, this function's "tuple argument" comes first,
- * while its "array/scankey argument" comes second.
-*/
-static inline int32
-_bt_compare_array_skey(FmgrInfo *orderproc,
- Datum tupdatum, bool tupnull,
- Datum arrdatum, ScanKey cur)
-{
- int32 result = 0;
+ /*
+ * Ask opclass support routine to provide decremented copy of existing
+ * non-NULL sk_argument
+ */
+ dec_sk_argument = array->sksup->decrement(rel, skey->sk_argument, &uflow);
+ if (unlikely(uflow))
+ {
+ /* dec_sk_argument has undefined value (so no pfree) */
+ if (array->null_elem && (skey->sk_flags & SK_BT_NULLS_FIRST))
+ {
+ _bt_skiparray_set_isnull(rel, skey, array);
- Assert(cur->sk_strategy == BTEqualStrategyNumber);
+ /* Successfully "decremented" array to NULL */
+ return true;
+ }
- if (tupnull) /* NULL tupdatum */
- {
- if (cur->sk_flags & SK_ISNULL)
- result = 0; /* NULL "=" NULL */
- else if (cur->sk_flags & SK_BT_NULLS_FIRST)
- result = -1; /* NULL "<" NOT_NULL */
- else
- result = 1; /* NULL ">" NOT_NULL */
- }
- else if (cur->sk_flags & SK_ISNULL) /* NOT_NULL tupdatum, NULL arrdatum */
- {
- if (cur->sk_flags & SK_BT_NULLS_FIRST)
- result = 1; /* NOT_NULL ">" NULL */
- else
- result = -1; /* NOT_NULL "<" NULL */
+ /* Cannot decrement to before first array element */
+ return false;
}
- else
+
+ /*
+ * Successfully decremented sk_argument to a non-NULL value. Make sure
+ * that the decremented value is still within the range of the array.
+ */
+ if (array->low_compare &&
+ !DatumGetBool(FunctionCall2Coll(&array->low_compare->sk_func,
+ array->low_compare->sk_collation,
+ dec_sk_argument,
+ array->low_compare->sk_argument)))
{
- /*
- * Like _bt_compare, we need to be careful of cross-type comparisons,
- * so the left value has to be the value that came from an index tuple
- */
- result = DatumGetInt32(FunctionCall2Coll(orderproc, cur->sk_collation,
- tupdatum, arrdatum));
+ /* Keep existing sk_argument after all */
+ if (!array->attbyval)
+ pfree(DatumGetPointer(dec_sk_argument));
- /*
- * We flip the sign by following the obvious rule: flip whenever the
- * column is a DESC column.
- *
- * _bt_compare does it the wrong way around (flip when *ASC*) in order
- * to compensate for passing its orderproc arguments backwards. We
- * don't need to play these games because we find it natural to pass
- * tupdatum as the left value (and arrdatum as the right value).
- */
- if (cur->sk_flags & SK_BT_DESC)
- INVERT_COMPARE_RESULT(result);
+ /* Cannot decrement to before first array element */
+ return false;
}
- return result;
+ /* Accept value returned by opclass decrement callback */
+ if (!array->attbyval && skey->sk_argument)
+ pfree(DatumGetPointer(skey->sk_argument));
+ skey->sk_argument = dec_sk_argument;
+
+ /* Successfully decremented array */
+ return true;
}
/*
- * _bt_binsrch_array_skey() -- Binary search for next matching array key
- *
- * Returns an index to the first array element >= caller's tupdatum argument.
- * This convention is more natural for forwards scan callers, but that can't
- * really matter to backwards scan callers. Both callers require handling for
- * the case where the match we return is < tupdatum, and symmetric handling
- * for the case where our best match is > tupdatum.
- *
- * Also sets *set_elem_result to the result _bt_compare_array_skey returned
- * when we used it to compare the matching array element to tupdatum/tupnull.
+ * _bt_array_increment() -- increment array scan key's sk_argument
*
- * cur_elem_trig indicates if array advancement was triggered by this array's
- * scan key, and that the array is for a required scan key. We can apply this
- * information to find the next matching array element in the current scan
- * direction using far fewer comparisons (fewer on average, compared to naive
- * binary search). This scheme takes advantage of an important property of
- * required arrays: required arrays always advance in lockstep with the index
- * scan's progress through the index's key space.
+ * Return value indicates whether caller's array was successfully incremented.
+ * Cannot increment an array whose current element is already the final one.
*/
-static int
-_bt_binsrch_array_skey(FmgrInfo *orderproc,
- bool cur_elem_trig, ScanDirection dir,
- Datum tupdatum, bool tupnull,
- BTArrayKeyInfo *array, ScanKey cur,
- int32 *set_elem_result)
+static bool
+_bt_array_increment(Relation rel, ScanKey skey, BTArrayKeyInfo *array)
{
- int low_elem = 0,
- mid_elem = -1,
- high_elem = array->num_elems - 1,
- result = 0;
- Datum arrdatum;
+ bool oflow = false;
+ Datum inc_sk_argument;
- Assert(cur->sk_flags & SK_SEARCHARRAY);
- Assert(cur->sk_strategy == BTEqualStrategyNumber);
+ Assert(skey->sk_flags & SK_SEARCHARRAY);
+ Assert(!(skey->sk_flags & (SK_BT_MINVAL | SK_BT_NEXT | SK_BT_PRIOR)));
- if (cur_elem_trig)
+ /* SAOP array? */
+ if (array->num_elems != -1)
{
- Assert(!ScanDirectionIsNoMovement(dir));
- Assert(cur->sk_flags & SK_BT_REQFWD);
-
- /*
- * When the scan key that triggered array advancement is a required
- * array scan key, it is now certain that the current array element
- * (plus all prior elements relative to the current scan direction)
- * cannot possibly be at or ahead of the corresponding tuple value.
- * (_bt_checkkeys must have called _bt_tuple_before_array_skeys, which
- * makes sure this is true as a condition of advancing the arrays.)
- *
- * This makes it safe to exclude array elements up to and including
- * the former-current array element from our search.
- *
- * Separately, when array advancement was triggered by a required scan
- * key, the array element immediately after the former-current element
- * is often either an exact tupdatum match, or a "close by" near-match
- * (a near-match tupdatum is one whose key space falls _between_ the
- * former-current and new-current array elements). We'll detect both
- * cases via an optimistic comparison of the new search lower bound
- * (or new search upper bound in the case of backwards scans).
- */
- if (ScanDirectionIsForward(dir))
+ Assert(!(skey->sk_flags & (SK_BT_SKIP | SK_BT_MINVAL | SK_BT_MAXVAL)));
+ if (array->cur_elem < array->num_elems - 1)
{
- low_elem = array->cur_elem + 1; /* old cur_elem exhausted */
+ /*
+ * Just increment current element, and assign its datum to skey
+ * (only skip arrays need us to free existing sk_argument memory)
+ */
+ array->cur_elem++;
+ skey->sk_argument = array->elem_values[array->cur_elem];
- /* Compare prospective new cur_elem (also the new lower bound) */
- if (high_elem >= low_elem)
- {
- arrdatum = array->elem_values[low_elem];
- result = _bt_compare_array_skey(orderproc, tupdatum, tupnull,
- arrdatum, cur);
+ /* Successfully incremented array */
+ return true;
+ }
- if (result <= 0)
- {
- /* Optimistic comparison optimization worked out */
- *set_elem_result = result;
- return low_elem;
- }
- mid_elem = low_elem;
- low_elem++; /* this cur_elem exhausted, too */
- }
+ /* Cannot increment past final array element */
+ return false;
+ }
- if (high_elem < low_elem)
- {
- /* Caller needs to perform "beyond end" array advancement */
- *set_elem_result = 1;
- return high_elem;
- }
- }
- else
- {
- high_elem = array->cur_elem - 1; /* old cur_elem exhausted */
+ /* Nope, this is a skip array */
+ Assert(skey->sk_flags & SK_BT_SKIP);
- /* Compare prospective new cur_elem (also the new upper bound) */
- if (high_elem >= low_elem)
- {
- arrdatum = array->elem_values[high_elem];
- result = _bt_compare_array_skey(orderproc, tupdatum, tupnull,
- arrdatum, cur);
+ /*
+ * The sentinel value that represents the maximum value within the range
+ * of a skip array (often just +inf) is never incrementable
+ */
+ if (skey->sk_flags & SK_BT_MAXVAL)
+ return false;
- if (result >= 0)
- {
- /* Optimistic comparison optimization worked out */
- *set_elem_result = result;
- return high_elem;
- }
- mid_elem = high_elem;
- high_elem--; /* this cur_elem exhausted, too */
- }
+ /*
+ * When the current array element is NULL, and the highest sorting value
+ * in the index is also NULL, we cannot increment past the final element
+ */
+ if ((skey->sk_flags & SK_ISNULL) && !(skey->sk_flags & SK_BT_NULLS_FIRST))
+ return false;
- if (high_elem < low_elem)
- {
- /* Caller needs to perform "beyond end" array advancement */
- *set_elem_result = -1;
- return low_elem;
- }
- }
+ /*
+ * Opclasses without skip support "increment" the scan key's current
+ * element by setting the NEXT flag. The true next value is determined by
+ * repositioning to the first index tuple > existing sk_argument/current
+ * array element. Note that this works in the usual way when the scan key
+ * is already marked ISNULL (i.e. when the current element is NULL).
+ */
+ if (!array->sksup)
+ {
+ /* Successfully "incremented" array */
+ skey->sk_flags |= SK_BT_NEXT;
+ return true;
}
- while (high_elem > low_elem)
+ /*
+ * Opclasses with skip support directly increment sk_argument
+ */
+ if (skey->sk_flags & SK_ISNULL)
{
- mid_elem = low_elem + ((high_elem - low_elem) / 2);
- arrdatum = array->elem_values[mid_elem];
+ Assert(skey->sk_flags & SK_BT_NULLS_FIRST);
- result = _bt_compare_array_skey(orderproc, tupdatum, tupnull,
- arrdatum, cur);
+ /*
+ * Existing sk_argument/array element is NULL (for an IS NULL qual).
+ *
+ * "Increment" from NULL to the low_elem value provided by opclass
+ * skip support routine.
+ */
+ skey->sk_flags &= ~(SK_SEARCHNULL | SK_ISNULL);
+ skey->sk_argument = datumCopy(array->sksup->low_elem,
+ array->attbyval, array->attlen);
+ return true;
+ }
- if (result == 0)
+ /*
+ * Ask opclass support routine to provide incremented copy of existing
+ * non-NULL sk_argument
+ */
+ inc_sk_argument = array->sksup->increment(rel, skey->sk_argument, &oflow);
+ if (unlikely(oflow))
+ {
+ /* inc_sk_argument has undefined value (so no pfree) */
+ if (array->null_elem && !(skey->sk_flags & SK_BT_NULLS_FIRST))
{
- /*
- * It's safe to quit as soon as we see an equal array element.
- * This often saves an extra comparison or two...
- */
- low_elem = mid_elem;
- break;
+ _bt_skiparray_set_isnull(rel, skey, array);
+
+ /* Successfully "incremented" array to NULL */
+ return true;
}
- if (result > 0)
- low_elem = mid_elem + 1;
- else
- high_elem = mid_elem;
+ /* Cannot increment past final array element */
+ return false;
}
/*
- * ...but our caller also cares about how its searched-for tuple datum
- * compares to the low_elem datum. Must always set *set_elem_result with
- * the result of that comparison specifically.
+ * Successfully incremented sk_argument to a non-NULL value. Make sure
+ * that the incremented value is still within the range of the array.
*/
- if (low_elem != mid_elem)
- result = _bt_compare_array_skey(orderproc, tupdatum, tupnull,
- array->elem_values[low_elem], cur);
-
- *set_elem_result = result;
-
- return low_elem;
-}
-
-/*
- * _bt_start_array_keys() -- Initialize array keys at start of a scan
- *
- * Set up the cur_elem counters and fill in the first sk_argument value for
- * each array scankey.
- */
-void
-_bt_start_array_keys(IndexScanDesc scan, ScanDirection dir)
-{
- BTScanOpaque so = (BTScanOpaque) scan->opaque;
- int i;
-
- Assert(so->numArrayKeys);
- Assert(so->qual_ok);
-
- for (i = 0; i < so->numArrayKeys; i++)
+ if (array->high_compare &&
+ !DatumGetBool(FunctionCall2Coll(&array->high_compare->sk_func,
+ array->high_compare->sk_collation,
+ inc_sk_argument,
+ array->high_compare->sk_argument)))
{
- BTArrayKeyInfo *curArrayKey = &so->arrayKeys[i];
- ScanKey skey = &so->keyData[curArrayKey->scan_key];
+ /* Keep existing sk_argument after all */
+ if (!array->attbyval)
+ pfree(DatumGetPointer(inc_sk_argument));
- Assert(curArrayKey->num_elems > 0);
- Assert(skey->sk_flags & SK_SEARCHARRAY);
-
- if (ScanDirectionIsBackward(dir))
- curArrayKey->cur_elem = curArrayKey->num_elems - 1;
- else
- curArrayKey->cur_elem = 0;
- skey->sk_argument = curArrayKey->elem_values[curArrayKey->cur_elem];
+ /* Cannot increment past final array element */
+ return false;
}
- so->scanBehind = false;
+
+ /* Accept value returned by opclass increment callback */
+ if (!array->attbyval && skey->sk_argument)
+ pfree(DatumGetPointer(skey->sk_argument));
+ skey->sk_argument = inc_sk_argument;
+
+ /* Successfully incremented array */
+ return true;
}
/*
@@ -1378,8 +973,10 @@ _bt_start_array_keys(IndexScanDesc scan, ScanDirection dir)
* advanced (every array remains at its final element for scan direction).
*/
static bool
-_bt_advance_array_keys_increment(IndexScanDesc scan, ScanDirection dir)
+_bt_advance_array_keys_increment(IndexScanDesc scan, ScanDirection dir,
+ bool *skip_array_set)
{
+ Relation rel = scan->indexRelation;
BTScanOpaque so = (BTScanOpaque) scan->opaque;
/*
@@ -1389,115 +986,55 @@ _bt_advance_array_keys_increment(IndexScanDesc scan, ScanDirection dir)
*/
for (int i = so->numArrayKeys - 1; i >= 0; i--)
{
- BTArrayKeyInfo *curArrayKey = &so->arrayKeys[i];
- ScanKey skey = &so->keyData[curArrayKey->scan_key];
- int cur_elem = curArrayKey->cur_elem;
- int num_elems = curArrayKey->num_elems;
- bool rolled = false;
+ BTArrayKeyInfo *array = &so->arrayKeys[i];
+ ScanKey skey = &so->keyData[array->scan_key];
- if (ScanDirectionIsForward(dir) && ++cur_elem >= num_elems)
+ if (array->num_elems == -1)
+ *skip_array_set = true;
+
+ if (ScanDirectionIsForward(dir))
{
- cur_elem = 0;
- rolled = true;
+ if (_bt_array_increment(rel, skey, array))
+ return true;
}
- else if (ScanDirectionIsBackward(dir) && --cur_elem < 0)
+ else
{
- cur_elem = num_elems - 1;
- rolled = true;
+ if (_bt_array_decrement(rel, skey, array))
+ return true;
}
- curArrayKey->cur_elem = cur_elem;
- skey->sk_argument = curArrayKey->elem_values[cur_elem];
- if (!rolled)
- return true;
+ /*
+ * Couldn't increment (or decrement) array. Handle array roll over.
+ *
+ * Start over at the array's lowest sorting value (or its highest
+ * value, for backward scans)...
+ */
+ _bt_array_set_low_or_high(rel, skey, array,
+ ScanDirectionIsForward(dir));
- /* Need to advance next array key, if any */
+ /* ...then increment (or decrement) next most significant array */
}
/*
- * The array keys are now exhausted. (There isn't actually a distinct
- * state that represents array exhaustion, since index scans don't always
- * end after btgettuple returns "false".)
+ * The array keys are now exhausted.
*
* Restore the array keys to the state they were in immediately before we
* were called. This ensures that the arrays only ever ratchet in the
- * current scan direction. Without this, scans would overlook matching
- * tuples if and when the scan's direction was subsequently reversed.
+ * current scan direction.
+ *
+ * Without this, scans could overlook matching tuples when the scan
+ * direction gets reversed just before btgettuple runs out of items to
+ * return, but just after _bt_readpage prepares all the items from the
+ * scan's final page in so->currPos. When we're on the final page it is
+ * typical for so->currPos to get invalidated once btgettuple finally
+ * returns false, which'll effectively invalidate the scan's array keys.
+ * That hasn't happened yet, though -- and in general it may never happen.
*/
_bt_start_array_keys(scan, -dir);
return false;
}
-/*
- * _bt_rewind_nonrequired_arrays() -- Rewind non-required arrays
- *
- * Called when _bt_advance_array_keys decides to start a new primitive index
- * scan on the basis of the current scan position being before the position
- * that _bt_first is capable of repositioning the scan to by applying an
- * inequality operator required in the opposite-to-scan direction only.
- *
- * Although equality strategy scan keys (for both arrays and non-arrays alike)
- * are either marked required in both directions or in neither direction,
- * there is a sense in which non-required arrays behave like required arrays.
- * With a qual such as "WHERE a IN (100, 200) AND b >= 3 AND c IN (5, 6, 7)",
- * the scan key on "c" is non-required, but nevertheless enables positioning
- * the scan at the first tuple >= "(100, 3, 5)" on the leaf level during the
- * first descent of the tree by _bt_first. Later on, there could also be a
- * second descent, that places the scan right before tuples >= "(200, 3, 5)".
- * _bt_first must never be allowed to build an insertion scan key whose "c"
- * entry is set to a value other than 5, the "c" array's first element/value.
- * (Actually, it's the first in the current scan direction. This example uses
- * a forward scan.)
- *
- * Calling here resets the array scan key elements for the scan's non-required
- * arrays. This is strictly necessary for correctness in a subset of cases
- * involving "required in opposite direction"-triggered primitive index scans.
- * Not all callers are at risk of _bt_first using a non-required array like
- * this, but advancement always resets the arrays when another primitive scan
- * is scheduled, just to keep things simple. Array advancement even makes
- * sure to reset non-required arrays during scans that have no inequalities.
- * (Advancement still won't call here when there are no inequalities, though
- * that's just because it's all handled indirectly instead.)
- *
- * Note: _bt_verify_arrays_bt_first is called by an assertion to enforce that
- * everybody got this right.
- */
-static void
-_bt_rewind_nonrequired_arrays(IndexScanDesc scan, ScanDirection dir)
-{
- BTScanOpaque so = (BTScanOpaque) scan->opaque;
- int arrayidx = 0;
-
- for (int ikey = 0; ikey < so->numberOfKeys; ikey++)
- {
- ScanKey cur = so->keyData + ikey;
- BTArrayKeyInfo *array = NULL;
- int first_elem_dir;
-
- if (!(cur->sk_flags & SK_SEARCHARRAY) ||
- cur->sk_strategy != BTEqualStrategyNumber)
- continue;
-
- array = &so->arrayKeys[arrayidx++];
- Assert(array->scan_key == ikey);
-
- if ((cur->sk_flags & (SK_BT_REQFWD | SK_BT_REQBKWD)))
- continue;
-
- if (ScanDirectionIsForward(dir))
- first_elem_dir = 0;
- else
- first_elem_dir = array->num_elems - 1;
-
- if (array->cur_elem != first_elem_dir)
- {
- array->cur_elem = first_elem_dir;
- cur->sk_argument = array->elem_values[first_elem_dir];
- }
- }
-}
-
/*
* _bt_tuple_before_array_skeys() -- too early to advance required arrays?
*
@@ -1507,7 +1044,7 @@ _bt_rewind_nonrequired_arrays(IndexScanDesc scan, ScanDirection dir)
*
* readpagetup callers must only call here when _bt_check_compare already set
* continuescan=false. We help these callers deal with _bt_check_compare's
- * inability to distinguishing between the < and > cases (it uses equality
+ * inability to distinguish between the < and > cases (it uses equality
* operator scan keys, whereas we use 3-way ORDER procs). These callers pass
* a _bt_check_compare-set sktrig value that indicates which scan key
* triggered the call (!readpagetup callers just pass us sktrig=0 instead).
@@ -1617,11 +1154,79 @@ _bt_tuple_before_array_skeys(IndexScanDesc scan, ScanDirection dir,
continue;
}
- tupdatum = index_getattr(tuple, cur->sk_attno, tupdesc, &tupnull);
+ tupdatum = index_getattr(tuple, cur->sk_attno, tupdesc, &tupnull);
+
+ if (likely(!(cur->sk_flags & (SK_BT_MINVAL | SK_BT_MAXVAL))))
+ {
+ /* Scankey has a valid/comparable sk_argument value */
+ result = _bt_compare_array_skey(&so->orderProcs[ikey],
+ tupdatum, tupnull,
+ cur->sk_argument, cur);
+
+ if (result == 0)
+ {
+ /*
+ * Interpret result in a way that takes NEXT/PRIOR into
+ * account
+ */
+ if (cur->sk_flags & SK_BT_NEXT)
+ result = -1;
+ else if (cur->sk_flags & SK_BT_PRIOR)
+ result = 1;
+
+ Assert(result == 0 || (cur->sk_flags & SK_BT_SKIP));
+ }
+ }
+ else
+ {
+ BTArrayKeyInfo *array = NULL;
+
+ /*
+ * Current array element/array = scan key value is a sentinel
+ * value that represents the lowest (or highest) possible value
+ * that's still within the range of the array.
+ *
+ * Like _bt_first, we only see MINVAL keys during forwards scans
+ * (and similarly only see MAXVAL keys during backwards scans).
+ * Even if the scan's direction changes, we'll stop at some higher
+ * order key before we can ever reach any MAXVAL (or MINVAL) keys.
+ * (However, unlike _bt_first we _can_ get to keys marked either
+ * NEXT or PRIOR, regardless of the scan's current direction.)
+ */
+ Assert(ScanDirectionIsForward(dir) ?
+ !(cur->sk_flags & SK_BT_MAXVAL) :
+ !(cur->sk_flags & SK_BT_MINVAL));
+
+ /*
+ * There are no valid sk_argument values in MINVAL/MAXVAL keys.
+ * Check if tupdatum is within the range of skip array instead.
+ */
+ for (int arrayidx = 0; arrayidx < so->numArrayKeys; arrayidx++)
+ {
+ array = &so->arrayKeys[arrayidx];
+ if (array->scan_key == ikey)
+ break;
+ }
+
+ _bt_binsrch_skiparray_skey(false, dir, tupdatum, tupnull,
+ array, cur, &result);
- result = _bt_compare_array_skey(&so->orderProcs[ikey],
- tupdatum, tupnull,
- cur->sk_argument, cur);
+ if (result == 0)
+ {
+ /*
+ * tupdatum satisfies both low_compare and high_compare, so
+ * it's time to advance the array keys.
+ *
+ * Note: It's possible that the skip array will "advance" from
+ * its MINVAL (or MAXVAL) representation to an alternative,
+ * logically equivalent representation of the same value: a
+ * representation where the = key gets a valid datum in its
+ * sk_argument. This is only possible when low_compare uses
+ * the >= strategy (or high_compare uses the <= strategy).
+ */
+ return false;
+ }
+ }
/*
* Does this comparison indicate that caller must _not_ advance the
@@ -1671,8 +1276,7 @@ _bt_start_prim_scan(IndexScanDesc scan, ScanDirection dir)
Assert(so->numArrayKeys);
- /* scanBehind flag doesn't persist across primitive index scans - reset */
- so->scanBehind = false;
+ so->scanBehind = so->oppositeDirCheck = false; /* reset */
/*
* Array keys are advanced within _bt_checkkeys when the scan reaches the
@@ -1710,8 +1314,6 @@ _bt_start_prim_scan(IndexScanDesc scan, ScanDirection dir)
*/
if (so->needPrimScan)
{
- Assert(_bt_verify_arrays_bt_first(scan, dir));
-
/*
* Flag was set -- must call _bt_first again, which will reset the
* scan's needPrimScan flag
@@ -1758,9 +1360,10 @@ _bt_start_prim_scan(IndexScanDesc scan, ScanDirection dir)
* postcondition's <= operator with a >=. In other words, just swap the
* precondition with the postcondition.)
*
- * We also deal with "advancing" non-required arrays here. Callers whose
- * sktrig scan key is non-required specify sktrig_required=false. These calls
- * are the only exception to the general rule about always advancing the
+ * We also deal with "advancing" non-required arrays here (or arrays that are
+ * treated as non-required for the duration of a _bt_readpage call). Callers
+ * whose sktrig scan key is non-required specify sktrig_required=false. These
+ * calls are the only exception to the general rule about always advancing the
* required array keys (the scan may not even have a required array). These
* callers should just pass a NULL pstate (since there is never any question
* of stopping the scan). No call to _bt_tuple_before_array_skeys is required
@@ -1792,14 +1395,17 @@ _bt_advance_array_keys(IndexScanDesc scan, BTReadPageState *pstate,
{
BTScanOpaque so = (BTScanOpaque) scan->opaque;
Relation rel = scan->indexRelation;
- ScanDirection dir = pstate ? pstate->dir : ForwardScanDirection;
+ ScanDirection dir = so->currPos.dir;
int arrayidx = 0;
bool beyond_end_advance = false,
+ skip_array_advanced = false,
has_required_opposite_direction_only = false,
- oppodir_inequality_sktrig = false,
all_required_satisfied = true,
all_satisfied = true;
+ Assert(!so->needPrimScan && !so->scanBehind && !so->oppositeDirCheck);
+ Assert(_bt_verify_keys_with_arraykeys(scan));
+
if (sktrig_required)
{
/*
@@ -1808,19 +1414,6 @@ _bt_advance_array_keys(IndexScanDesc scan, BTReadPageState *pstate,
Assert(!_bt_tuple_before_array_skeys(scan, dir, tuple, tupdesc,
tupnatts, false, 0, NULL));
- so->scanBehind = false; /* reset */
-
- /*
- * Required scan key wasn't satisfied, so required arrays will have to
- * advance. Invalidate page-level state that tracks whether the
- * scan's required-in-opposite-direction-only keys are known to be
- * satisfied by page's remaining tuples.
- */
- pstate->firstmatch = false;
-
- /* Shouldn't have to invalidate 'prechecked', though */
- Assert(!pstate->prechecked);
-
/*
* Once we return we'll have a new set of required array keys, so
* reset state used by "look ahead" optimization
@@ -1828,8 +1421,26 @@ _bt_advance_array_keys(IndexScanDesc scan, BTReadPageState *pstate,
pstate->rechecks = 0;
pstate->targetdistance = 0;
}
+ else if (sktrig < so->numberOfKeys - 1 &&
+ !(so->keyData[so->numberOfKeys - 1].sk_flags & SK_SEARCHARRAY))
+ {
+ int least_sign_ikey = so->numberOfKeys - 1;
+ bool continuescan;
- Assert(_bt_verify_keys_with_arraykeys(scan));
+ /*
+ * Optimization: perform a precheck of the least significant key
+ * during !sktrig_required calls when it isn't already our sktrig
+ * (provided the precheck key is not itself an array).
+ *
+ * When the precheck works out we'll avoid an expensive binary search
+ * of sktrig's array (plus any other arrays before least_sign_ikey).
+ */
+ Assert(so->keyData[sktrig].sk_flags & SK_SEARCHARRAY);
+ if (!_bt_check_compare(scan, dir, tuple, tupnatts, tupdesc, false,
+ false, &continuescan,
+ &least_sign_ikey))
+ return false;
+ }
for (int ikey = 0; ikey < so->numberOfKeys; ikey++)
{
@@ -1871,8 +1482,6 @@ _bt_advance_array_keys(IndexScanDesc scan, BTReadPageState *pstate,
if (cur->sk_flags & (SK_BT_REQFWD | SK_BT_REQBKWD))
{
- Assert(sktrig_required);
-
required = true;
if (cur->sk_attno > tupnatts)
@@ -1912,18 +1521,6 @@ _bt_advance_array_keys(IndexScanDesc scan, BTReadPageState *pstate,
beyond_end_advance = true;
all_satisfied = all_required_satisfied = false;
- /*
- * Set a flag that remembers that this was an inequality required
- * in the opposite scan direction only, that nevertheless
- * triggered the call here.
- *
- * This only happens when an inequality operator (which must be
- * strict) encounters a group of NULLs that indicate the end of
- * non-NULL values for tuples in the current scan direction.
- */
- if (unlikely(required_opposite_direction_only))
- oppodir_inequality_sktrig = true;
-
continue;
}
@@ -1954,18 +1551,9 @@ _bt_advance_array_keys(IndexScanDesc scan, BTReadPageState *pstate,
*/
if (beyond_end_advance)
{
- int final_elem_dir;
-
- if (ScanDirectionIsBackward(dir) || !array)
- final_elem_dir = 0;
- else
- final_elem_dir = array->num_elems - 1;
-
- if (array && array->cur_elem != final_elem_dir)
- {
- array->cur_elem = final_elem_dir;
- cur->sk_argument = array->elem_values[final_elem_dir];
- }
+ if (array)
+ _bt_array_set_low_or_high(rel, cur, array,
+ ScanDirectionIsBackward(dir));
continue;
}
@@ -1990,18 +1578,9 @@ _bt_advance_array_keys(IndexScanDesc scan, BTReadPageState *pstate,
*/
if (!all_required_satisfied || cur->sk_attno > tupnatts)
{
- int first_elem_dir;
-
- if (ScanDirectionIsForward(dir) || !array)
- first_elem_dir = 0;
- else
- first_elem_dir = array->num_elems - 1;
-
- if (array && array->cur_elem != first_elem_dir)
- {
- array->cur_elem = first_elem_dir;
- cur->sk_argument = array->elem_values[first_elem_dir];
- }
+ if (array)
+ _bt_array_set_low_or_high(rel, cur, array,
+ ScanDirectionIsForward(dir));
continue;
}
@@ -2017,18 +1596,26 @@ _bt_advance_array_keys(IndexScanDesc scan, BTReadPageState *pstate,
bool cur_elem_trig = (sktrig_required && ikey == sktrig);
/*
- * Binary search for closest match that's available from the array
+ * "Binary search" by checking if tupdatum/tupnull are within the
+ * range of the skip array
*/
- set_elem = _bt_binsrch_array_skey(&so->orderProcs[ikey],
- cur_elem_trig, dir,
- tupdatum, tupnull, array, cur,
- &result);
+ if (array->num_elems == -1)
+ _bt_binsrch_skiparray_skey(cur_elem_trig, dir,
+ tupdatum, tupnull, array, cur,
+ &result);
- Assert(set_elem >= 0 && set_elem < array->num_elems);
+ /*
+ * Binary search for the closest match from the SAOP array
+ */
+ else
+ set_elem = _bt_binsrch_array_skey(&so->orderProcs[ikey],
+ cur_elem_trig, dir,
+ tupdatum, tupnull, array, cur,
+ &result);
}
else
{
- Assert(sktrig_required && required);
+ Assert(required);
/*
* This is a required non-array equality strategy scan key, which
@@ -2070,7 +1657,7 @@ _bt_advance_array_keys(IndexScanDesc scan, BTReadPageState *pstate,
* be eliminated by _bt_preprocess_keys. It won't matter if some of
* our "true" array scan keys (or even all of them) are non-required.
*/
- if (required &&
+ if (sktrig_required && required &&
((ScanDirectionIsForward(dir) && result > 0) ||
(ScanDirectionIsBackward(dir) && result < 0)))
beyond_end_advance = true;
@@ -2085,7 +1672,7 @@ _bt_advance_array_keys(IndexScanDesc scan, BTReadPageState *pstate,
* array scan keys are considered interesting.)
*/
all_satisfied = false;
- if (required)
+ if (sktrig_required && required)
all_required_satisfied = false;
else
{
@@ -2100,11 +1687,22 @@ _bt_advance_array_keys(IndexScanDesc scan, BTReadPageState *pstate,
}
}
- /* Advance array keys, even when set_elem isn't an exact match */
- if (array && array->cur_elem != set_elem)
+ /* Advance array keys, even when we don't have an exact match */
+ if (array)
{
- array->cur_elem = set_elem;
- cur->sk_argument = array->elem_values[set_elem];
+ if (array->num_elems == -1)
+ {
+ /* Skip array's new element is tupdatum (or MINVAL/MAXVAL) */
+ _bt_skiparray_set_element(rel, cur, array, result,
+ tupdatum, tupnull);
+ skip_array_advanced = true;
+ }
+ else if (array->cur_elem != set_elem)
+ {
+ /* SAOP array's new element is set_elem datum */
+ array->cur_elem = set_elem;
+ cur->sk_argument = array->elem_values[set_elem];
+ }
}
}
@@ -2114,11 +1712,19 @@ _bt_advance_array_keys(IndexScanDesc scan, BTReadPageState *pstate,
* higher-order arrays (might exhaust all the scan's arrays instead, which
* ends the top-level scan).
*/
- if (beyond_end_advance && !_bt_advance_array_keys_increment(scan, dir))
+ if (beyond_end_advance &&
+ !_bt_advance_array_keys_increment(scan, dir, &skip_array_advanced))
goto end_toplevel_scan;
Assert(_bt_verify_keys_with_arraykeys(scan));
+ /*
+ * Maintain a page-level count of the number of times the scan's array
+ * keys advanced in a way that affected at least one skip array
+ */
+ if (sktrig_required && skip_array_advanced)
+ pstate->nskipadvances++;
+
/*
* Does tuple now satisfy our new qual? Recheck with _bt_check_compare.
*
@@ -2135,6 +1741,12 @@ _bt_advance_array_keys(IndexScanDesc scan, BTReadPageState *pstate,
* of any required scan key). All that matters is whether caller's tuple
* satisfies the new qual, so it's safe to just skip the _bt_check_compare
* recheck when we've already determined that it can only return 'false'.
+ *
+ * Note: In practice most scan keys are marked required by preprocessing,
+ * if necessary by generating a preceding skip array. We nevertheless
+ * often handle array keys marked required as if they were nonrequired.
+ * This behavior is requested by our _bt_check_compare caller, though only
+ * when it is passed "forcenonrequired=true" by _bt_checkkeys.
*/
if ((sktrig_required && all_required_satisfied) ||
(!sktrig_required && all_satisfied))
@@ -2145,9 +1757,9 @@ _bt_advance_array_keys(IndexScanDesc scan, BTReadPageState *pstate,
Assert(all_required_satisfied);
/* Recheck _bt_check_compare on behalf of caller */
- if (_bt_check_compare(scan, dir, tuple, tupnatts, tupdesc,
- false, false, false,
- &continuescan, &nsktrig) &&
+ if (_bt_check_compare(scan, dir, tuple, tupnatts, tupdesc, false,
+ !sktrig_required, &continuescan,
+ &nsktrig) &&
!so->scanBehind)
{
/* This tuple satisfies the new qual */
@@ -2228,10 +1840,7 @@ _bt_advance_array_keys(IndexScanDesc scan, BTReadPageState *pstate,
* Note: we don't just quit at this point when all required scan keys were
* found to be satisfied because we need to consider edge-cases involving
* scan keys required in the opposite direction only; those aren't tracked
- * by all_required_satisfied. (Actually, oppodir_inequality_sktrig trigger
- * scan keys are tracked by all_required_satisfied, since it's convenient
- * for _bt_check_compare to behave as if they are required in the current
- * scan direction to deal with NULLs. We'll account for that separately.)
+ * by all_required_satisfied.
*/
Assert(_bt_tuple_before_array_skeys(scan, dir, tuple, tupdesc, tupnatts,
false, 0, NULL) ==
@@ -2265,7 +1874,7 @@ _bt_advance_array_keys(IndexScanDesc scan, BTReadPageState *pstate,
/*
* When we encounter a truncated finaltup high key attribute, we're
* optimistic about the chances of its corresponding required scan key
- * being satisfied when we go on to check it against tuples from this
+ * being satisfied when we go on to recheck it against tuples from this
* page's right sibling leaf page. We consider truncated attributes to be
* satisfied by required scan keys, which allows the primitive index scan
* to continue to the next leaf page. We must set so->scanBehind to true
@@ -2273,7 +1882,7 @@ _bt_advance_array_keys(IndexScanDesc scan, BTReadPageState *pstate,
* keys for one or more truncated attribute values (scan keys required in
* _either_ scan direction).
*
- * There is a chance that _bt_checkkeys (which checks so->scanBehind) will
+ * There is a chance that _bt_readpage (which checks so->scanBehind) will
* find that even the sibling leaf page's finaltup is < the new array
* keys. When that happens, our optimistic policy will have incurred a
* single extra leaf page access that could have been avoided.
@@ -2285,27 +1894,12 @@ _bt_advance_array_keys(IndexScanDesc scan, BTReadPageState *pstate,
* Being pessimistic would also give some scans with non-required arrays a
* perverse advantage over similar scans that use required arrays instead.
*
- * You can think of this as a speculative bet on what the scan is likely
- * to find on the next page. It's not much of a gamble, though, since the
- * untruncated prefix of attributes must strictly satisfy the new qual
- * (though it's okay if any non-required scan keys fail to be satisfied).
+ * This is similar to our scan-level heuristics, below. They also set
+ * scanBehind to speculatively continue the primscan onto the next page.
*/
- if (so->scanBehind && has_required_opposite_direction_only)
+ if (so->scanBehind)
{
- /*
- * However, we avoid this behavior whenever the scan involves a scan
- * key required in the opposite direction to the scan only, along with
- * a finaltup with at least one truncated attribute that's associated
- * with a scan key marked required (required in either direction).
- *
- * _bt_check_compare simply won't stop the scan for a scan key that's
- * marked required in the opposite scan direction only. That leaves
- * us without any reliable way of reconsidering any opposite-direction
- * inequalities if it turns out that starting a new primitive index
- * scan will allow _bt_first to skip ahead by a great many leaf pages
- * (see next section for details of how that works).
- */
- goto new_prim_scan;
+ /* Truncated high key -- _bt_scanbehind_checkkeys recheck scheduled */
}
/*
@@ -2330,78 +1924,24 @@ _bt_advance_array_keys(IndexScanDesc scan, BTReadPageState *pstate,
* (primitive) scan. If this happens at the start of a large group of
* NULL values, then we shouldn't expect to be called again until after
* the scan has already read indefinitely-many leaf pages full of tuples
- * with NULL suffix values. We need a separate test for this case so that
- * we don't miss our only opportunity to skip over such a group of pages.
- * (_bt_first is expected to skip over the group of NULLs by applying a
- * similar "deduce NOT NULL" rule, where it finishes its insertion scan
- * key by consing up an explicit SK_SEARCHNOTNULL key.)
+ * with NULL suffix values. (_bt_first is expected to skip over the group
+ * of NULLs by applying a similar "deduce NOT NULL" rule of its own, which
+ * involves consing up an explicit SK_SEARCHNOTNULL key.)
*
- * Apply a test against finaltup to detect and recover from these problem:
+ * Apply a test against finaltup to detect and recover from the problem:
* if even finaltup doesn't satisfy such an inequality, we just skip by
* starting a new primitive index scan. When we skip, we know for sure
* that all of the tuples on the current page following caller's tuple are
* also before the _bt_first-wise start of tuples for our new qual. That
* at least suggests many more skippable pages beyond the current page.
+ * (when so->scanBehind and so->oppositeDirCheck are set, this'll happen
+ * when we test the next page's finaltup/high key instead.)
*/
- if (has_required_opposite_direction_only && pstate->finaltup &&
- (all_required_satisfied || oppodir_inequality_sktrig))
- {
- int nfinaltupatts = BTreeTupleGetNAtts(pstate->finaltup, rel);
- ScanDirection flipped;
- bool continuescanflip;
- int opsktrig;
-
- /*
- * We're checking finaltup (which is usually not caller's tuple), so
- * cannot reuse work from caller's earlier _bt_check_compare call.
- *
- * Flip the scan direction when calling _bt_check_compare this time,
- * so that it will set continuescanflip=false when it encounters an
- * inequality required in the opposite scan direction.
- */
- Assert(!so->scanBehind);
- opsktrig = 0;
- flipped = -dir;
- _bt_check_compare(scan, flipped,
- pstate->finaltup, nfinaltupatts, tupdesc,
- false, false, false,
- &continuescanflip, &opsktrig);
-
- /*
- * If we ended up here due to the all_required_satisfied criteria,
- * test opsktrig in a way that ensures that finaltup contains the same
- * prefix of key columns as caller's tuple (a prefix that satisfies
- * earlier required-in-current-direction scan keys).
- *
- * If we ended up here due to the oppodir_inequality_sktrig criteria,
- * test opsktrig in a way that ensures that the same scan key that our
- * caller found to be unsatisfied (by the scan's tuple) was also the
- * one unsatisfied just now (by finaltup). That way we'll only start
- * a new primitive scan when we're sure that both tuples _don't_ share
- * the same prefix of satisfied equality-constrained attribute values,
- * and that finaltup has a non-NULL attribute value indicated by the
- * unsatisfied scan key at offset opsktrig/sktrig. (This depends on
- * _bt_check_compare not caring about the direction that inequalities
- * are required in whenever NULL attribute values are unsatisfied. It
- * only cares about the scan direction, and its relationship to
- * whether NULLs are stored first or last relative to non-NULLs.)
- */
- Assert(all_required_satisfied != oppodir_inequality_sktrig);
- if (unlikely(!continuescanflip &&
- ((all_required_satisfied && opsktrig > sktrig) ||
- (oppodir_inequality_sktrig && opsktrig >= sktrig))))
- {
- Assert(so->keyData[opsktrig].sk_strategy != BTEqualStrategyNumber);
-
- /*
- * Make sure that any non-required arrays are set to the first
- * array element for the current scan direction
- */
- _bt_rewind_nonrequired_arrays(scan, dir);
+ else if (has_required_opposite_direction_only && pstate->finaltup &&
+ unlikely(!_bt_oppodir_checkkeys(scan, dir, pstate->finaltup)))
+ goto new_prim_scan;
- goto new_prim_scan;
- }
- }
+continue_scan:
/*
* Stick with the ongoing primitive index scan for now.
@@ -2421,625 +1961,110 @@ _bt_advance_array_keys(IndexScanDesc scan, BTReadPageState *pstate,
pstate->continuescan = true; /* Override _bt_check_compare */
so->needPrimScan = false; /* _bt_readpage has more tuples to check */
- if (so->scanBehind)
- {
- /* Optimization: skip by setting "look ahead" mechanism's offnum */
- Assert(ScanDirectionIsForward(dir));
- pstate->skip = pstate->maxoff + 1;
- }
-
- /* Caller's tuple doesn't match the new qual */
- return false;
-
-new_prim_scan:
-
- /*
- * End this primitive index scan, but schedule another.
- *
- * Note: If the scan direction happens to change, this scheduled primitive
- * index scan won't go ahead after all.
- */
- pstate->continuescan = false; /* Tell _bt_readpage we're done... */
- so->needPrimScan = true; /* ...but call _bt_first again */
-
- if (scan->parallel_scan)
- _bt_parallel_primscan_schedule(scan, pstate->prev_scan_page);
-
- /* Caller's tuple doesn't match the new qual */
- return false;
-
-end_toplevel_scan:
-
- /*
- * End the current primitive index scan, but don't schedule another.
- *
- * This ends the entire top-level scan in the current scan direction.
- *
- * Note: The scan's arrays (including any non-required arrays) are now in
- * their final positions for the current scan direction. If the scan
- * direction happens to change, then the arrays will already be in their
- * first positions for what will then be the current scan direction.
- */
- pstate->continuescan = false; /* Tell _bt_readpage we're done... */
- so->needPrimScan = false; /* ...don't call _bt_first again, though */
-
- /* Caller's tuple doesn't match any qual */
- return false;
-}
-
-/*
- * _bt_preprocess_keys() -- Preprocess scan keys
- *
- * The given search-type keys (taken from scan->keyData[])
- * are copied to so->keyData[] with possible transformation.
- * scan->numberOfKeys is the number of input keys, so->numberOfKeys gets
- * the number of output keys (possibly less, never greater).
- *
- * The output keys are marked with additional sk_flags bits beyond the
- * system-standard bits supplied by the caller. The DESC and NULLS_FIRST
- * indoption bits for the relevant index attribute are copied into the flags.
- * Also, for a DESC column, we commute (flip) all the sk_strategy numbers
- * so that the index sorts in the desired direction.
- *
- * One key purpose of this routine is to discover which scan keys must be
- * satisfied to continue the scan. It also attempts to eliminate redundant
- * keys and detect contradictory keys. (If the index opfamily provides
- * incomplete sets of cross-type operators, we may fail to detect redundant
- * or contradictory keys, but we can survive that.)
- *
- * The output keys must be sorted by index attribute. Presently we expect
- * (but verify) that the input keys are already so sorted --- this is done
- * by match_clauses_to_index() in indxpath.c. Some reordering of the keys
- * within each attribute may be done as a byproduct of the processing here.
- * That process must leave array scan keys (within an attribute) in the same
- * order as corresponding entries from the scan's BTArrayKeyInfo array info.
- *
- * The output keys are marked with flags SK_BT_REQFWD and/or SK_BT_REQBKWD
- * if they must be satisfied in order to continue the scan forward or backward
- * respectively. _bt_checkkeys uses these flags. For example, if the quals
- * are "x = 1 AND y < 4 AND z < 5", then _bt_checkkeys will reject a tuple
- * (1,2,7), but we must continue the scan in case there are tuples (1,3,z).
- * But once we reach tuples like (1,4,z) we can stop scanning because no
- * later tuples could match. This is reflected by marking the x and y keys,
- * but not the z key, with SK_BT_REQFWD. In general, the keys for leading
- * attributes with "=" keys are marked both SK_BT_REQFWD and SK_BT_REQBKWD.
- * For the first attribute without an "=" key, any "<" and "<=" keys are
- * marked SK_BT_REQFWD while any ">" and ">=" keys are marked SK_BT_REQBKWD.
- * This can be seen to be correct by considering the above example. Note
- * in particular that if there are no keys for a given attribute, the keys for
- * subsequent attributes can never be required; for instance "WHERE y = 4"
- * requires a full-index scan.
- *
- * If possible, redundant keys are eliminated: we keep only the tightest
- * >/>= bound and the tightest />= or both
- * 4::int AND x > 10::bigint", and we are unable to determine
- * which key is more restrictive for lack of a suitable cross-type operator.
- * _bt_first will arbitrarily pick one of the keys to do the initial
- * positioning with. If it picks x > 4, then the x > 10 condition will fail
- * until we reach index entries > 10; but we can't stop the scan just because
- * x > 10 is failing. On the other hand, if we are scanning backwards, then
- * failure of either key is indeed enough to stop the scan. (In general, when
- * inequality keys are present, the initial-positioning code only promises to
- * position before the first possible match, not exactly at the first match,
- * for a forward scan; or after the last match for a backward scan.)
- *
- * As a byproduct of this work, we can detect contradictory quals such
- * as "x = 1 AND x > 2". If we see that, we return so->qual_ok = false,
- * indicating the scan need not be run at all since no tuples can match.
- * (In this case we do not bother completing the output key array!)
- * Again, missing cross-type operators might cause us to fail to prove the
- * quals contradictory when they really are, but the scan will work correctly.
- *
- * Row comparison keys are currently also treated without any smarts:
- * we just transfer them into the preprocessed array without any
- * editorialization. We can treat them the same as an ordinary inequality
- * comparison on the row's first index column, for the purposes of the logic
- * about required keys.
- *
- * Note: the reason we have to copy the preprocessed scan keys into private
- * storage is that we are modifying the array based on comparisons of the
- * key argument values, which could change on a rescan. Therefore we can't
- * overwrite the source data.
- */
-void
-_bt_preprocess_keys(IndexScanDesc scan)
-{
- BTScanOpaque so = (BTScanOpaque) scan->opaque;
- int numberOfKeys = scan->numberOfKeys;
- int16 *indoption = scan->indexRelation->rd_indoption;
- int new_numberOfKeys;
- int numberOfEqualCols;
- ScanKey inkeys;
- ScanKey outkeys;
- ScanKey cur;
- BTScanKeyPreproc xform[BTMaxStrategyNumber];
- bool test_result;
- int i,
- j;
- AttrNumber attno;
- ScanKey arrayKeyData;
- int *keyDataMap = NULL;
- int arrayidx = 0;
-
- if (so->numberOfKeys > 0)
- {
- /*
- * Only need to do preprocessing once per btrescan, at most. All
- * calls after the first are handled as no-ops.
- *
- * If there are array scan keys in so->keyData[], then the now-current
- * array elements must already be present in each array's scan key.
- * Verify that that happened using an assertion.
- */
- Assert(_bt_verify_keys_with_arraykeys(scan));
- return;
- }
-
- /* initialize result variables */
- so->qual_ok = true;
- so->numberOfKeys = 0;
-
- if (numberOfKeys < 1)
- return; /* done if qual-less scan */
-
- /* If any keys are SK_SEARCHARRAY type, set up array-key info */
- arrayKeyData = _bt_preprocess_array_keys(scan);
- if (!so->qual_ok)
- {
- /* unmatchable array, so give up */
- return;
- }
-
- /*
- * Treat arrayKeyData[] (a partially preprocessed copy of scan->keyData[])
- * as our input if _bt_preprocess_array_keys just allocated it, else just
- * use scan->keyData[]
- */
- if (arrayKeyData)
- {
- inkeys = arrayKeyData;
-
- /* Also maintain keyDataMap for remapping so->orderProc[] later */
- keyDataMap = MemoryContextAlloc(so->arrayContext,
- numberOfKeys * sizeof(int));
- }
- else
- inkeys = scan->keyData;
-
- outkeys = so->keyData;
- cur = &inkeys[0];
- /* we check that input keys are correctly ordered */
- if (cur->sk_attno < 1)
- elog(ERROR, "btree index keys must be ordered by attribute");
-
- /* We can short-circuit most of the work if there's just one key */
- if (numberOfKeys == 1)
- {
- /* Apply indoption to scankey (might change sk_strategy!) */
- if (!_bt_fix_scankey_strategy(cur, indoption))
- so->qual_ok = false;
- memcpy(outkeys, cur, sizeof(ScanKeyData));
- so->numberOfKeys = 1;
- /* We can mark the qual as required if it's for first index col */
- if (cur->sk_attno == 1)
- _bt_mark_scankey_required(outkeys);
- if (arrayKeyData)
- {
- /*
- * Don't call _bt_preprocess_array_keys_final in this fast path
- * (we'll miss out on the single value array transformation, but
- * that's not nearly as important when there's only one scan key)
- */
- Assert(cur->sk_flags & SK_SEARCHARRAY);
- Assert(cur->sk_strategy != BTEqualStrategyNumber ||
- (so->arrayKeys[0].scan_key == 0 &&
- OidIsValid(so->orderProcs[0].fn_oid)));
- }
-
- return;
- }
-
- /*
- * Otherwise, do the full set of pushups.
- */
- new_numberOfKeys = 0;
- numberOfEqualCols = 0;
-
- /*
- * Initialize for processing of keys for attr 1.
- *
- * xform[i] points to the currently best scan key of strategy type i+1; it
- * is NULL if we haven't yet found such a key for this attr.
- */
- attno = 1;
- memset(xform, 0, sizeof(xform));
-
- /*
- * Loop iterates from 0 to numberOfKeys inclusive; we use the last pass to
- * handle after-last-key processing. Actual exit from the loop is at the
- * "break" statement below.
- */
- for (i = 0;; cur++, i++)
- {
- if (i < numberOfKeys)
- {
- /* Apply indoption to scankey (might change sk_strategy!) */
- if (!_bt_fix_scankey_strategy(cur, indoption))
- {
- /* NULL can't be matched, so give up */
- so->qual_ok = false;
- return;
- }
- }
-
- /*
- * If we are at the end of the keys for a particular attr, finish up
- * processing and emit the cleaned-up keys.
- */
- if (i == numberOfKeys || cur->sk_attno != attno)
- {
- int priorNumberOfEqualCols = numberOfEqualCols;
-
- /* check input keys are correctly ordered */
- if (i < numberOfKeys && cur->sk_attno < attno)
- elog(ERROR, "btree index keys must be ordered by attribute");
-
- /*
- * If = has been specified, all other keys can be eliminated as
- * redundant. If we have a case like key = 1 AND key > 2, we can
- * set qual_ok to false and abandon further processing.
- *
- * We also have to deal with the case of "key IS NULL", which is
- * unsatisfiable in combination with any other index condition. By
- * the time we get here, that's been classified as an equality
- * check, and we've rejected any combination of it with a regular
- * equality condition; but not with other types of conditions.
- */
- if (xform[BTEqualStrategyNumber - 1].skey)
- {
- ScanKey eq = xform[BTEqualStrategyNumber - 1].skey;
- BTArrayKeyInfo *array = NULL;
- FmgrInfo *orderproc = NULL;
-
- if (arrayKeyData && (eq->sk_flags & SK_SEARCHARRAY))
- {
- int eq_in_ikey,
- eq_arrayidx;
-
- eq_in_ikey = xform[BTEqualStrategyNumber - 1].ikey;
- eq_arrayidx = xform[BTEqualStrategyNumber - 1].arrayidx;
- array = &so->arrayKeys[eq_arrayidx - 1];
- orderproc = so->orderProcs + eq_in_ikey;
-
- Assert(array->scan_key == eq_in_ikey);
- Assert(OidIsValid(orderproc->fn_oid));
- }
-
- for (j = BTMaxStrategyNumber; --j >= 0;)
- {
- ScanKey chk = xform[j].skey;
-
- if (!chk || j == (BTEqualStrategyNumber - 1))
- continue;
-
- if (eq->sk_flags & SK_SEARCHNULL)
- {
- /* IS NULL is contradictory to anything else */
- so->qual_ok = false;
- return;
- }
-
- if (_bt_compare_scankey_args(scan, chk, eq, chk,
- array, orderproc,
- &test_result))
- {
- if (!test_result)
- {
- /* keys proven mutually contradictory */
- so->qual_ok = false;
- return;
- }
- /* else discard the redundant non-equality key */
- Assert(!array || array->num_elems > 0);
- xform[j].skey = NULL;
- xform[j].ikey = -1;
- }
- /* else, cannot determine redundancy, keep both keys */
- }
- /* track number of attrs for which we have "=" keys */
- numberOfEqualCols++;
- }
-
- /* try to keep only one of <, <= */
- if (xform[BTLessStrategyNumber - 1].skey
- && xform[BTLessEqualStrategyNumber - 1].skey)
- {
- ScanKey lt = xform[BTLessStrategyNumber - 1].skey;
- ScanKey le = xform[BTLessEqualStrategyNumber - 1].skey;
-
- if (_bt_compare_scankey_args(scan, le, lt, le, NULL, NULL,
- &test_result))
- {
- if (test_result)
- xform[BTLessEqualStrategyNumber - 1].skey = NULL;
- else
- xform[BTLessStrategyNumber - 1].skey = NULL;
- }
- }
-
- /* try to keep only one of >, >= */
- if (xform[BTGreaterStrategyNumber - 1].skey
- && xform[BTGreaterEqualStrategyNumber - 1].skey)
- {
- ScanKey gt = xform[BTGreaterStrategyNumber - 1].skey;
- ScanKey ge = xform[BTGreaterEqualStrategyNumber - 1].skey;
-
- if (_bt_compare_scankey_args(scan, ge, gt, ge, NULL, NULL,
- &test_result))
- {
- if (test_result)
- xform[BTGreaterEqualStrategyNumber - 1].skey = NULL;
- else
- xform[BTGreaterStrategyNumber - 1].skey = NULL;
- }
- }
-
- /*
- * Emit the cleaned-up keys into the outkeys[] array, and then
- * mark them if they are required. They are required (possibly
- * only in one direction) if all attrs before this one had "=".
- */
- for (j = BTMaxStrategyNumber; --j >= 0;)
- {
- if (xform[j].skey)
- {
- ScanKey outkey = &outkeys[new_numberOfKeys++];
-
- memcpy(outkey, xform[j].skey, sizeof(ScanKeyData));
- if (arrayKeyData)
- keyDataMap[new_numberOfKeys - 1] = xform[j].ikey;
- if (priorNumberOfEqualCols == attno - 1)
- _bt_mark_scankey_required(outkey);
- }
- }
-
- /*
- * Exit loop here if done.
- */
- if (i == numberOfKeys)
- break;
-
- /* Re-initialize for new attno */
- attno = cur->sk_attno;
- memset(xform, 0, sizeof(xform));
- }
-
- /* check strategy this key's operator corresponds to */
- j = cur->sk_strategy - 1;
-
- /* if row comparison, push it directly to the output array */
- if (cur->sk_flags & SK_ROW_HEADER)
- {
- ScanKey outkey = &outkeys[new_numberOfKeys++];
-
- memcpy(outkey, cur, sizeof(ScanKeyData));
- if (arrayKeyData)
- keyDataMap[new_numberOfKeys - 1] = i;
- if (numberOfEqualCols == attno - 1)
- _bt_mark_scankey_required(outkey);
-
- /*
- * We don't support RowCompare using equality; such a qual would
- * mess up the numberOfEqualCols tracking.
- */
- Assert(j != (BTEqualStrategyNumber - 1));
- continue;
- }
-
- /*
- * Does this input scan key require further processing as an array?
- */
- if (cur->sk_strategy == InvalidStrategy)
- {
- /* _bt_preprocess_array_keys marked this array key redundant */
- Assert(arrayKeyData);
- Assert(cur->sk_flags & SK_SEARCHARRAY);
- continue;
- }
-
- if (cur->sk_strategy == BTEqualStrategyNumber &&
- (cur->sk_flags & SK_SEARCHARRAY))
- {
- /* _bt_preprocess_array_keys kept this array key */
- Assert(arrayKeyData);
- arrayidx++;
- }
-
- /*
- * have we seen a scan key for this same attribute and using this same
- * operator strategy before now?
- */
- if (xform[j].skey == NULL)
- {
- /* nope, so this scan key wins by default (at least for now) */
- xform[j].skey = cur;
- xform[j].ikey = i;
- xform[j].arrayidx = arrayidx;
- }
- else
- {
- FmgrInfo *orderproc = NULL;
- BTArrayKeyInfo *array = NULL;
-
- /*
- * Seen one of these before, so keep only the more restrictive key
- * if possible
- */
- if (j == (BTEqualStrategyNumber - 1) && arrayKeyData)
- {
- /*
- * Have to set up array keys
- */
- if ((cur->sk_flags & SK_SEARCHARRAY))
- {
- array = &so->arrayKeys[arrayidx - 1];
- orderproc = so->orderProcs + i;
-
- Assert(array->scan_key == i);
- Assert(OidIsValid(orderproc->fn_oid));
- }
- else if ((xform[j].skey->sk_flags & SK_SEARCHARRAY))
- {
- array = &so->arrayKeys[xform[j].arrayidx - 1];
- orderproc = so->orderProcs + xform[j].ikey;
-
- Assert(array->scan_key == xform[j].ikey);
- Assert(OidIsValid(orderproc->fn_oid));
- }
+ if (so->scanBehind)
+ {
+ /*
+ * Remember if recheck needs to call _bt_oppodir_checkkeys for next
+ * page's finaltup (see above comments about "Handle inequalities
+ * marked required in the opposite scan direction" for why).
+ */
+ so->oppositeDirCheck = has_required_opposite_direction_only;
- /*
- * Both scan keys might have arrays, in which case we'll
- * arbitrarily pass only one of the arrays. That won't
- * matter, since _bt_compare_scankey_args is aware that two
- * SEARCHARRAY scan keys mean that _bt_preprocess_array_keys
- * failed to eliminate redundant arrays through array merging.
- * _bt_compare_scankey_args just returns false when it sees
- * this; it won't even try to examine either array.
- */
- }
+ /*
+ * skip by setting "look ahead" mechanism's offnum for forwards scans
+ * (backwards scans check scanBehind flag directly instead)
+ */
+ if (ScanDirectionIsForward(dir))
+ pstate->skip = pstate->maxoff + 1;
+ }
- if (_bt_compare_scankey_args(scan, cur, cur, xform[j].skey,
- array, orderproc, &test_result))
- {
- /* Have all we need to determine redundancy */
- if (test_result)
- {
- Assert(!array || array->num_elems > 0);
+ /* Caller's tuple doesn't match the new qual */
+ return false;
- /*
- * New key is more restrictive, and so replaces old key...
- */
- if (j != (BTEqualStrategyNumber - 1) ||
- !(xform[j].skey->sk_flags & SK_SEARCHARRAY))
- {
- xform[j].skey = cur;
- xform[j].ikey = i;
- xform[j].arrayidx = arrayidx;
- }
- else
- {
- /*
- * ...unless we have to keep the old key because it's
- * an array that rendered the new key redundant. We
- * need to make sure that we don't throw away an array
- * scan key. _bt_compare_scankey_args expects us to
- * always keep arrays (and discard non-arrays).
- */
- Assert(!(cur->sk_flags & SK_SEARCHARRAY));
- }
- }
- else if (j == (BTEqualStrategyNumber - 1))
- {
- /* key == a && key == b, but a != b */
- so->qual_ok = false;
- return;
- }
- /* else old key is more restrictive, keep it */
- }
- else
- {
- /*
- * We can't determine which key is more restrictive. Push
- * xform[j] directly to the output array, then set xform[j] to
- * the new scan key.
- *
- * Note: We do things this way around so that our arrays are
- * always in the same order as their corresponding scan keys,
- * even with incomplete opfamilies. _bt_advance_array_keys
- * depends on this.
- */
- ScanKey outkey = &outkeys[new_numberOfKeys++];
-
- memcpy(outkey, xform[j].skey, sizeof(ScanKeyData));
- if (arrayKeyData)
- keyDataMap[new_numberOfKeys - 1] = xform[j].ikey;
- if (numberOfEqualCols == attno - 1)
- _bt_mark_scankey_required(outkey);
- xform[j].skey = cur;
- xform[j].ikey = i;
- xform[j].arrayidx = arrayidx;
- }
- }
- }
+new_prim_scan:
- so->numberOfKeys = new_numberOfKeys;
+ Assert(pstate->finaltup); /* not on rightmost/leftmost page */
/*
- * Now that we've built a temporary mapping from so->keyData[] (output
- * scan keys) to scan->keyData[] (input scan keys), fix array->scan_key
- * references. Also consolidate the so->orderProc[] array such that it
- * can be subscripted using so->keyData[]-wise offsets.
+ * Looks like another primitive index scan is required. But consider
+ * continuing the current primscan based on scan-level heuristics.
+ *
+ * Continue the ongoing primitive scan (and schedule a recheck for when
+ * the scan arrives on the next sibling leaf page) when it has already
+ * read at least one leaf page before the one we're reading now. This
+ * makes primscan scheduling more efficient when scanning subsets of an
+ * index with many distinct attribute values matching many array elements.
+ * It encourages fewer, larger primitive scans where that makes sense.
+ * This will in turn encourage _bt_readpage to apply the pstate.startikey
+ * optimization more often.
+ *
+ * Also continue the ongoing primitive index scan when it is still on the
+ * first page if there have been more than NSKIPADVANCES_THRESHOLD calls
+ * here that each advanced at least one of the scan's skip arrays
+ * (deliberately ignore advancements that only affected SAOP arrays here).
+ * A page that cycles through this many skip array elements is quite
+ * likely to neighbor similar pages, that we'll also need to read.
+ *
+ * Note: These heuristics aren't as aggressive as you might think. We're
+ * conservative about allowing a primitive scan to step from the first
+ * leaf page it reads to the page's sibling page (we only allow it on
+ * first pages whose finaltup strongly suggests that it'll work out, as
+ * well as first pages that have a large number of skip array advances).
+ * Clearing this first page finaltup hurdle is a strong signal in itself.
+ *
+ * Note: The NSKIPADVANCES_THRESHOLD heuristic exists only to avoid
+ * pathological cases. Specifically, cases where a skip scan should just
+ * behave like a traditional full index scan, but ends up "skipping" again
+ * and again, descending to the prior leaf page's direct sibling leaf page
+ * each time. This misbehavior would otherwise be possible during scans
+ * that never quite manage to "clear the first page finaltup hurdle".
*/
- if (arrayKeyData)
- _bt_preprocess_array_keys_final(scan, keyDataMap);
-
- /* Could pfree arrayKeyData/keyDataMap now, but not worth the cycles */
-}
-
-#ifdef USE_ASSERT_CHECKING
-/*
- * Verify that the scan's qual state matches what we expect at the point that
- * _bt_start_prim_scan is about to start a just-scheduled new primitive scan.
- *
- * We enforce a rule against non-required array scan keys: they must start out
- * with whatever element is the first for the scan's current scan direction.
- * See _bt_rewind_nonrequired_arrays comments for an explanation.
- */
-static bool
-_bt_verify_arrays_bt_first(IndexScanDesc scan, ScanDirection dir)
-{
- BTScanOpaque so = (BTScanOpaque) scan->opaque;
- int arrayidx = 0;
-
- for (int ikey = 0; ikey < so->numberOfKeys; ikey++)
+ if (!pstate->firstpage || pstate->nskipadvances > NSKIPADVANCES_THRESHOLD)
{
- ScanKey cur = so->keyData + ikey;
- BTArrayKeyInfo *array = NULL;
- int first_elem_dir;
+ /* Schedule a recheck once on the next (or previous) page */
+ so->scanBehind = true;
- if (!(cur->sk_flags & SK_SEARCHARRAY) ||
- cur->sk_strategy != BTEqualStrategyNumber)
- continue;
+ /* Continue the current primitive scan after all */
+ goto continue_scan;
+ }
- array = &so->arrayKeys[arrayidx++];
+ /*
+ * End this primitive index scan, but schedule another.
+ *
+ * Note: We make a soft assumption that the current scan direction will
+ * also be used within _bt_next, when it is asked to step off this page.
+ * It is up to _bt_next to cancel this scheduled primitive index scan
+ * whenever it steps to a page in the direction opposite currPos.dir.
+ */
+ pstate->continuescan = false; /* Tell _bt_readpage we're done... */
+ so->needPrimScan = true; /* ...but call _bt_first again */
- if (((cur->sk_flags & SK_BT_REQFWD) && ScanDirectionIsForward(dir)) ||
- ((cur->sk_flags & SK_BT_REQBKWD) && ScanDirectionIsBackward(dir)))
- continue;
+ if (scan->parallel_scan)
+ _bt_parallel_primscan_schedule(scan, so->currPos.currPage);
- if (ScanDirectionIsForward(dir))
- first_elem_dir = 0;
- else
- first_elem_dir = array->num_elems - 1;
+ /* Caller's tuple doesn't match the new qual */
+ return false;
- if (array->cur_elem != first_elem_dir)
- return false;
- }
+end_toplevel_scan:
+
+ /*
+ * End the current primitive index scan, but don't schedule another.
+ *
+ * This ends the entire top-level scan in the current scan direction.
+ *
+ * Note: The scan's arrays (including any non-required arrays) are now in
+ * their final positions for the current scan direction. If the scan
+ * direction happens to change, then the arrays will already be in their
+ * first positions for what will then be the current scan direction.
+ */
+ pstate->continuescan = false; /* Tell _bt_readpage we're done... */
+ so->needPrimScan = false; /* ...and don't call _bt_first again */
- return _bt_verify_keys_with_arraykeys(scan);
+ /* Caller's tuple doesn't match any qual */
+ return false;
}
+#ifdef USE_ASSERT_CHECKING
/*
* Verify that the scan's "so->keyData[]" scan keys are in agreement with
* its array key state
@@ -3050,6 +2075,7 @@ _bt_verify_keys_with_arraykeys(IndexScanDesc scan)
BTScanOpaque so = (BTScanOpaque) scan->opaque;
int last_sk_attno = InvalidAttrNumber,
arrayidx = 0;
+ bool nonrequiredseen = false;
if (!so->qual_ok)
return false;
@@ -3067,13 +2093,22 @@ _bt_verify_keys_with_arraykeys(IndexScanDesc scan)
if (array->scan_key != ikey)
return false;
- if (array->num_elems <= 0)
+ if (array->num_elems == 0 || array->num_elems < -1)
return false;
- if (cur->sk_argument != array->elem_values[array->cur_elem])
- return false;
- if (last_sk_attno > cur->sk_attno)
+ if (array->num_elems != -1 &&
+ cur->sk_argument != array->elem_values[array->cur_elem])
return false;
+ if (cur->sk_flags & (SK_BT_REQFWD | SK_BT_REQBKWD))
+ {
+ if (last_sk_attno > cur->sk_attno)
+ return false;
+ if (nonrequiredseen)
+ return false;
+ }
+ else
+ nonrequiredseen = true;
+
last_sk_attno = cur->sk_attno;
}
@@ -3085,563 +2120,532 @@ _bt_verify_keys_with_arraykeys(IndexScanDesc scan)
#endif
/*
- * Compare two scankey values using a specified operator.
- *
- * The test we want to perform is logically "leftarg op rightarg", where
- * leftarg and rightarg are the sk_argument values in those ScanKeys, and
- * the comparison operator is the one in the op ScanKey. However, in
- * cross-data-type situations we may need to look up the correct operator in
- * the index's opfamily: it is the one having amopstrategy = op->sk_strategy
- * and amoplefttype/amoprighttype equal to the two argument datatypes.
+ * Test whether an indextuple satisfies all the scankey conditions.
*
- * If the opfamily doesn't supply a complete set of cross-type operators we
- * may not be able to make the comparison. If we can make the comparison
- * we store the operator result in *result and return true. We return false
- * if the comparison could not be made.
+ * Return true if so, false if not. If the tuple fails to pass the qual,
+ * we also determine whether there's any need to continue the scan beyond
+ * this tuple, and set pstate.continuescan accordingly. See comments for
+ * _bt_preprocess_keys() about how this is done.
*
- * If either leftarg or rightarg are an array, we'll apply array-specific
- * rules to determine which array elements are redundant on behalf of caller.
- * It is up to our caller to save whichever of the two scan keys is the array,
- * and discard the non-array scan key (the non-array scan key is guaranteed to
- * be redundant with any complete opfamily). Caller isn't expected to call
- * here with a pair of array scan keys provided we're dealing with a complete
- * opfamily (_bt_preprocess_array_keys will merge array keys together to make
- * sure of that).
+ * Forward scan callers can pass a high key tuple in the hopes of having
+ * us set *continuescan to false, and avoiding an unnecessary visit to
+ * the page to the right.
*
- * Note: we'll also shrink caller's array as needed to eliminate redundant
- * array elements. One reason why caller should prefer to discard non-array
- * scan keys is so that we'll have the opportunity to shrink the array
- * multiple times, in multiple calls (for each of several other scan keys on
- * the same index attribute).
+ * Advances the scan's array keys when necessary for arrayKeys=true callers.
+ * Scans without any array keys must always pass arrayKeys=false.
*
- * Note: op always points at the same ScanKey as either leftarg or rightarg.
- * Since we don't scribble on the scankeys themselves, this aliasing should
- * cause no trouble.
+ * Also stops and starts primitive index scans for arrayKeys=true callers.
+ * Scans with array keys are required to set up page state that helps us with
+ * this. The page's finaltup tuple (the page high key for a forward scan, or
+ * the page's first non-pivot tuple for a backward scan) must be set in
+ * pstate.finaltup ahead of the first call here for the page. Set this to
+ * NULL for rightmost page (or the leftmost page for backwards scans).
*
- * Note: this routine needs to be insensitive to any DESC option applied
- * to the index column. For example, "x < 4" is a tighter constraint than
- * "x < 5" regardless of which way the index is sorted.
+ * scan: index scan descriptor (containing a search-type scankey)
+ * pstate: page level input and output parameters
+ * arrayKeys: should we advance the scan's array keys if necessary?
+ * tuple: index tuple to test
+ * tupnatts: number of attributes in tupnatts (high key may be truncated)
*/
-static bool
-_bt_compare_scankey_args(IndexScanDesc scan, ScanKey op,
- ScanKey leftarg, ScanKey rightarg,
- BTArrayKeyInfo *array, FmgrInfo *orderproc,
- bool *result)
+bool
+_bt_checkkeys(IndexScanDesc scan, BTReadPageState *pstate, bool arrayKeys,
+ IndexTuple tuple, int tupnatts)
{
- Relation rel = scan->indexRelation;
- Oid lefttype,
- righttype,
- optype,
- opcintype,
- cmp_op;
- StrategyNumber strat;
-
- /*
- * First, deal with cases where one or both args are NULL. This should
- * only happen when the scankeys represent IS NULL/NOT NULL conditions.
- */
- if ((leftarg->sk_flags | rightarg->sk_flags) & SK_ISNULL)
- {
- bool leftnull,
- rightnull;
-
- if (leftarg->sk_flags & SK_ISNULL)
- {
- Assert(leftarg->sk_flags & (SK_SEARCHNULL | SK_SEARCHNOTNULL));
- leftnull = true;
- }
- else
- leftnull = false;
- if (rightarg->sk_flags & SK_ISNULL)
- {
- Assert(rightarg->sk_flags & (SK_SEARCHNULL | SK_SEARCHNOTNULL));
- rightnull = true;
- }
- else
- rightnull = false;
+ TupleDesc tupdesc = RelationGetDescr(scan->indexRelation);
+ BTScanOpaque so = (BTScanOpaque) scan->opaque;
+ ScanDirection dir = so->currPos.dir;
+ int ikey = pstate->startikey;
+ bool res;
- /*
- * We treat NULL as either greater than or less than all other values.
- * Since true > false, the tests below work correctly for NULLS LAST
- * logic. If the index is NULLS FIRST, we need to flip the strategy.
- */
- strat = op->sk_strategy;
- if (op->sk_flags & SK_BT_NULLS_FIRST)
- strat = BTCommuteStrategyNumber(strat);
+ Assert(BTreeTupleGetNAtts(tuple, scan->indexRelation) == tupnatts);
+ Assert(!so->needPrimScan && !so->scanBehind && !so->oppositeDirCheck);
+ Assert(arrayKeys || so->numArrayKeys == 0);
- switch (strat)
- {
- case BTLessStrategyNumber:
- *result = (leftnull < rightnull);
- break;
- case BTLessEqualStrategyNumber:
- *result = (leftnull <= rightnull);
- break;
- case BTEqualStrategyNumber:
- *result = (leftnull == rightnull);
- break;
- case BTGreaterEqualStrategyNumber:
- *result = (leftnull >= rightnull);
- break;
- case BTGreaterStrategyNumber:
- *result = (leftnull > rightnull);
- break;
- default:
- elog(ERROR, "unrecognized StrategyNumber: %d", (int) strat);
- *result = false; /* keep compiler quiet */
- break;
- }
- return true;
- }
+ res = _bt_check_compare(scan, dir, tuple, tupnatts, tupdesc, arrayKeys,
+ pstate->forcenonrequired, &pstate->continuescan,
+ &ikey);
/*
- * If either leftarg or rightarg are equality-type array scankeys, we need
- * specialized handling (since by now we know that IS NULL wasn't used)
+ * If _bt_check_compare relied on the pstate.startikey optimization, call
+ * again (in assert-enabled builds) to verify it didn't affect our answer.
+ *
+ * Note: we can't do this when !pstate.forcenonrequired, since any arrays
+ * before pstate.startikey won't have advanced on this page at all.
*/
- if (array)
+ Assert(!pstate->forcenonrequired || arrayKeys);
+#ifdef USE_ASSERT_CHECKING
+ if (pstate->startikey > 0 && !pstate->forcenonrequired)
{
- bool leftarray,
- rightarray;
-
- leftarray = ((leftarg->sk_flags & SK_SEARCHARRAY) &&
- leftarg->sk_strategy == BTEqualStrategyNumber);
- rightarray = ((rightarg->sk_flags & SK_SEARCHARRAY) &&
- rightarg->sk_strategy == BTEqualStrategyNumber);
+ bool dres,
+ dcontinuescan;
+ int dikey = 0;
- /*
- * _bt_preprocess_array_keys is responsible for merging together array
- * scan keys, and will do so whenever the opfamily has the required
- * cross-type support. If it failed to do that, we handle it just
- * like the case where we can't make the comparison ourselves.
- */
- if (leftarray && rightarray)
- {
- /* Can't make the comparison */
- *result = false; /* suppress compiler warnings */
- return false;
- }
+ /* Pass arrayKeys=false to avoid array side-effects */
+ dres = _bt_check_compare(scan, dir, tuple, tupnatts, tupdesc, false,
+ pstate->forcenonrequired, &dcontinuescan,
+ &dikey);
+ Assert(res == dres);
+ Assert(pstate->continuescan == dcontinuescan);
/*
- * Otherwise we need to determine if either one of leftarg or rightarg
- * uses an array, then pass this through to a dedicated helper
- * function.
+ * Should also get the same ikey result. We need a slightly weaker
+ * assertion during arrayKeys calls, since they might be using an
+ * array that couldn't be marked required during preprocessing.
*/
- if (leftarray)
- return _bt_compare_array_scankey_args(scan, leftarg, rightarg,
- orderproc, array, result);
- else if (rightarray)
- return _bt_compare_array_scankey_args(scan, rightarg, leftarg,
- orderproc, array, result);
-
- /* FALL THRU */
+ Assert(arrayKeys || ikey == dikey);
+ Assert(ikey <= dikey);
}
+#endif
/*
- * The opfamily we need to worry about is identified by the index column.
- */
- Assert(leftarg->sk_attno == rightarg->sk_attno);
-
- opcintype = rel->rd_opcintype[leftarg->sk_attno - 1];
-
- /*
- * Determine the actual datatypes of the ScanKey arguments. We have to
- * support the convention that sk_subtype == InvalidOid means the opclass
- * input type; this is a hack to simplify life for ScanKeyInit().
- */
- lefttype = leftarg->sk_subtype;
- if (lefttype == InvalidOid)
- lefttype = opcintype;
- righttype = rightarg->sk_subtype;
- if (righttype == InvalidOid)
- righttype = opcintype;
- optype = op->sk_subtype;
- if (optype == InvalidOid)
- optype = opcintype;
-
- /*
- * If leftarg and rightarg match the types expected for the "op" scankey,
- * we can use its already-looked-up comparison function.
+ * Only one _bt_check_compare call is required in the common case where
+ * there are no equality strategy array scan keys. Otherwise we can only
+ * accept _bt_check_compare's answer unreservedly when it didn't set
+ * pstate.continuescan=false.
*/
- if (lefttype == opcintype && righttype == optype)
- {
- *result = DatumGetBool(FunctionCall2Coll(&op->sk_func,
- op->sk_collation,
- leftarg->sk_argument,
- rightarg->sk_argument));
- return true;
- }
+ if (!arrayKeys || pstate->continuescan)
+ return res;
/*
- * Otherwise, we need to go to the syscache to find the appropriate
- * operator. (This cannot result in infinite recursion, since no
- * indexscan initiated by syscache lookup will use cross-data-type
- * operators.)
+ * _bt_check_compare call set continuescan=false in the presence of
+ * equality type array keys. This could mean that the tuple is just past
+ * the end of matches for the current array keys.
*
- * If the sk_strategy was flipped by _bt_fix_scankey_strategy, we have to
- * un-flip it to get the correct opfamily member.
+ * It's also possible that the scan is still _before_ the _start_ of
+ * tuples matching the current set of array keys. Check for that first.
*/
- strat = op->sk_strategy;
- if (op->sk_flags & SK_BT_DESC)
- strat = BTCommuteStrategyNumber(strat);
-
- cmp_op = get_opfamily_member(rel->rd_opfamily[leftarg->sk_attno - 1],
- lefttype,
- righttype,
- strat);
- if (OidIsValid(cmp_op))
+ Assert(!pstate->forcenonrequired);
+ if (_bt_tuple_before_array_skeys(scan, dir, tuple, tupdesc, tupnatts, true,
+ ikey, NULL))
{
- RegProcedure cmp_proc = get_opcode(cmp_op);
+ /* Override _bt_check_compare, continue primitive scan */
+ pstate->continuescan = true;
- if (RegProcedureIsValid(cmp_proc))
+ /*
+ * We will end up here repeatedly given a group of tuples > the
+ * previous array keys and < the now-current keys (for a backwards
+ * scan it's just the same, though the operators swap positions).
+ *
+ * We must avoid allowing this linear search process to scan very many
+ * tuples from well before the start of tuples matching the current
+ * array keys (or from well before the point where we'll once again
+ * have to advance the scan's array keys).
+ *
+ * We keep the overhead under control by speculatively "looking ahead"
+ * to later still-unscanned items from this same leaf page. We'll
+ * only attempt this once the number of tuples that the linear search
+ * process has examined starts to get out of hand.
+ */
+ pstate->rechecks++;
+ if (pstate->rechecks >= LOOK_AHEAD_REQUIRED_RECHECKS)
{
- *result = DatumGetBool(OidFunctionCall2Coll(cmp_proc,
- op->sk_collation,
- leftarg->sk_argument,
- rightarg->sk_argument));
- return true;
+ /* See if we should skip ahead within the current leaf page */
+ _bt_checkkeys_look_ahead(scan, pstate, tupnatts, tupdesc);
+
+ /*
+ * Might have set pstate.skip to a later page offset. When that
+ * happens then _bt_readpage caller will inexpensively skip ahead
+ * to a later tuple from the same page (the one just after the
+ * tuple we successfully "looked ahead" to).
+ */
}
+
+ /* This indextuple doesn't match the current qual, in any case */
+ return false;
}
- /* Can't make the comparison */
- *result = false; /* suppress compiler warnings */
- return false;
+ /*
+ * Caller's tuple is >= the current set of array keys and other equality
+ * constraint scan keys (or <= if this is a backwards scan). It's now
+ * clear that we _must_ advance any required array keys in lockstep with
+ * the scan.
+ */
+ return _bt_advance_array_keys(scan, pstate, tuple, tupnatts, tupdesc,
+ ikey, true);
}
/*
- * Adjust a scankey's strategy and flags setting as needed for indoptions.
- *
- * We copy the appropriate indoption value into the scankey sk_flags
- * (shifting to avoid clobbering system-defined flag bits). Also, if
- * the DESC option is set, commute (flip) the operator strategy number.
+ * Test whether caller's finaltup tuple is still before the start of matches
+ * for the current array keys.
*
- * A secondary purpose is to check for IS NULL/NOT NULL scankeys and set up
- * the strategy field correctly for them.
+ * Called at the start of reading a page during a scan with array keys, though
+ * only when the so->scanBehind flag was set on the scan's prior page.
*
- * Lastly, for ordinary scankeys (not IS NULL/NOT NULL), we check for a
- * NULL comparison value. Since all btree operators are assumed strict,
- * a NULL means that the qual cannot be satisfied. We return true if the
- * comparison value isn't NULL, or false if the scan should be abandoned.
- *
- * This function is applied to the *input* scankey structure; therefore
- * on a rescan we will be looking at already-processed scankeys. Hence
- * we have to be careful not to re-commute the strategy if we already did it.
- * It's a bit ugly to modify the caller's copy of the scankey but in practice
- * there shouldn't be any problem, since the index's indoptions are certainly
- * not going to change while the scankey survives.
+ * Returns false if the tuple is still before the start of matches. When that
+ * happens, caller should cut its losses and start a new primitive index scan.
+ * Otherwise returns true.
*/
-static bool
-_bt_fix_scankey_strategy(ScanKey skey, int16 *indoption)
+bool
+_bt_scanbehind_checkkeys(IndexScanDesc scan, ScanDirection dir,
+ IndexTuple finaltup)
{
- int addflags;
+ Relation rel = scan->indexRelation;
+ TupleDesc tupdesc = RelationGetDescr(rel);
+ BTScanOpaque so = (BTScanOpaque) scan->opaque;
+ int nfinaltupatts = BTreeTupleGetNAtts(finaltup, rel);
+ bool scanBehind;
+
+ Assert(so->numArrayKeys);
- addflags = indoption[skey->sk_attno - 1] << SK_BT_INDOPTION_SHIFT;
+ if (_bt_tuple_before_array_skeys(scan, dir, finaltup, tupdesc,
+ nfinaltupatts, false, 0, &scanBehind))
+ return false;
/*
- * We treat all btree operators as strict (even if they're not so marked
- * in pg_proc). This means that it is impossible for an operator condition
- * with a NULL comparison constant to succeed, and we can reject it right
- * away.
+ * If scanBehind was set, all of the untruncated attribute values from
+ * finaltup that correspond to an array match the array's current element,
+ * but there are other keys associated with truncated suffix attributes.
+ * Array advancement must have incremented the scan's arrays on the
+ * previous page, resulting in a set of array keys that happen to be an
+ * exact match for the current page high key's untruncated prefix values.
*
- * However, we now also support "x IS NULL" clauses as search conditions,
- * so in that case keep going. The planner has not filled in any
- * particular strategy in this case, so set it to BTEqualStrategyNumber
- * --- we can treat IS NULL as an equality operator for purposes of search
- * strategy.
- *
- * Likewise, "x IS NOT NULL" is supported. We treat that as either "less
- * than NULL" in a NULLS LAST index, or "greater than NULL" in a NULLS
- * FIRST index.
- *
- * Note: someday we might have to fill in sk_collation from the index
- * column's collation. At the moment this is a non-issue because we'll
- * never actually call the comparison operator on a NULL.
+ * This page definitely doesn't contain tuples that the scan will need to
+ * return. The next page may or may not contain relevant tuples. Handle
+ * this by cutting our losses and starting a new primscan.
*/
- if (skey->sk_flags & SK_ISNULL)
- {
- /* SK_ISNULL shouldn't be set in a row header scankey */
- Assert(!(skey->sk_flags & SK_ROW_HEADER));
-
- /* Set indoption flags in scankey (might be done already) */
- skey->sk_flags |= addflags;
-
- /* Set correct strategy for IS NULL or NOT NULL search */
- if (skey->sk_flags & SK_SEARCHNULL)
- {
- skey->sk_strategy = BTEqualStrategyNumber;
- skey->sk_subtype = InvalidOid;
- skey->sk_collation = InvalidOid;
- }
- else if (skey->sk_flags & SK_SEARCHNOTNULL)
- {
- if (skey->sk_flags & SK_BT_NULLS_FIRST)
- skey->sk_strategy = BTGreaterStrategyNumber;
- else
- skey->sk_strategy = BTLessStrategyNumber;
- skey->sk_subtype = InvalidOid;
- skey->sk_collation = InvalidOid;
- }
- else
- {
- /* regular qual, so it cannot be satisfied */
- return false;
- }
-
- /* Needn't do the rest */
- return true;
- }
+ if (scanBehind)
+ return false;
- if (skey->sk_strategy == InvalidStrategy)
- {
- /* Already-eliminated array scan key; don't need to fix anything */
- Assert(skey->sk_flags & SK_SEARCHARRAY);
+ if (!so->oppositeDirCheck)
return true;
- }
-
- /* Adjust strategy for DESC, if we didn't already */
- if ((addflags & SK_BT_DESC) && !(skey->sk_flags & SK_BT_DESC))
- skey->sk_strategy = BTCommuteStrategyNumber(skey->sk_strategy);
- skey->sk_flags |= addflags;
-
- /* If it's a row header, fix row member flags and strategies similarly */
- if (skey->sk_flags & SK_ROW_HEADER)
- {
- ScanKey subkey = (ScanKey) DatumGetPointer(skey->sk_argument);
-
- for (;;)
- {
- Assert(subkey->sk_flags & SK_ROW_MEMBER);
- addflags = indoption[subkey->sk_attno - 1] << SK_BT_INDOPTION_SHIFT;
- if ((addflags & SK_BT_DESC) && !(subkey->sk_flags & SK_BT_DESC))
- subkey->sk_strategy = BTCommuteStrategyNumber(subkey->sk_strategy);
- subkey->sk_flags |= addflags;
- if (subkey->sk_flags & SK_ROW_END)
- break;
- subkey++;
- }
- }
- return true;
+ return _bt_oppodir_checkkeys(scan, dir, finaltup);
}
/*
- * Mark a scankey as "required to continue the scan".
+ * Test whether an indextuple fails to satisfy an inequality required in the
+ * opposite direction only.
*
- * Depending on the operator type, the key may be required for both scan
- * directions or just one. Also, if the key is a row comparison header,
- * we have to mark its first subsidiary ScanKey as required. (Subsequent
- * subsidiary ScanKeys are normally for lower-order columns, and thus
- * cannot be required, since they're after the first non-equality scankey.)
+ * Caller's finaltup tuple is the page high key (for forwards scans), or the
+ * first non-pivot tuple (for backwards scans). Called during scans with
+ * required array keys and required opposite-direction inequalities.
*
- * Note: when we set required-key flag bits in a subsidiary scankey, we are
- * scribbling on a data structure belonging to the index AM's caller, not on
- * our private copy. This should be OK because the marking will not change
- * from scan to scan within a query, and so we'd just re-mark the same way
- * anyway on a rescan. Something to keep an eye on though.
+ * Returns false if an inequality scan key required in the opposite direction
+ * only isn't satisfied (and any earlier required scan keys are satisfied).
+ * Otherwise returns true.
+ *
+ * An unsatisfied inequality required in the opposite direction only might
+ * well enable skipping over many leaf pages, provided another _bt_first call
+ * takes place. This type of unsatisfied inequality won't usually cause
+ * _bt_checkkeys to stop the scan to consider array advancement/starting a new
+ * primitive index scan.
*/
-static void
-_bt_mark_scankey_required(ScanKey skey)
+static bool
+_bt_oppodir_checkkeys(IndexScanDesc scan, ScanDirection dir,
+ IndexTuple finaltup)
{
- int addflags;
+ Relation rel = scan->indexRelation;
+ TupleDesc tupdesc = RelationGetDescr(rel);
+ BTScanOpaque so = (BTScanOpaque) scan->opaque;
+ int nfinaltupatts = BTreeTupleGetNAtts(finaltup, rel);
+ bool continuescan;
+ ScanDirection flipped = -dir;
+ int ikey = 0;
- switch (skey->sk_strategy)
- {
- case BTLessStrategyNumber:
- case BTLessEqualStrategyNumber:
- addflags = SK_BT_REQFWD;
- break;
- case BTEqualStrategyNumber:
- addflags = SK_BT_REQFWD | SK_BT_REQBKWD;
- break;
- case BTGreaterEqualStrategyNumber:
- case BTGreaterStrategyNumber:
- addflags = SK_BT_REQBKWD;
- break;
- default:
- elog(ERROR, "unrecognized StrategyNumber: %d",
- (int) skey->sk_strategy);
- addflags = 0; /* keep compiler quiet */
- break;
- }
+ Assert(so->numArrayKeys);
- skey->sk_flags |= addflags;
+ _bt_check_compare(scan, flipped, finaltup, nfinaltupatts, tupdesc, false,
+ false, &continuescan,
+ &ikey);
- if (skey->sk_flags & SK_ROW_HEADER)
- {
- ScanKey subkey = (ScanKey) DatumGetPointer(skey->sk_argument);
+ if (!continuescan && so->keyData[ikey].sk_strategy != BTEqualStrategyNumber)
+ return false;
- /* First subkey should be same column/operator as the header */
- Assert(subkey->sk_flags & SK_ROW_MEMBER);
- Assert(subkey->sk_attno == skey->sk_attno);
- Assert(subkey->sk_strategy == skey->sk_strategy);
- subkey->sk_flags |= addflags;
- }
+ return true;
}
/*
- * Test whether an indextuple satisfies all the scankey conditions.
- *
- * Return true if so, false if not. If the tuple fails to pass the qual,
- * we also determine whether there's any need to continue the scan beyond
- * this tuple, and set pstate.continuescan accordingly. See comments for
- * _bt_preprocess_keys(), above, about how this is done.
+ * Determines an offset to the first scan key (an so->keyData[]-wise offset)
+ * that is _not_ guaranteed to be satisfied by every tuple from pstate.page,
+ * which is set in pstate.startikey for _bt_checkkeys calls for the page.
+ * This allows caller to save cycles on comparisons of a prefix of keys while
+ * reading pstate.page.
*
- * Forward scan callers can pass a high key tuple in the hopes of having
- * us set *continuescan to false, and avoiding an unnecessary visit to
- * the page to the right.
- *
- * Advances the scan's array keys when necessary for arrayKeys=true callers.
- * Caller can avoid all array related side-effects when calling just to do a
- * page continuescan precheck -- pass arrayKeys=false for that. Scans without
- * any arrays keys must always pass arrayKeys=false.
+ * Also determines if later calls to _bt_checkkeys (for pstate.page) should be
+ * forced to treat all required scan keys >= pstate.startikey as nonrequired
+ * (that is, if they're to be treated as if any SK_BT_REQFWD/SK_BT_REQBKWD
+ * markings that were set by preprocessing were not set at all, for the
+ * duration of _bt_checkkeys calls prior to the call for pstate.finaltup).
+ * This is indicated to caller by setting pstate.forcenonrequired.
*
- * Also stops and starts primitive index scans for arrayKeys=true callers.
- * Scans with array keys are required to set up page state that helps us with
- * this. The page's finaltup tuple (the page high key for a forward scan, or
- * the page's first non-pivot tuple for a backward scan) must be set in
- * pstate.finaltup ahead of the first call here for the page (or possibly the
- * first call after an initial continuescan-setting page precheck call). Set
- * this to NULL for rightmost page (or the leftmost page for backwards scans).
+ * Call here at the start of reading a leaf page beyond the first one for the
+ * primitive index scan. We consider all non-pivot tuples, so it doesn't make
+ * sense to call here when only a subset of those tuples can ever be read.
+ * This is also a good idea on performance grounds; not calling here when on
+ * the first page (first for the current primitive scan) avoids wasting cycles
+ * during selective point queries. They typically don't stand to gain as much
+ * when we can set pstate.startikey, and are likely to notice the overhead of
+ * calling here. (Also, allowing pstate.forcenonrequired to be set on a
+ * primscan's first page would mislead _bt_advance_array_keys, which expects
+ * pstate.nskipadvances to be representative of every first page's key space.)
*
- * scan: index scan descriptor (containing a search-type scankey)
- * pstate: page level input and output parameters
- * arrayKeys: should we advance the scan's array keys if necessary?
- * tuple: index tuple to test
- * tupnatts: number of attributes in tupnatts (high key may be truncated)
+ * Caller must call _bt_start_array_keys and reset startikey/forcenonrequired
+ * ahead of the finaltup _bt_checkkeys call when we set forcenonrequired=true.
+ * This will give _bt_checkkeys the opportunity to call _bt_advance_array_keys
+ * with sktrig_required=true, restoring the invariant that the scan's required
+ * arrays always track the scan's progress through the index's key space.
+ * Caller won't need to do this on the rightmost/leftmost page in the index
+ * (where pstate.finaltup isn't ever set), since forcenonrequired will never
+ * be set here in the first place.
*/
-bool
-_bt_checkkeys(IndexScanDesc scan, BTReadPageState *pstate, bool arrayKeys,
- IndexTuple tuple, int tupnatts)
+void
+_bt_set_startikey(IndexScanDesc scan, BTReadPageState *pstate)
{
- TupleDesc tupdesc = RelationGetDescr(scan->indexRelation);
BTScanOpaque so = (BTScanOpaque) scan->opaque;
- ScanDirection dir = pstate->dir;
- int ikey = 0;
- bool res;
-
- Assert(BTreeTupleGetNAtts(tuple, scan->indexRelation) == tupnatts);
-
- res = _bt_check_compare(scan, dir, tuple, tupnatts, tupdesc,
- arrayKeys, pstate->prechecked, pstate->firstmatch,
- &pstate->continuescan, &ikey);
+ Relation rel = scan->indexRelation;
+ TupleDesc tupdesc = RelationGetDescr(rel);
+ ItemId iid;
+ IndexTuple firsttup,
+ lasttup;
+ int startikey = 0,
+ arrayidx = 0,
+ firstchangingattnum;
+ bool start_past_saop_eq = false;
+
+ Assert(!so->scanBehind);
+ Assert(pstate->minoff < pstate->maxoff);
+ Assert(!pstate->firstpage);
+ Assert(pstate->startikey == 0);
+ Assert(!so->numArrayKeys || pstate->finaltup ||
+ P_RIGHTMOST(BTPageGetOpaque(pstate->page)) ||
+ P_LEFTMOST(BTPageGetOpaque(pstate->page)));
+
+ if (so->numberOfKeys == 0)
+ return;
-#ifdef USE_ASSERT_CHECKING
- if (!arrayKeys && so->numArrayKeys)
- {
- /*
- * This is a continuescan precheck call for a scan with array keys.
- *
- * Assert that the scan isn't in danger of becoming confused.
- */
- Assert(!so->scanBehind && !pstate->prechecked && !pstate->firstmatch);
- Assert(!_bt_tuple_before_array_skeys(scan, dir, tuple, tupdesc,
- tupnatts, false, 0, NULL));
- }
- if (pstate->prechecked || pstate->firstmatch)
- {
- bool dcontinuescan;
- int dikey = 0;
+ /* minoff is an offset to the lowest non-pivot tuple on the page */
+ iid = PageGetItemId(pstate->page, pstate->minoff);
+ firsttup = (IndexTuple) PageGetItem(pstate->page, iid);
- /*
- * Call relied on continuescan/firstmatch prechecks -- assert that we
- * get the same answer without those optimizations
- */
- Assert(res == _bt_check_compare(scan, dir, tuple, tupnatts, tupdesc,
- false, false, false,
- &dcontinuescan, &dikey));
- Assert(pstate->continuescan == dcontinuescan);
- }
-#endif
+ /* maxoff is an offset to the highest non-pivot tuple on the page */
+ iid = PageGetItemId(pstate->page, pstate->maxoff);
+ lasttup = (IndexTuple) PageGetItem(pstate->page, iid);
- /*
- * Only one _bt_check_compare call is required in the common case where
- * there are no equality strategy array scan keys. Otherwise we can only
- * accept _bt_check_compare's answer unreservedly when it didn't set
- * pstate.continuescan=false.
- */
- if (!arrayKeys || pstate->continuescan)
- return res;
+ /* Determine the first attribute whose values change on caller's page */
+ firstchangingattnum = _bt_keep_natts_fast(rel, firsttup, lasttup);
- /*
- * _bt_check_compare call set continuescan=false in the presence of
- * equality type array keys. This could mean that the tuple is just past
- * the end of matches for the current array keys.
- *
- * It's also possible that the scan is still _before_ the _start_ of
- * tuples matching the current set of array keys. Check for that first.
- */
- if (_bt_tuple_before_array_skeys(scan, dir, tuple, tupdesc, tupnatts, true,
- ikey, NULL))
+ for (; startikey < so->numberOfKeys; startikey++)
{
+ ScanKey key = so->keyData + startikey;
+ BTArrayKeyInfo *array;
+ Datum firstdatum,
+ lastdatum;
+ bool firstnull,
+ lastnull;
+ int32 result;
+
/*
- * Tuple is still before the start of matches according to the scan's
- * required array keys (according to _all_ of its required equality
- * strategy keys, actually).
- *
- * _bt_advance_array_keys occasionally sets so->scanBehind to signal
- * that the scan's current position/tuples might be significantly
- * behind (multiple pages behind) its current array keys. When this
- * happens, we need to be prepared to recover by starting a new
- * primitive index scan here, on our own.
+ * Determine if it's safe to set pstate.startikey to an offset to a
+ * key that comes after this key, by examining this key
*/
- Assert(!so->scanBehind ||
- so->keyData[ikey].sk_strategy == BTEqualStrategyNumber);
- if (unlikely(so->scanBehind) && pstate->finaltup &&
- _bt_tuple_before_array_skeys(scan, dir, pstate->finaltup, tupdesc,
- BTreeTupleGetNAtts(pstate->finaltup,
- scan->indexRelation),
- false, 0, NULL))
+ if (!(key->sk_flags & (SK_BT_REQFWD | SK_BT_REQBKWD)))
{
- /* Cut our losses -- start a new primitive index scan now */
- pstate->continuescan = false;
- so->needPrimScan = true;
+ /* Scan key isn't marked required (corner case) */
+ break; /* unsafe */
}
- else
+ if (key->sk_flags & SK_ROW_HEADER)
+ {
+ /* RowCompare inequalities currently aren't supported */
+ break; /* "unsafe" */
+ }
+ if (key->sk_strategy != BTEqualStrategyNumber)
{
- /* Override _bt_check_compare, continue primitive scan */
- pstate->continuescan = true;
-
/*
- * We will end up here repeatedly given a group of tuples > the
- * previous array keys and < the now-current keys (for a backwards
- * scan it's just the same, though the operators swap positions).
+ * Scalar inequality key.
*
- * We must avoid allowing this linear search process to scan very
- * many tuples from well before the start of tuples matching the
- * current array keys (or from well before the point where we'll
- * once again have to advance the scan's array keys).
+ * It's definitely safe for _bt_checkkeys to avoid assessing this
+ * inequality when the page's first and last non-pivot tuples both
+ * satisfy the inequality (since the same must also be true of all
+ * the tuples in between these two).
*
- * We keep the overhead under control by speculatively "looking
- * ahead" to later still-unscanned items from this same leaf page.
- * We'll only attempt this once the number of tuples that the
- * linear search process has examined starts to get out of hand.
+ * Unlike the "=" case, it doesn't matter if this attribute has
+ * more than one distinct value (though it _is_ necessary for any
+ * and all _prior_ attributes to contain no more than one distinct
+ * value amongst all of the tuples from pstate.page).
*/
- pstate->rechecks++;
- if (pstate->rechecks >= LOOK_AHEAD_REQUIRED_RECHECKS)
+ if (key->sk_attno > firstchangingattnum) /* >, not >= */
+ break; /* unsafe, preceding attr has multiple
+ * distinct values */
+
+ firstdatum = index_getattr(firsttup, key->sk_attno, tupdesc, &firstnull);
+ lastdatum = index_getattr(lasttup, key->sk_attno, tupdesc, &lastnull);
+
+ if (key->sk_flags & SK_ISNULL)
{
- /* See if we should skip ahead within the current leaf page */
- _bt_checkkeys_look_ahead(scan, pstate, tupnatts, tupdesc);
+ /* IS NOT NULL key */
+ Assert(key->sk_flags & SK_SEARCHNOTNULL);
- /*
- * Might have set pstate.skip to a later page offset. When
- * that happens then _bt_readpage caller will inexpensively
- * skip ahead to a later tuple from the same page (the one
- * just after the tuple we successfully "looked ahead" to).
- */
+ if (firstnull || lastnull)
+ break; /* unsafe */
+
+ /* Safe, IS NOT NULL key satisfied by every tuple */
+ continue;
}
+
+ /* Test firsttup */
+ if (firstnull ||
+ !DatumGetBool(FunctionCall2Coll(&key->sk_func,
+ key->sk_collation, firstdatum,
+ key->sk_argument)))
+ break; /* unsafe */
+
+ /* Test lasttup */
+ if (lastnull ||
+ !DatumGetBool(FunctionCall2Coll(&key->sk_func,
+ key->sk_collation, lastdatum,
+ key->sk_argument)))
+ break; /* unsafe */
+
+ /* Safe, scalar inequality satisfied by every tuple */
+ continue;
}
- /* This indextuple doesn't match the current qual, in any case */
- return false;
+ /* Some = key (could be a scalar = key, could be an array = key) */
+ Assert(key->sk_strategy == BTEqualStrategyNumber);
+
+ if (!(key->sk_flags & SK_SEARCHARRAY))
+ {
+ /*
+ * Scalar = key (possibly an IS NULL key).
+ *
+ * It is unsafe to set pstate.startikey to an ikey beyond this
+ * key, unless the = key is satisfied by every possible tuple on
+ * the page (possible only when attribute has just one distinct
+ * value among all tuples on the page).
+ */
+ if (key->sk_attno >= firstchangingattnum)
+ break; /* unsafe, multiple distinct attr values */
+
+ firstdatum = index_getattr(firsttup, key->sk_attno, tupdesc,
+ &firstnull);
+ if (key->sk_flags & SK_ISNULL)
+ {
+ /* IS NULL key */
+ Assert(key->sk_flags & SK_SEARCHNULL);
+
+ if (!firstnull)
+ break; /* unsafe */
+
+ /* Safe, IS NULL key satisfied by every tuple */
+ continue;
+ }
+ if (firstnull ||
+ !DatumGetBool(FunctionCall2Coll(&key->sk_func,
+ key->sk_collation, firstdatum,
+ key->sk_argument)))
+ break; /* unsafe */
+
+ /* Safe, scalar = key satisfied by every tuple */
+ continue;
+ }
+
+ /* = array key (could be a SAOP array, could be a skip array) */
+ array = &so->arrayKeys[arrayidx++];
+ Assert(array->scan_key == startikey);
+ if (array->num_elems != -1)
+ {
+ /*
+ * SAOP array = key.
+ *
+ * Handle this like we handle scalar = keys (though binary search
+ * for a matching element, to avoid relying on key's sk_argument).
+ */
+ if (key->sk_attno >= firstchangingattnum)
+ break; /* unsafe, multiple distinct attr values */
+
+ firstdatum = index_getattr(firsttup, key->sk_attno, tupdesc,
+ &firstnull);
+ _bt_binsrch_array_skey(&so->orderProcs[startikey],
+ false, NoMovementScanDirection,
+ firstdatum, firstnull, array, key,
+ &result);
+ if (result != 0)
+ break; /* unsafe */
+
+ /* Safe, SAOP = key satisfied by every tuple */
+ start_past_saop_eq = true;
+ continue;
+ }
+
+ /*
+ * Skip array = key
+ */
+ Assert(key->sk_flags & SK_BT_SKIP);
+ if (array->null_elem)
+ {
+ /*
+ * Non-range skip array = key.
+ *
+ * Safe, non-range skip array "satisfied" by every tuple on page
+ * (safe even when "key->sk_attno > firstchangingattnum").
+ */
+ continue;
+ }
+
+ /*
+ * Range skip array = key.
+ *
+ * Handle this like we handle scalar inequality keys (but avoid using
+ * key's sk_argument directly, as in the SAOP array case).
+ */
+ if (key->sk_attno > firstchangingattnum) /* >, not >= */
+ break; /* unsafe, preceding attr has multiple
+ * distinct values */
+
+ firstdatum = index_getattr(firsttup, key->sk_attno, tupdesc, &firstnull);
+ lastdatum = index_getattr(lasttup, key->sk_attno, tupdesc, &lastnull);
+
+ /* Test firsttup */
+ _bt_binsrch_skiparray_skey(false, ForwardScanDirection,
+ firstdatum, firstnull, array, key,
+ &result);
+ if (result != 0)
+ break; /* unsafe */
+
+ /* Test lasttup */
+ _bt_binsrch_skiparray_skey(false, ForwardScanDirection,
+ lastdatum, lastnull, array, key,
+ &result);
+ if (result != 0)
+ break; /* unsafe */
+
+ /* Safe, range skip array satisfied by every tuple on page */
}
/*
- * Caller's tuple is >= the current set of array keys and other equality
- * constraint scan keys (or <= if this is a backwards scan). It's now
- * clear that we _must_ advance any required array keys in lockstep with
- * the scan.
+ * Use of forcenonrequired is typically undesirable, since it'll force
+ * _bt_readpage caller to read every tuple on the page -- even though, in
+ * general, it might well be possible to end the scan on an earlier tuple.
+ * However, caller must use forcenonrequired when start_past_saop_eq=true,
+ * since the usual required array behavior might fail to roll over to the
+ * SAOP array.
+ *
+ * We always prefer forcenonrequired=true during scans with skip arrays
+ * (except on the first page of each primitive index scan), though -- even
+ * when "startikey == 0". That way, _bt_advance_array_keys's low-order
+ * key precheck optimization can always be used (unless on the first page
+ * of the scan). It seems slightly preferable to check more tuples when
+ * that allows us to do significantly less skip array maintenance.
*/
- return _bt_advance_array_keys(scan, pstate, tuple, tupnatts, tupdesc,
- ikey, true);
+ pstate->forcenonrequired = (start_past_saop_eq || so->skipScan);
+ pstate->startikey = startikey;
+
+ /*
+ * _bt_readpage caller is required to call _bt_checkkeys against page's
+ * finaltup with forcenonrequired=false whenever we initially set
+ * forcenonrequired=true. That way the scan's arrays will reliably track
+ * its progress through the index's key space.
+ *
+ * We don't expect this when _bt_readpage caller has no finaltup due to
+ * its page being the rightmost (or the leftmost, during backwards scans).
+ * When we see that _bt_readpage has no finaltup, back out of everything.
+ */
+ Assert(!pstate->forcenonrequired || so->numArrayKeys);
+ if (pstate->forcenonrequired && !pstate->finaltup)
+ {
+ pstate->forcenonrequired = false;
+ pstate->startikey = 0;
+ }
}
/*
@@ -3673,19 +2677,27 @@ _bt_checkkeys(IndexScanDesc scan, BTReadPageState *pstate, bool arrayKeys,
* by the current array key, or if they're truly unsatisfied (that is, if
* they're unsatisfied by every possible array key).
*
- * Though we advance non-required array keys on our own, that shouldn't have
- * any lasting consequences for the scan. By definition, non-required arrays
- * have no fixed relationship with the scan's progress. (There are delicate
- * considerations for non-required arrays when the arrays need to be advanced
- * following our setting continuescan to false, but that doesn't concern us.)
- *
* Pass advancenonrequired=false to avoid all array related side effects.
* This allows _bt_advance_array_keys caller to avoid infinite recursion.
+ *
+ * Pass forcenonrequired=true to instruct us to treat all keys as nonrequired.
+ * This is used to make it safe to temporarily stop properly maintaining the
+ * scan's required arrays. _bt_checkkeys caller (_bt_readpage, actually)
+ * determines a prefix of keys that must satisfy every possible corresponding
+ * index attribute value from its page, which is passed to us via *ikey arg
+ * (this is the first key that might be unsatisfied by tuples on the page).
+ * Obviously, we won't maintain any array keys from before *ikey, so it's
+ * quite possible for such arrays to "fall behind" the index's keyspace.
+ * Caller will need to "catch up" by passing forcenonrequired=true (alongside
+ * an *ikey=0) once the page's finaltup is reached.
+ *
+ * Note: it's safe to pass an *ikey > 0 with forcenonrequired=false, but only
+ * when caller determines that it won't affect array maintenance.
*/
static bool
_bt_check_compare(IndexScanDesc scan, ScanDirection dir,
IndexTuple tuple, int tupnatts, TupleDesc tupdesc,
- bool advancenonrequired, bool prechecked, bool firstmatch,
+ bool advancenonrequired, bool forcenonrequired,
bool *continuescan, int *ikey)
{
BTScanOpaque so = (BTScanOpaque) scan->opaque;
@@ -3702,36 +2714,20 @@ _bt_check_compare(IndexScanDesc scan, ScanDirection dir,
/*
* Check if the key is required in the current scan direction, in the
- * opposite scan direction _only_, or in neither direction
+ * opposite scan direction _only_, or in neither direction (except
+ * when we're forced to treat all scan keys as nonrequired)
*/
- if (((key->sk_flags & SK_BT_REQFWD) && ScanDirectionIsForward(dir)) ||
- ((key->sk_flags & SK_BT_REQBKWD) && ScanDirectionIsBackward(dir)))
+ if (forcenonrequired)
+ {
+ /* treating scan's keys as non-required */
+ }
+ else if (((key->sk_flags & SK_BT_REQFWD) && ScanDirectionIsForward(dir)) ||
+ ((key->sk_flags & SK_BT_REQBKWD) && ScanDirectionIsBackward(dir)))
requiredSameDir = true;
else if (((key->sk_flags & SK_BT_REQFWD) && ScanDirectionIsBackward(dir)) ||
((key->sk_flags & SK_BT_REQBKWD) && ScanDirectionIsForward(dir)))
requiredOppositeDirOnly = true;
- /*
- * If the caller told us the *continuescan flag is known to be true
- * for the last item on the page, then we know the keys required for
- * the current direction scan should be matched. Otherwise, the
- * *continuescan flag would be set for the current item and
- * subsequently the last item on the page accordingly.
- *
- * If the key is required for the opposite direction scan, we can skip
- * the check if the caller tells us there was already at least one
- * matching item on the page. Also, we require the *continuescan flag
- * to be true for the last item on the page to know there are no
- * NULLs.
- *
- * Both cases above work except for the row keys, where NULLs could be
- * found in the middle of matching values.
- */
- if (prechecked &&
- (requiredSameDir || (requiredOppositeDirOnly && firstmatch)) &&
- !(key->sk_flags & SK_ROW_HEADER))
- continue;
-
if (key->sk_attno > tupnatts)
{
/*
@@ -3744,11 +2740,35 @@ _bt_check_compare(IndexScanDesc scan, ScanDirection dir,
continue;
}
+ /*
+ * A skip array scan key uses one of several sentinel values. We just
+ * fall back on _bt_tuple_before_array_skeys when we see such a value.
+ */
+ if (key->sk_flags & (SK_BT_MINVAL | SK_BT_MAXVAL |
+ SK_BT_NEXT | SK_BT_PRIOR))
+ {
+ Assert(key->sk_flags & SK_SEARCHARRAY);
+ Assert(key->sk_flags & SK_BT_SKIP);
+ Assert(requiredSameDir || forcenonrequired);
+
+ /*
+ * Cannot fall back on _bt_tuple_before_array_skeys when we're
+ * treating the scan's keys as nonrequired, though. Just handle
+ * this like any other non-required equality-type array key.
+ */
+ if (forcenonrequired)
+ return _bt_advance_array_keys(scan, NULL, tuple, tupnatts,
+ tupdesc, *ikey, false);
+
+ *continuescan = false;
+ return false;
+ }
+
/* row-comparison keys need special processing */
if (key->sk_flags & SK_ROW_HEADER)
{
if (_bt_check_rowcompare(key, tuple, tupnatts, tupdesc, dir,
- continuescan))
+ forcenonrequired, continuescan))
continue;
return false;
}
@@ -3769,6 +2789,7 @@ _bt_check_compare(IndexScanDesc scan, ScanDirection dir,
else
{
Assert(key->sk_flags & SK_SEARCHNOTNULL);
+ Assert(!(key->sk_flags & SK_BT_SKIP));
if (!isNull)
continue; /* tuple satisfies this qual */
}
@@ -3780,15 +2801,37 @@ _bt_check_compare(IndexScanDesc scan, ScanDirection dir,
*/
if (requiredSameDir)
*continuescan = false;
+ else if (unlikely(key->sk_flags & SK_BT_SKIP))
+ {
+ /*
+ * If we're treating scan keys as nonrequired, and encounter a
+ * skip array scan key whose current element is NULL, then it
+ * must be a non-range skip array. It must be satisfied, so
+ * there's no need to call _bt_advance_array_keys to check.
+ */
+ Assert(forcenonrequired && *ikey > 0);
+ continue;
+ }
/*
- * In any case, this indextuple doesn't match the qual.
+ * This indextuple doesn't match the qual.
*/
return false;
}
if (isNull)
{
+ /*
+ * Scalar scan key isn't satisfied by NULL tuple value.
+ *
+ * If we're treating scan keys as nonrequired, and key is for a
+ * skip array, then we must attempt to advance the array to NULL
+ * (if we're successful then the tuple might match the qual).
+ */
+ if (unlikely(forcenonrequired && key->sk_flags & SK_BT_SKIP))
+ return _bt_advance_array_keys(scan, NULL, tuple, tupnatts,
+ tupdesc, *ikey, false);
+
if (key->sk_flags & SK_BT_NULLS_FIRST)
{
/*
@@ -3803,7 +2846,7 @@ _bt_check_compare(IndexScanDesc scan, ScanDirection dir,
* (_bt_advance_array_keys also relies on this behavior during
* forward scans.)
*/
- if ((key->sk_flags & (SK_BT_REQFWD | SK_BT_REQBKWD)) &&
+ if ((requiredSameDir || requiredOppositeDirOnly) &&
ScanDirectionIsBackward(dir))
*continuescan = false;
}
@@ -3821,26 +2864,18 @@ _bt_check_compare(IndexScanDesc scan, ScanDirection dir,
* (_bt_advance_array_keys also relies on this behavior during
* backward scans.)
*/
- if ((key->sk_flags & (SK_BT_REQFWD | SK_BT_REQBKWD)) &&
+ if ((requiredSameDir || requiredOppositeDirOnly) &&
ScanDirectionIsForward(dir))
*continuescan = false;
}
/*
- * In any case, this indextuple doesn't match the qual.
+ * This indextuple doesn't match the qual.
*/
return false;
}
- /*
- * Apply the key-checking function, though only if we must.
- *
- * When a key is required in the opposite-of-scan direction _only_,
- * then it must already be satisfied if firstmatch=true indicates that
- * an earlier tuple from this same page satisfied it earlier on.
- */
- if (!(requiredOppositeDirOnly && firstmatch) &&
- !DatumGetBool(FunctionCall2Coll(&key->sk_func, key->sk_collation,
+ if (!DatumGetBool(FunctionCall2Coll(&key->sk_func, key->sk_collation,
datum, key->sk_argument)))
{
/*
@@ -3890,7 +2925,8 @@ _bt_check_compare(IndexScanDesc scan, ScanDirection dir,
*/
static bool
_bt_check_rowcompare(ScanKey skey, IndexTuple tuple, int tupnatts,
- TupleDesc tupdesc, ScanDirection dir, bool *continuescan)
+ TupleDesc tupdesc, ScanDirection dir,
+ bool forcenonrequired, bool *continuescan)
{
ScanKey subkey = (ScanKey) DatumGetPointer(skey->sk_argument);
int32 cmpresult = 0;
@@ -3907,6 +2943,31 @@ _bt_check_rowcompare(ScanKey skey, IndexTuple tuple, int tupnatts,
Assert(subkey->sk_flags & SK_ROW_MEMBER);
+ /* When a NULL row member is compared, the row never matches */
+ if (subkey->sk_flags & SK_ISNULL)
+ {
+ /*
+ * Unlike the simple-scankey case, this isn't a disallowed case
+ * (except when it's the first row element that has the NULL arg).
+ * But it can never match. If all the earlier row comparison
+ * columns are required for the scan direction, we can stop the
+ * scan, because there can't be another tuple that will succeed.
+ */
+ Assert(subkey != (ScanKey) DatumGetPointer(skey->sk_argument));
+ subkey--;
+ if (forcenonrequired)
+ {
+ /* treating scan's keys as non-required */
+ }
+ else if ((subkey->sk_flags & SK_BT_REQFWD) &&
+ ScanDirectionIsForward(dir))
+ *continuescan = false;
+ else if ((subkey->sk_flags & SK_BT_REQBKWD) &&
+ ScanDirectionIsBackward(dir))
+ *continuescan = false;
+ return false;
+ }
+
if (subkey->sk_attno > tupnatts)
{
/*
@@ -3916,11 +2977,7 @@ _bt_check_rowcompare(ScanKey skey, IndexTuple tuple, int tupnatts,
* attribute passes the qual.
*/
Assert(BTreeTupleIsPivot(tuple));
- cmpresult = 0;
- if (subkey->sk_flags & SK_ROW_END)
- break;
- subkey++;
- continue;
+ return true;
}
datum = index_getattr(tuple,
@@ -3930,21 +2987,47 @@ _bt_check_rowcompare(ScanKey skey, IndexTuple tuple, int tupnatts,
if (isNull)
{
- if (subkey->sk_flags & SK_BT_NULLS_FIRST)
+ int reqflags;
+
+ if (forcenonrequired)
+ {
+ /* treating scan's keys as non-required */
+ }
+ else if (subkey->sk_flags & SK_BT_NULLS_FIRST)
{
/*
* Since NULLs are sorted before non-NULLs, we know we have
* reached the lower limit of the range of values for this
* index attr. On a backward scan, we can stop if this qual
- * is one of the "must match" subset. We can stop regardless
- * of whether the qual is > or <, so long as it's required,
- * because it's not possible for any future tuples to pass. On
- * a forward scan, however, we must keep going, because we may
- * have initially positioned to the start of the index.
- * (_bt_advance_array_keys also relies on this behavior during
- * forward scans.)
+ * is one of the "must match" subset. However, on a forwards
+ * scan, we must keep going, because we may have initially
+ * positioned to the start of the index.
+ *
+ * All required NULLS FIRST > row members can use NULL tuple
+ * values to end backwards scans, just like with other values.
+ * A qual "WHERE (a, b, c) > (9, 42, 'foo')" can terminate a
+ * backwards scan upon reaching the index's rightmost "a = 9"
+ * tuple whose "b" column contains a NULL (if not sooner).
+ * Since "b" is NULLS FIRST, we can treat its NULLs as "<" 42.
+ */
+ reqflags = SK_BT_REQBKWD;
+
+ /*
+ * When a most significant required NULLS FIRST < row compare
+ * member sees NULL tuple values during a backwards scan, it
+ * signals the end of matches for the whole row compare/scan.
+ * A qual "WHERE (a, b, c) < (9, 42, 'foo')" will terminate a
+ * backwards scan upon reaching the rightmost tuple whose "a"
+ * column has a NULL. The "a" NULL value is "<" 9, and yet
+ * our < row compare will still end the scan. (This isn't
+ * safe with later/lower-order row members. Notice that it
+ * can only happen with an "a" NULL some time after the scan
+ * completely stops needing to use its "b" and "c" members.)
*/
- if ((subkey->sk_flags & (SK_BT_REQFWD | SK_BT_REQBKWD)) &&
+ if (subkey == (ScanKey) DatumGetPointer(skey->sk_argument))
+ reqflags |= SK_BT_REQFWD; /* safe, first row member */
+
+ if ((subkey->sk_flags & reqflags) &&
ScanDirectionIsBackward(dir))
*continuescan = false;
}
@@ -3954,15 +3037,35 @@ _bt_check_rowcompare(ScanKey skey, IndexTuple tuple, int tupnatts,
* Since NULLs are sorted after non-NULLs, we know we have
* reached the upper limit of the range of values for this
* index attr. On a forward scan, we can stop if this qual is
- * one of the "must match" subset. We can stop regardless of
- * whether the qual is > or <, so long as it's required,
- * because it's not possible for any future tuples to pass. On
- * a backward scan, however, we must keep going, because we
- * may have initially positioned to the end of the index.
- * (_bt_advance_array_keys also relies on this behavior during
- * backward scans.)
+ * one of the "must match" subset. However, on a backward
+ * scan, we must keep going, because we may have initially
+ * positioned to the end of the index.
+ *
+ * All required NULLS LAST < row members can use NULL tuple
+ * values to end forwards scans, just like with other values.
+ * A qual "WHERE (a, b, c) < (9, 42, 'foo')" can terminate a
+ * forwards scan upon reaching the index's leftmost "a = 9"
+ * tuple whose "b" column contains a NULL (if not sooner).
+ * Since "b" is NULLS LAST, we can treat its NULLs as ">" 42.
+ */
+ reqflags = SK_BT_REQFWD;
+
+ /*
+ * When a most significant required NULLS LAST > row compare
+ * member sees NULL tuple values during a forwards scan, it
+ * signals the end of matches for the whole row compare/scan.
+ * A qual "WHERE (a, b, c) > (9, 42, 'foo')" will terminate a
+ * forwards scan upon reaching the leftmost tuple whose "a"
+ * column has a NULL. The "a" NULL value is ">" 9, and yet
+ * our > row compare will end the scan. (This isn't safe with
+ * later/lower-order row members. Notice that it can only
+ * happen with an "a" NULL some time after the scan completely
+ * stops needing to use its "b" and "c" members.)
*/
- if ((subkey->sk_flags & (SK_BT_REQFWD | SK_BT_REQBKWD)) &&
+ if (subkey == (ScanKey) DatumGetPointer(skey->sk_argument))
+ reqflags |= SK_BT_REQBKWD; /* safe, first row member */
+
+ if ((subkey->sk_flags & reqflags) &&
ScanDirectionIsForward(dir))
*continuescan = false;
}
@@ -3973,25 +3076,6 @@ _bt_check_rowcompare(ScanKey skey, IndexTuple tuple, int tupnatts,
return false;
}
- if (subkey->sk_flags & SK_ISNULL)
- {
- /*
- * Unlike the simple-scankey case, this isn't a disallowed case.
- * But it can never match. If all the earlier row comparison
- * columns are required for the scan direction, we can stop the
- * scan, because there can't be another tuple that will succeed.
- */
- if (subkey != (ScanKey) DatumGetPointer(skey->sk_argument))
- subkey--;
- if ((subkey->sk_flags & SK_BT_REQFWD) &&
- ScanDirectionIsForward(dir))
- *continuescan = false;
- else if ((subkey->sk_flags & SK_BT_REQBKWD) &&
- ScanDirectionIsBackward(dir))
- *continuescan = false;
- return false;
- }
-
/* Perform the test --- three-way comparison not bool operator */
cmpresult = DatumGetInt32(FunctionCall2Coll(&subkey->sk_func,
subkey->sk_collation,
@@ -4031,13 +3115,12 @@ _bt_check_rowcompare(ScanKey skey, IndexTuple tuple, int tupnatts,
result = (cmpresult > 0);
break;
default:
- elog(ERROR, "unrecognized RowCompareType: %d",
- (int) subkey->sk_strategy);
+ elog(ERROR, "unexpected strategy number %d", subkey->sk_strategy);
result = 0; /* keep compiler quiet */
break;
}
- if (!result)
+ if (!result && !forcenonrequired)
{
/*
* Tuple fails this qual. If it's a required qual for the current
@@ -4076,10 +3159,13 @@ static void
_bt_checkkeys_look_ahead(IndexScanDesc scan, BTReadPageState *pstate,
int tupnatts, TupleDesc tupdesc)
{
- ScanDirection dir = pstate->dir;
+ BTScanOpaque so = (BTScanOpaque) scan->opaque;
+ ScanDirection dir = so->currPos.dir;
OffsetNumber aheadoffnum;
IndexTuple ahead;
+ Assert(!pstate->forcenonrequired);
+
/* Avoid looking ahead when comparing the page high key */
if (pstate->offnum < pstate->minoff)
return;
@@ -4101,7 +3187,7 @@ _bt_checkkeys_look_ahead(IndexScanDesc scan, BTReadPageState *pstate,
*/
if (!pstate->targetdistance)
pstate->targetdistance = LOOK_AHEAD_DEFAULT_DISTANCE;
- else
+ else if (pstate->targetdistance < MaxIndexTuplesPerPage / 2)
pstate->targetdistance *= 2;
/* Don't read past the end (or before the start) of the page, though */
@@ -4148,87 +3234,85 @@ _bt_checkkeys_look_ahead(IndexScanDesc scan, BTReadPageState *pstate,
* current page and killed tuples thereon (generally, this should only be
* called if so->numKilled > 0).
*
- * The caller does not have a lock on the page and may or may not have the
- * page pinned in a buffer. Note that read-lock is sufficient for setting
- * LP_DEAD status (which is only a hint).
- *
- * We match items by heap TID before assuming they are the right ones to
- * delete. We cope with cases where items have moved right due to insertions.
- * If an item has moved off the current page due to a split, we'll fail to
- * find it and do nothing (this is not an error case --- we assume the item
- * will eventually get marked in a future indexscan).
+ * Caller should not have a lock on the so->currPos page, but must hold a
+ * buffer pin when !so->dropPin. When we return, it still won't be locked.
+ * It'll continue to hold whatever pins were held before calling here.
*
- * Note that if we hold a pin on the target page continuously from initially
- * reading the items until applying this function, VACUUM cannot have deleted
- * any items from the page, and so there is no need to search left from the
- * recorded offset. (This observation also guarantees that the item is still
- * the right one to delete, which might otherwise be questionable since heap
- * TIDs can get recycled.) This holds true even if the page has been modified
- * by inserts and page splits, so there is no need to consult the LSN.
+ * We match items by heap TID before assuming they are the right ones to set
+ * LP_DEAD. If the scan is one that holds a buffer pin on the target page
+ * continuously from initially reading the items until applying this function
+ * (if it is a !so->dropPin scan), VACUUM cannot have deleted any items on the
+ * page, so the page's TIDs can't have been recycled by now. There's no risk
+ * that we'll confuse a new index tuple that happens to use a recycled TID
+ * with a now-removed tuple with the same TID (that used to be on this same
+ * page). We can't rely on that during scans that drop buffer pins eagerly
+ * (so->dropPin scans), though, so we must condition setting LP_DEAD bits on
+ * the page LSN having not changed since back when _bt_readpage saw the page.
+ * We totally give up on setting LP_DEAD bits when the page LSN changed.
*
- * If the pin was released after reading the page, then we re-read it. If it
- * has been modified since we read it (as determined by the LSN), we dare not
- * flag any entries because it is possible that the old entry was vacuumed
- * away and the TID was re-used by a completely different heap tuple.
+ * We give up much less often during !so->dropPin scans, but it still happens.
+ * We cope with cases where items have moved right due to insertions. If an
+ * item has moved off the current page due to a split, we'll fail to find it
+ * and just give up on it.
*/
void
_bt_killitems(IndexScanDesc scan)
{
+ Relation rel = scan->indexRelation;
BTScanOpaque so = (BTScanOpaque) scan->opaque;
Page page;
BTPageOpaque opaque;
OffsetNumber minoff;
OffsetNumber maxoff;
- int i;
int numKilled = so->numKilled;
bool killedsomething = false;
- bool droppedpin PG_USED_FOR_ASSERTS_ONLY;
+ Buffer buf;
+ Assert(numKilled > 0);
Assert(BTScanPosIsValid(so->currPos));
+ Assert(scan->heapRelation != NULL); /* can't be a bitmap index scan */
- /*
- * Always reset the scan state, so we don't look for same items on other
- * pages.
- */
+ /* Always invalidate so->killedItems[] before leaving so->currPos */
so->numKilled = 0;
- if (BTScanPosIsPinned(so->currPos))
+ if (!so->dropPin)
{
/*
* We have held the pin on this page since we read the index tuples,
* so all we need to do is lock it. The pin will have prevented
- * re-use of any TID on the page, so there is no need to check the
- * LSN.
+ * concurrent VACUUMs from recycling any of the TIDs on the page.
*/
- droppedpin = false;
- _bt_lockbuf(scan->indexRelation, so->currPos.buf, BT_READ);
-
- page = BufferGetPage(so->currPos.buf);
+ Assert(BTScanPosIsPinned(so->currPos));
+ buf = so->currPos.buf;
+ _bt_lockbuf(rel, buf, BT_READ);
}
else
{
- Buffer buf;
+ XLogRecPtr latestlsn;
- droppedpin = true;
- /* Attempt to re-read the buffer, getting pin and lock. */
- buf = _bt_getbuf(scan->indexRelation, so->currPos.currPage, BT_READ);
+ Assert(!BTScanPosIsPinned(so->currPos));
+ Assert(RelationNeedsWAL(rel));
+ buf = _bt_getbuf(rel, so->currPos.currPage, BT_READ);
- page = BufferGetPage(buf);
- if (BufferGetLSNAtomic(buf) == so->currPos.lsn)
- so->currPos.buf = buf;
- else
+ latestlsn = BufferGetLSNAtomic(buf);
+ Assert(!XLogRecPtrIsInvalid(so->currPos.lsn));
+ Assert(so->currPos.lsn <= latestlsn);
+ if (so->currPos.lsn != latestlsn)
{
- /* Modified while not pinned means hinting is not safe. */
- _bt_relbuf(scan->indexRelation, buf);
+ /* Modified, give up on hinting */
+ _bt_relbuf(rel, buf);
return;
}
+
+ /* Unmodified, hinting is safe */
}
+ page = BufferGetPage(buf);
opaque = BTPageGetOpaque(page);
minoff = P_FIRSTDATAKEY(opaque);
maxoff = PageGetMaxOffsetNumber(page);
- for (i = 0; i < numKilled; i++)
+ for (int i = 0; i < numKilled; i++)
{
int itemIndex = so->killedItems[i];
BTScanPosItem *kitem = &so->currPos.items[itemIndex];
@@ -4260,7 +3344,7 @@ _bt_killitems(IndexScanDesc scan)
* correctness.
*
* Note that the page may have been modified in almost any way
- * since we first read it (in the !droppedpin case), so it's
+ * since we first read it (in the !so->dropPin case), so it's
* possible that this posting list tuple wasn't a posting list
* tuple when we first encountered its heap TIDs.
*/
@@ -4276,7 +3360,7 @@ _bt_killitems(IndexScanDesc scan)
* though only in the common case where the page can't
* have been concurrently modified
*/
- Assert(kitem->indexOffset == offnum || !droppedpin);
+ Assert(kitem->indexOffset == offnum || !so->dropPin);
/*
* Read-ahead to later kitems here.
@@ -4340,10 +3424,13 @@ _bt_killitems(IndexScanDesc scan)
if (killedsomething)
{
opaque->btpo_flags |= BTP_HAS_GARBAGE;
- MarkBufferDirtyHint(so->currPos.buf, true);
+ MarkBufferDirtyHint(buf, true);
}
- _bt_unlockbuf(scan->indexRelation, so->currPos.buf);
+ if (!so->dropPin)
+ _bt_unlockbuf(rel, buf);
+ else
+ _bt_relbuf(rel, buf);
}
@@ -4884,11 +3971,11 @@ _bt_keep_natts_fast(Relation rel, IndexTuple lastleft, IndexTuple firstright)
datum2;
bool isNull1,
isNull2;
- Form_pg_attribute att;
+ CompactAttribute *att;
datum1 = index_getattr(lastleft, attnum, itupdesc, &isNull1);
datum2 = index_getattr(firstright, attnum, itupdesc, &isNull2);
- att = TupleDescAttr(itupdesc, attnum - 1);
+ att = TupleDescCompactAttr(itupdesc, attnum - 1);
if (isNull1 != isNull2)
break;
@@ -5087,7 +4174,7 @@ _bt_check_third_page(Relation rel, Relation heap, bool needheaptidspace,
itemsz = MAXALIGN(IndexTupleSize(newtup));
/* Double check item size against limit */
- if (itemsz <= BTMaxItemSize(page))
+ if (itemsz <= BTMaxItemSize)
return;
/*
@@ -5095,7 +4182,7 @@ _bt_check_third_page(Relation rel, Relation heap, bool needheaptidspace,
* index uses version 2 or version 3, or that page is an internal page, in
* which case a slightly higher limit applies.
*/
- if (!needheaptidspace && itemsz <= BTMaxItemSizeNoHeapTid(page))
+ if (!needheaptidspace && itemsz <= BTMaxItemSizeNoHeapTid)
return;
/*
@@ -5112,8 +4199,7 @@ _bt_check_third_page(Relation rel, Relation heap, bool needheaptidspace,
errmsg("index row size %zu exceeds btree version %u maximum %zu for index \"%s\"",
itemsz,
needheaptidspace ? BTREE_VERSION : BTREE_NOVAC_VERSION,
- needheaptidspace ? BTMaxItemSize(page) :
- BTMaxItemSizeNoHeapTid(page),
+ needheaptidspace ? BTMaxItemSize : BTMaxItemSizeNoHeapTid,
RelationGetRelationName(rel)),
errdetail("Index row references tuple (%u,%u) in relation \"%s\".",
ItemPointerGetBlockNumber(BTreeTupleGetHeapTID(newtup)),
diff --git a/src/backend/access/nbtree/nbtvalidate.c b/src/backend/access/nbtree/nbtvalidate.c
index e9d4cd60de3c2..817ad358f0caa 100644
--- a/src/backend/access/nbtree/nbtvalidate.c
+++ b/src/backend/access/nbtree/nbtvalidate.c
@@ -3,7 +3,7 @@
* nbtvalidate.c
* Opclass validator for btree.
*
- * Portions Copyright (c) 1996-2024, PostgreSQL Global Development Group
+ * Portions Copyright (c) 1996-2025, PostgreSQL Global Development Group
* Portions Copyright (c) 1994, Regents of the University of California
*
* IDENTIFICATION
@@ -21,7 +21,6 @@
#include "catalog/pg_amop.h"
#include "catalog/pg_amproc.h"
#include "catalog/pg_opclass.h"
-#include "catalog/pg_opfamily.h"
#include "catalog/pg_type.h"
#include "utils/builtins.h"
#include "utils/lsyscache.h"
@@ -46,8 +45,6 @@ btvalidate(Oid opclassoid)
Oid opfamilyoid;
Oid opcintype;
char *opclassname;
- HeapTuple familytup;
- Form_pg_opfamily familyform;
char *opfamilyname;
CatCList *proclist,
*oprlist;
@@ -69,12 +66,7 @@ btvalidate(Oid opclassoid)
opclassname = NameStr(classform->opcname);
/* Fetch opfamily information */
- familytup = SearchSysCache1(OPFAMILYOID, ObjectIdGetDatum(opfamilyoid));
- if (!HeapTupleIsValid(familytup))
- elog(ERROR, "cache lookup failed for operator family %u", opfamilyoid);
- familyform = (Form_pg_opfamily) GETSTRUCT(familytup);
-
- opfamilyname = NameStr(familyform->opfname);
+ opfamilyname = get_opfamily_name(opfamilyoid, false);
/* Fetch all operators and support functions of the opfamily */
oprlist = SearchSysCacheList1(AMOPSTRATEGY, ObjectIdGetDatum(opfamilyoid));
@@ -114,6 +106,10 @@ btvalidate(Oid opclassoid)
case BTOPTIONS_PROC:
ok = check_amoptsproc_signature(procform->amproc);
break;
+ case BTSKIPSUPPORT_PROC:
+ ok = check_amproc_signature(procform->amproc, VOIDOID, true,
+ 1, 1, INTERNALOID);
+ break;
default:
ereport(INFO,
(errcode(ERRCODE_INVALID_OBJECT_DEFINITION),
@@ -280,7 +276,6 @@ btvalidate(Oid opclassoid)
ReleaseCatCacheList(proclist);
ReleaseCatCacheList(oprlist);
- ReleaseSysCache(familytup);
ReleaseSysCache(classtup);
return result;
diff --git a/src/backend/access/nbtree/nbtxlog.c b/src/backend/access/nbtree/nbtxlog.c
index b5b0e22447e4b..69ea668bb0d92 100644
--- a/src/backend/access/nbtree/nbtxlog.c
+++ b/src/backend/access/nbtree/nbtxlog.c
@@ -4,7 +4,7 @@
* WAL replay logic for btrees.
*
*
- * Portions Copyright (c) 1996-2024, PostgreSQL Global Development Group
+ * Portions Copyright (c) 1996-2025, PostgreSQL Global Development Group
* Portions Copyright (c) 1994, Regents of the University of California
*
* IDENTIFICATION
@@ -143,7 +143,7 @@ _bt_clear_incomplete_split(XLogReaderState *record, uint8 block_id)
if (XLogReadBufferForRedo(record, block_id, &buf) == BLK_NEEDS_REDO)
{
- Page page = (Page) BufferGetPage(buf);
+ Page page = BufferGetPage(buf);
BTPageOpaque pageop = BTPageGetOpaque(page);
Assert(P_INCOMPLETE_SPLIT(pageop));
@@ -287,7 +287,7 @@ btree_xlog_split(bool newitemonleft, XLogReaderState *record)
/* Reconstruct right (new) sibling page from scratch */
rbuf = XLogInitBufferForRedo(record, 1);
datapos = XLogRecGetBlockData(record, 1, &datalen);
- rpage = (Page) BufferGetPage(rbuf);
+ rpage = BufferGetPage(rbuf);
_bt_pageinit(rpage, BufferGetPageSize(rbuf));
ropaque = BTPageGetOpaque(rpage);
@@ -314,7 +314,7 @@ btree_xlog_split(bool newitemonleft, XLogReaderState *record)
* checking possible. See also _bt_restore_page(), which does the
* same for the right page.
*/
- Page origpage = (Page) BufferGetPage(buf);
+ Page origpage = BufferGetPage(buf);
BTPageOpaque oopaque = BTPageGetOpaque(origpage);
OffsetNumber off;
IndexTuple newitem = NULL,
@@ -439,7 +439,7 @@ btree_xlog_split(bool newitemonleft, XLogReaderState *record)
if (XLogReadBufferForRedo(record, 2, &sbuf) == BLK_NEEDS_REDO)
{
- Page spage = (Page) BufferGetPage(sbuf);
+ Page spage = BufferGetPage(sbuf);
BTPageOpaque spageop = BTPageGetOpaque(spage);
spageop->btpo_prev = rightpagenumber;
@@ -470,7 +470,7 @@ btree_xlog_dedup(XLogReaderState *record)
if (XLogReadBufferForRedo(record, 0, &buf) == BLK_NEEDS_REDO)
{
char *ptr = XLogRecGetBlockData(record, 0, NULL);
- Page page = (Page) BufferGetPage(buf);
+ Page page = BufferGetPage(buf);
BTPageOpaque opaque = BTPageGetOpaque(page);
OffsetNumber offnum,
minoff,
@@ -483,7 +483,7 @@ btree_xlog_dedup(XLogReaderState *record)
state->deduplicate = true; /* unused */
state->nmaxitems = 0; /* unused */
/* Conservatively use larger maxpostingsize than primary */
- state->maxpostingsize = BTMaxItemSize(page);
+ state->maxpostingsize = BTMaxItemSize;
state->base = NULL;
state->baseoff = InvalidOffsetNumber;
state->basetupsize = 0;
@@ -614,7 +614,7 @@ btree_xlog_vacuum(XLogReaderState *record)
{
char *ptr = XLogRecGetBlockData(record, 0, NULL);
- page = (Page) BufferGetPage(buffer);
+ page = BufferGetPage(buffer);
if (xlrec->nupdated > 0)
{
@@ -634,10 +634,11 @@ btree_xlog_vacuum(XLogReaderState *record)
PageIndexMultiDelete(page, (OffsetNumber *) ptr, xlrec->ndeleted);
/*
- * Mark the page as not containing any LP_DEAD items --- see comments
- * in _bt_delitems_vacuum().
+ * Clear the vacuum cycle ID, and mark the page as not containing any
+ * LP_DEAD items
*/
opaque = BTPageGetOpaque(page);
+ opaque->btpo_cycleid = 0;
opaque->btpo_flags &= ~BTP_HAS_GARBAGE;
PageSetLSN(page, lsn);
@@ -679,7 +680,7 @@ btree_xlog_delete(XLogReaderState *record)
{
char *ptr = XLogRecGetBlockData(record, 0, NULL);
- page = (Page) BufferGetPage(buffer);
+ page = BufferGetPage(buffer);
if (xlrec->nupdated > 0)
{
@@ -698,7 +699,10 @@ btree_xlog_delete(XLogReaderState *record)
if (xlrec->ndeleted > 0)
PageIndexMultiDelete(page, (OffsetNumber *) ptr, xlrec->ndeleted);
- /* Mark the page as not containing any LP_DEAD items */
+ /*
+ * Do *not* clear the vacuum cycle ID, but do mark the page as not
+ * containing any LP_DEAD items
+ */
opaque = BTPageGetOpaque(page);
opaque->btpo_flags &= ~BTP_HAS_GARBAGE;
@@ -736,7 +740,7 @@ btree_xlog_mark_page_halfdead(uint8 info, XLogReaderState *record)
OffsetNumber nextoffset;
BlockNumber rightsib;
- page = (Page) BufferGetPage(buffer);
+ page = BufferGetPage(buffer);
pageop = BTPageGetOpaque(page);
poffset = xlrec->poffset;
@@ -765,7 +769,7 @@ btree_xlog_mark_page_halfdead(uint8 info, XLogReaderState *record)
/* Rewrite the leaf page as a halfdead page */
buffer = XLogInitBufferForRedo(record, 0);
- page = (Page) BufferGetPage(buffer);
+ page = BufferGetPage(buffer);
_bt_pageinit(page, BufferGetPageSize(buffer));
pageop = BTPageGetOpaque(page);
@@ -832,7 +836,7 @@ btree_xlog_unlink_page(uint8 info, XLogReaderState *record)
{
if (XLogReadBufferForRedo(record, 1, &leftbuf) == BLK_NEEDS_REDO)
{
- page = (Page) BufferGetPage(leftbuf);
+ page = BufferGetPage(leftbuf);
pageop = BTPageGetOpaque(page);
pageop->btpo_next = rightsib;
@@ -845,7 +849,7 @@ btree_xlog_unlink_page(uint8 info, XLogReaderState *record)
/* Rewrite target page as empty deleted page */
target = XLogInitBufferForRedo(record, 0);
- page = (Page) BufferGetPage(target);
+ page = BufferGetPage(target);
_bt_pageinit(page, BufferGetPageSize(target));
pageop = BTPageGetOpaque(page);
@@ -864,7 +868,7 @@ btree_xlog_unlink_page(uint8 info, XLogReaderState *record)
/* Fix left-link of right sibling */
if (XLogReadBufferForRedo(record, 2, &rightbuf) == BLK_NEEDS_REDO)
{
- page = (Page) BufferGetPage(rightbuf);
+ page = BufferGetPage(rightbuf);
pageop = BTPageGetOpaque(page);
pageop->btpo_prev = leftsib;
@@ -903,7 +907,7 @@ btree_xlog_unlink_page(uint8 info, XLogReaderState *record)
Assert(!isleaf);
leafbuf = XLogInitBufferForRedo(record, 3);
- page = (Page) BufferGetPage(leafbuf);
+ page = BufferGetPage(leafbuf);
_bt_pageinit(page, BufferGetPageSize(leafbuf));
pageop = BTPageGetOpaque(page);
@@ -945,7 +949,7 @@ btree_xlog_newroot(XLogReaderState *record)
Size len;
buffer = XLogInitBufferForRedo(record, 0);
- page = (Page) BufferGetPage(buffer);
+ page = BufferGetPage(buffer);
_bt_pageinit(page, BufferGetPageSize(buffer));
pageop = BTPageGetOpaque(page);
@@ -982,9 +986,9 @@ btree_xlog_newroot(XLogReaderState *record)
* As far as any backend operating during original execution is concerned, the
* FSM is a cache of recycle-safe pages; the mere presence of the page in the
* FSM indicates that the page must already be safe to recycle (actually,
- * _bt_getbuf() verifies it's safe using BTPageIsRecyclable(), but that's just
- * because it would be unwise to completely trust the FSM, given its current
- * limitations).
+ * _bt_allocbuf() verifies it's safe using BTPageIsRecyclable(), but that's
+ * just because it would be unwise to completely trust the FSM, given its
+ * current limitations).
*
* This isn't sufficient to prevent similar concurrent recycling race
* conditions during Hot Standby, though. For that we need to log a
diff --git a/src/backend/access/rmgrdesc/brindesc.c b/src/backend/access/rmgrdesc/brindesc.c
index 3f55022a3e000..9fc0bfe2a523a 100644
--- a/src/backend/access/rmgrdesc/brindesc.c
+++ b/src/backend/access/rmgrdesc/brindesc.c
@@ -3,7 +3,7 @@
* brindesc.c
* rmgr descriptor routines for BRIN indexes
*
- * Portions Copyright (c) 1996-2024, PostgreSQL Global Development Group
+ * Portions Copyright (c) 1996-2025, PostgreSQL Global Development Group
* Portions Copyright (c) 1994, Regents of the University of California
*
*
diff --git a/src/backend/access/rmgrdesc/clogdesc.c b/src/backend/access/rmgrdesc/clogdesc.c
index c1d47c219f9d2..41bf28dcfd05c 100644
--- a/src/backend/access/rmgrdesc/clogdesc.c
+++ b/src/backend/access/rmgrdesc/clogdesc.c
@@ -3,7 +3,7 @@
* clogdesc.c
* rmgr descriptor routines for access/transam/clog.c
*
- * Portions Copyright (c) 1996-2024, PostgreSQL Global Development Group
+ * Portions Copyright (c) 1996-2025, PostgreSQL Global Development Group
* Portions Copyright (c) 1994, Regents of the University of California
*
*
@@ -28,15 +28,15 @@ clog_desc(StringInfo buf, XLogReaderState *record)
int64 pageno;
memcpy(&pageno, rec, sizeof(pageno));
- appendStringInfo(buf, "page %lld", (long long) pageno);
+ appendStringInfo(buf, "page %" PRId64, pageno);
}
else if (info == CLOG_TRUNCATE)
{
xl_clog_truncate xlrec;
memcpy(&xlrec, rec, sizeof(xl_clog_truncate));
- appendStringInfo(buf, "page %lld; oldestXact %u",
- (long long) xlrec.pageno, xlrec.oldestXact);
+ appendStringInfo(buf, "page %" PRId64 "; oldestXact %u",
+ xlrec.pageno, xlrec.oldestXact);
}
}
diff --git a/src/backend/access/rmgrdesc/committsdesc.c b/src/backend/access/rmgrdesc/committsdesc.c
index f5f09a1bc7968..a6ab9dd78de17 100644
--- a/src/backend/access/rmgrdesc/committsdesc.c
+++ b/src/backend/access/rmgrdesc/committsdesc.c
@@ -3,7 +3,7 @@
* committsdesc.c
* rmgr descriptor routines for access/transam/commit_ts.c
*
- * Portions Copyright (c) 1996-2024, PostgreSQL Global Development Group
+ * Portions Copyright (c) 1996-2025, PostgreSQL Global Development Group
* Portions Copyright (c) 1994, Regents of the University of California
*
*
@@ -28,14 +28,14 @@ commit_ts_desc(StringInfo buf, XLogReaderState *record)
int64 pageno;
memcpy(&pageno, rec, sizeof(pageno));
- appendStringInfo(buf, "%lld", (long long) pageno);
+ appendStringInfo(buf, "%" PRId64, pageno);
}
else if (info == COMMIT_TS_TRUNCATE)
{
xl_commit_ts_truncate *trunc = (xl_commit_ts_truncate *) rec;
- appendStringInfo(buf, "pageno %lld, oldestXid %u",
- (long long) trunc->pageno, trunc->oldestXid);
+ appendStringInfo(buf, "pageno %" PRId64 ", oldestXid %u",
+ trunc->pageno, trunc->oldestXid);
}
}
diff --git a/src/backend/access/rmgrdesc/dbasedesc.c b/src/backend/access/rmgrdesc/dbasedesc.c
index 731dac826cccd..4224c5673ff87 100644
--- a/src/backend/access/rmgrdesc/dbasedesc.c
+++ b/src/backend/access/rmgrdesc/dbasedesc.c
@@ -3,7 +3,7 @@
* dbasedesc.c
* rmgr descriptor routines for commands/dbcommands.c
*
- * Portions Copyright (c) 1996-2024, PostgreSQL Global Development Group
+ * Portions Copyright (c) 1996-2025, PostgreSQL Global Development Group
* Portions Copyright (c) 1994, Regents of the University of California
*
*
diff --git a/src/backend/access/rmgrdesc/genericdesc.c b/src/backend/access/rmgrdesc/genericdesc.c
index c35641483b8f9..75dc4108b9aa2 100644
--- a/src/backend/access/rmgrdesc/genericdesc.c
+++ b/src/backend/access/rmgrdesc/genericdesc.c
@@ -4,7 +4,7 @@
* rmgr descriptor routines for access/transam/generic_xlog.c
*
*
- * Portions Copyright (c) 1996-2024, PostgreSQL Global Development Group
+ * Portions Copyright (c) 1996-2025, PostgreSQL Global Development Group
* Portions Copyright (c) 1994, Regents of the University of California
*
* src/backend/access/rmgrdesc/genericdesc.c
diff --git a/src/backend/access/rmgrdesc/gindesc.c b/src/backend/access/rmgrdesc/gindesc.c
index 4746f246ff1f9..723ff9499cf46 100644
--- a/src/backend/access/rmgrdesc/gindesc.c
+++ b/src/backend/access/rmgrdesc/gindesc.c
@@ -3,7 +3,7 @@
* gindesc.c
* rmgr descriptor routines for access/transam/gin/ginxlog.c
*
- * Portions Copyright (c) 1996-2024, PostgreSQL Global Development Group
+ * Portions Copyright (c) 1996-2025, PostgreSQL Global Development Group
* Portions Copyright (c) 1994, Regents of the University of California
*
*
diff --git a/src/backend/access/rmgrdesc/gistdesc.c b/src/backend/access/rmgrdesc/gistdesc.c
index 5efbbf72e5781..a2b84e898f959 100644
--- a/src/backend/access/rmgrdesc/gistdesc.c
+++ b/src/backend/access/rmgrdesc/gistdesc.c
@@ -3,7 +3,7 @@
* gistdesc.c
* rmgr descriptor routines for access/gist/gistxlog.c
*
- * Portions Copyright (c) 1996-2024, PostgreSQL Global Development Group
+ * Portions Copyright (c) 1996-2025, PostgreSQL Global Development Group
* Portions Copyright (c) 1994, Regents of the University of California
*
*
diff --git a/src/backend/access/rmgrdesc/hashdesc.c b/src/backend/access/rmgrdesc/hashdesc.c
index dd0bfff8cbc25..75f43a9152071 100644
--- a/src/backend/access/rmgrdesc/hashdesc.c
+++ b/src/backend/access/rmgrdesc/hashdesc.c
@@ -3,7 +3,7 @@
* hashdesc.c
* rmgr descriptor routines for access/hash/hash.c
*
- * Portions Copyright (c) 1996-2024, PostgreSQL Global Development Group
+ * Portions Copyright (c) 1996-2025, PostgreSQL Global Development Group
* Portions Copyright (c) 1994, Regents of the University of California
*
*
diff --git a/src/backend/access/rmgrdesc/heapdesc.c b/src/backend/access/rmgrdesc/heapdesc.c
index 5f5673e088b01..82b62c95de574 100644
--- a/src/backend/access/rmgrdesc/heapdesc.c
+++ b/src/backend/access/rmgrdesc/heapdesc.c
@@ -3,7 +3,7 @@
* heapdesc.c
* rmgr descriptor routines for access/heap/heapam.c
*
- * Portions Copyright (c) 1996-2024, PostgreSQL Global Development Group
+ * Portions Copyright (c) 1996-2025, PostgreSQL Global Development Group
* Portions Copyright (c) 1994, Regents of the University of California
*
*
@@ -16,6 +16,7 @@
#include "access/heapam_xlog.h"
#include "access/rmgrdesc_utils.h"
+#include "storage/standbydefs.h"
/*
* NOTE: "keyname" argument cannot have trailing spaces or punctuation
@@ -253,6 +254,9 @@ heap_desc(StringInfo buf, XLogReaderState *record)
xl_heap_inplace *xlrec = (xl_heap_inplace *) rec;
appendStringInfo(buf, "off: %u", xlrec->offnum);
+ standby_desc_invalidations(buf, xlrec->nmsgs, xlrec->msgs,
+ xlrec->dbId, xlrec->tsId,
+ xlrec->relcacheInitFileInval);
}
}
diff --git a/src/backend/access/rmgrdesc/logicalmsgdesc.c b/src/backend/access/rmgrdesc/logicalmsgdesc.c
index 430d7668c0c2e..1c8c99f19f836 100644
--- a/src/backend/access/rmgrdesc/logicalmsgdesc.c
+++ b/src/backend/access/rmgrdesc/logicalmsgdesc.c
@@ -3,7 +3,7 @@
* logicalmsgdesc.c
* rmgr descriptor routines for replication/logical/message.c
*
- * Portions Copyright (c) 2015-2024, PostgreSQL Global Development Group
+ * Portions Copyright (c) 2015-2025, PostgreSQL Global Development Group
*
*
* IDENTIFICATION
diff --git a/src/backend/access/rmgrdesc/meson.build b/src/backend/access/rmgrdesc/meson.build
index e8b7a65fc76c2..96c98e800c22d 100644
--- a/src/backend/access/rmgrdesc/meson.build
+++ b/src/backend/access/rmgrdesc/meson.build
@@ -1,4 +1,4 @@
-# Copyright (c) 2022-2024, PostgreSQL Global Development Group
+# Copyright (c) 2022-2025, PostgreSQL Global Development Group
# used by frontend programs like pg_waldump
rmgr_desc_sources = files(
diff --git a/src/backend/access/rmgrdesc/mxactdesc.c b/src/backend/access/rmgrdesc/mxactdesc.c
index 3e8ad4d5ef82b..3ca0582db3647 100644
--- a/src/backend/access/rmgrdesc/mxactdesc.c
+++ b/src/backend/access/rmgrdesc/mxactdesc.c
@@ -3,7 +3,7 @@
* mxactdesc.c
* rmgr descriptor routines for access/transam/multixact.c
*
- * Portions Copyright (c) 1996-2024, PostgreSQL Global Development Group
+ * Portions Copyright (c) 1996-2025, PostgreSQL Global Development Group
* Portions Copyright (c) 1994, Regents of the University of California
*
*
@@ -58,7 +58,7 @@ multixact_desc(StringInfo buf, XLogReaderState *record)
int64 pageno;
memcpy(&pageno, rec, sizeof(pageno));
- appendStringInfo(buf, "%lld", (long long) pageno);
+ appendStringInfo(buf, "%" PRId64, pageno);
}
else if (info == XLOG_MULTIXACT_CREATE_ID)
{
diff --git a/src/backend/access/rmgrdesc/nbtdesc.c b/src/backend/access/rmgrdesc/nbtdesc.c
index 0f201ca2237c8..c05d19ab00753 100644
--- a/src/backend/access/rmgrdesc/nbtdesc.c
+++ b/src/backend/access/rmgrdesc/nbtdesc.c
@@ -3,7 +3,7 @@
* nbtdesc.c
* rmgr descriptor routines for access/nbtree/nbtxlog.c
*
- * Portions Copyright (c) 1996-2024, PostgreSQL Global Development Group
+ * Portions Copyright (c) 1996-2025, PostgreSQL Global Development Group
* Portions Copyright (c) 1994, Regents of the University of California
*
*
diff --git a/src/backend/access/rmgrdesc/relmapdesc.c b/src/backend/access/rmgrdesc/relmapdesc.c
index 46d39cdca0eed..caf1846032167 100644
--- a/src/backend/access/rmgrdesc/relmapdesc.c
+++ b/src/backend/access/rmgrdesc/relmapdesc.c
@@ -3,7 +3,7 @@
* relmapdesc.c
* rmgr descriptor routines for utils/cache/relmapper.c
*
- * Portions Copyright (c) 1996-2024, PostgreSQL Global Development Group
+ * Portions Copyright (c) 1996-2025, PostgreSQL Global Development Group
* Portions Copyright (c) 1994, Regents of the University of California
*
*
diff --git a/src/backend/access/rmgrdesc/replorigindesc.c b/src/backend/access/rmgrdesc/replorigindesc.c
index c369ca01171ff..35e3af2903ed2 100644
--- a/src/backend/access/rmgrdesc/replorigindesc.c
+++ b/src/backend/access/rmgrdesc/replorigindesc.c
@@ -3,7 +3,7 @@
* replorigindesc.c
* rmgr descriptor routines for replication/logical/origin.c
*
- * Portions Copyright (c) 2015-2024, PostgreSQL Global Development Group
+ * Portions Copyright (c) 2015-2025, PostgreSQL Global Development Group
*
*
* IDENTIFICATION
@@ -29,7 +29,7 @@ replorigin_desc(StringInfo buf, XLogReaderState *record)
xlrec = (xl_replorigin_set *) rec;
- appendStringInfo(buf, "set %u; lsn %X/%X; force: %d",
+ appendStringInfo(buf, "set %u; lsn %X/%08X; force: %d",
xlrec->node_id,
LSN_FORMAT_ARGS(xlrec->remote_lsn),
xlrec->force);
diff --git a/src/backend/access/rmgrdesc/rmgrdesc_utils.c b/src/backend/access/rmgrdesc/rmgrdesc_utils.c
index 2665c45873a64..25cf167f17524 100644
--- a/src/backend/access/rmgrdesc/rmgrdesc_utils.c
+++ b/src/backend/access/rmgrdesc/rmgrdesc_utils.c
@@ -3,7 +3,7 @@
* rmgrdesc_utils.c
* Support functions for rmgrdesc routines
*
- * Copyright (c) 2023-2024, PostgreSQL Global Development Group
+ * Copyright (c) 2023-2025, PostgreSQL Global Development Group
*
*
* IDENTIFICATION
diff --git a/src/backend/access/rmgrdesc/seqdesc.c b/src/backend/access/rmgrdesc/seqdesc.c
index cf0e02ded592e..0d289d77fcf7a 100644
--- a/src/backend/access/rmgrdesc/seqdesc.c
+++ b/src/backend/access/rmgrdesc/seqdesc.c
@@ -3,7 +3,7 @@
* seqdesc.c
* rmgr descriptor routines for commands/sequence.c
*
- * Portions Copyright (c) 1996-2024, PostgreSQL Global Development Group
+ * Portions Copyright (c) 1996-2025, PostgreSQL Global Development Group
* Portions Copyright (c) 1994, Regents of the University of California
*
*
diff --git a/src/backend/access/rmgrdesc/smgrdesc.c b/src/backend/access/rmgrdesc/smgrdesc.c
index 71410e0a2d358..4bb7fc79bced6 100644
--- a/src/backend/access/rmgrdesc/smgrdesc.c
+++ b/src/backend/access/rmgrdesc/smgrdesc.c
@@ -3,7 +3,7 @@
* smgrdesc.c
* rmgr descriptor routines for catalog/storage.c
*
- * Portions Copyright (c) 1996-2024, PostgreSQL Global Development Group
+ * Portions Copyright (c) 1996-2025, PostgreSQL Global Development Group
* Portions Copyright (c) 1994, Regents of the University of California
*
*
@@ -26,19 +26,17 @@ smgr_desc(StringInfo buf, XLogReaderState *record)
if (info == XLOG_SMGR_CREATE)
{
xl_smgr_create *xlrec = (xl_smgr_create *) rec;
- char *path = relpathperm(xlrec->rlocator, xlrec->forkNum);
- appendStringInfoString(buf, path);
- pfree(path);
+ appendStringInfoString(buf,
+ relpathperm(xlrec->rlocator, xlrec->forkNum).str);
}
else if (info == XLOG_SMGR_TRUNCATE)
{
xl_smgr_truncate *xlrec = (xl_smgr_truncate *) rec;
- char *path = relpathperm(xlrec->rlocator, MAIN_FORKNUM);
- appendStringInfo(buf, "%s to %u blocks flags %d", path,
+ appendStringInfo(buf, "%s to %u blocks flags %d",
+ relpathperm(xlrec->rlocator, MAIN_FORKNUM).str,
xlrec->blkno, xlrec->flags);
- pfree(path);
}
}
diff --git a/src/backend/access/rmgrdesc/spgdesc.c b/src/backend/access/rmgrdesc/spgdesc.c
index e75971100c9c8..72efedc5b40d3 100644
--- a/src/backend/access/rmgrdesc/spgdesc.c
+++ b/src/backend/access/rmgrdesc/spgdesc.c
@@ -3,7 +3,7 @@
* spgdesc.c
* rmgr descriptor routines for access/spgist/spgxlog.c
*
- * Portions Copyright (c) 1996-2024, PostgreSQL Global Development Group
+ * Portions Copyright (c) 1996-2025, PostgreSQL Global Development Group
* Portions Copyright (c) 1994, Regents of the University of California
*
*
diff --git a/src/backend/access/rmgrdesc/standbydesc.c b/src/backend/access/rmgrdesc/standbydesc.c
index 25f870b187e8e..81eff5f31c4f6 100644
--- a/src/backend/access/rmgrdesc/standbydesc.c
+++ b/src/backend/access/rmgrdesc/standbydesc.c
@@ -3,7 +3,7 @@
* standbydesc.c
* rmgr descriptor routines for storage/ipc/standby.c
*
- * Portions Copyright (c) 1996-2024, PostgreSQL Global Development Group
+ * Portions Copyright (c) 1996-2025, PostgreSQL Global Development Group
* Portions Copyright (c) 1994, Regents of the University of California
*
*
@@ -96,11 +96,7 @@ standby_identify(uint8 info)
return id;
}
-/*
- * This routine is used by both standby_desc and xact_desc, because
- * transaction commits and XLOG_INVALIDATIONS messages contain invalidations;
- * it seems pointless to duplicate the code.
- */
+/* also used by non-standby records having analogous invalidation fields */
void
standby_desc_invalidations(StringInfo buf,
int nmsgs, SharedInvalidationMessage *msgs,
@@ -136,6 +132,8 @@ standby_desc_invalidations(StringInfo buf,
appendStringInfo(buf, " relmap db %u", msg->rm.dbId);
else if (msg->id == SHAREDINVALSNAPSHOT_ID)
appendStringInfo(buf, " snapshot %u", msg->sn.relId);
+ else if (msg->id == SHAREDINVALRELSYNC_ID)
+ appendStringInfo(buf, " relsync %u", msg->rs.relid);
else
appendStringInfo(buf, " unrecognized id %d", msg->id);
}
diff --git a/src/backend/access/rmgrdesc/tblspcdesc.c b/src/backend/access/rmgrdesc/tblspcdesc.c
index 56396ca946fef..5d612b4232e26 100644
--- a/src/backend/access/rmgrdesc/tblspcdesc.c
+++ b/src/backend/access/rmgrdesc/tblspcdesc.c
@@ -3,7 +3,7 @@
* tblspcdesc.c
* rmgr descriptor routines for commands/tablespace.c
*
- * Portions Copyright (c) 1996-2024, PostgreSQL Global Development Group
+ * Portions Copyright (c) 1996-2025, PostgreSQL Global Development Group
* Portions Copyright (c) 1994, Regents of the University of California
*
*
diff --git a/src/backend/access/rmgrdesc/xactdesc.c b/src/backend/access/rmgrdesc/xactdesc.c
index dccca201e05c0..f0f696855b9af 100644
--- a/src/backend/access/rmgrdesc/xactdesc.c
+++ b/src/backend/access/rmgrdesc/xactdesc.c
@@ -3,7 +3,7 @@
* xactdesc.c
* rmgr descriptor routines for access/transam/xact.c
*
- * Portions Copyright (c) 1996-2024, PostgreSQL Global Development Group
+ * Portions Copyright (c) 1996-2025, PostgreSQL Global Development Group
* Portions Copyright (c) 1994, Regents of the University of California
*
*
@@ -252,6 +252,8 @@ ParsePrepareRecord(uint8 info, xl_xact_prepare *xlrec, xl_xact_parsed_prepare *p
parsed->nsubxacts = xlrec->nsubxacts;
parsed->nrels = xlrec->ncommitrels;
parsed->nabortrels = xlrec->nabortrels;
+ parsed->nstats = xlrec->ncommitstats;
+ parsed->nabortstats = xlrec->nabortstats;
parsed->nmsgs = xlrec->ninvalmsgs;
strncpy(parsed->twophase_gid, bufptr, xlrec->gidlen);
@@ -287,10 +289,8 @@ xact_desc_relations(StringInfo buf, char *label, int nrels,
appendStringInfo(buf, "; %s:", label);
for (i = 0; i < nrels; i++)
{
- char *path = relpathperm(xlocators[i], MAIN_FORKNUM);
-
- appendStringInfo(buf, " %s", path);
- pfree(path);
+ appendStringInfo(buf, " %s",
+ relpathperm(xlocators[i], MAIN_FORKNUM).str);
}
}
}
@@ -319,10 +319,13 @@ xact_desc_stats(StringInfo buf, const char *label,
appendStringInfo(buf, "; %sdropped stats:", label);
for (i = 0; i < ndropped; i++)
{
- appendStringInfo(buf, " %d/%u/%u",
+ uint64 objid =
+ ((uint64) dropped_stats[i].objid_hi) << 32 | dropped_stats[i].objid_lo;
+
+ appendStringInfo(buf, " %d/%u/%" PRIu64,
dropped_stats[i].kind,
dropped_stats[i].dboid,
- dropped_stats[i].objoid);
+ objid);
}
}
}
@@ -356,7 +359,7 @@ xact_desc_commit(StringInfo buf, uint8 info, xl_xact_commit *xlrec, RepOriginId
if (parsed.xinfo & XACT_XINFO_HAS_ORIGIN)
{
- appendStringInfo(buf, "; origin: node %u, lsn %X/%X, at %s",
+ appendStringInfo(buf, "; origin: node %u, lsn %X/%08X, at %s",
origin_id,
LSN_FORMAT_ARGS(parsed.origin_lsn),
timestamptz_to_str(parsed.origin_timestamp));
@@ -381,7 +384,7 @@ xact_desc_abort(StringInfo buf, uint8 info, xl_xact_abort *xlrec, RepOriginId or
if (parsed.xinfo & XACT_XINFO_HAS_ORIGIN)
{
- appendStringInfo(buf, "; origin: node %u, lsn %X/%X, at %s",
+ appendStringInfo(buf, "; origin: node %u, lsn %X/%08X, at %s",
origin_id,
LSN_FORMAT_ARGS(parsed.origin_lsn),
timestamptz_to_str(parsed.origin_timestamp));
@@ -415,7 +418,7 @@ xact_desc_prepare(StringInfo buf, uint8 info, xl_xact_prepare *xlrec, RepOriginI
* way as PrepareRedoAdd().
*/
if (origin_id != InvalidRepOriginId)
- appendStringInfo(buf, "; origin: node %u, lsn %X/%X, at %s",
+ appendStringInfo(buf, "; origin: node %u, lsn %X/%08X, at %s",
origin_id,
LSN_FORMAT_ARGS(parsed.origin_lsn),
timestamptz_to_str(parsed.origin_timestamp));
diff --git a/src/backend/access/rmgrdesc/xlogdesc.c b/src/backend/access/rmgrdesc/xlogdesc.c
index e455400716d8c..cd6c2a2f650a6 100644
--- a/src/backend/access/rmgrdesc/xlogdesc.c
+++ b/src/backend/access/rmgrdesc/xlogdesc.c
@@ -3,7 +3,7 @@
* xlogdesc.c
* rmgr descriptor routines for access/transam/xlog.c
*
- * Portions Copyright (c) 1996-2024, PostgreSQL Global Development Group
+ * Portions Copyright (c) 1996-2025, PostgreSQL Global Development Group
* Portions Copyright (c) 1994, Regents of the University of California
*
*
@@ -33,6 +33,27 @@ const struct config_enum_entry wal_level_options[] = {
{NULL, 0, false}
};
+/*
+ * Find a string representation for wal_level
+ */
+static const char *
+get_wal_level_string(int wal_level)
+{
+ const struct config_enum_entry *entry;
+ const char *wal_level_str = "?";
+
+ for (entry = wal_level_options; entry->name; entry++)
+ {
+ if (entry->val == wal_level)
+ {
+ wal_level_str = entry->name;
+ break;
+ }
+ }
+
+ return wal_level_str;
+}
+
void
xlog_desc(StringInfo buf, XLogReaderState *record)
{
@@ -44,8 +65,8 @@ xlog_desc(StringInfo buf, XLogReaderState *record)
{
CheckPoint *checkpoint = (CheckPoint *) rec;
- appendStringInfo(buf, "redo %X/%X; "
- "tli %u; prev tli %u; fpw %s; xid %u:%u; oid %u; multi %u; offset %u; "
+ appendStringInfo(buf, "redo %X/%08X; "
+ "tli %u; prev tli %u; fpw %s; wal_level %s; xid %u:%u; oid %u; multi %u; offset %u; "
"oldest xid %u in DB %u; oldest multi %u in DB %u; "
"oldest/newest commit timestamp xid: %u/%u; "
"oldest running xid %u; %s",
@@ -53,6 +74,7 @@ xlog_desc(StringInfo buf, XLogReaderState *record)
checkpoint->ThisTimeLineID,
checkpoint->PrevTimeLineID,
checkpoint->fullPageWrites ? "true" : "false",
+ get_wal_level_string(checkpoint->wal_level),
EpochFromFullTransactionId(checkpoint->nextXid),
XidFromFullTransactionId(checkpoint->nextXid),
checkpoint->nextOid,
@@ -89,26 +111,15 @@ xlog_desc(StringInfo buf, XLogReaderState *record)
XLogRecPtr startpoint;
memcpy(&startpoint, rec, sizeof(XLogRecPtr));
- appendStringInfo(buf, "%X/%X", LSN_FORMAT_ARGS(startpoint));
+ appendStringInfo(buf, "%X/%08X", LSN_FORMAT_ARGS(startpoint));
}
else if (info == XLOG_PARAMETER_CHANGE)
{
xl_parameter_change xlrec;
const char *wal_level_str;
- const struct config_enum_entry *entry;
memcpy(&xlrec, rec, sizeof(xl_parameter_change));
-
- /* Find a string representation for wal_level */
- wal_level_str = "?";
- for (entry = wal_level_options; entry->name; entry++)
- {
- if (entry->val == xlrec.wal_level)
- {
- wal_level_str = entry->name;
- break;
- }
- }
+ wal_level_str = get_wal_level_string(xlrec.wal_level);
appendStringInfo(buf, "max_connections=%d max_worker_processes=%d "
"max_wal_senders=%d max_prepared_xacts=%d "
@@ -135,22 +146,26 @@ xlog_desc(StringInfo buf, XLogReaderState *record)
xl_end_of_recovery xlrec;
memcpy(&xlrec, rec, sizeof(xl_end_of_recovery));
- appendStringInfo(buf, "tli %u; prev tli %u; time %s",
+ appendStringInfo(buf, "tli %u; prev tli %u; time %s; wal_level %s",
xlrec.ThisTimeLineID, xlrec.PrevTimeLineID,
- timestamptz_to_str(xlrec.end_time));
+ timestamptz_to_str(xlrec.end_time),
+ get_wal_level_string(xlrec.wal_level));
}
else if (info == XLOG_OVERWRITE_CONTRECORD)
{
xl_overwrite_contrecord xlrec;
memcpy(&xlrec, rec, sizeof(xl_overwrite_contrecord));
- appendStringInfo(buf, "lsn %X/%X; time %s",
+ appendStringInfo(buf, "lsn %X/%08X; time %s",
LSN_FORMAT_ARGS(xlrec.overwritten_lsn),
timestamptz_to_str(xlrec.overwrite_time));
}
else if (info == XLOG_CHECKPOINT_REDO)
{
- /* No details to write out */
+ int wal_level;
+
+ memcpy(&wal_level, rec, sizeof(int));
+ appendStringInfo(buf, "wal_level %s", get_wal_level_string(wal_level));
}
}
diff --git a/src/backend/access/sequence/meson.build b/src/backend/access/sequence/meson.build
index 1843aed38db23..ec9ab9b7e9dbd 100644
--- a/src/backend/access/sequence/meson.build
+++ b/src/backend/access/sequence/meson.build
@@ -1,4 +1,4 @@
-# Copyright (c) 2022-2024, PostgreSQL Global Development Group
+# Copyright (c) 2022-2025, PostgreSQL Global Development Group
backend_sources += files(
'sequence.c',
diff --git a/src/backend/access/sequence/sequence.c b/src/backend/access/sequence/sequence.c
index 8d6b7bb5dc25b..8b53035537022 100644
--- a/src/backend/access/sequence/sequence.c
+++ b/src/backend/access/sequence/sequence.c
@@ -3,7 +3,7 @@
* sequence.c
* Generic routines for sequence-related code.
*
- * Portions Copyright (c) 1996-2024, PostgreSQL Global Development Group
+ * Portions Copyright (c) 1996-2025, PostgreSQL Global Development Group
* Portions Copyright (c) 1994, Regents of the University of California
*
*
@@ -22,7 +22,7 @@
#include "access/relation.h"
#include "access/sequence.h"
-#include "storage/lmgr.h"
+#include "utils/rel.h"
static inline void validate_relation_kind(Relation r);
diff --git a/src/backend/access/spgist/meson.build b/src/backend/access/spgist/meson.build
index a6f4f3182bbed..e763f05304f73 100644
--- a/src/backend/access/spgist/meson.build
+++ b/src/backend/access/spgist/meson.build
@@ -1,4 +1,4 @@
-# Copyright (c) 2022-2024, PostgreSQL Global Development Group
+# Copyright (c) 2022-2025, PostgreSQL Global Development Group
backend_sources += files(
'spgdoinsert.c',
diff --git a/src/backend/access/spgist/spgdoinsert.c b/src/backend/access/spgist/spgdoinsert.c
index a4995c168b44d..af6b27b2135ac 100644
--- a/src/backend/access/spgist/spgdoinsert.c
+++ b/src/backend/access/spgist/spgdoinsert.c
@@ -4,7 +4,7 @@
* implementation of insert algorithm
*
*
- * Portions Copyright (c) 1996-2024, PostgreSQL Global Development Group
+ * Portions Copyright (c) 1996-2025, PostgreSQL Global Development Group
* Portions Copyright (c) 1994, Regents of the University of California
*
* IDENTIFICATION
@@ -295,8 +295,8 @@ addLeafTuple(Relation index, SpGistState *state, SpGistLeafTuple leafTuple,
int flags;
XLogBeginInsert();
- XLogRegisterData((char *) &xlrec, sizeof(xlrec));
- XLogRegisterData((char *) leafTuple, leafTuple->size);
+ XLogRegisterData(&xlrec, sizeof(xlrec));
+ XLogRegisterData(leafTuple, leafTuple->size);
flags = REGBUF_STANDARD;
if (xlrec.newPage)
@@ -532,12 +532,12 @@ moveLeafs(Relation index, SpGistState *state,
xlrec.nodeI = parent->node;
XLogBeginInsert();
- XLogRegisterData((char *) &xlrec, SizeOfSpgxlogMoveLeafs);
- XLogRegisterData((char *) toDelete,
+ XLogRegisterData(&xlrec, SizeOfSpgxlogMoveLeafs);
+ XLogRegisterData(toDelete,
sizeof(OffsetNumber) * nDelete);
- XLogRegisterData((char *) toInsert,
+ XLogRegisterData(toInsert,
sizeof(OffsetNumber) * nInsert);
- XLogRegisterData((char *) leafdata, leafptr - leafdata);
+ XLogRegisterData(leafdata, leafptr - leafdata);
XLogRegisterBuffer(0, current->buffer, REGBUF_STANDARD);
XLogRegisterBuffer(1, nbuf, REGBUF_STANDARD | (xlrec.newPage ? REGBUF_WILL_INIT : 0));
@@ -1365,15 +1365,15 @@ doPickSplit(Relation index, SpGistState *state,
XLogBeginInsert();
xlrec.nInsert = nToInsert;
- XLogRegisterData((char *) &xlrec, SizeOfSpgxlogPickSplit);
+ XLogRegisterData(&xlrec, SizeOfSpgxlogPickSplit);
- XLogRegisterData((char *) toDelete,
+ XLogRegisterData(toDelete,
sizeof(OffsetNumber) * xlrec.nDelete);
- XLogRegisterData((char *) toInsert,
+ XLogRegisterData(toInsert,
sizeof(OffsetNumber) * xlrec.nInsert);
- XLogRegisterData((char *) leafPageSelect,
+ XLogRegisterData(leafPageSelect,
sizeof(uint8) * xlrec.nInsert);
- XLogRegisterData((char *) innerTuple, innerTuple->size);
+ XLogRegisterData(innerTuple, innerTuple->size);
XLogRegisterData(leafdata, leafptr - leafdata);
/* Old leaf page */
@@ -1559,8 +1559,8 @@ spgAddNodeAction(Relation index, SpGistState *state,
XLogRecPtr recptr;
XLogBeginInsert();
- XLogRegisterData((char *) &xlrec, sizeof(xlrec));
- XLogRegisterData((char *) newInnerTuple, newInnerTuple->size);
+ XLogRegisterData(&xlrec, sizeof(xlrec));
+ XLogRegisterData(newInnerTuple, newInnerTuple->size);
XLogRegisterBuffer(0, current->buffer, REGBUF_STANDARD);
@@ -1685,8 +1685,8 @@ spgAddNodeAction(Relation index, SpGistState *state,
if (xlrec.parentBlk == 2)
XLogRegisterBuffer(2, parent->buffer, REGBUF_STANDARD);
- XLogRegisterData((char *) &xlrec, sizeof(xlrec));
- XLogRegisterData((char *) newInnerTuple, newInnerTuple->size);
+ XLogRegisterData(&xlrec, sizeof(xlrec));
+ XLogRegisterData(newInnerTuple, newInnerTuple->size);
recptr = XLogInsert(RM_SPGIST_ID, XLOG_SPGIST_ADD_NODE);
@@ -1868,9 +1868,9 @@ spgSplitNodeAction(Relation index, SpGistState *state,
XLogRecPtr recptr;
XLogBeginInsert();
- XLogRegisterData((char *) &xlrec, sizeof(xlrec));
- XLogRegisterData((char *) prefixTuple, prefixTuple->size);
- XLogRegisterData((char *) postfixTuple, postfixTuple->size);
+ XLogRegisterData(&xlrec, sizeof(xlrec));
+ XLogRegisterData(prefixTuple, prefixTuple->size);
+ XLogRegisterData(postfixTuple, postfixTuple->size);
XLogRegisterBuffer(0, current->buffer, REGBUF_STANDARD);
if (newBuffer != InvalidBuffer)
@@ -1974,7 +1974,7 @@ spgdoinsert(Relation index, SpGistState *state,
{
if (!isnulls[i])
{
- if (TupleDescAttr(leafDescriptor, i)->attlen == -1)
+ if (TupleDescCompactAttr(leafDescriptor, i)->attlen == -1)
leafDatums[i] = PointerGetDatum(PG_DETOAST_DATUM(datums[i]));
else
leafDatums[i] = datums[i];
diff --git a/src/backend/access/spgist/spginsert.c b/src/backend/access/spgist/spginsert.c
index 1bec19c2b88f7..6a61e093fa05a 100644
--- a/src/backend/access/spgist/spginsert.c
+++ b/src/backend/access/spgist/spginsert.c
@@ -5,7 +5,7 @@
*
* All the actual insertion logic is in spgdoinsert.c.
*
- * Portions Copyright (c) 1996-2024, PostgreSQL Global Development Group
+ * Portions Copyright (c) 1996-2025, PostgreSQL Global Development Group
* Portions Copyright (c) 1994, Regents of the University of California
*
* IDENTIFICATION
@@ -122,7 +122,7 @@ spgbuild(Relation heap, Relation index, IndexInfo *indexInfo)
ALLOCSET_DEFAULT_SIZES);
reltuples = table_index_build_scan(heap, index, indexInfo, true, true,
- spgistBuildCallback, (void *) &buildstate,
+ spgistBuildCallback, &buildstate,
NULL);
MemoryContextDelete(buildstate.tmpCtx);
diff --git a/src/backend/access/spgist/spgkdtreeproc.c b/src/backend/access/spgist/spgkdtreeproc.c
index 44d054525202a..d6989759e5fd7 100644
--- a/src/backend/access/spgist/spgkdtreeproc.c
+++ b/src/backend/access/spgist/spgkdtreeproc.c
@@ -4,7 +4,7 @@
* implementation of k-d tree over points for SP-GiST
*
*
- * Portions Copyright (c) 1996-2024, PostgreSQL Global Development Group
+ * Portions Copyright (c) 1996-2025, PostgreSQL Global Development Group
* Portions Copyright (c) 1994, Regents of the University of California
*
* IDENTIFICATION
diff --git a/src/backend/access/spgist/spgproc.c b/src/backend/access/spgist/spgproc.c
index 89699e7e7ffc6..660009291da4d 100644
--- a/src/backend/access/spgist/spgproc.c
+++ b/src/backend/access/spgist/spgproc.c
@@ -4,7 +4,7 @@
* Common supporting procedures for SP-GiST opclasses.
*
*
- * Portions Copyright (c) 1996-2024, PostgreSQL Global Development Group
+ * Portions Copyright (c) 1996-2025, PostgreSQL Global Development Group
* Portions Copyright (c) 1994, Regents of the University of California
*
* IDENTIFICATION
diff --git a/src/backend/access/spgist/spgquadtreeproc.c b/src/backend/access/spgist/spgquadtreeproc.c
index 791db1d42e002..3e8cfa1709af3 100644
--- a/src/backend/access/spgist/spgquadtreeproc.c
+++ b/src/backend/access/spgist/spgquadtreeproc.c
@@ -4,7 +4,7 @@
* implementation of quad tree over points for SP-GiST
*
*
- * Portions Copyright (c) 1996-2024, PostgreSQL Global Development Group
+ * Portions Copyright (c) 1996-2025, PostgreSQL Global Development Group
* Portions Copyright (c) 1994, Regents of the University of California
*
* IDENTIFICATION
diff --git a/src/backend/access/spgist/spgscan.c b/src/backend/access/spgist/spgscan.c
index 03293a7816e6f..25893050c5876 100644
--- a/src/backend/access/spgist/spgscan.c
+++ b/src/backend/access/spgist/spgscan.c
@@ -4,7 +4,7 @@
* routines for scanning SP-GiST indexes
*
*
- * Portions Copyright (c) 1996-2024, PostgreSQL Global Development Group
+ * Portions Copyright (c) 1996-2025, PostgreSQL Global Development Group
* Portions Copyright (c) 1994, Regents of the University of California
*
* IDENTIFICATION
@@ -384,16 +384,14 @@ spgrescan(IndexScanDesc scan, ScanKey scankey, int nscankeys,
/* copy scankeys into local storage */
if (scankey && scan->numberOfKeys > 0)
- memmove(scan->keyData, scankey,
- scan->numberOfKeys * sizeof(ScanKeyData));
+ memcpy(scan->keyData, scankey, scan->numberOfKeys * sizeof(ScanKeyData));
/* initialize order-by data if needed */
if (orderbys && scan->numberOfOrderBys > 0)
{
int i;
- memmove(scan->orderByData, orderbys,
- scan->numberOfOrderBys * sizeof(ScanKeyData));
+ memcpy(scan->orderByData, orderbys, scan->numberOfOrderBys * sizeof(ScanKeyData));
for (i = 0; i < scan->numberOfOrderBys; i++)
{
@@ -423,6 +421,8 @@ spgrescan(IndexScanDesc scan, ScanKey scankey, int nscankeys,
/* count an indexscan for stats */
pgstat_count_index_scan(scan->indexRelation);
+ if (scan->instrument)
+ scan->instrument->nsearches++;
}
void
@@ -867,7 +867,7 @@ spgWalk(Relation index, SpGistScanOpaque so, bool scanWholeIndex,
if (SpGistPageIsLeaf(page))
{
- /* Page is a leaf - that is, all it's tuples are heap items */
+ /* Page is a leaf - that is, all its tuples are heap items */
OffsetNumber max = PageGetMaxOffsetNumber(page);
if (SpGistBlockIsRoot(blkno))
diff --git a/src/backend/access/spgist/spgtextproc.c b/src/backend/access/spgist/spgtextproc.c
index 3f08d330b6113..73842655f086c 100644
--- a/src/backend/access/spgist/spgtextproc.c
+++ b/src/backend/access/spgist/spgtextproc.c
@@ -29,7 +29,7 @@
* No new entries ever get pushed into a -2-labeled child, either.
*
*
- * Portions Copyright (c) 1996-2024, PostgreSQL Global Development Group
+ * Portions Copyright (c) 1996-2025, PostgreSQL Global Development Group
* Portions Copyright (c) 1994, Regents of the University of California
*
* IDENTIFICATION
@@ -427,7 +427,7 @@ spg_text_inner_consistent(PG_FUNCTION_ARGS)
{
spgInnerConsistentIn *in = (spgInnerConsistentIn *) PG_GETARG_POINTER(0);
spgInnerConsistentOut *out = (spgInnerConsistentOut *) PG_GETARG_POINTER(1);
- bool collate_is_c = lc_collate_is_c(PG_GET_COLLATION());
+ bool collate_is_c = pg_newlocale_from_collation(PG_GET_COLLATION())->collate_is_c;
text *reconstructedValue;
text *reconstrText;
int maxReconstrLen;
diff --git a/src/backend/access/spgist/spgutils.c b/src/backend/access/spgist/spgutils.c
index 3f793125f745d..9b86c016acb37 100644
--- a/src/backend/access/spgist/spgutils.c
+++ b/src/backend/access/spgist/spgutils.c
@@ -4,7 +4,7 @@
* various support functions for SP-GiST
*
*
- * Portions Copyright (c) 1996-2024, PostgreSQL Global Development Group
+ * Portions Copyright (c) 1996-2025, PostgreSQL Global Development Group
* Portions Copyright (c) 1994, Regents of the University of California
*
* IDENTIFICATION
@@ -50,6 +50,9 @@ spghandler(PG_FUNCTION_ARGS)
amroutine->amoptsprocnum = SPGIST_OPTIONS_PROC;
amroutine->amcanorder = false;
amroutine->amcanorderbyop = true;
+ amroutine->amcanhash = false;
+ amroutine->amconsistentequality = false;
+ amroutine->amconsistentordering = false;
amroutine->amcanbackward = false;
amroutine->amcanunique = false;
amroutine->amcanmulticol = false;
@@ -76,6 +79,7 @@ spghandler(PG_FUNCTION_ARGS)
amroutine->amvacuumcleanup = spgvacuumcleanup;
amroutine->amcanreturn = spgcanreturn;
amroutine->amcostestimate = spgcostestimate;
+ amroutine->amgettreeheight = NULL;
amroutine->amoptions = spgoptions;
amroutine->amproperty = spgproperty;
amroutine->ambuildphasename = NULL;
@@ -91,6 +95,8 @@ spghandler(PG_FUNCTION_ARGS)
amroutine->amestimateparallelscan = NULL;
amroutine->aminitparallelscan = NULL;
amroutine->amparallelrescan = NULL;
+ amroutine->amtranslatestrategy = NULL;
+ amroutine->amtranslatecmptype = NULL;
PG_RETURN_POINTER(amroutine);
}
@@ -278,7 +284,7 @@ spgGetCache(Relation index)
UnlockReleaseBuffer(metabuffer);
}
- index->rd_amcache = (void *) cache;
+ index->rd_amcache = cache;
}
else
{
@@ -330,7 +336,9 @@ getSpGistTupleDesc(Relation index, SpGistTypeDesc *keyType)
att->attcollation = InvalidOid;
/* In case we changed typlen, we'd better reset following offsets */
for (int i = spgFirstIncludeColumn; i < outTupDesc->natts; i++)
- TupleDescAttr(outTupDesc, i)->attcacheoff = -1;
+ TupleDescCompactAttr(outTupDesc, i)->attcacheoff = -1;
+
+ populate_compact_attribute(outTupDesc, spgKeyColumn);
}
return outTupDesc;
}
@@ -358,8 +366,19 @@ initSpGistState(SpGistState *state, Relation index)
/* Make workspace for constructing dead tuples */
state->deadTupleStorage = palloc0(SGDTSIZE);
- /* Set XID to use in redirection tuples */
- state->myXid = GetTopTransactionIdIfAny();
+ /*
+ * Set horizon XID to use in redirection tuples. Use our own XID if we
+ * have one, else use InvalidTransactionId. The latter case can happen in
+ * VACUUM or REINDEX CONCURRENTLY, and in neither case would it be okay to
+ * force an XID to be assigned. VACUUM won't create any redirection
+ * tuples anyway, but REINDEX CONCURRENTLY can. Fortunately, REINDEX
+ * CONCURRENTLY doesn't mark the index valid until the end, so there could
+ * never be any concurrent scans "in flight" to a redirection tuple it has
+ * inserted. And it locks out VACUUM until the end, too. So it's okay
+ * for VACUUM to immediately expire a redirection tuple that contains an
+ * invalid xid.
+ */
+ state->redirectXid = GetTopTransactionIdIfAny();
/* Assume we're not in an index build (spgbuild will override) */
state->isBuild = false;
@@ -766,7 +785,7 @@ SpGistGetInnerTypeSize(SpGistTypeDesc *att, Datum datum)
else if (att->attlen > 0)
size = att->attlen;
else
- size = VARSIZE_ANY(datum);
+ size = VARSIZE_ANY(DatumGetPointer(datum));
return MAXALIGN(size);
}
@@ -785,7 +804,7 @@ memcpyInnerDatum(void *target, SpGistTypeDesc *att, Datum datum)
}
else
{
- size = (att->attlen > 0) ? att->attlen : VARSIZE_ANY(datum);
+ size = (att->attlen > 0) ? att->attlen : VARSIZE_ANY(DatumGetPointer(datum));
memcpy(target, DatumGetPointer(datum), size);
}
}
@@ -1075,8 +1094,7 @@ spgFormDeadTuple(SpGistState *state, int tupstate,
if (tupstate == SPGIST_REDIRECT)
{
ItemPointerSet(&tuple->pointer, blkno, offnum);
- Assert(TransactionIdIsValid(state->myXid));
- tuple->xid = state->myXid;
+ tuple->xid = state->redirectXid;
}
else
{
diff --git a/src/backend/access/spgist/spgvacuum.c b/src/backend/access/spgist/spgvacuum.c
index d2e1624924a5a..8f8a1ad7796aa 100644
--- a/src/backend/access/spgist/spgvacuum.c
+++ b/src/backend/access/spgist/spgvacuum.c
@@ -4,7 +4,7 @@
* vacuum for SP-GiST
*
*
- * Portions Copyright (c) 1996-2024, PostgreSQL Global Development Group
+ * Portions Copyright (c) 1996-2025, PostgreSQL Global Development Group
* Portions Copyright (c) 1994, Regents of the University of California
*
* IDENTIFICATION
@@ -25,6 +25,7 @@
#include "storage/bufmgr.h"
#include "storage/indexfsm.h"
#include "storage/lmgr.h"
+#include "storage/read_stream.h"
#include "utils/snapmgr.h"
@@ -188,7 +189,9 @@ vacuumLeafPage(spgBulkDeleteState *bds, Relation index, Buffer buffer,
/*
* Add target TID to pending list if the redirection could have
- * happened since VACUUM started.
+ * happened since VACUUM started. (If xid is invalid, assume it
+ * must have happened before VACUUM started, since REINDEX
+ * CONCURRENTLY locks out VACUUM.)
*
* Note: we could make a tighter test by seeing if the xid is
* "running" according to the active snapshot; but snapmgr.c
@@ -378,14 +381,14 @@ vacuumLeafPage(spgBulkDeleteState *bds, Relation index, Buffer buffer,
STORE_STATE(&bds->spgstate, xlrec.stateSrc);
- XLogRegisterData((char *) &xlrec, SizeOfSpgxlogVacuumLeaf);
+ XLogRegisterData(&xlrec, SizeOfSpgxlogVacuumLeaf);
/* sizeof(xlrec) should be a multiple of sizeof(OffsetNumber) */
- XLogRegisterData((char *) toDead, sizeof(OffsetNumber) * xlrec.nDead);
- XLogRegisterData((char *) toPlaceholder, sizeof(OffsetNumber) * xlrec.nPlaceholder);
- XLogRegisterData((char *) moveSrc, sizeof(OffsetNumber) * xlrec.nMove);
- XLogRegisterData((char *) moveDest, sizeof(OffsetNumber) * xlrec.nMove);
- XLogRegisterData((char *) chainSrc, sizeof(OffsetNumber) * xlrec.nChain);
- XLogRegisterData((char *) chainDest, sizeof(OffsetNumber) * xlrec.nChain);
+ XLogRegisterData(toDead, sizeof(OffsetNumber) * xlrec.nDead);
+ XLogRegisterData(toPlaceholder, sizeof(OffsetNumber) * xlrec.nPlaceholder);
+ XLogRegisterData(moveSrc, sizeof(OffsetNumber) * xlrec.nMove);
+ XLogRegisterData(moveDest, sizeof(OffsetNumber) * xlrec.nMove);
+ XLogRegisterData(chainSrc, sizeof(OffsetNumber) * xlrec.nChain);
+ XLogRegisterData(chainDest, sizeof(OffsetNumber) * xlrec.nChain);
XLogRegisterBuffer(0, buffer, REGBUF_STANDARD);
@@ -463,9 +466,9 @@ vacuumLeafRoot(spgBulkDeleteState *bds, Relation index, Buffer buffer)
/* Prepare WAL record */
STORE_STATE(&bds->spgstate, xlrec.stateSrc);
- XLogRegisterData((char *) &xlrec, SizeOfSpgxlogVacuumRoot);
+ XLogRegisterData(&xlrec, SizeOfSpgxlogVacuumRoot);
/* sizeof(xlrec) should be a multiple of sizeof(OffsetNumber) */
- XLogRegisterData((char *) toDelete,
+ XLogRegisterData(toDelete,
sizeof(OffsetNumber) * xlrec.nDelete);
XLogRegisterBuffer(0, buffer, REGBUF_STANDARD);
@@ -523,8 +526,17 @@ vacuumRedirectAndPlaceholder(Relation index, Relation heaprel, Buffer buffer)
dt = (SpGistDeadTuple) PageGetItem(page, PageGetItemId(page, i));
+ /*
+ * We can convert a REDIRECT to a PLACEHOLDER if there could no longer
+ * be any index scans "in flight" to it. Such an index scan would
+ * have to be in a transaction whose snapshot sees the REDIRECT's XID
+ * as still running, so comparing the XID against global xmin is a
+ * conservatively safe test. If the XID is invalid, it must have been
+ * inserted by REINDEX CONCURRENTLY, so we can zap it immediately.
+ */
if (dt->tupstate == SPGIST_REDIRECT &&
- GlobalVisTestIsRemovableXid(vistest, dt->xid))
+ (!TransactionIdIsValid(dt->xid) ||
+ GlobalVisTestIsRemovableXid(vistest, dt->xid)))
{
dt->tupstate = SPGIST_PLACEHOLDER;
Assert(opaque->nRedirection > 0);
@@ -589,8 +601,8 @@ vacuumRedirectAndPlaceholder(Relation index, Relation heaprel, Buffer buffer)
XLogBeginInsert();
- XLogRegisterData((char *) &xlrec, SizeOfSpgxlogVacuumRedirect);
- XLogRegisterData((char *) itemToPlaceholder,
+ XLogRegisterData(&xlrec, SizeOfSpgxlogVacuumRedirect);
+ XLogRegisterData(itemToPlaceholder,
sizeof(OffsetNumber) * xlrec.nToPlaceholder);
XLogRegisterBuffer(0, buffer, REGBUF_STANDARD);
@@ -607,19 +619,14 @@ vacuumRedirectAndPlaceholder(Relation index, Relation heaprel, Buffer buffer)
* Process one page during a bulkdelete scan
*/
static void
-spgvacuumpage(spgBulkDeleteState *bds, BlockNumber blkno)
+spgvacuumpage(spgBulkDeleteState *bds, Buffer buffer)
{
Relation index = bds->info->index;
- Buffer buffer;
+ BlockNumber blkno = BufferGetBlockNumber(buffer);
Page page;
- /* call vacuum_delay_point while not holding any buffer lock */
- vacuum_delay_point();
-
- buffer = ReadBufferExtended(index, MAIN_FORKNUM, blkno,
- RBM_NORMAL, bds->info->strategy);
LockBuffer(buffer, BUFFER_LOCK_EXCLUSIVE);
- page = (Page) BufferGetPage(buffer);
+ page = BufferGetPage(buffer);
if (PageIsNew(page))
{
@@ -693,14 +700,14 @@ spgprocesspending(spgBulkDeleteState *bds)
continue; /* ignore already-done items */
/* call vacuum_delay_point while not holding any buffer lock */
- vacuum_delay_point();
+ vacuum_delay_point(false);
/* examine the referenced page */
blkno = ItemPointerGetBlockNumber(&pitem->tid);
buffer = ReadBufferExtended(index, MAIN_FORKNUM, blkno,
RBM_NORMAL, bds->info->strategy);
LockBuffer(buffer, BUFFER_LOCK_EXCLUSIVE);
- page = (Page) BufferGetPage(buffer);
+ page = BufferGetPage(buffer);
if (PageIsNew(page) || SpGistPageIsDeleted(page))
{
@@ -794,8 +801,9 @@ spgvacuumscan(spgBulkDeleteState *bds)
{
Relation index = bds->info->index;
bool needLock;
- BlockNumber num_pages,
- blkno;
+ BlockNumber num_pages;
+ BlockRangeReadStreamPrivate p;
+ ReadStream *stream = NULL;
/* Finish setting up spgBulkDeleteState */
initSpGistState(&bds->spgstate, index);
@@ -813,6 +821,21 @@ spgvacuumscan(spgBulkDeleteState *bds)
/* We can skip locking for new or temp relations */
needLock = !RELATION_IS_LOCAL(index);
+ p.current_blocknum = SPGIST_METAPAGE_BLKNO + 1;
+
+ /*
+ * It is safe to use batchmode as block_range_read_stream_cb takes no
+ * locks.
+ */
+ stream = read_stream_begin_relation(READ_STREAM_MAINTENANCE |
+ READ_STREAM_FULL |
+ READ_STREAM_USE_BATCHING,
+ bds->info->strategy,
+ index,
+ MAIN_FORKNUM,
+ block_range_read_stream_cb,
+ &p,
+ 0);
/*
* The outer loop iterates over all index pages except the metapage, in
@@ -822,7 +845,6 @@ spgvacuumscan(spgBulkDeleteState *bds)
* delete some deletable tuples. See more extensive comments about this
* in btvacuumscan().
*/
- blkno = SPGIST_METAPAGE_BLKNO + 1;
for (;;)
{
/* Get the current relation length */
@@ -833,18 +855,41 @@ spgvacuumscan(spgBulkDeleteState *bds)
UnlockRelationForExtension(index, ExclusiveLock);
/* Quit if we've scanned the whole relation */
- if (blkno >= num_pages)
+ if (p.current_blocknum >= num_pages)
break;
+
+ p.last_exclusive = num_pages;
+
/* Iterate over pages, then loop back to recheck length */
- for (; blkno < num_pages; blkno++)
+ while (true)
{
- spgvacuumpage(bds, blkno);
+ Buffer buf;
+
+ /* call vacuum_delay_point while not holding any buffer lock */
+ vacuum_delay_point(false);
+
+ buf = read_stream_next_buffer(stream, NULL);
+
+ if (!BufferIsValid(buf))
+ break;
+
+ spgvacuumpage(bds, buf);
+
/* empty the pending-list after each page */
if (bds->pendingList != NULL)
spgprocesspending(bds);
}
+
+ /*
+ * We have to reset the read stream to use it again. After returning
+ * InvalidBuffer, the read stream API won't invoke our callback again
+ * until the stream has been reset.
+ */
+ read_stream_reset(stream);
}
+ read_stream_end(stream);
+
/* Propagate local lastUsedPages cache to metablock */
SpGistUpdateMetaPage(index);
diff --git a/src/backend/access/spgist/spgvalidate.c b/src/backend/access/spgist/spgvalidate.c
index 850c3b675d63c..e9964fab4f41a 100644
--- a/src/backend/access/spgist/spgvalidate.c
+++ b/src/backend/access/spgist/spgvalidate.c
@@ -3,7 +3,7 @@
* spgvalidate.c
* Opclass validator for SP-GiST.
*
- * Portions Copyright (c) 1996-2024, PostgreSQL Global Development Group
+ * Portions Copyright (c) 1996-2025, PostgreSQL Global Development Group
* Portions Copyright (c) 1994, Regents of the University of California
*
* IDENTIFICATION
@@ -19,7 +19,6 @@
#include "catalog/pg_amop.h"
#include "catalog/pg_amproc.h"
#include "catalog/pg_opclass.h"
-#include "catalog/pg_opfamily.h"
#include "catalog/pg_type.h"
#include "utils/builtins.h"
#include "utils/lsyscache.h"
@@ -45,8 +44,6 @@ spgvalidate(Oid opclassoid)
Oid opcintype;
Oid opckeytype;
char *opclassname;
- HeapTuple familytup;
- Form_pg_opfamily familyform;
char *opfamilyname;
CatCList *proclist,
*oprlist;
@@ -72,12 +69,7 @@ spgvalidate(Oid opclassoid)
opclassname = NameStr(classform->opcname);
/* Fetch opfamily information */
- familytup = SearchSysCache1(OPFAMILYOID, ObjectIdGetDatum(opfamilyoid));
- if (!HeapTupleIsValid(familytup))
- elog(ERROR, "cache lookup failed for operator family %u", opfamilyoid);
- familyform = (Form_pg_opfamily) GETSTRUCT(familytup);
-
- opfamilyname = NameStr(familyform->opfname);
+ opfamilyname = get_opfamily_name(opfamilyoid, false);
/* Fetch all operators and support functions of the opfamily */
oprlist = SearchSysCacheList1(AMOPSTRATEGY, ObjectIdGetDatum(opfamilyoid));
@@ -319,7 +311,6 @@ spgvalidate(Oid opclassoid)
ReleaseCatCacheList(proclist);
ReleaseCatCacheList(oprlist);
- ReleaseSysCache(familytup);
ReleaseSysCache(classtup);
return result;
diff --git a/src/backend/access/spgist/spgxlog.c b/src/backend/access/spgist/spgxlog.c
index 11d006998ed3c..d4620c915d0cc 100644
--- a/src/backend/access/spgist/spgxlog.c
+++ b/src/backend/access/spgist/spgxlog.c
@@ -4,7 +4,7 @@
* WAL replay logic for SP-GiST
*
*
- * Portions Copyright (c) 1996-2024, PostgreSQL Global Development Group
+ * Portions Copyright (c) 1996-2025, PostgreSQL Global Development Group
* Portions Copyright (c) 1994, Regents of the University of California
*
* IDENTIFICATION
@@ -36,7 +36,7 @@ fillFakeState(SpGistState *state, spgxlogState stateSrc)
{
memset(state, 0, sizeof(*state));
- state->myXid = stateSrc.myXid;
+ state->redirectXid = stateSrc.redirectXid;
state->isBuild = stateSrc.isBuild;
state->deadTupleStorage = palloc0(SGDTSIZE);
}
@@ -576,7 +576,7 @@ spgRedoPickSplit(XLogReaderState *record)
{
/* just re-init the source page */
srcBuffer = XLogInitBufferForRedo(record, 0);
- srcPage = (Page) BufferGetPage(srcBuffer);
+ srcPage = BufferGetPage(srcBuffer);
SpGistInitBuffer(srcBuffer,
SPGIST_LEAF | (xldata->storesNulls ? SPGIST_NULLS : 0));
@@ -629,7 +629,7 @@ spgRedoPickSplit(XLogReaderState *record)
{
/* just re-init the dest page */
destBuffer = XLogInitBufferForRedo(record, 1);
- destPage = (Page) BufferGetPage(destBuffer);
+ destPage = BufferGetPage(destBuffer);
SpGistInitBuffer(destBuffer,
SPGIST_LEAF | (xldata->storesNulls ? SPGIST_NULLS : 0));
@@ -642,7 +642,7 @@ spgRedoPickSplit(XLogReaderState *record)
* full-page-image case, but for safety let's hold it till later.
*/
if (XLogReadBufferForRedo(record, 1, &destBuffer) == BLK_NEEDS_REDO)
- destPage = (Page) BufferGetPage(destBuffer);
+ destPage = BufferGetPage(destBuffer);
else
destPage = NULL; /* don't do any page updates */
}
diff --git a/src/backend/access/table/meson.build b/src/backend/access/table/meson.build
index 8ed1335a55d68..36ad5fb835ad1 100644
--- a/src/backend/access/table/meson.build
+++ b/src/backend/access/table/meson.build
@@ -1,4 +1,4 @@
-# Copyright (c) 2022-2024, PostgreSQL Global Development Group
+# Copyright (c) 2022-2025, PostgreSQL Global Development Group
backend_sources += files(
'table.c',
diff --git a/src/backend/access/table/table.c b/src/backend/access/table/table.c
index e589730ca0842..be698bba0ed1b 100644
--- a/src/backend/access/table/table.c
+++ b/src/backend/access/table/table.c
@@ -3,7 +3,7 @@
* table.c
* Generic routines for table related code.
*
- * Portions Copyright (c) 1996-2024, PostgreSQL Global Development Group
+ * Portions Copyright (c) 1996-2025, PostgreSQL Global Development Group
* Portions Copyright (c) 1994, Regents of the University of California
*
*
diff --git a/src/backend/access/table/tableam.c b/src/backend/access/table/tableam.c
index e57a0b7ea310b..a56c5eceb14ad 100644
--- a/src/backend/access/table/tableam.c
+++ b/src/backend/access/table/tableam.c
@@ -3,7 +3,7 @@
* tableam.c
* Table access method routines too big to be inline functions.
*
- * Portions Copyright (c) 1996-2024, PostgreSQL Global Development Group
+ * Portions Copyright (c) 1996-2025, PostgreSQL Global Development Group
* Portions Copyright (c) 1994, Regents of the University of California
*
*
@@ -24,6 +24,7 @@
#include "access/syncscan.h"
#include "access/tableam.h"
#include "access/xact.h"
+#include "optimizer/optimizer.h"
#include "optimizer/plancat.h"
#include "port/pg_bitutils.h"
#include "storage/bufmgr.h"
@@ -168,7 +169,7 @@ table_beginscan_parallel(Relation relation, ParallelTableScanDesc pscan)
uint32 flags = SO_TYPE_SEQSCAN |
SO_ALLOW_STRAT | SO_ALLOW_SYNC | SO_ALLOW_PAGEMODE;
- Assert(RelationGetRelid(relation) == pscan->phs_relid);
+ Assert(RelFileLocatorEquals(relation->rd_locator, pscan->phs_locator));
if (!pscan->phs_snapshot_any)
{
@@ -389,7 +390,7 @@ table_block_parallelscan_initialize(Relation rel, ParallelTableScanDesc pscan)
{
ParallelBlockTableScanDesc bpscan = (ParallelBlockTableScanDesc) pscan;
- bpscan->base.phs_relid = RelationGetRelid(rel);
+ bpscan->base.phs_locator = rel->rd_locator;
bpscan->phs_nblocks = RelationGetNumberOfBlocks(rel);
/* compare phs_syncscan initialization to similar logic in initscan */
bpscan->base.phs_syncscan = synchronize_seqscans &&
@@ -740,6 +741,8 @@ table_block_relation_estimate_size(Relation rel, int32 *attr_widths,
tuple_width += overhead_bytes_per_tuple;
/* note: integer division is intentional here */
density = (usable_bytes_per_page * fillfactor / 100) / tuple_width;
+ /* There's at least one row on the page, even with low fillfactor. */
+ density = clamp_row_est(density);
}
*tuples = rint(density * (double) curpages);
diff --git a/src/backend/access/table/tableamapi.c b/src/backend/access/table/tableamapi.c
index e9b598256fbe0..476663b66aada 100644
--- a/src/backend/access/table/tableamapi.c
+++ b/src/backend/access/table/tableamapi.c
@@ -3,7 +3,7 @@
* tableamapi.c
* Support routines for API for Postgres table access methods
*
- * Portions Copyright (c) 1996-2024, PostgreSQL Global Development Group
+ * Portions Copyright (c) 1996-2025, PostgreSQL Global Development Group
* Portions Copyright (c) 1994, Regents of the University of California
*
* src/backend/access/table/tableamapi.c
@@ -91,9 +91,6 @@ GetTableAmRoutine(Oid amhandler)
Assert(routine->relation_estimate_size != NULL);
- /* optional, but one callback implies presence of the other */
- Assert((routine->scan_bitmap_next_block == NULL) ==
- (routine->scan_bitmap_next_tuple == NULL));
Assert(routine->scan_sample_next_block != NULL);
Assert(routine->scan_sample_next_tuple != NULL);
diff --git a/src/backend/access/table/toast_helper.c b/src/backend/access/table/toast_helper.c
index 53224932f0db4..11f97d65367d5 100644
--- a/src/backend/access/table/toast_helper.c
+++ b/src/backend/access/table/toast_helper.c
@@ -4,7 +4,7 @@
* Helper functions for table AMs implementing compressed or
* out-of-line storage of varlena attributes.
*
- * Copyright (c) 2000-2024, PostgreSQL Global Development Group
+ * Copyright (c) 2000-2025, PostgreSQL Global Development Group
*
* IDENTIFICATION
* src/backend/access/table/toast_helper.c
@@ -75,7 +75,7 @@ toast_tuple_init(ToastTupleContext *ttc)
{
if (ttc->ttc_isnull[i] ||
!VARATT_IS_EXTERNAL_ONDISK(new_value) ||
- memcmp((char *) old_value, (char *) new_value,
+ memcmp(old_value, new_value,
VARSIZE_EXTERNAL(old_value)) != 0)
{
/*
@@ -324,13 +324,13 @@ toast_delete_external(Relation rel, const Datum *values, const bool *isnull,
for (i = 0; i < numAttrs; i++)
{
- if (TupleDescAttr(tupleDesc, i)->attlen == -1)
+ if (TupleDescCompactAttr(tupleDesc, i)->attlen == -1)
{
Datum value = values[i];
if (isnull[i])
continue;
- else if (VARATT_IS_EXTERNAL_ONDISK(value))
+ else if (VARATT_IS_EXTERNAL_ONDISK(DatumGetPointer(value)))
toast_delete_datum(rel, value, is_speculative);
}
}
diff --git a/src/backend/access/tablesample/bernoulli.c b/src/backend/access/tablesample/bernoulli.c
index c8ac308ff8c55..5e1c5d2b7231a 100644
--- a/src/backend/access/tablesample/bernoulli.c
+++ b/src/backend/access/tablesample/bernoulli.c
@@ -13,7 +13,7 @@
* cutoff value computed from the selection probability by BeginSampleScan.
*
*
- * Portions Copyright (c) 1996-2024, PostgreSQL Global Development Group
+ * Portions Copyright (c) 1996-2025, PostgreSQL Global Development Group
* Portions Copyright (c) 1994, Regents of the University of California
*
* IDENTIFICATION
diff --git a/src/backend/access/tablesample/meson.build b/src/backend/access/tablesample/meson.build
index 6f3112fb758b5..b0124cde63a01 100644
--- a/src/backend/access/tablesample/meson.build
+++ b/src/backend/access/tablesample/meson.build
@@ -1,4 +1,4 @@
-# Copyright (c) 2022-2024, PostgreSQL Global Development Group
+# Copyright (c) 2022-2025, PostgreSQL Global Development Group
backend_sources += files(
'bernoulli.c',
diff --git a/src/backend/access/tablesample/system.c b/src/backend/access/tablesample/system.c
index fe483ab859725..8db813b89fc64 100644
--- a/src/backend/access/tablesample/system.c
+++ b/src/backend/access/tablesample/system.c
@@ -13,7 +13,7 @@
* cutoff value computed from the selection probability by BeginSampleScan.
*
*
- * Portions Copyright (c) 1996-2024, PostgreSQL Global Development Group
+ * Portions Copyright (c) 1996-2025, PostgreSQL Global Development Group
* Portions Copyright (c) 1994, Regents of the University of California
*
* IDENTIFICATION
diff --git a/src/backend/access/tablesample/tablesample.c b/src/backend/access/tablesample/tablesample.c
index e9a495e4cc879..5ad424cf8491f 100644
--- a/src/backend/access/tablesample/tablesample.c
+++ b/src/backend/access/tablesample/tablesample.c
@@ -3,7 +3,7 @@
* tablesample.c
* Support functions for TABLESAMPLE feature
*
- * Portions Copyright (c) 1996-2024, PostgreSQL Global Development Group
+ * Portions Copyright (c) 1996-2025, PostgreSQL Global Development Group
* Portions Copyright (c) 1994, Regents of the University of California
*
*
diff --git a/src/backend/access/transam/README b/src/backend/access/transam/README
index 28d196cf62b33..231106270fd40 100644
--- a/src/backend/access/transam/README
+++ b/src/backend/access/transam/README
@@ -586,13 +586,13 @@ void XLogRegisterBuffer(uint8 block_id, Buffer buf, uint8 flags);
XLogRegisterBufData() is included in the WAL record even if a full-page
image is taken.
-void XLogRegisterData(char *data, int len);
+void XLogRegisterData(const void *data, int len);
XLogRegisterData is used to include arbitrary data in the WAL record. If
XLogRegisterData() is called multiple times, the data are appended, and
will be made available to the redo routine as one contiguous chunk.
-void XLogRegisterBufData(uint8 block_id, char *data, int len);
+void XLogRegisterBufData(uint8 block_id, const void *data, int len);
XLogRegisterBufData is used to include data associated with a particular
buffer that was registered earlier with XLogRegisterBuffer(). If
diff --git a/src/backend/access/transam/clog.c b/src/backend/access/transam/clog.c
index 44c253246b9c4..e80fbe109cf3c 100644
--- a/src/backend/access/transam/clog.c
+++ b/src/backend/access/transam/clog.c
@@ -24,7 +24,7 @@
* for aborts (whether sync or async), since the post-crash assumption would
* be that such transactions failed anyway.
*
- * Portions Copyright (c) 1996-2024, PostgreSQL Global Development Group
+ * Portions Copyright (c) 1996-2025, PostgreSQL Global Development Group
* Portions Copyright (c) 1994, Regents of the University of California
*
* src/backend/access/transam/clog.c
@@ -110,9 +110,7 @@ static SlruCtlData XactCtlData;
#define XactCtl (&XactCtlData)
-static int ZeroCLOGPage(int64 pageno, bool writeXlog);
static bool CLOGPagePrecedes(int64 page1, int64 page2);
-static void WriteZeroPageXlogRec(int64 pageno);
static void WriteTruncateXlogRec(int64 pageno, TransactionId oldestXact,
Oid oldestXactDb);
static void TransactionIdSetPageStatus(TransactionId xid, int nsubxids,
@@ -445,7 +443,7 @@ TransactionGroupUpdateXidStatus(TransactionId xid, XidStatus status,
PGPROC *proc = MyProc;
uint32 nextidx;
uint32 wakeidx;
- int prevpageno;
+ int64 prevpageno;
LWLock *prevlock = NULL;
/* We should definitely have an XID whose status needs to be updated. */
@@ -577,7 +575,7 @@ TransactionGroupUpdateXidStatus(TransactionId xid, XidStatus status,
while (nextidx != INVALID_PROC_NUMBER)
{
PGPROC *nextproc = &ProcGlobal->allProcs[nextidx];
- int thispageno = nextproc->clogGroupMemberPage;
+ int64 thispageno = nextproc->clogGroupMemberPage;
/*
* If the page to update belongs to a different bank than the previous
@@ -832,41 +830,8 @@ check_transaction_buffers(int *newval, void **extra, GucSource source)
void
BootStrapCLOG(void)
{
- int slotno;
- LWLock *lock = SimpleLruGetBankLock(XactCtl, 0);
-
- LWLockAcquire(lock, LW_EXCLUSIVE);
-
- /* Create and zero the first page of the commit log */
- slotno = ZeroCLOGPage(0, false);
-
- /* Make sure it's written out */
- SimpleLruWritePage(XactCtl, slotno);
- Assert(!XactCtl->shared->page_dirty[slotno]);
-
- LWLockRelease(lock);
-}
-
-/*
- * Initialize (or reinitialize) a page of CLOG to zeroes.
- * If writeXlog is true, also emit an XLOG record saying we did this.
- *
- * The page is not actually written, just set up in shared memory.
- * The slot number of the new page is returned.
- *
- * Control lock must be held at entry, and will be held at exit.
- */
-static int
-ZeroCLOGPage(int64 pageno, bool writeXlog)
-{
- int slotno;
-
- slotno = SimpleLruZeroPage(XactCtl, pageno);
-
- if (writeXlog)
- WriteZeroPageXlogRec(pageno);
-
- return slotno;
+ /* Zero the initial page and flush it to disk */
+ SimpleLruZeroAndWritePage(XactCtl, 0);
}
/*
@@ -974,8 +939,9 @@ ExtendCLOG(TransactionId newestXact)
LWLockAcquire(lock, LW_EXCLUSIVE);
- /* Zero the page and make an XLOG entry about it */
- ZeroCLOGPage(pageno, true);
+ /* Zero the page and make a WAL entry about it */
+ SimpleLruZeroPage(XactCtl, pageno);
+ XLogSimpleInsertInt64(RM_CLOG_ID, CLOG_ZEROPAGE, pageno);
LWLockRelease(lock);
}
@@ -984,8 +950,8 @@ ExtendCLOG(TransactionId newestXact)
/*
* Remove all CLOG segments before the one holding the passed transaction ID
*
- * Before removing any CLOG data, we must flush XLOG to disk, to ensure
- * that any recently-emitted FREEZE_PAGE records have reached disk; otherwise
+ * Before removing any CLOG data, we must flush XLOG to disk, to ensure that
+ * any recently-emitted records with freeze plans have reached disk; otherwise
* a crash and restart might leave us with some unfrozen tuples referencing
* removed CLOG data. We choose to emit a special TRUNCATE XLOG record too.
* Replaying the deletion from XLOG is not critical, since the files could
@@ -1067,17 +1033,6 @@ CLOGPagePrecedes(int64 page1, int64 page2)
}
-/*
- * Write a ZEROPAGE xlog record
- */
-static void
-WriteZeroPageXlogRec(int64 pageno)
-{
- XLogBeginInsert();
- XLogRegisterData((char *) (&pageno), sizeof(pageno));
- (void) XLogInsert(RM_CLOG_ID, CLOG_ZEROPAGE);
-}
-
/*
* Write a TRUNCATE xlog record
*
@@ -1095,7 +1050,7 @@ WriteTruncateXlogRec(int64 pageno, TransactionId oldestXact, Oid oldestXactDb)
xlrec.oldestXactDb = oldestXactDb;
XLogBeginInsert();
- XLogRegisterData((char *) (&xlrec), sizeof(xl_clog_truncate));
+ XLogRegisterData(&xlrec, sizeof(xl_clog_truncate));
recptr = XLogInsert(RM_CLOG_ID, CLOG_TRUNCATE);
XLogFlush(recptr);
}
@@ -1114,19 +1069,9 @@ clog_redo(XLogReaderState *record)
if (info == CLOG_ZEROPAGE)
{
int64 pageno;
- int slotno;
- LWLock *lock;
memcpy(&pageno, XLogRecGetData(record), sizeof(pageno));
-
- lock = SimpleLruGetBankLock(XactCtl, pageno);
- LWLockAcquire(lock, LW_EXCLUSIVE);
-
- slotno = ZeroCLOGPage(pageno, false);
- SimpleLruWritePage(XactCtl, slotno);
- Assert(!XactCtl->shared->page_dirty[slotno]);
-
- LWLockRelease(lock);
+ SimpleLruZeroAndWritePage(XactCtl, pageno);
}
else if (info == CLOG_TRUNCATE)
{
diff --git a/src/backend/access/transam/commit_ts.c b/src/backend/access/transam/commit_ts.c
index 77e1899d7ad21..370b38e048b91 100644
--- a/src/backend/access/transam/commit_ts.c
+++ b/src/backend/access/transam/commit_ts.c
@@ -12,7 +12,7 @@
* XLOG records for these events and will re-perform the status update on
* redo; so we need make no additional XLOG entry here.
*
- * Portions Copyright (c) 1996-2024, PostgreSQL Global Development Group
+ * Portions Copyright (c) 1996-2025, PostgreSQL Global Development Group
* Portions Copyright (c) 1994, Regents of the University of California
*
* src/backend/access/transam/commit_ts.c
@@ -114,11 +114,9 @@ static void SetXidCommitTsInPage(TransactionId xid, int nsubxids,
static void TransactionIdSetCommitTs(TransactionId xid, TimestampTz ts,
RepOriginId nodeid, int slotno);
static void error_commit_ts_disabled(void);
-static int ZeroCommitTsPage(int64 pageno, bool writeXlog);
static bool CommitTsPagePrecedes(int64 page1, int64 page2);
static void ActivateCommitTs(void);
static void DeactivateCommitTs(void);
-static void WriteZeroPageXlogRec(int64 pageno);
static void WriteTruncateXlogRec(int64 pageno, TransactionId oldestXid);
/*
@@ -602,28 +600,6 @@ BootStrapCommitTs(void)
*/
}
-/*
- * Initialize (or reinitialize) a page of CommitTs to zeroes.
- * If writeXlog is true, also emit an XLOG record saying we did this.
- *
- * The page is not actually written, just set up in shared memory.
- * The slot number of the new page is returned.
- *
- * Control lock must be held at entry, and will be held at exit.
- */
-static int
-ZeroCommitTsPage(int64 pageno, bool writeXlog)
-{
- int slotno;
-
- slotno = SimpleLruZeroPage(CommitTsCtl, pageno);
-
- if (writeXlog)
- WriteZeroPageXlogRec(pageno);
-
- return slotno;
-}
-
/*
* This must be called ONCE during postmaster or standalone-backend startup,
* after StartupXLOG has initialized TransamVariables->nextXid.
@@ -707,6 +683,13 @@ ActivateCommitTs(void)
TransactionId xid;
int64 pageno;
+ /*
+ * During bootstrap, we should not register commit timestamps so skip the
+ * activation in this case.
+ */
+ if (IsBootstrapProcessingMode())
+ return;
+
/* If we've done this already, there's nothing to do */
LWLockAcquire(CommitTsLock, LW_EXCLUSIVE);
if (commitTsShared->commitTsActive)
@@ -747,16 +730,7 @@ ActivateCommitTs(void)
/* Create the current segment file, if necessary */
if (!SimpleLruDoesPhysicalPageExist(CommitTsCtl, pageno))
- {
- LWLock *lock = SimpleLruGetBankLock(CommitTsCtl, pageno);
- int slotno;
-
- LWLockAcquire(lock, LW_EXCLUSIVE);
- slotno = ZeroCommitTsPage(pageno, false);
- SimpleLruWritePage(CommitTsCtl, slotno);
- Assert(!CommitTsCtl->shared->page_dirty[slotno]);
- LWLockRelease(lock);
- }
+ SimpleLruZeroAndWritePage(CommitTsCtl, pageno);
/* Change the activation status in shared memory. */
LWLockAcquire(CommitTsLock, LW_EXCLUSIVE);
@@ -867,8 +841,12 @@ ExtendCommitTs(TransactionId newestXact)
LWLockAcquire(lock, LW_EXCLUSIVE);
- /* Zero the page and make an XLOG entry about it */
- ZeroCommitTsPage(pageno, !InRecovery);
+ /* Zero the page ... */
+ SimpleLruZeroPage(CommitTsCtl, pageno);
+
+ /* and make a WAL entry about that, unless we're in REDO */
+ if (!InRecovery)
+ XLogSimpleInsertInt64(RM_COMMIT_TS_ID, COMMIT_TS_ZEROPAGE, pageno);
LWLockRelease(lock);
}
@@ -982,17 +960,6 @@ CommitTsPagePrecedes(int64 page1, int64 page2)
}
-/*
- * Write a ZEROPAGE xlog record
- */
-static void
-WriteZeroPageXlogRec(int64 pageno)
-{
- XLogBeginInsert();
- XLogRegisterData((char *) (&pageno), sizeof(pageno));
- (void) XLogInsert(RM_COMMIT_TS_ID, COMMIT_TS_ZEROPAGE);
-}
-
/*
* Write a TRUNCATE xlog record
*/
@@ -1005,7 +972,7 @@ WriteTruncateXlogRec(int64 pageno, TransactionId oldestXid)
xlrec.oldestXid = oldestXid;
XLogBeginInsert();
- XLogRegisterData((char *) (&xlrec), SizeOfCommitTsTruncate);
+ XLogRegisterData(&xlrec, SizeOfCommitTsTruncate);
(void) XLogInsert(RM_COMMIT_TS_ID, COMMIT_TS_TRUNCATE);
}
@@ -1023,19 +990,9 @@ commit_ts_redo(XLogReaderState *record)
if (info == COMMIT_TS_ZEROPAGE)
{
int64 pageno;
- int slotno;
- LWLock *lock;
memcpy(&pageno, XLogRecGetData(record), sizeof(pageno));
-
- lock = SimpleLruGetBankLock(CommitTsCtl, pageno);
- LWLockAcquire(lock, LW_EXCLUSIVE);
-
- slotno = ZeroCommitTsPage(pageno, false);
- SimpleLruWritePage(CommitTsCtl, slotno);
- Assert(!CommitTsCtl->shared->page_dirty[slotno]);
-
- LWLockRelease(lock);
+ SimpleLruZeroAndWritePage(CommitTsCtl, pageno);
}
else if (info == COMMIT_TS_TRUNCATE)
{
diff --git a/src/backend/access/transam/generic_xlog.c b/src/backend/access/transam/generic_xlog.c
index e8522781631df..2ce11e96af0dd 100644
--- a/src/backend/access/transam/generic_xlog.c
+++ b/src/backend/access/transam/generic_xlog.c
@@ -4,7 +4,7 @@
* Implementation of generic xlog records.
*
*
- * Portions Copyright (c) 1996-2024, PostgreSQL Global Development Group
+ * Portions Copyright (c) 1996-2025, PostgreSQL Global Development Group
* Portions Copyright (c) 1994, Regents of the University of California
*
* src/backend/access/transam/generic_xlog.c
@@ -55,7 +55,7 @@ typedef struct
char *image; /* copy of page image for modification, do not
* do it in-place to have aligned memory chunk */
char delta[MAX_DELTA_SIZE]; /* delta between page images */
-} PageData;
+} GenericXLogPageData;
/*
* State of generic xlog record construction. Must be allocated at an I/O
@@ -66,17 +66,17 @@ struct GenericXLogState
/* Page images (properly aligned, must be first) */
PGIOAlignedBlock images[MAX_GENERIC_XLOG_PAGES];
/* Info about each page, see above */
- PageData pages[MAX_GENERIC_XLOG_PAGES];
+ GenericXLogPageData pages[MAX_GENERIC_XLOG_PAGES];
bool isLogged;
};
-static void writeFragment(PageData *pageData, OffsetNumber offset,
+static void writeFragment(GenericXLogPageData *pageData, OffsetNumber offset,
OffsetNumber length, const char *data);
-static void computeRegionDelta(PageData *pageData,
+static void computeRegionDelta(GenericXLogPageData *pageData,
const char *curpage, const char *targetpage,
int targetStart, int targetEnd,
int validStart, int validEnd);
-static void computeDelta(PageData *pageData, Page curpage, Page targetpage);
+static void computeDelta(GenericXLogPageData *pageData, Page curpage, Page targetpage);
static void applyPageRedo(Page page, const char *delta, Size deltaSize);
@@ -87,7 +87,7 @@ static void applyPageRedo(Page page, const char *delta, Size deltaSize);
* actual data (of length length).
*/
static void
-writeFragment(PageData *pageData, OffsetNumber offset, OffsetNumber length,
+writeFragment(GenericXLogPageData *pageData, OffsetNumber offset, OffsetNumber length,
const char *data)
{
char *ptr = pageData->delta + pageData->deltaLen;
@@ -118,7 +118,7 @@ writeFragment(PageData *pageData, OffsetNumber offset, OffsetNumber length,
* about the data-matching loops.
*/
static void
-computeRegionDelta(PageData *pageData,
+computeRegionDelta(GenericXLogPageData *pageData,
const char *curpage, const char *targetpage,
int targetStart, int targetEnd,
int validStart, int validEnd)
@@ -225,7 +225,7 @@ computeRegionDelta(PageData *pageData,
* and store it in pageData's delta field.
*/
static void
-computeDelta(PageData *pageData, Page curpage, Page targetpage)
+computeDelta(GenericXLogPageData *pageData, Page curpage, Page targetpage)
{
int targetLower = ((PageHeader) targetpage)->pd_lower,
targetUpper = ((PageHeader) targetpage)->pd_upper,
@@ -303,7 +303,7 @@ GenericXLogRegisterBuffer(GenericXLogState *state, Buffer buffer, int flags)
/* Search array for existing entry or first unused slot */
for (block_id = 0; block_id < MAX_GENERIC_XLOG_PAGES; block_id++)
{
- PageData *page = &state->pages[block_id];
+ GenericXLogPageData *page = &state->pages[block_id];
if (BufferIsInvalid(page->buffer))
{
@@ -352,7 +352,7 @@ GenericXLogFinish(GenericXLogState *state)
*/
for (i = 0; i < MAX_GENERIC_XLOG_PAGES; i++)
{
- PageData *pageData = &state->pages[i];
+ GenericXLogPageData *pageData = &state->pages[i];
Page page;
PageHeader pageHeader;
@@ -401,7 +401,7 @@ GenericXLogFinish(GenericXLogState *state)
/* Set LSN */
for (i = 0; i < MAX_GENERIC_XLOG_PAGES; i++)
{
- PageData *pageData = &state->pages[i];
+ GenericXLogPageData *pageData = &state->pages[i];
if (BufferIsInvalid(pageData->buffer))
continue;
@@ -415,7 +415,7 @@ GenericXLogFinish(GenericXLogState *state)
START_CRIT_SECTION();
for (i = 0; i < MAX_GENERIC_XLOG_PAGES; i++)
{
- PageData *pageData = &state->pages[i];
+ GenericXLogPageData *pageData = &state->pages[i];
if (BufferIsInvalid(pageData->buffer))
continue;
diff --git a/src/backend/access/transam/meson.build b/src/backend/access/transam/meson.build
index 8a3522557cd90..e8ae9b13c8e49 100644
--- a/src/backend/access/transam/meson.build
+++ b/src/backend/access/transam/meson.build
@@ -1,4 +1,4 @@
-# Copyright (c) 2022-2024, PostgreSQL Global Development Group
+# Copyright (c) 2022-2025, PostgreSQL Global Development Group
backend_sources += files(
'clog.c',
diff --git a/src/backend/access/transam/multixact.c b/src/backend/access/transam/multixact.c
index 54c916e0347f4..8bf59d369f848 100644
--- a/src/backend/access/transam/multixact.c
+++ b/src/backend/access/transam/multixact.c
@@ -59,7 +59,7 @@
* counter does not fall within the wraparound horizon considering the global
* minimum value.
*
- * Portions Copyright (c) 1996-2024, PostgreSQL Global Development Group
+ * Portions Copyright (c) 1996-2025, PostgreSQL Global Development Group
* Portions Copyright (c) 1994, Regents of the University of California
*
* src/backend/access/transam/multixact.c
@@ -70,16 +70,11 @@
#include "access/multixact.h"
#include "access/slru.h"
-#include "access/transam.h"
#include "access/twophase.h"
#include "access/twophase_rmgr.h"
-#include "access/xact.h"
#include "access/xlog.h"
#include "access/xloginsert.h"
#include "access/xlogutils.h"
-#include "commands/dbcommands.h"
-#include "funcapi.h"
-#include "lib/ilist.h"
#include "miscadmin.h"
#include "pg_trace.h"
#include "pgstat.h"
@@ -87,8 +82,9 @@
#include "storage/pmsignal.h"
#include "storage/proc.h"
#include "storage/procarray.h"
-#include "utils/fmgrprotos.h"
#include "utils/guc_hooks.h"
+#include "utils/injection_point.h"
+#include "utils/lsyscache.h"
#include "utils/memutils.h"
@@ -108,11 +104,23 @@
/* We need four bytes per offset */
#define MULTIXACT_OFFSETS_PER_PAGE (BLCKSZ / sizeof(MultiXactOffset))
-#define MultiXactIdToOffsetPage(xid) \
- ((xid) / (MultiXactOffset) MULTIXACT_OFFSETS_PER_PAGE)
-#define MultiXactIdToOffsetEntry(xid) \
- ((xid) % (MultiXactOffset) MULTIXACT_OFFSETS_PER_PAGE)
-#define MultiXactIdToOffsetSegment(xid) (MultiXactIdToOffsetPage(xid) / SLRU_PAGES_PER_SEGMENT)
+static inline int64
+MultiXactIdToOffsetPage(MultiXactId multi)
+{
+ return multi / MULTIXACT_OFFSETS_PER_PAGE;
+}
+
+static inline int
+MultiXactIdToOffsetEntry(MultiXactId multi)
+{
+ return multi % MULTIXACT_OFFSETS_PER_PAGE;
+}
+
+static inline int64
+MultiXactIdToOffsetSegment(MultiXactId multi)
+{
+ return MultiXactIdToOffsetPage(multi) / SLRU_PAGES_PER_SEGMENT;
+}
/*
* The situation for members is a bit more complex: we store one byte of
@@ -156,30 +164,59 @@
((uint32) ((0xFFFFFFFF % MULTIXACT_MEMBERS_PER_PAGE) + 1))
/* page in which a member is to be found */
-#define MXOffsetToMemberPage(xid) ((xid) / (TransactionId) MULTIXACT_MEMBERS_PER_PAGE)
-#define MXOffsetToMemberSegment(xid) (MXOffsetToMemberPage(xid) / SLRU_PAGES_PER_SEGMENT)
+static inline int64
+MXOffsetToMemberPage(MultiXactOffset offset)
+{
+ return offset / MULTIXACT_MEMBERS_PER_PAGE;
+}
+
+static inline int64
+MXOffsetToMemberSegment(MultiXactOffset offset)
+{
+ return MXOffsetToMemberPage(offset) / SLRU_PAGES_PER_SEGMENT;
+}
/* Location (byte offset within page) of flag word for a given member */
-#define MXOffsetToFlagsOffset(xid) \
- ((((xid) / (TransactionId) MULTIXACT_MEMBERS_PER_MEMBERGROUP) % \
- (TransactionId) MULTIXACT_MEMBERGROUPS_PER_PAGE) * \
- (TransactionId) MULTIXACT_MEMBERGROUP_SIZE)
-#define MXOffsetToFlagsBitShift(xid) \
- (((xid) % (TransactionId) MULTIXACT_MEMBERS_PER_MEMBERGROUP) * \
- MXACT_MEMBER_BITS_PER_XACT)
+static inline int
+MXOffsetToFlagsOffset(MultiXactOffset offset)
+{
+ MultiXactOffset group = offset / MULTIXACT_MEMBERS_PER_MEMBERGROUP;
+ int grouponpg = group % MULTIXACT_MEMBERGROUPS_PER_PAGE;
+ int byteoff = grouponpg * MULTIXACT_MEMBERGROUP_SIZE;
+
+ return byteoff;
+}
+
+static inline int
+MXOffsetToFlagsBitShift(MultiXactOffset offset)
+{
+ int member_in_group = offset % MULTIXACT_MEMBERS_PER_MEMBERGROUP;
+ int bshift = member_in_group * MXACT_MEMBER_BITS_PER_XACT;
+
+ return bshift;
+}
/* Location (byte offset within page) of TransactionId of given member */
-#define MXOffsetToMemberOffset(xid) \
- (MXOffsetToFlagsOffset(xid) + MULTIXACT_FLAGBYTES_PER_GROUP + \
- ((xid) % MULTIXACT_MEMBERS_PER_MEMBERGROUP) * sizeof(TransactionId))
+static inline int
+MXOffsetToMemberOffset(MultiXactOffset offset)
+{
+ int member_in_group = offset % MULTIXACT_MEMBERS_PER_MEMBERGROUP;
+
+ return MXOffsetToFlagsOffset(offset) +
+ MULTIXACT_FLAGBYTES_PER_GROUP +
+ member_in_group * sizeof(TransactionId);
+}
/* Multixact members wraparound thresholds. */
#define MULTIXACT_MEMBER_SAFE_THRESHOLD (MaxMultiXactOffset / 2)
#define MULTIXACT_MEMBER_DANGER_THRESHOLD \
(MaxMultiXactOffset - MaxMultiXactOffset / 4)
-#define PreviousMultiXactId(xid) \
- ((xid) == FirstMultiXactId ? MaxMultiXactId : (xid) - 1)
+static inline MultiXactId
+PreviousMultiXactId(MultiXactId multi)
+{
+ return multi == FirstMultiXactId ? MaxMultiXactId : multi - 1;
+}
/*
* Links to shared-memory data structures for MultiXact control
@@ -356,11 +393,7 @@ static int mXactCacheGetById(MultiXactId multi, MultiXactMember **members);
static void mXactCachePut(MultiXactId multi, int nmembers,
MultiXactMember *members);
-static char *mxstatus_to_string(MultiXactStatus status);
-
/* management of SLRU infrastructure */
-static int ZeroMultiXactOffsetPage(int64 pageno, bool writeXlog);
-static int ZeroMultiXactMemberPage(int64 pageno, bool writeXlog);
static bool MultiXactOffsetPagePrecedes(int64 page1, int64 page2);
static bool MultiXactMemberPagePrecedes(int64 page1, int64 page2);
static bool MultiXactOffsetPrecedes(MultiXactOffset offset1,
@@ -371,7 +404,6 @@ static bool MultiXactOffsetWouldWrap(MultiXactOffset boundary,
MultiXactOffset start, uint32 distance);
static bool SetOffsetVacuumLimit(bool is_startup);
static bool find_multixact_start(MultiXactId multi, MultiXactOffset *result);
-static void WriteMZeroPageXlogRec(int64 pageno, uint8 info);
static void WriteMTruncateXlogRec(Oid oldestMultiDB,
MultiXactId startTruncOff,
MultiXactId endTruncOff,
@@ -813,6 +845,9 @@ MultiXactIdCreateFromMembers(int nmembers, MultiXactMember *members)
}
}
+ /* Load the injection point before entering the critical section */
+ INJECTION_POINT_LOAD("multixact-create-from-members");
+
/*
* Assign the MXID and offsets range to use, and make sure there is space
* in the OFFSETs and MEMBERs files. NB: this routine does
@@ -827,6 +862,8 @@ MultiXactIdCreateFromMembers(int nmembers, MultiXactMember *members)
*/
multi = GetNewMultiXactId(nmembers, &offset);
+ INJECTION_POINT_CACHED("multixact-create-from-members", NULL);
+
/* Make an XLOG entry describing the new MXID. */
xlrec.mid = multi;
xlrec.moff = offset;
@@ -839,8 +876,8 @@ MultiXactIdCreateFromMembers(int nmembers, MultiXactMember *members)
* Not clear that it's worth the trouble though.
*/
XLogBeginInsert();
- XLogRegisterData((char *) (&xlrec), SizeOfMultiXactCreate);
- XLogRegisterData((char *) members, nmembers * sizeof(MultiXactMember));
+ XLogRegisterData(&xlrec, SizeOfMultiXactCreate);
+ XLogRegisterData(members, nmembers * sizeof(MultiXactMember));
(void) XLogInsert(RM_MULTIXACT_ID, XLOG_MULTIXACT_CREATE_ID);
@@ -1240,7 +1277,7 @@ GetNewMultiXactId(int nmembers, MultiXactOffset *offset)
* range, in which case an error would be raised.
*
* In all other cases, the passed multixact must be within the known valid
- * range, that is, greater to or equal than oldestMultiXactId, and less than
+ * range, that is, greater than or equal to oldestMultiXactId, and less than
* nextMXact. Otherwise, an error is raised.
*
* isLockOnly must be set to true if caller is certain that the given multi
@@ -1439,6 +1476,8 @@ GetMultiXactIdMembers(MultiXactId multi, MultiXactMember **members,
LWLockRelease(lock);
CHECK_FOR_INTERRUPTS();
+ INJECTION_POINT("multixact-get-members-cv-sleep", NULL);
+
ConditionVariableSleep(&MultiXactState->nextoff_cv,
WAIT_EVENT_MULTIXACT_CREATION);
slept = true;
@@ -1701,7 +1740,7 @@ mXactCachePut(MultiXactId multi, int nmembers, MultiXactMember *members)
}
}
-static char *
+char *
mxstatus_to_string(MultiXactStatus status)
{
switch (status)
@@ -1798,7 +1837,7 @@ AtPrepare_MultiXact(void)
* Clean up after successful PREPARE TRANSACTION
*/
void
-PostPrepare_MultiXact(TransactionId xid)
+PostPrepare_MultiXact(FullTransactionId fxid)
{
MultiXactId myOldestMember;
@@ -1809,7 +1848,7 @@ PostPrepare_MultiXact(TransactionId xid)
myOldestMember = OldestMemberMXactId[MyProcNumber];
if (MultiXactIdIsValid(myOldestMember))
{
- ProcNumber dummyProcNumber = TwoPhaseGetDummyProcNumber(xid, false);
+ ProcNumber dummyProcNumber = TwoPhaseGetDummyProcNumber(fxid, false);
/*
* Even though storing MultiXactId is atomic, acquire lock to make
@@ -1847,10 +1886,10 @@ PostPrepare_MultiXact(TransactionId xid)
* Recover the state of a prepared transaction at startup
*/
void
-multixact_twophase_recover(TransactionId xid, uint16 info,
+multixact_twophase_recover(FullTransactionId fxid, uint16 info,
void *recdata, uint32 len)
{
- ProcNumber dummyProcNumber = TwoPhaseGetDummyProcNumber(xid, false);
+ ProcNumber dummyProcNumber = TwoPhaseGetDummyProcNumber(fxid, false);
MultiXactId oldestMember;
/*
@@ -1868,10 +1907,10 @@ multixact_twophase_recover(TransactionId xid, uint16 info,
* Similar to AtEOXact_MultiXact but for COMMIT PREPARED
*/
void
-multixact_twophase_postcommit(TransactionId xid, uint16 info,
+multixact_twophase_postcommit(FullTransactionId fxid, uint16 info,
void *recdata, uint32 len)
{
- ProcNumber dummyProcNumber = TwoPhaseGetDummyProcNumber(xid, true);
+ ProcNumber dummyProcNumber = TwoPhaseGetDummyProcNumber(fxid, true);
Assert(len == sizeof(MultiXactId));
@@ -1883,10 +1922,10 @@ multixact_twophase_postcommit(TransactionId xid, uint16 info,
* This is actually just the same as the COMMIT case.
*/
void
-multixact_twophase_postabort(TransactionId xid, uint16 info,
+multixact_twophase_postabort(FullTransactionId fxid, uint16 info,
void *recdata, uint32 len)
{
- multixact_twophase_postcommit(xid, info, recdata, len);
+ multixact_twophase_postcommit(fxid, info, recdata, len);
}
/*
@@ -1968,7 +2007,7 @@ check_multixact_offset_buffers(int *newval, void **extra, GucSource source)
}
/*
- * GUC check_hook for multixact_member_buffer
+ * GUC check_hook for multixact_member_buffers
*/
bool
check_multixact_member_buffers(int *newval, void **extra, GucSource source)
@@ -1984,70 +2023,9 @@ check_multixact_member_buffers(int *newval, void **extra, GucSource source)
void
BootStrapMultiXact(void)
{
- int slotno;
- LWLock *lock;
-
- lock = SimpleLruGetBankLock(MultiXactOffsetCtl, 0);
- LWLockAcquire(lock, LW_EXCLUSIVE);
-
- /* Create and zero the first page of the offsets log */
- slotno = ZeroMultiXactOffsetPage(0, false);
-
- /* Make sure it's written out */
- SimpleLruWritePage(MultiXactOffsetCtl, slotno);
- Assert(!MultiXactOffsetCtl->shared->page_dirty[slotno]);
-
- LWLockRelease(lock);
-
- lock = SimpleLruGetBankLock(MultiXactMemberCtl, 0);
- LWLockAcquire(lock, LW_EXCLUSIVE);
-
- /* Create and zero the first page of the members log */
- slotno = ZeroMultiXactMemberPage(0, false);
-
- /* Make sure it's written out */
- SimpleLruWritePage(MultiXactMemberCtl, slotno);
- Assert(!MultiXactMemberCtl->shared->page_dirty[slotno]);
-
- LWLockRelease(lock);
-}
-
-/*
- * Initialize (or reinitialize) a page of MultiXactOffset to zeroes.
- * If writeXlog is true, also emit an XLOG record saying we did this.
- *
- * The page is not actually written, just set up in shared memory.
- * The slot number of the new page is returned.
- *
- * Control lock must be held at entry, and will be held at exit.
- */
-static int
-ZeroMultiXactOffsetPage(int64 pageno, bool writeXlog)
-{
- int slotno;
-
- slotno = SimpleLruZeroPage(MultiXactOffsetCtl, pageno);
-
- if (writeXlog)
- WriteMZeroPageXlogRec(pageno, XLOG_MULTIXACT_ZERO_OFF_PAGE);
-
- return slotno;
-}
-
-/*
- * Ditto, for MultiXactMember
- */
-static int
-ZeroMultiXactMemberPage(int64 pageno, bool writeXlog)
-{
- int slotno;
-
- slotno = SimpleLruZeroPage(MultiXactMemberCtl, pageno);
-
- if (writeXlog)
- WriteMZeroPageXlogRec(pageno, XLOG_MULTIXACT_ZERO_MEM_PAGE);
-
- return slotno;
+ /* Zero the initial pages and flush them to disk */
+ SimpleLruZeroAndWritePage(MultiXactOffsetCtl, 0);
+ SimpleLruZeroAndWritePage(MultiXactMemberCtl, 0);
}
/*
@@ -2085,7 +2063,7 @@ MaybeExtendOffsetSlru(void)
* with creating a new segment file even if the page we're writing is
* not the first in it, so this is enough.
*/
- slotno = ZeroMultiXactOffsetPage(pageno, false);
+ slotno = SimpleLruZeroPage(MultiXactOffsetCtl, pageno);
SimpleLruWritePage(MultiXactOffsetCtl, slotno);
}
@@ -2519,8 +2497,10 @@ ExtendMultiXactOffset(MultiXactId multi)
LWLockAcquire(lock, LW_EXCLUSIVE);
- /* Zero the page and make an XLOG entry about it */
- ZeroMultiXactOffsetPage(pageno, true);
+ /* Zero the page and make a WAL entry about it */
+ SimpleLruZeroPage(MultiXactOffsetCtl, pageno);
+ XLogSimpleInsertInt64(RM_MULTIXACT_ID, XLOG_MULTIXACT_ZERO_OFF_PAGE,
+ pageno);
LWLockRelease(lock);
}
@@ -2562,8 +2542,10 @@ ExtendMultiXactMember(MultiXactOffset offset, int nmembers)
LWLockAcquire(lock, LW_EXCLUSIVE);
- /* Zero the page and make an XLOG entry about it */
- ZeroMultiXactMemberPage(pageno, true);
+ /* Zero the page and make a WAL entry about it */
+ SimpleLruZeroPage(MultiXactMemberCtl, pageno);
+ XLogSimpleInsertInt64(RM_MULTIXACT_ID,
+ XLOG_MULTIXACT_ZERO_MEM_PAGE, pageno);
LWLockRelease(lock);
}
@@ -2870,31 +2852,43 @@ find_multixact_start(MultiXactId multi, MultiXactOffset *result)
}
/*
- * Determine how many multixacts, and how many multixact members, currently
- * exist. Return false if unable to determine.
+ * GetMultiXactInfo
+ *
+ * Returns information about the current MultiXact state, as of:
+ * multixacts: Number of MultiXacts (nextMultiXactId - oldestMultiXactId)
+ * members: Number of member entries (nextOffset - oldestOffset)
+ * oldestMultiXactId: Oldest MultiXact ID still in use
+ * oldestOffset: Oldest offset still in use
+ *
+ * Returns false if unable to determine, the oldest offset being unknown.
*/
-static bool
-ReadMultiXactCounts(uint32 *multixacts, MultiXactOffset *members)
+bool
+GetMultiXactInfo(uint32 *multixacts, MultiXactOffset *members,
+ MultiXactId *oldestMultiXactId, MultiXactOffset *oldestOffset)
{
MultiXactOffset nextOffset;
- MultiXactOffset oldestOffset;
- MultiXactId oldestMultiXactId;
MultiXactId nextMultiXactId;
bool oldestOffsetKnown;
LWLockAcquire(MultiXactGenLock, LW_SHARED);
nextOffset = MultiXactState->nextOffset;
- oldestMultiXactId = MultiXactState->oldestMultiXactId;
+ *oldestMultiXactId = MultiXactState->oldestMultiXactId;
nextMultiXactId = MultiXactState->nextMXact;
- oldestOffset = MultiXactState->oldestOffset;
+ *oldestOffset = MultiXactState->oldestOffset;
oldestOffsetKnown = MultiXactState->oldestOffsetKnown;
LWLockRelease(MultiXactGenLock);
if (!oldestOffsetKnown)
+ {
+ *members = 0;
+ *multixacts = 0;
+ *oldestMultiXactId = InvalidMultiXactId;
+ *oldestOffset = 0;
return false;
+ }
- *members = nextOffset - oldestOffset;
- *multixacts = nextMultiXactId - oldestMultiXactId;
+ *members = nextOffset - *oldestOffset;
+ *multixacts = nextMultiXactId - *oldestMultiXactId;
return true;
}
@@ -2932,9 +2926,12 @@ MultiXactMemberFreezeThreshold(void)
uint32 multixacts;
uint32 victim_multixacts;
double fraction;
+ int result;
+ MultiXactId oldestMultiXactId;
+ MultiXactOffset oldestOffset;
/* If we can't determine member space utilization, assume the worst. */
- if (!ReadMultiXactCounts(&multixacts, &members))
+ if (!GetMultiXactInfo(&multixacts, &members, &oldestMultiXactId, &oldestOffset))
return 0;
/* If member space utilization is low, no special action is required. */
@@ -2953,7 +2950,13 @@ MultiXactMemberFreezeThreshold(void)
/* fraction could be > 1.0, but lowest possible freeze age is zero */
if (victim_multixacts > multixacts)
return 0;
- return multixacts - victim_multixacts;
+ result = multixacts - victim_multixacts;
+
+ /*
+ * Clamp to autovacuum_multixact_freeze_max_age, so that we never make
+ * autovacuum less aggressive than it would otherwise be.
+ */
+ return Min(result, autovacuum_multixact_freeze_max_age);
}
typedef struct mxtruncinfo
@@ -2991,10 +2994,10 @@ SlruScanDirCbFindEarliest(SlruCtl ctl, char *filename, int64 segpage, void *data
static void
PerformMembersTruncation(MultiXactOffset oldestOffset, MultiXactOffset newOldestOffset)
{
- const int maxsegment = MXOffsetToMemberSegment(MaxMultiXactOffset);
- int startsegment = MXOffsetToMemberSegment(oldestOffset);
- int endsegment = MXOffsetToMemberSegment(newOldestOffset);
- int segment = startsegment;
+ const int64 maxsegment = MXOffsetToMemberSegment(MaxMultiXactOffset);
+ int64 startsegment = MXOffsetToMemberSegment(oldestOffset);
+ int64 endsegment = MXOffsetToMemberSegment(newOldestOffset);
+ int64 segment = startsegment;
/*
* Delete all the segments but the last one. The last segment can still
@@ -3002,7 +3005,8 @@ PerformMembersTruncation(MultiXactOffset oldestOffset, MultiXactOffset newOldest
*/
while (segment != endsegment)
{
- elog(DEBUG2, "truncating multixact members segment %x", segment);
+ elog(DEBUG2, "truncating multixact members segment %" PRIx64,
+ segment);
SlruDeleteSegment(MultiXactMemberCtl, segment);
/* move to next segment, handling wraparound correctly */
@@ -3153,8 +3157,8 @@ TruncateMultiXact(MultiXactId newOldestMulti, Oid newOldestMultiDB)
}
elog(DEBUG1, "performing multixact truncation: "
- "offsets [%u, %u), offsets segments [%x, %x), "
- "members [%u, %u), members segments [%x, %x)",
+ "offsets [%u, %u), offsets segments [%" PRIx64 ", %" PRIx64 "), "
+ "members [%u, %u), members segments [%" PRIx64 ", %" PRIx64 ")",
oldestMulti, newOldestMulti,
MultiXactIdToOffsetSegment(oldestMulti),
MultiXactIdToOffsetSegment(newOldestMulti),
@@ -3290,18 +3294,6 @@ MultiXactOffsetPrecedes(MultiXactOffset offset1, MultiXactOffset offset2)
return (diff < 0);
}
-/*
- * Write an xlog record reflecting the zeroing of either a MEMBERs or
- * OFFSETs page (info shows which)
- */
-static void
-WriteMZeroPageXlogRec(int64 pageno, uint8 info)
-{
- XLogBeginInsert();
- XLogRegisterData((char *) (&pageno), sizeof(pageno));
- (void) XLogInsert(RM_MULTIXACT_ID, info);
-}
-
/*
* Write a TRUNCATE xlog record
*
@@ -3325,7 +3317,7 @@ WriteMTruncateXlogRec(Oid oldestMultiDB,
xlrec.endTruncMemb = endTruncMemb;
XLogBeginInsert();
- XLogRegisterData((char *) (&xlrec), SizeOfMultiXactTruncate);
+ XLogRegisterData(&xlrec, SizeOfMultiXactTruncate);
recptr = XLogInsert(RM_MULTIXACT_ID, XLOG_MULTIXACT_TRUNCATE_ID);
XLogFlush(recptr);
}
@@ -3344,36 +3336,16 @@ multixact_redo(XLogReaderState *record)
if (info == XLOG_MULTIXACT_ZERO_OFF_PAGE)
{
int64 pageno;
- int slotno;
- LWLock *lock;
memcpy(&pageno, XLogRecGetData(record), sizeof(pageno));
-
- lock = SimpleLruGetBankLock(MultiXactOffsetCtl, pageno);
- LWLockAcquire(lock, LW_EXCLUSIVE);
-
- slotno = ZeroMultiXactOffsetPage(pageno, false);
- SimpleLruWritePage(MultiXactOffsetCtl, slotno);
- Assert(!MultiXactOffsetCtl->shared->page_dirty[slotno]);
-
- LWLockRelease(lock);
+ SimpleLruZeroAndWritePage(MultiXactOffsetCtl, pageno);
}
else if (info == XLOG_MULTIXACT_ZERO_MEM_PAGE)
{
int64 pageno;
- int slotno;
- LWLock *lock;
memcpy(&pageno, XLogRecGetData(record), sizeof(pageno));
-
- lock = SimpleLruGetBankLock(MultiXactMemberCtl, pageno);
- LWLockAcquire(lock, LW_EXCLUSIVE);
-
- slotno = ZeroMultiXactMemberPage(pageno, false);
- SimpleLruWritePage(MultiXactMemberCtl, slotno);
- Assert(!MultiXactMemberCtl->shared->page_dirty[slotno]);
-
- LWLockRelease(lock);
+ SimpleLruZeroAndWritePage(MultiXactMemberCtl, pageno);
}
else if (info == XLOG_MULTIXACT_CREATE_ID)
{
@@ -3413,8 +3385,8 @@ multixact_redo(XLogReaderState *record)
SizeOfMultiXactTruncate);
elog(DEBUG1, "replaying multixact truncation: "
- "offsets [%u, %u), offsets segments [%x, %x), "
- "members [%u, %u), members segments [%x, %x)",
+ "offsets [%u, %u), offsets segments [%" PRIx64 ", %" PRIx64 "), "
+ "members [%u, %u), members segments [%" PRIx64 ", %" PRIx64 ")",
xlrec.startTruncOff, xlrec.endTruncOff,
MultiXactIdToOffsetSegment(xlrec.startTruncOff),
MultiXactIdToOffsetSegment(xlrec.endTruncOff),
@@ -3449,68 +3421,6 @@ multixact_redo(XLogReaderState *record)
elog(PANIC, "multixact_redo: unknown op code %u", info);
}
-Datum
-pg_get_multixact_members(PG_FUNCTION_ARGS)
-{
- typedef struct
- {
- MultiXactMember *members;
- int nmembers;
- int iter;
- } mxact;
- MultiXactId mxid = PG_GETARG_TRANSACTIONID(0);
- mxact *multi;
- FuncCallContext *funccxt;
-
- if (mxid < FirstMultiXactId)
- ereport(ERROR,
- (errcode(ERRCODE_INVALID_PARAMETER_VALUE),
- errmsg("invalid MultiXactId: %u", mxid)));
-
- if (SRF_IS_FIRSTCALL())
- {
- MemoryContext oldcxt;
- TupleDesc tupdesc;
-
- funccxt = SRF_FIRSTCALL_INIT();
- oldcxt = MemoryContextSwitchTo(funccxt->multi_call_memory_ctx);
-
- multi = palloc(sizeof(mxact));
- /* no need to allow for old values here */
- multi->nmembers = GetMultiXactIdMembers(mxid, &multi->members, false,
- false);
- multi->iter = 0;
-
- if (get_call_result_type(fcinfo, NULL, &tupdesc) != TYPEFUNC_COMPOSITE)
- elog(ERROR, "return type must be a row type");
- funccxt->tuple_desc = tupdesc;
- funccxt->attinmeta = TupleDescGetAttInMetadata(tupdesc);
- funccxt->user_fctx = multi;
-
- MemoryContextSwitchTo(oldcxt);
- }
-
- funccxt = SRF_PERCALL_SETUP();
- multi = (mxact *) funccxt->user_fctx;
-
- while (multi->iter < multi->nmembers)
- {
- HeapTuple tuple;
- char *values[2];
-
- values[0] = psprintf("%u", multi->members[multi->iter].xid);
- values[1] = mxstatus_to_string(multi->members[multi->iter].status);
-
- tuple = BuildTupleFromCStrings(funccxt->attinmeta, values);
-
- multi->iter++;
- pfree(values[0]);
- SRF_RETURN_NEXT(funccxt, HeapTupleGetDatum(tuple));
- }
-
- SRF_RETURN_DONE(funccxt);
-}
-
/*
* Entrypoint for sync.c to sync offsets files.
*/
diff --git a/src/backend/access/transam/parallel.c b/src/backend/access/transam/parallel.c
index 8613fc6fb547c..94db1ec30126a 100644
--- a/src/backend/access/transam/parallel.c
+++ b/src/backend/access/transam/parallel.c
@@ -3,7 +3,7 @@
* parallel.c
* Infrastructure for launching parallel workers
*
- * Portions Copyright (c) 1996-2024, PostgreSQL Global Development Group
+ * Portions Copyright (c) 1996-2025, PostgreSQL Global Development Group
* Portions Copyright (c) 1994, Regents of the University of California
*
* IDENTIFICATION
@@ -15,6 +15,7 @@
#include "postgres.h"
#include "access/brin.h"
+#include "access/gin.h"
#include "access/nbtree.h"
#include "access/parallel.h"
#include "access/session.h"
@@ -83,12 +84,14 @@ typedef struct FixedParallelState
/* Fixed-size state that workers must restore. */
Oid database_id;
Oid authenticated_user_id;
- Oid current_user_id;
+ Oid session_user_id;
Oid outer_user_id;
+ Oid current_user_id;
Oid temp_namespace_id;
Oid temp_toast_namespace_id;
int sec_context;
- bool is_superuser;
+ bool session_user_is_superuser;
+ bool role_is_superuser;
PGPROC *parallel_leader_pgproc;
pid_t parallel_leader_pid;
ProcNumber parallel_leader_proc_number;
@@ -146,13 +149,16 @@ static const struct
{
"_brin_parallel_build_main", _brin_parallel_build_main
},
+ {
+ "_gin_parallel_build_main", _gin_parallel_build_main
+ },
{
"parallel_vacuum_main", parallel_vacuum_main
}
};
/* Private functions. */
-static void HandleParallelMessage(ParallelContext *pcxt, int i, StringInfo msg);
+static void ProcessParallelMessage(ParallelContext *pcxt, int i, StringInfo msg);
static void WaitForParallelWorkersToExit(ParallelContext *pcxt);
static parallel_worker_main_type LookupParallelWorkerFunction(const char *libraryname, const char *funcname);
static void ParallelWorkerShutdown(int code, Datum arg);
@@ -230,6 +236,15 @@ InitializeParallelDSM(ParallelContext *pcxt)
shm_toc_estimate_chunk(&pcxt->estimator, sizeof(FixedParallelState));
shm_toc_estimate_keys(&pcxt->estimator, 1);
+ /*
+ * If we manage to reach here while non-interruptible, it's unsafe to
+ * launch any workers: we would fail to process interrupts sent by them.
+ * We can deal with that edge case by pretending no workers were
+ * requested.
+ */
+ if (!INTERRUPTS_CAN_BE_PROCESSED())
+ pcxt->nworkers = 0;
+
/*
* Normally, the user will have requested at least one worker process, but
* if by chance they have not, we can skip a bunch of things here.
@@ -327,9 +342,11 @@ InitializeParallelDSM(ParallelContext *pcxt)
shm_toc_allocate(pcxt->toc, sizeof(FixedParallelState));
fps->database_id = MyDatabaseId;
fps->authenticated_user_id = GetAuthenticatedUserId();
+ fps->session_user_id = GetSessionUserId();
fps->outer_user_id = GetCurrentRoleId();
- fps->is_superuser = current_role_is_superuser;
GetUserIdAndSecContext(&fps->current_user_id, &fps->sec_context);
+ fps->session_user_is_superuser = GetSessionUserIsSuperuser();
+ fps->role_is_superuser = current_role_is_superuser;
GetTempNamespaceState(&fps->temp_namespace_id,
&fps->temp_toast_namespace_id);
fps->parallel_leader_pgproc = MyProc;
@@ -476,6 +493,9 @@ InitializeParallelDSM(ParallelContext *pcxt)
shm_toc_insert(pcxt->toc, PARALLEL_KEY_ENTRYPOINT, entrypointstate);
}
+ /* Update nworkers_to_launch, in case we changed nworkers above. */
+ pcxt->nworkers_to_launch = pcxt->nworkers;
+
/* Restore previous memory context. */
MemoryContextSwitchTo(oldcontext);
}
@@ -539,10 +559,11 @@ ReinitializeParallelWorkers(ParallelContext *pcxt, int nworkers_to_launch)
{
/*
* The number of workers that need to be launched must be less than the
- * number of workers with which the parallel context is initialized.
+ * number of workers with which the parallel context is initialized. But
+ * the caller might not know that InitializeParallelDSM reduced nworkers,
+ * so just silently trim the request.
*/
- Assert(pcxt->nworkers >= nworkers_to_launch);
- pcxt->nworkers_to_launch = nworkers_to_launch;
+ pcxt->nworkers_to_launch = Min(pcxt->nworkers, nworkers_to_launch);
}
/*
@@ -1010,7 +1031,7 @@ ParallelContextActive(void)
*
* Note: this is called within a signal handler! All we can do is set
* a flag that will cause the next CHECK_FOR_INTERRUPTS() to invoke
- * HandleParallelMessages().
+ * ProcessParallelMessages().
*/
void
HandleParallelMessageInterrupt(void)
@@ -1021,10 +1042,10 @@ HandleParallelMessageInterrupt(void)
}
/*
- * Handle any queued protocol messages received from parallel workers.
+ * Process any queued protocol messages received from parallel workers.
*/
void
-HandleParallelMessages(void)
+ProcessParallelMessages(void)
{
dlist_iter iter;
MemoryContext oldcontext;
@@ -1047,7 +1068,7 @@ HandleParallelMessages(void)
*/
if (hpm_context == NULL) /* first time through? */
hpm_context = AllocSetContextCreate(TopMemoryContext,
- "HandleParallelMessages",
+ "ProcessParallelMessages",
ALLOCSET_DEFAULT_SIZES);
else
MemoryContextReset(hpm_context);
@@ -1090,7 +1111,7 @@ HandleParallelMessages(void)
initStringInfo(&msg);
appendBinaryStringInfo(&msg, data, nbytes);
- HandleParallelMessage(pcxt, i, &msg);
+ ProcessParallelMessage(pcxt, i, &msg);
pfree(msg.data);
}
else
@@ -1110,10 +1131,10 @@ HandleParallelMessages(void)
}
/*
- * Handle a single protocol message received from a single parallel worker.
+ * Process a single protocol message received from a single parallel worker.
*/
static void
-HandleParallelMessage(ParallelContext *pcxt, int i, StringInfo msg)
+ProcessParallelMessage(ParallelContext *pcxt, int i, StringInfo msg)
{
char msgtype;
@@ -1191,7 +1212,7 @@ HandleParallelMessage(ParallelContext *pcxt, int i, StringInfo msg)
break;
}
- case 'P': /* Parallel progress reporting */
+ case PqMsg_Progress:
{
/*
* Only incremental progress reporting is currently supported.
@@ -1391,16 +1412,37 @@ ParallelWorkerMain(Datum main_arg)
entrypt = LookupParallelWorkerFunction(library_name, function_name);
- /* Restore database connection. */
+ /*
+ * Restore current session authorization and role id. No verification
+ * happens here, we just blindly adopt the leader's state. Note that this
+ * has to happen before InitPostgres, since InitializeSessionUserId will
+ * not set these variables.
+ */
+ SetAuthenticatedUserId(fps->authenticated_user_id);
+ SetSessionAuthorization(fps->session_user_id,
+ fps->session_user_is_superuser);
+ SetCurrentRoleId(fps->outer_user_id, fps->role_is_superuser);
+
+ /*
+ * Restore database connection. We skip connection authorization checks,
+ * reasoning that (a) the leader checked these things when it started, and
+ * (b) we do not want parallel mode to cause these failures, because that
+ * would make use of parallel query plans not transparent to applications.
+ */
BackgroundWorkerInitializeConnectionByOid(fps->database_id,
fps->authenticated_user_id,
- 0);
+ BGWORKER_BYPASS_ALLOWCONN |
+ BGWORKER_BYPASS_ROLELOGINCHECK);
/*
* Set the client encoding to the database encoding, since that is what
- * the leader will expect.
+ * the leader will expect. (We're cheating a bit by not calling
+ * PrepareClientEncoding first. It's okay because this call will always
+ * result in installing a no-op conversion. No error should be possible,
+ * but check anyway.)
*/
- SetClientEncoding(GetDatabaseEncoding());
+ if (SetClientEncoding(GetDatabaseEncoding()) < 0)
+ elog(ERROR, "SetClientEncoding(%d) failed", GetDatabaseEncoding());
/*
* Load libraries that were loaded by original backend. We want to do
@@ -1410,17 +1452,25 @@ ParallelWorkerMain(Datum main_arg)
libraryspace = shm_toc_lookup(toc, PARALLEL_KEY_LIBRARY, false);
StartTransactionCommand();
RestoreLibraryState(libraryspace);
-
- /* Restore GUC values from launching backend. */
- gucspace = shm_toc_lookup(toc, PARALLEL_KEY_GUC, false);
- RestoreGUCState(gucspace);
CommitTransactionCommand();
/* Crank up a transaction state appropriate to a parallel worker. */
tstatespace = shm_toc_lookup(toc, PARALLEL_KEY_TRANSACTION_STATE, false);
StartParallelWorkerTransaction(tstatespace);
- /* Restore combo CID state. */
+ /*
+ * Restore state that affects catalog access. Ideally we'd do this even
+ * before calling InitPostgres, but that has order-of-initialization
+ * problems, and also the relmapper would get confused during the
+ * CommitTransactionCommand call above.
+ */
+ pendingsyncsspace = shm_toc_lookup(toc, PARALLEL_KEY_PENDING_SYNCS,
+ false);
+ RestorePendingSyncs(pendingsyncsspace);
+ relmapperspace = shm_toc_lookup(toc, PARALLEL_KEY_RELMAPPER_STATE, false);
+ RestoreRelationMap(relmapperspace);
+ reindexspace = shm_toc_lookup(toc, PARALLEL_KEY_REINDEX_STATE, false);
+ RestoreReindexState(reindexspace);
combocidspace = shm_toc_lookup(toc, PARALLEL_KEY_COMBO_CID, false);
RestoreComboCIDState(combocidspace);
@@ -1456,32 +1506,29 @@ ParallelWorkerMain(Datum main_arg)
InvalidateSystemCaches();
/*
- * Restore current role id. Skip verifying whether session user is
- * allowed to become this role and blindly restore the leader's state for
- * current role.
+ * Restore GUC values from launching backend. We can't do this earlier,
+ * because GUC check hooks that do catalog lookups need to see the same
+ * database state as the leader. Also, the check hooks for
+ * session_authorization and role assume we already set the correct role
+ * OIDs.
*/
- SetCurrentRoleId(fps->outer_user_id, fps->is_superuser);
+ gucspace = shm_toc_lookup(toc, PARALLEL_KEY_GUC, false);
+ RestoreGUCState(gucspace);
- /* Restore user ID and security context. */
+ /*
+ * Restore current user ID and security context. No verification happens
+ * here, we just blindly adopt the leader's state. We can't do this till
+ * after restoring GUCs, else we'll get complaints about restoring
+ * session_authorization and role. (In effect, we're assuming that all
+ * the restored values are okay to set, even if we are now inside a
+ * restricted context.)
+ */
SetUserIdAndSecContext(fps->current_user_id, fps->sec_context);
/* Restore temp-namespace state to ensure search path matches leader's. */
SetTempNamespaceState(fps->temp_namespace_id,
fps->temp_toast_namespace_id);
- /* Restore pending syncs. */
- pendingsyncsspace = shm_toc_lookup(toc, PARALLEL_KEY_PENDING_SYNCS,
- false);
- RestorePendingSyncs(pendingsyncsspace);
-
- /* Restore reindex state. */
- reindexspace = shm_toc_lookup(toc, PARALLEL_KEY_REINDEX_STATE, false);
- RestoreReindexState(reindexspace);
-
- /* Restore relmapper state. */
- relmapperspace = shm_toc_lookup(toc, PARALLEL_KEY_RELMAPPER_STATE, false);
- RestoreRelationMap(relmapperspace);
-
/* Restore uncommitted enums. */
uncommittedenumsspace = shm_toc_lookup(toc, PARALLEL_KEY_UNCOMMITTEDENUMS,
false);
diff --git a/src/backend/access/transam/slru.c b/src/backend/access/transam/slru.c
index 77b05cc0a746d..5d3fcd62c9443 100644
--- a/src/backend/access/transam/slru.c
+++ b/src/backend/access/transam/slru.c
@@ -49,7 +49,7 @@
* by re-setting the page's page_dirty flag.
*
*
- * Portions Copyright (c) 1996-2024, PostgreSQL Global Development Group
+ * Portions Copyright (c) 1996-2025, PostgreSQL Global Development Group
* Portions Copyright (c) 1994, Regents of the University of California
*
* src/backend/access/transam/slru.c
@@ -70,8 +70,23 @@
#include "pgstat.h"
#include "storage/fd.h"
#include "storage/shmem.h"
-#include "utils/guc_hooks.h"
+#include "utils/guc.h"
+/*
+ * Converts segment number to the filename of the segment.
+ *
+ * "path" should point to a buffer at least MAXPGPATH characters long.
+ *
+ * If ctl->long_segment_names is true, segno can be in the range [0, 2^60-1].
+ * The resulting file name is made of 15 characters, e.g. dir/123456789ABCDEF.
+ *
+ * If ctl->long_segment_names is false, segno can be in the range [0, 2^24-1].
+ * The resulting file name is made of 4 to 6 characters, as of:
+ *
+ * dir/1234 for [0, 2^16-1]
+ * dir/12345 for [2^16, 2^20-1]
+ * dir/123456 for [2^20, 2^24-1]
+ */
static inline int
SlruFileName(SlruCtl ctl, char *path, int64 segno)
{
@@ -85,8 +100,7 @@ SlruFileName(SlruCtl ctl, char *path, int64 segno)
* that in the future we can't decrease SLRU_PAGES_PER_SEGMENT easily.
*/
Assert(segno >= 0 && segno <= INT64CONST(0xFFFFFFFFFFFFFFF));
- return snprintf(path, MAXPGPATH, "%s/%015llX", ctl->Dir,
- (long long) segno);
+ return snprintf(path, MAXPGPATH, "%s/%015" PRIX64, ctl->Dir, segno);
}
else
{
@@ -232,6 +246,7 @@ SimpleLruAutotuneBuffers(int divisor, int max)
* buffer_tranche_id: tranche ID to use for the SLRU's per-buffer LWLocks.
* bank_tranche_id: tranche ID to use for the bank LWLocks.
* sync_handler: which set of functions to use to handle sync requests
+ * long_segment_names: use short or long segment names
*/
void
SimpleLruInit(SlruCtl ctl, const char *name, int nslots, int nlsns,
@@ -328,7 +343,7 @@ SimpleLruInit(SlruCtl ctl, const char *name, int nslots, int nlsns,
ctl->shared = shared;
ctl->sync_handler = sync_handler;
ctl->long_segment_names = long_segment_names;
- ctl->bank_mask = (nslots / SLRU_BANK_SIZE) - 1;
+ ctl->nbanks = nbanks;
strlcpy(ctl->Dir, subdir, sizeof(ctl->Dir));
}
@@ -343,7 +358,7 @@ check_slru_buffers(const char *name, int *newval)
if (*newval % SLRU_BANK_SIZE == 0)
return true;
- GUC_check_errdetail("\"%s\" must be a multiple of %d", name,
+ GUC_check_errdetail("\"%s\" must be a multiple of %d.", name,
SLRU_BANK_SIZE);
return false;
}
@@ -386,15 +401,15 @@ SimpleLruZeroPage(SlruCtl ctl, int64 pageno)
/*
* Assume this page is now the latest active page.
*
- * Note that because both this routine and SlruSelectLRUPage run with
- * ControlLock held, it is not possible for this to be zeroing a page that
- * SlruSelectLRUPage is going to evict simultaneously. Therefore, there's
- * no memory barrier here.
+ * Note that because both this routine and SlruSelectLRUPage run with a
+ * SLRU bank lock held, it is not possible for this to be zeroing a page
+ * that SlruSelectLRUPage is going to evict simultaneously. Therefore,
+ * there's no memory barrier here.
*/
pg_atomic_write_u64(&shared->latest_page_number, pageno);
/* update the stats counter of zeroed pages */
- pgstat_count_slru_page_zeroed(shared->slru_stats_idx);
+ pgstat_count_slru_blocks_zeroed(shared->slru_stats_idx);
return slotno;
}
@@ -419,6 +434,31 @@ SimpleLruZeroLSNs(SlruCtl ctl, int slotno)
shared->lsn_groups_per_page * sizeof(XLogRecPtr));
}
+/*
+ * This is a convenience wrapper for the common case of zeroing a page and
+ * immediately flushing it to disk.
+ *
+ * SLRU bank lock is acquired and released here.
+ */
+void
+SimpleLruZeroAndWritePage(SlruCtl ctl, int64 pageno)
+{
+ int slotno;
+ LWLock *lock;
+
+ lock = SimpleLruGetBankLock(ctl, pageno);
+ LWLockAcquire(lock, LW_EXCLUSIVE);
+
+ /* Create and zero the page */
+ slotno = SimpleLruZeroPage(ctl, pageno);
+
+ /* Make sure it's written out */
+ SimpleLruWritePage(ctl, slotno);
+ Assert(!ctl->shared->page_dirty[slotno]);
+
+ LWLockRelease(lock);
+}
+
/*
* Wait for any active I/O on a page slot to finish. (This does not
* guarantee that new I/O hasn't been started before we return, though.
@@ -521,7 +561,7 @@ SimpleLruReadPage(SlruCtl ctl, int64 pageno, bool write_ok,
SlruRecentlyUsed(shared, slotno);
/* update the stats counter of pages found in the SLRU */
- pgstat_count_slru_page_hit(shared->slru_stats_idx);
+ pgstat_count_slru_blocks_hit(shared->slru_stats_idx);
return slotno;
}
@@ -566,7 +606,7 @@ SimpleLruReadPage(SlruCtl ctl, int64 pageno, bool write_ok,
SlruRecentlyUsed(shared, slotno);
/* update the stats counter of pages not found in SLRU */
- pgstat_count_slru_page_read(shared->slru_stats_idx);
+ pgstat_count_slru_blocks_read(shared->slru_stats_idx);
return slotno;
}
@@ -591,7 +631,7 @@ SimpleLruReadPage_ReadOnly(SlruCtl ctl, int64 pageno, TransactionId xid)
{
SlruShared shared = ctl->shared;
LWLock *banklock = SimpleLruGetBankLock(ctl, pageno);
- int bankno = pageno & ctl->bank_mask;
+ int bankno = pageno % ctl->nbanks;
int bankstart = bankno * SLRU_BANK_SIZE;
int bankend = bankstart + SLRU_BANK_SIZE;
@@ -605,11 +645,11 @@ SimpleLruReadPage_ReadOnly(SlruCtl ctl, int64 pageno, TransactionId xid)
shared->page_number[slotno] == pageno &&
shared->page_status[slotno] != SLRU_PAGE_READ_IN_PROGRESS)
{
- /* See comments for SlruRecentlyUsed macro */
+ /* See comments for SlruRecentlyUsed() */
SlruRecentlyUsed(shared, slotno);
/* update the stats counter of pages found in the SLRU */
- pgstat_count_slru_page_hit(shared->slru_stats_idx);
+ pgstat_count_slru_blocks_hit(shared->slru_stats_idx);
return slotno;
}
@@ -701,9 +741,12 @@ SlruInternalWritePage(SlruCtl ctl, int slotno, SlruWriteAll fdata)
if (!ok)
SlruReportIOError(ctl, pageno, InvalidTransactionId);
- /* If part of a checkpoint, count this as a buffer written. */
+ /* If part of a checkpoint, count this as a SLRU buffer written. */
if (fdata)
- CheckpointStats.ckpt_bufs_written++;
+ {
+ CheckpointStats.ckpt_slru_written++;
+ PendingCheckpointerStats.slru_written++;
+ }
}
/*
@@ -736,7 +779,7 @@ SimpleLruDoesPhysicalPageExist(SlruCtl ctl, int64 pageno)
off_t endpos;
/* update the stats counter of checked pages */
- pgstat_count_slru_page_exists(ctl->shared->slru_stats_idx);
+ pgstat_count_slru_blocks_exists(ctl->shared->slru_stats_idx);
SlruFileName(ctl, path, segno);
@@ -865,7 +908,7 @@ SlruPhysicalWritePage(SlruCtl ctl, int64 pageno, int slotno, SlruWriteAll fdata)
int fd = -1;
/* update the stats counter of written pages */
- pgstat_count_slru_page_written(shared->slru_stats_idx);
+ pgstat_count_slru_blocks_written(shared->slru_stats_idx);
/*
* Honor the write-WAL-before-data rule, if appropriate, so that we do not
@@ -1162,14 +1205,14 @@ SlruSelectLRUPage(SlruCtl ctl, int64 pageno)
int bestinvalidslot = 0; /* keep compiler quiet */
int best_invalid_delta = -1;
int64 best_invalid_page_number = 0; /* keep compiler quiet */
- int bankno = pageno & ctl->bank_mask;
+ int bankno = pageno % ctl->nbanks;
int bankstart = bankno * SLRU_BANK_SIZE;
int bankend = bankstart + SLRU_BANK_SIZE;
Assert(LWLockHeldByMe(SimpleLruGetBankLock(ctl, pageno)));
/* See if page already has a buffer assigned */
- for (int slotno = 0; slotno < shared->num_slots; slotno++)
+ for (int slotno = bankstart; slotno < bankend; slotno++)
{
if (shared->page_status[slotno] != SLRU_PAGE_EMPTY &&
shared->page_number[slotno] == pageno)
@@ -1517,7 +1560,7 @@ SlruDeleteSegment(SlruCtl ctl, int64 segno)
did_write = false;
for (int slotno = 0; slotno < shared->num_slots; slotno++)
{
- int pagesegno;
+ int64 pagesegno;
int curbank = SlotGetBankNumber(slotno);
/*
diff --git a/src/backend/access/transam/subtrans.c b/src/backend/access/transam/subtrans.c
index 50bb1d8cfc5f0..09aace9e09f0e 100644
--- a/src/backend/access/transam/subtrans.c
+++ b/src/backend/access/transam/subtrans.c
@@ -19,7 +19,7 @@
* data across crashes. During database startup, we simply force the
* currently-active page of SUBTRANS to zeroes.
*
- * Portions Copyright (c) 1996-2024, PostgreSQL Global Development Group
+ * Portions Copyright (c) 1996-2025, PostgreSQL Global Development Group
* Portions Copyright (c) 1994, Regents of the University of California
*
* src/backend/access/transam/subtrans.c
@@ -74,7 +74,6 @@ static SlruCtlData SubTransCtlData;
#define SubTransCtl (&SubTransCtlData)
-static int ZeroSUBTRANSPage(int64 pageno);
static bool SubTransPagePrecedes(int64 page1, int64 page2);
@@ -269,33 +268,8 @@ check_subtrans_buffers(int *newval, void **extra, GucSource source)
void
BootStrapSUBTRANS(void)
{
- int slotno;
- LWLock *lock = SimpleLruGetBankLock(SubTransCtl, 0);
-
- LWLockAcquire(lock, LW_EXCLUSIVE);
-
- /* Create and zero the first page of the subtrans log */
- slotno = ZeroSUBTRANSPage(0);
-
- /* Make sure it's written out */
- SimpleLruWritePage(SubTransCtl, slotno);
- Assert(!SubTransCtl->shared->page_dirty[slotno]);
-
- LWLockRelease(lock);
-}
-
-/*
- * Initialize (or reinitialize) a page of SUBTRANS to zeroes.
- *
- * The page is not actually written, just set up in shared memory.
- * The slot number of the new page is returned.
- *
- * Control lock must be held at entry, and will be held at exit.
- */
-static int
-ZeroSUBTRANSPage(int64 pageno)
-{
- return SimpleLruZeroPage(SubTransCtl, pageno);
+ /* Zero the initial page and flush it to disk */
+ SimpleLruZeroAndWritePage(SubTransCtl, 0);
}
/*
@@ -335,7 +309,7 @@ StartupSUBTRANS(TransactionId oldestActiveXID)
prevlock = lock;
}
- (void) ZeroSUBTRANSPage(startPage);
+ (void) SimpleLruZeroPage(SubTransCtl, startPage);
if (startPage == endPage)
break;
@@ -395,7 +369,7 @@ ExtendSUBTRANS(TransactionId newestXact)
LWLockAcquire(lock, LW_EXCLUSIVE);
/* Zero the page */
- ZeroSUBTRANSPage(pageno);
+ SimpleLruZeroPage(SubTransCtl, pageno);
LWLockRelease(lock);
}
diff --git a/src/backend/access/transam/timeline.c b/src/backend/access/transam/timeline.c
index 146751ae37526..186eb91f60943 100644
--- a/src/backend/access/transam/timeline.c
+++ b/src/backend/access/transam/timeline.c
@@ -21,7 +21,7 @@
* The fields are separated by tabs. Lines beginning with # are comments, and
* are ignored. Empty lines are also ignored.
*
- * Portions Copyright (c) 1996-2024, PostgreSQL Global Development Group
+ * Portions Copyright (c) 1996-2025, PostgreSQL Global Development Group
* Portions Copyright (c) 1994, Regents of the University of California
*
* src/backend/access/transam/timeline.c
@@ -154,7 +154,7 @@ readTimeLineHistory(TimeLineID targetTLI)
if (*ptr == '\0' || *ptr == '#')
continue;
- nfields = sscanf(fline, "%u\t%X/%X", &tli, &switchpoint_hi, &switchpoint_lo);
+ nfields = sscanf(fline, "%u\t%X/%08X", &tli, &switchpoint_hi, &switchpoint_lo);
if (nfields < 1)
{
@@ -399,7 +399,7 @@ writeTimeLineHistory(TimeLineID newTLI, TimeLineID parentTLI,
* parent file failed to end with one.
*/
snprintf(buffer, sizeof(buffer),
- "%s%u\t%X/%X\t%s\n",
+ "%s%u\t%X/%08X\t%s\n",
(srcfd < 0) ? "" : "\n",
parentTLI,
LSN_FORMAT_ARGS(switchpoint),
diff --git a/src/backend/access/transam/transam.c b/src/backend/access/transam/transam.c
index 75b5325df8b28..9a39451a29a96 100644
--- a/src/backend/access/transam/transam.c
+++ b/src/backend/access/transam/transam.c
@@ -3,7 +3,7 @@
* transam.c
* postgres transaction (commit) log interface routines
*
- * Portions Copyright (c) 1996-2024, PostgreSQL Global Development Group
+ * Portions Copyright (c) 1996-2025, PostgreSQL Global Development Group
* Portions Copyright (c) 1994, Regents of the University of California
*
*
diff --git a/src/backend/access/transam/twophase.c b/src/backend/access/transam/twophase.c
index bf451d42ffb5d..d8e2fce2c99b7 100644
--- a/src/backend/access/transam/twophase.c
+++ b/src/backend/access/transam/twophase.c
@@ -3,7 +3,7 @@
* twophase.c
* Two-phase commit support functions.
*
- * Portions Copyright (c) 1996-2024, PostgreSQL Global Development Group
+ * Portions Copyright (c) 1996-2025, PostgreSQL Global Development Group
* Portions Copyright (c) 1994, Regents of the University of California
*
* IDENTIFICATION
@@ -103,6 +103,7 @@
#include "storage/proc.h"
#include "storage/procarray.h"
#include "utils/builtins.h"
+#include "utils/injection_point.h"
#include "utils/memutils.h"
#include "utils/timestamp.h"
@@ -159,7 +160,7 @@ typedef struct GlobalTransactionData
*/
XLogRecPtr prepare_start_lsn; /* XLOG offset of prepare record start */
XLogRecPtr prepare_end_lsn; /* XLOG offset of prepare record end */
- TransactionId xid; /* The GXACT id */
+ FullTransactionId fxid; /* The GXACT full xid */
Oid owner; /* ID of user that executed the xact */
ProcNumber locking_backend; /* backend currently working on the xact */
@@ -197,6 +198,7 @@ static GlobalTransaction MyLockedGxact = NULL;
static bool twophaseExitRegistered = false;
+static void PrepareRedoRemoveFull(FullTransactionId fxid, bool giveWarning);
static void RecordTransactionCommitPrepared(TransactionId xid,
int nchildren,
TransactionId *children,
@@ -216,19 +218,19 @@ static void RecordTransactionAbortPrepared(TransactionId xid,
int nstats,
xl_xact_stats_item *stats,
const char *gid);
-static void ProcessRecords(char *bufptr, TransactionId xid,
+static void ProcessRecords(char *bufptr, FullTransactionId fxid,
const TwoPhaseCallback callbacks[]);
static void RemoveGXact(GlobalTransaction gxact);
static void XlogReadTwoPhaseData(XLogRecPtr lsn, char **buf, int *len);
-static char *ProcessTwoPhaseBuffer(TransactionId xid,
+static char *ProcessTwoPhaseBuffer(FullTransactionId fxid,
XLogRecPtr prepare_start_lsn,
bool fromdisk, bool setParent, bool setNextXid);
-static void MarkAsPreparingGuts(GlobalTransaction gxact, TransactionId xid,
+static void MarkAsPreparingGuts(GlobalTransaction gxact, FullTransactionId fxid,
const char *gid, TimestampTz prepared_at, Oid owner,
Oid databaseid);
-static void RemoveTwoPhaseFile(TransactionId xid, bool giveWarning);
-static void RecreateTwoPhaseFile(TransactionId xid, void *content, int len);
+static void RemoveTwoPhaseFile(FullTransactionId fxid, bool giveWarning);
+static void RecreateTwoPhaseFile(FullTransactionId fxid, void *content, int len);
/*
* Initialization of shared memory
@@ -356,7 +358,7 @@ PostPrepare_Twophase(void)
* Reserve the GID for the given transaction.
*/
GlobalTransaction
-MarkAsPreparing(TransactionId xid, const char *gid,
+MarkAsPreparing(FullTransactionId fxid, const char *gid,
TimestampTz prepared_at, Oid owner, Oid databaseid)
{
GlobalTransaction gxact;
@@ -407,7 +409,7 @@ MarkAsPreparing(TransactionId xid, const char *gid,
gxact = TwoPhaseState->freeGXacts;
TwoPhaseState->freeGXacts = gxact->next;
- MarkAsPreparingGuts(gxact, xid, gid, prepared_at, owner, databaseid);
+ MarkAsPreparingGuts(gxact, fxid, gid, prepared_at, owner, databaseid);
gxact->ondisk = false;
@@ -430,11 +432,13 @@ MarkAsPreparing(TransactionId xid, const char *gid,
* Note: This function should be called with appropriate locks held.
*/
static void
-MarkAsPreparingGuts(GlobalTransaction gxact, TransactionId xid, const char *gid,
- TimestampTz prepared_at, Oid owner, Oid databaseid)
+MarkAsPreparingGuts(GlobalTransaction gxact, FullTransactionId fxid,
+ const char *gid, TimestampTz prepared_at, Oid owner,
+ Oid databaseid)
{
PGPROC *proc;
int i;
+ TransactionId xid = XidFromFullTransactionId(fxid);
Assert(LWLockHeldByMeInMode(TwoPhaseStateLock, LW_EXCLUSIVE));
@@ -466,7 +470,7 @@ MarkAsPreparingGuts(GlobalTransaction gxact, TransactionId xid, const char *gid,
proc->databaseId = databaseid;
proc->roleId = owner;
proc->tempNamespaceId = InvalidOid;
- proc->isBackgroundWorker = false;
+ proc->isRegularBackend = false;
proc->lwWaiting = LW_WS_NOT_WAITING;
proc->lwWaitMode = 0;
proc->waitLock = NULL;
@@ -479,7 +483,7 @@ MarkAsPreparingGuts(GlobalTransaction gxact, TransactionId xid, const char *gid,
proc->subxidStatus.count = 0;
gxact->prepared_at = prepared_at;
- gxact->xid = xid;
+ gxact->fxid = fxid;
gxact->owner = owner;
gxact->locking_backend = MyProcNumber;
gxact->valid = false;
@@ -747,7 +751,7 @@ pg_prepared_xact(PG_FUNCTION_ARGS)
* out as a result set.
*/
status = (Working_State *) palloc(sizeof(Working_State));
- funcctx->user_fctx = (void *) status;
+ funcctx->user_fctx = status;
status->ngxacts = GetPreparedTransactionList(&status->array);
status->currIdx = 0;
@@ -797,12 +801,12 @@ pg_prepared_xact(PG_FUNCTION_ARGS)
* caller had better hold it.
*/
static GlobalTransaction
-TwoPhaseGetGXact(TransactionId xid, bool lock_held)
+TwoPhaseGetGXact(FullTransactionId fxid, bool lock_held)
{
GlobalTransaction result = NULL;
int i;
- static TransactionId cached_xid = InvalidTransactionId;
+ static FullTransactionId cached_fxid = {InvalidTransactionId};
static GlobalTransaction cached_gxact = NULL;
Assert(!lock_held || LWLockHeldByMe(TwoPhaseStateLock));
@@ -811,7 +815,7 @@ TwoPhaseGetGXact(TransactionId xid, bool lock_held)
* During a recovery, COMMIT PREPARED, or ABORT PREPARED, we'll be called
* repeatedly for the same XID. We can save work with a simple cache.
*/
- if (xid == cached_xid)
+ if (FullTransactionIdEquals(fxid, cached_fxid))
return cached_gxact;
if (!lock_held)
@@ -821,7 +825,7 @@ TwoPhaseGetGXact(TransactionId xid, bool lock_held)
{
GlobalTransaction gxact = TwoPhaseState->prepXacts[i];
- if (gxact->xid == xid)
+ if (FullTransactionIdEquals(gxact->fxid, fxid))
{
result = gxact;
break;
@@ -832,9 +836,10 @@ TwoPhaseGetGXact(TransactionId xid, bool lock_held)
LWLockRelease(TwoPhaseStateLock);
if (result == NULL) /* should not happen */
- elog(ERROR, "failed to find GlobalTransaction for xid %u", xid);
+ elog(ERROR, "failed to find GlobalTransaction for xid %u",
+ XidFromFullTransactionId(fxid));
- cached_xid = xid;
+ cached_fxid = fxid;
cached_gxact = result;
return result;
@@ -881,7 +886,7 @@ TwoPhaseGetXidByVirtualXID(VirtualTransactionId vxid,
*have_more = true;
break;
}
- result = gxact->xid;
+ result = XidFromFullTransactionId(gxact->fxid);
}
}
@@ -892,7 +897,7 @@ TwoPhaseGetXidByVirtualXID(VirtualTransactionId vxid,
/*
* TwoPhaseGetDummyProcNumber
- * Get the dummy proc number for prepared transaction specified by XID
+ * Get the dummy proc number for prepared transaction
*
* Dummy proc numbers are similar to proc numbers of real backends. They
* start at MaxBackends, and are unique across all currently active real
@@ -900,24 +905,24 @@ TwoPhaseGetXidByVirtualXID(VirtualTransactionId vxid,
* TwoPhaseStateLock will not be taken, so the caller had better hold it.
*/
ProcNumber
-TwoPhaseGetDummyProcNumber(TransactionId xid, bool lock_held)
+TwoPhaseGetDummyProcNumber(FullTransactionId fxid, bool lock_held)
{
- GlobalTransaction gxact = TwoPhaseGetGXact(xid, lock_held);
+ GlobalTransaction gxact = TwoPhaseGetGXact(fxid, lock_held);
return gxact->pgprocno;
}
/*
* TwoPhaseGetDummyProc
- * Get the PGPROC that represents a prepared transaction specified by XID
+ * Get the PGPROC that represents a prepared transaction
*
* If lock_held is set to true, TwoPhaseStateLock will not be taken, so the
* caller had better hold it.
*/
PGPROC *
-TwoPhaseGetDummyProc(TransactionId xid, bool lock_held)
+TwoPhaseGetDummyProc(FullTransactionId fxid, bool lock_held)
{
- GlobalTransaction gxact = TwoPhaseGetGXact(xid, lock_held);
+ GlobalTransaction gxact = TwoPhaseGetGXact(fxid, lock_held);
return GetPGProcByNumber(gxact->pgprocno);
}
@@ -929,39 +934,21 @@ TwoPhaseGetDummyProc(TransactionId xid, bool lock_held)
/*
* Compute the FullTransactionId for the given TransactionId.
*
- * The wrap logic is safe here because the span of active xids cannot exceed one
- * epoch at any given time.
+ * This is safe if the xid has not yet reached COMMIT PREPARED or ROLLBACK
+ * PREPARED. After those commands, concurrent vac_truncate_clog() may make
+ * the xid cease to qualify as allowable. XXX Not all callers limit their
+ * calls accordingly.
*/
static inline FullTransactionId
AdjustToFullTransactionId(TransactionId xid)
{
- FullTransactionId nextFullXid;
- TransactionId nextXid;
- uint32 epoch;
-
Assert(TransactionIdIsValid(xid));
-
- LWLockAcquire(XidGenLock, LW_SHARED);
- nextFullXid = TransamVariables->nextXid;
- LWLockRelease(XidGenLock);
-
- nextXid = XidFromFullTransactionId(nextFullXid);
- epoch = EpochFromFullTransactionId(nextFullXid);
- if (unlikely(xid > nextXid))
- {
- /* Wraparound occurred, must be from a prev epoch. */
- Assert(epoch > 0);
- epoch--;
- }
-
- return FullTransactionIdFromEpochAndXid(epoch, xid);
+ return FullTransactionIdFromAllowableAt(ReadNextFullTransactionId(), xid);
}
static inline int
-TwoPhaseFilePath(char *path, TransactionId xid)
+TwoPhaseFilePath(char *path, FullTransactionId fxid)
{
- FullTransactionId fxid = AdjustToFullTransactionId(xid);
-
return snprintf(path, MAXPGPATH, TWOPHASE_DIR "/%08X%08X",
EpochFromFullTransactionId(fxid),
XidFromFullTransactionId(fxid));
@@ -1065,7 +1052,7 @@ void
StartPrepare(GlobalTransaction gxact)
{
PGPROC *proc = GetPGProcByNumber(gxact->pgprocno);
- TransactionId xid = gxact->xid;
+ TransactionId xid = XidFromFullTransactionId(gxact->fxid);
TwoPhaseFileHeader hdr;
TransactionId *children;
RelFileLocator *commitrels;
@@ -1197,7 +1184,11 @@ EndPrepare(GlobalTransaction gxact)
* starting immediately after the WAL record is inserted could complete
* without fsync'ing our state file. (This is essentially the same kind
* of race condition as the COMMIT-to-clog-write case that
- * RecordTransactionCommit uses DELAY_CHKPT_START for; see notes there.)
+ * RecordTransactionCommit uses DELAY_CHKPT_IN_COMMIT for; see notes
+ * there.) Note that DELAY_CHKPT_IN_COMMIT is used to find transactions in
+ * the critical commit section. We need to know about such transactions
+ * for conflict detection in logical replication. See
+ * GetOldestActiveTransactionId(true, false) and its use.
*
* We save the PREPARE record's location in the gxact for later use by
* CheckPointTwoPhase.
@@ -1297,10 +1288,11 @@ RegisterTwoPhaseRecord(TwoPhaseRmgrId rmid, uint16 info,
* If it looks OK (has a valid magic number and CRC), return the palloc'd
* contents of the file, issuing an error when finding corrupted data. If
* missing_ok is true, which indicates that missing files can be safely
- * ignored, then return NULL. This state can be reached when doing recovery.
+ * ignored, then return NULL. This state can be reached when doing recovery
+ * after discarding two-phase files from frozen epochs.
*/
static char *
-ReadTwoPhaseFile(TransactionId xid, bool missing_ok)
+ReadTwoPhaseFile(FullTransactionId fxid, bool missing_ok)
{
char path[MAXPGPATH];
char *buf;
@@ -1312,7 +1304,7 @@ ReadTwoPhaseFile(TransactionId xid, bool missing_ok)
file_crc;
int r;
- TwoPhaseFilePath(path, xid);
+ TwoPhaseFilePath(path, fxid);
fd = OpenTransientFile(path, O_RDONLY | PG_BINARY);
if (fd < 0)
@@ -1442,12 +1434,12 @@ XlogReadTwoPhaseData(XLogRecPtr lsn, char **buf, int *len)
if (errormsg)
ereport(ERROR,
(errcode_for_file_access(),
- errmsg("could not read two-phase state from WAL at %X/%X: %s",
+ errmsg("could not read two-phase state from WAL at %X/%08X: %s",
LSN_FORMAT_ARGS(lsn), errormsg)));
else
ereport(ERROR,
(errcode_for_file_access(),
- errmsg("could not read two-phase state from WAL at %X/%X",
+ errmsg("could not read two-phase state from WAL at %X/%08X",
LSN_FORMAT_ARGS(lsn))));
}
@@ -1455,7 +1447,7 @@ XlogReadTwoPhaseData(XLogRecPtr lsn, char **buf, int *len)
(XLogRecGetInfo(xlogreader) & XLOG_XACT_OPMASK) != XLOG_XACT_PREPARE)
ereport(ERROR,
(errcode_for_file_access(),
- errmsg("expected two-phase state data is not present in WAL at %X/%X",
+ errmsg("expected two-phase state data is not present in WAL at %X/%08X",
LSN_FORMAT_ARGS(lsn))));
if (len != NULL)
@@ -1477,6 +1469,7 @@ StandbyTransactionIdIsPrepared(TransactionId xid)
char *buf;
TwoPhaseFileHeader *hdr;
bool result;
+ FullTransactionId fxid;
Assert(TransactionIdIsValid(xid));
@@ -1484,7 +1477,8 @@ StandbyTransactionIdIsPrepared(TransactionId xid)
return false; /* nothing to do */
/* Read and validate file */
- buf = ReadTwoPhaseFile(xid, true);
+ fxid = AdjustToFullTransactionId(xid);
+ buf = ReadTwoPhaseFile(fxid, true);
if (buf == NULL)
return false;
@@ -1504,7 +1498,9 @@ FinishPreparedTransaction(const char *gid, bool isCommit)
{
GlobalTransaction gxact;
PGPROC *proc;
+ FullTransactionId fxid;
TransactionId xid;
+ bool ondisk;
char *buf;
char *bufptr;
TwoPhaseFileHeader *hdr;
@@ -1524,7 +1520,8 @@ FinishPreparedTransaction(const char *gid, bool isCommit)
*/
gxact = LockGXact(gid, GetUserId());
proc = GetPGProcByNumber(gxact->pgprocno);
- xid = gxact->xid;
+ fxid = gxact->fxid;
+ xid = XidFromFullTransactionId(fxid);
/*
* Read and validate 2PC state data. State data will typically be stored
@@ -1532,7 +1529,7 @@ FinishPreparedTransaction(const char *gid, bool isCommit)
* to disk if for some reason they have lived for a long time.
*/
if (gxact->ondisk)
- buf = ReadTwoPhaseFile(xid, false);
+ buf = ReadTwoPhaseFile(fxid, false);
else
XlogReadTwoPhaseData(gxact->prepare_start_lsn, &buf, NULL);
@@ -1651,11 +1648,17 @@ FinishPreparedTransaction(const char *gid, bool isCommit)
/* And now do the callbacks */
if (isCommit)
- ProcessRecords(bufptr, xid, twophase_postcommit_callbacks);
+ ProcessRecords(bufptr, fxid, twophase_postcommit_callbacks);
else
- ProcessRecords(bufptr, xid, twophase_postabort_callbacks);
+ ProcessRecords(bufptr, fxid, twophase_postabort_callbacks);
+
+ PredicateLockTwoPhaseFinish(fxid, isCommit);
- PredicateLockTwoPhaseFinish(xid, isCommit);
+ /*
+ * Read this value while holding the two-phase lock, as the on-disk 2PC
+ * file is physically removed after the lock is released.
+ */
+ ondisk = gxact->ondisk;
/* Clear shared memory state */
RemoveGXact(gxact);
@@ -1672,8 +1675,8 @@ FinishPreparedTransaction(const char *gid, bool isCommit)
/*
* And now we can clean up any files we may have left.
*/
- if (gxact->ondisk)
- RemoveTwoPhaseFile(xid, true);
+ if (ondisk)
+ RemoveTwoPhaseFile(fxid, true);
MyLockedGxact = NULL;
@@ -1686,7 +1689,7 @@ FinishPreparedTransaction(const char *gid, bool isCommit)
* Scan 2PC state data in memory and call the indicated callbacks for each 2PC record.
*/
static void
-ProcessRecords(char *bufptr, TransactionId xid,
+ProcessRecords(char *bufptr, FullTransactionId fxid,
const TwoPhaseCallback callbacks[])
{
for (;;)
@@ -1700,25 +1703,28 @@ ProcessRecords(char *bufptr, TransactionId xid,
bufptr += MAXALIGN(sizeof(TwoPhaseRecordOnDisk));
if (callbacks[record->rmid] != NULL)
- callbacks[record->rmid] (xid, record->info,
- (void *) bufptr, record->len);
+ callbacks[record->rmid] (fxid, record->info, bufptr, record->len);
bufptr += MAXALIGN(record->len);
}
}
/*
- * Remove the 2PC file for the specified XID.
+ * Remove the 2PC file.
*
* If giveWarning is false, do not complain about file-not-present;
* this is an expected case during WAL replay.
+ *
+ * This routine is used at early stages at recovery where future and
+ * past orphaned files are checked, hence the FullTransactionId to build
+ * a complete file name fit for the removal.
*/
static void
-RemoveTwoPhaseFile(TransactionId xid, bool giveWarning)
+RemoveTwoPhaseFile(FullTransactionId fxid, bool giveWarning)
{
char path[MAXPGPATH];
- TwoPhaseFilePath(path, xid);
+ TwoPhaseFilePath(path, fxid);
if (unlink(path))
if (errno != ENOENT || giveWarning)
ereport(WARNING,
@@ -1733,7 +1739,7 @@ RemoveTwoPhaseFile(TransactionId xid, bool giveWarning)
* Note: content and len don't include CRC.
*/
static void
-RecreateTwoPhaseFile(TransactionId xid, void *content, int len)
+RecreateTwoPhaseFile(FullTransactionId fxid, void *content, int len)
{
char path[MAXPGPATH];
pg_crc32c statefile_crc;
@@ -1744,7 +1750,7 @@ RecreateTwoPhaseFile(TransactionId xid, void *content, int len)
COMP_CRC32C(statefile_crc, content, len);
FIN_CRC32C(statefile_crc);
- TwoPhaseFilePath(path, xid);
+ TwoPhaseFilePath(path, fxid);
fd = OpenTransientFile(path,
O_CREAT | O_TRUNC | O_WRONLY | PG_BINARY);
@@ -1856,7 +1862,7 @@ CheckPointTwoPhase(XLogRecPtr redo_horizon)
int len;
XlogReadTwoPhaseData(gxact->prepare_start_lsn, &buf, &len);
- RecreateTwoPhaseFile(gxact->xid, buf, len);
+ RecreateTwoPhaseFile(gxact->fxid, buf, len);
gxact->ondisk = true;
gxact->prepare_start_lsn = InvalidXLogRecPtr;
gxact->prepare_end_lsn = InvalidXLogRecPtr;
@@ -1907,19 +1913,17 @@ restoreTwoPhaseData(void)
if (strlen(clde->d_name) == 16 &&
strspn(clde->d_name, "0123456789ABCDEF") == 16)
{
- TransactionId xid;
FullTransactionId fxid;
char *buf;
fxid = FullTransactionIdFromU64(strtou64(clde->d_name, NULL, 16));
- xid = XidFromFullTransactionId(fxid);
- buf = ProcessTwoPhaseBuffer(xid, InvalidXLogRecPtr,
+ buf = ProcessTwoPhaseBuffer(fxid, InvalidXLogRecPtr,
true, false, false);
if (buf == NULL)
continue;
- PrepareRedoAdd(buf, InvalidXLogRecPtr,
+ PrepareRedoAdd(fxid, buf, InvalidXLogRecPtr,
InvalidXLogRecPtr, InvalidRepOriginId);
}
}
@@ -1978,9 +1982,7 @@ PrescanPreparedTransactions(TransactionId **xids_p, int *nxids_p)
Assert(gxact->inredo);
- xid = gxact->xid;
-
- buf = ProcessTwoPhaseBuffer(xid,
+ buf = ProcessTwoPhaseBuffer(gxact->fxid,
gxact->prepare_start_lsn,
gxact->ondisk, false, true);
@@ -1991,6 +1993,7 @@ PrescanPreparedTransactions(TransactionId **xids_p, int *nxids_p)
* OK, we think this file is valid. Incorporate xid into the
* running-minimum result.
*/
+ xid = XidFromFullTransactionId(gxact->fxid);
if (TransactionIdPrecedes(xid, result))
result = xid;
@@ -2035,9 +2038,8 @@ PrescanPreparedTransactions(TransactionId **xids_p, int *nxids_p)
* This is never called at the end of recovery - we use
* RecoverPreparedTransactions() at that point.
*
- * The lack of calls to SubTransSetParent() calls here is by design;
- * those calls are made by RecoverPreparedTransactions() at the end of recovery
- * for those xacts that need this.
+ * This updates pg_subtrans, so that any subtransactions will be correctly
+ * seen as in-progress in snapshots taken during recovery.
*/
void
StandbyRecoverPreparedTransactions(void)
@@ -2047,17 +2049,14 @@ StandbyRecoverPreparedTransactions(void)
LWLockAcquire(TwoPhaseStateLock, LW_EXCLUSIVE);
for (i = 0; i < TwoPhaseState->numPrepXacts; i++)
{
- TransactionId xid;
char *buf;
GlobalTransaction gxact = TwoPhaseState->prepXacts[i];
Assert(gxact->inredo);
- xid = gxact->xid;
-
- buf = ProcessTwoPhaseBuffer(xid,
+ buf = ProcessTwoPhaseBuffer(gxact->fxid,
gxact->prepare_start_lsn,
- gxact->ondisk, false, false);
+ gxact->ondisk, true, false);
if (buf != NULL)
pfree(buf);
}
@@ -2088,16 +2087,14 @@ RecoverPreparedTransactions(void)
LWLockAcquire(TwoPhaseStateLock, LW_EXCLUSIVE);
for (i = 0; i < TwoPhaseState->numPrepXacts; i++)
{
- TransactionId xid;
char *buf;
GlobalTransaction gxact = TwoPhaseState->prepXacts[i];
+ FullTransactionId fxid = gxact->fxid;
char *bufptr;
TwoPhaseFileHeader *hdr;
TransactionId *subxids;
const char *gid;
- xid = gxact->xid;
-
/*
* Reconstruct subtrans state for the transaction --- needed because
* pg_subtrans is not preserved over a restart. Note that we are
@@ -2107,17 +2104,20 @@ RecoverPreparedTransactions(void)
* SubTransSetParent has been set before, if the prepared transaction
* generated xid assignment records.
*/
- buf = ProcessTwoPhaseBuffer(xid,
+ buf = ProcessTwoPhaseBuffer(gxact->fxid,
gxact->prepare_start_lsn,
gxact->ondisk, true, false);
if (buf == NULL)
continue;
ereport(LOG,
- (errmsg("recovering prepared transaction %u from shared memory", xid)));
+ (errmsg("recovering prepared transaction %u of epoch %u from shared memory",
+ XidFromFullTransactionId(gxact->fxid),
+ EpochFromFullTransactionId(gxact->fxid))));
hdr = (TwoPhaseFileHeader *) buf;
- Assert(TransactionIdEquals(hdr->xid, xid));
+ Assert(TransactionIdEquals(hdr->xid,
+ XidFromFullTransactionId(gxact->fxid)));
bufptr = buf + MAXALIGN(sizeof(TwoPhaseFileHeader));
gid = (const char *) bufptr;
bufptr += MAXALIGN(hdr->gidlen);
@@ -2133,7 +2133,7 @@ RecoverPreparedTransactions(void)
* Recreate its GXACT and dummy PGPROC. But, check whether it was
* added in redo and already has a shmem entry for it.
*/
- MarkAsPreparingGuts(gxact, xid, gid,
+ MarkAsPreparingGuts(gxact, gxact->fxid, gid,
hdr->prepared_at,
hdr->owner, hdr->database);
@@ -2148,7 +2148,7 @@ RecoverPreparedTransactions(void)
/*
* Recover other state (notably locks) using resource managers.
*/
- ProcessRecords(bufptr, xid, twophase_recover_callbacks);
+ ProcessRecords(bufptr, fxid, twophase_recover_callbacks);
/*
* Release locks held by the standby process after we process each
@@ -2156,7 +2156,7 @@ RecoverPreparedTransactions(void)
* additional locks at any one time.
*/
if (InHotStandby)
- StandbyReleaseLockTree(xid, hdr->nsubxacts, subxids);
+ StandbyReleaseLockTree(hdr->xid, hdr->nsubxacts, subxids);
/*
* We're done with recovering this transaction. Clear MyLockedGxact,
@@ -2175,7 +2175,7 @@ RecoverPreparedTransactions(void)
/*
* ProcessTwoPhaseBuffer
*
- * Given a transaction id, read it either from disk or read it directly
+ * Given a FullTransactionId, read it either from disk or read it directly
* via shmem xlog record pointer using the provided "prepare_start_lsn".
*
* If setParent is true, set up subtransaction parent linkages.
@@ -2184,13 +2184,12 @@ RecoverPreparedTransactions(void)
* value scanned.
*/
static char *
-ProcessTwoPhaseBuffer(TransactionId xid,
+ProcessTwoPhaseBuffer(FullTransactionId fxid,
XLogRecPtr prepare_start_lsn,
bool fromdisk,
bool setParent, bool setNextXid)
{
FullTransactionId nextXid = TransamVariables->nextXid;
- TransactionId origNextXid = XidFromFullTransactionId(nextXid);
TransactionId *subxids;
char *buf;
TwoPhaseFileHeader *hdr;
@@ -2202,41 +2201,46 @@ ProcessTwoPhaseBuffer(TransactionId xid,
Assert(prepare_start_lsn != InvalidXLogRecPtr);
/* Already processed? */
- if (TransactionIdDidCommit(xid) || TransactionIdDidAbort(xid))
+ if (TransactionIdDidCommit(XidFromFullTransactionId(fxid)) ||
+ TransactionIdDidAbort(XidFromFullTransactionId(fxid)))
{
if (fromdisk)
{
ereport(WARNING,
- (errmsg("removing stale two-phase state file for transaction %u",
- xid)));
- RemoveTwoPhaseFile(xid, true);
+ (errmsg("removing stale two-phase state file for transaction %u of epoch %u",
+ XidFromFullTransactionId(fxid),
+ EpochFromFullTransactionId(fxid))));
+ RemoveTwoPhaseFile(fxid, true);
}
else
{
ereport(WARNING,
- (errmsg("removing stale two-phase state from memory for transaction %u",
- xid)));
- PrepareRedoRemove(xid, true);
+ (errmsg("removing stale two-phase state from memory for transaction %u of epoch %u",
+ XidFromFullTransactionId(fxid),
+ EpochFromFullTransactionId(fxid))));
+ PrepareRedoRemoveFull(fxid, true);
}
return NULL;
}
/* Reject XID if too new */
- if (TransactionIdFollowsOrEquals(xid, origNextXid))
+ if (FullTransactionIdFollowsOrEquals(fxid, nextXid))
{
if (fromdisk)
{
ereport(WARNING,
- (errmsg("removing future two-phase state file for transaction %u",
- xid)));
- RemoveTwoPhaseFile(xid, true);
+ (errmsg("removing future two-phase state file for transaction %u of epoch %u",
+ XidFromFullTransactionId(fxid),
+ EpochFromFullTransactionId(fxid))));
+ RemoveTwoPhaseFile(fxid, true);
}
else
{
ereport(WARNING,
- (errmsg("removing future two-phase state from memory for transaction %u",
- xid)));
- PrepareRedoRemove(xid, true);
+ (errmsg("removing future two-phase state from memory for transaction %u of epoch %u",
+ XidFromFullTransactionId(fxid),
+ EpochFromFullTransactionId(fxid))));
+ PrepareRedoRemoveFull(fxid, true);
}
return NULL;
}
@@ -2244,7 +2248,7 @@ ProcessTwoPhaseBuffer(TransactionId xid,
if (fromdisk)
{
/* Read and validate file */
- buf = ReadTwoPhaseFile(xid, false);
+ buf = ReadTwoPhaseFile(fxid, false);
}
else
{
@@ -2254,18 +2258,20 @@ ProcessTwoPhaseBuffer(TransactionId xid,
/* Deconstruct header */
hdr = (TwoPhaseFileHeader *) buf;
- if (!TransactionIdEquals(hdr->xid, xid))
+ if (!TransactionIdEquals(hdr->xid, XidFromFullTransactionId(fxid)))
{
if (fromdisk)
ereport(ERROR,
(errcode(ERRCODE_DATA_CORRUPTED),
- errmsg("corrupted two-phase state file for transaction %u",
- xid)));
+ errmsg("corrupted two-phase state file for transaction %u of epoch %u",
+ XidFromFullTransactionId(fxid),
+ EpochFromFullTransactionId(fxid))));
else
ereport(ERROR,
(errcode(ERRCODE_DATA_CORRUPTED),
- errmsg("corrupted two-phase state in memory for transaction %u",
- xid)));
+ errmsg("corrupted two-phase state in memory for transaction %u of epoch %u",
+ XidFromFullTransactionId(fxid),
+ EpochFromFullTransactionId(fxid))));
}
/*
@@ -2279,14 +2285,14 @@ ProcessTwoPhaseBuffer(TransactionId xid,
{
TransactionId subxid = subxids[i];
- Assert(TransactionIdFollows(subxid, xid));
+ Assert(TransactionIdFollows(subxid, XidFromFullTransactionId(fxid)));
/* update nextXid if needed */
if (setNextXid)
AdvanceNextFullTransactionIdPastXid(subxid);
if (setParent)
- SubTransSetParent(subxid, xid);
+ SubTransSetParent(subxid, XidFromFullTransactionId(fxid));
}
return buf;
@@ -2297,7 +2303,7 @@ ProcessTwoPhaseBuffer(TransactionId xid,
* RecordTransactionCommitPrepared
*
* This is basically the same as RecordTransactionCommit (q.v. if you change
- * this function): in particular, we must set DELAY_CHKPT_START to avoid a
+ * this function): in particular, we must set DELAY_CHKPT_IN_COMMIT to avoid a
* race condition.
*
* We know the transaction made at least one XLOG entry (its PREPARE),
@@ -2317,7 +2323,7 @@ RecordTransactionCommitPrepared(TransactionId xid,
const char *gid)
{
XLogRecPtr recptr;
- TimestampTz committs = GetCurrentTimestamp();
+ TimestampTz committs;
bool replorigin;
/*
@@ -2327,11 +2333,32 @@ RecordTransactionCommitPrepared(TransactionId xid,
replorigin = (replorigin_session_origin != InvalidRepOriginId &&
replorigin_session_origin != DoNotReplicateId);
+ /* Load the injection point before entering the critical section */
+ INJECTION_POINT_LOAD("commit-after-delay-checkpoint");
+
START_CRIT_SECTION();
/* See notes in RecordTransactionCommit */
- Assert((MyProc->delayChkptFlags & DELAY_CHKPT_START) == 0);
- MyProc->delayChkptFlags |= DELAY_CHKPT_START;
+ Assert((MyProc->delayChkptFlags & DELAY_CHKPT_IN_COMMIT) == 0);
+ MyProc->delayChkptFlags |= DELAY_CHKPT_IN_COMMIT;
+
+ INJECTION_POINT_CACHED("commit-after-delay-checkpoint", NULL);
+
+ /*
+ * Ensures the DELAY_CHKPT_IN_COMMIT flag write is globally visible before
+ * commit time is written.
+ */
+ pg_write_barrier();
+
+ /*
+ * Note it is important to set committs value after marking ourselves as
+ * in the commit critical section (DELAY_CHKPT_IN_COMMIT). This is because
+ * we want to ensure all transactions that have acquired commit timestamp
+ * are finished before we allow the logical replication client to advance
+ * its xid which is used to hold back dead rows for conflict detection.
+ * See comments atop worker.c.
+ */
+ committs = GetCurrentTimestamp();
/*
* Emit the XLOG commit record. Note that we mark 2PC commits as
@@ -2380,7 +2407,7 @@ RecordTransactionCommitPrepared(TransactionId xid,
TransactionIdCommitTree(xid, nchildren, children);
/* Checkpoint can proceed now */
- MyProc->delayChkptFlags &= ~DELAY_CHKPT_START;
+ MyProc->delayChkptFlags &= ~DELAY_CHKPT_IN_COMMIT;
END_CRIT_SECTION();
@@ -2477,8 +2504,9 @@ RecordTransactionAbortPrepared(TransactionId xid,
* data, the entry is marked as located on disk.
*/
void
-PrepareRedoAdd(char *buf, XLogRecPtr start_lsn,
- XLogRecPtr end_lsn, RepOriginId origin_id)
+PrepareRedoAdd(FullTransactionId fxid, char *buf,
+ XLogRecPtr start_lsn, XLogRecPtr end_lsn,
+ RepOriginId origin_id)
{
TwoPhaseFileHeader *hdr = (TwoPhaseFileHeader *) buf;
char *bufptr;
@@ -2488,6 +2516,13 @@ PrepareRedoAdd(char *buf, XLogRecPtr start_lsn,
Assert(LWLockHeldByMeInMode(TwoPhaseStateLock, LW_EXCLUSIVE));
Assert(RecoveryInProgress());
+ if (!FullTransactionIdIsValid(fxid))
+ {
+ Assert(InRecovery);
+ fxid = FullTransactionIdFromAllowableAt(TransamVariables->nextXid,
+ hdr->xid);
+ }
+
bufptr = buf + MAXALIGN(sizeof(TwoPhaseFileHeader));
gid = (const char *) bufptr;
@@ -2516,14 +2551,15 @@ PrepareRedoAdd(char *buf, XLogRecPtr start_lsn,
{
char path[MAXPGPATH];
- TwoPhaseFilePath(path, hdr->xid);
+ Assert(InRecovery);
+ TwoPhaseFilePath(path, fxid);
if (access(path, F_OK) == 0)
{
ereport(reachedConsistency ? ERROR : WARNING,
(errmsg("could not recover two-phase state file for transaction %u",
hdr->xid),
- errdetail("Two-phase state file has been found in WAL record %X/%X, but this transaction has already been restored from disk.",
+ errdetail("Two-phase state file has been found in WAL record %X/%08X, but this transaction has already been restored from disk.",
LSN_FORMAT_ARGS(start_lsn))));
return;
}
@@ -2547,7 +2583,7 @@ PrepareRedoAdd(char *buf, XLogRecPtr start_lsn,
gxact->prepared_at = hdr->prepared_at;
gxact->prepare_start_lsn = start_lsn;
gxact->prepare_end_lsn = end_lsn;
- gxact->xid = hdr->xid;
+ gxact->fxid = fxid;
gxact->owner = hdr->owner;
gxact->locking_backend = INVALID_PROC_NUMBER;
gxact->valid = false;
@@ -2566,11 +2602,13 @@ PrepareRedoAdd(char *buf, XLogRecPtr start_lsn,
false /* backward */ , false /* WAL */ );
}
- elog(DEBUG2, "added 2PC data in shared memory for transaction %u", gxact->xid);
+ elog(DEBUG2, "added 2PC data in shared memory for transaction %u of epoch %u",
+ XidFromFullTransactionId(gxact->fxid),
+ EpochFromFullTransactionId(gxact->fxid));
}
/*
- * PrepareRedoRemove
+ * PrepareRedoRemoveFull
*
* Remove the corresponding gxact entry from TwoPhaseState. Also remove
* the 2PC file if a prepared transaction was saved via an earlier checkpoint.
@@ -2578,8 +2616,8 @@ PrepareRedoAdd(char *buf, XLogRecPtr start_lsn,
* Caller must hold TwoPhaseStateLock in exclusive mode, because TwoPhaseState
* is updated.
*/
-void
-PrepareRedoRemove(TransactionId xid, bool giveWarning)
+static void
+PrepareRedoRemoveFull(FullTransactionId fxid, bool giveWarning)
{
GlobalTransaction gxact = NULL;
int i;
@@ -2592,7 +2630,7 @@ PrepareRedoRemove(TransactionId xid, bool giveWarning)
{
gxact = TwoPhaseState->prepXacts[i];
- if (gxact->xid == xid)
+ if (FullTransactionIdEquals(gxact->fxid, fxid))
{
Assert(gxact->inredo);
found = true;
@@ -2609,12 +2647,28 @@ PrepareRedoRemove(TransactionId xid, bool giveWarning)
/*
* And now we can clean up any files we may have left.
*/
- elog(DEBUG2, "removing 2PC data for transaction %u", xid);
+ elog(DEBUG2, "removing 2PC data for transaction %u of epoch %u ",
+ XidFromFullTransactionId(fxid),
+ EpochFromFullTransactionId(fxid));
+
if (gxact->ondisk)
- RemoveTwoPhaseFile(xid, giveWarning);
+ RemoveTwoPhaseFile(fxid, giveWarning);
+
RemoveGXact(gxact);
}
+/*
+ * Wrapper of PrepareRedoRemoveFull(), for TransactionIds.
+ */
+void
+PrepareRedoRemove(TransactionId xid, bool giveWarning)
+{
+ FullTransactionId fxid =
+ FullTransactionIdFromAllowableAt(TransamVariables->nextXid, xid);
+
+ PrepareRedoRemoveFull(fxid, giveWarning);
+}
+
/*
* LookupGXact
* Check if the prepared transaction with the given GID, lsn and timestamp
@@ -2659,7 +2713,7 @@ LookupGXact(const char *gid, XLogRecPtr prepare_end_lsn,
* between publisher and subscriber.
*/
if (gxact->ondisk)
- buf = ReadTwoPhaseFile(gxact->xid, false);
+ buf = ReadTwoPhaseFile(gxact->fxid, false);
else
{
Assert(gxact->prepare_start_lsn);
@@ -2682,3 +2736,137 @@ LookupGXact(const char *gid, XLogRecPtr prepare_end_lsn,
LWLockRelease(TwoPhaseStateLock);
return found;
}
+
+/*
+ * TwoPhaseTransactionGid
+ * Form the prepared transaction GID for two_phase transactions.
+ *
+ * Return the GID in the supplied buffer.
+ */
+void
+TwoPhaseTransactionGid(Oid subid, TransactionId xid, char *gid_res, int szgid)
+{
+ Assert(OidIsValid(subid));
+
+ if (!TransactionIdIsValid(xid))
+ ereport(ERROR,
+ (errcode(ERRCODE_PROTOCOL_VIOLATION),
+ errmsg_internal("invalid two-phase transaction ID")));
+
+ snprintf(gid_res, szgid, "pg_gid_%u_%u", subid, xid);
+}
+
+/*
+ * IsTwoPhaseTransactionGidForSubid
+ * Check whether the given GID (as formed by TwoPhaseTransactionGid) is
+ * for the specified 'subid'.
+ */
+static bool
+IsTwoPhaseTransactionGidForSubid(Oid subid, char *gid)
+{
+ int ret;
+ Oid subid_from_gid;
+ TransactionId xid_from_gid;
+ char gid_tmp[GIDSIZE];
+
+ /* Extract the subid and xid from the given GID */
+ ret = sscanf(gid, "pg_gid_%u_%u", &subid_from_gid, &xid_from_gid);
+
+ /*
+ * Check that the given GID has expected format, and at least the subid
+ * matches.
+ */
+ if (ret != 2 || subid != subid_from_gid)
+ return false;
+
+ /*
+ * Reconstruct a temporary GID based on the subid and xid extracted from
+ * the given GID and check whether the temporary GID and the given GID
+ * match.
+ */
+ TwoPhaseTransactionGid(subid, xid_from_gid, gid_tmp, sizeof(gid_tmp));
+
+ return strcmp(gid, gid_tmp) == 0;
+}
+
+/*
+ * LookupGXactBySubid
+ * Check if the prepared transaction done by apply worker exists.
+ */
+bool
+LookupGXactBySubid(Oid subid)
+{
+ bool found = false;
+
+ LWLockAcquire(TwoPhaseStateLock, LW_SHARED);
+ for (int i = 0; i < TwoPhaseState->numPrepXacts; i++)
+ {
+ GlobalTransaction gxact = TwoPhaseState->prepXacts[i];
+
+ /* Ignore not-yet-valid GIDs. */
+ if (gxact->valid &&
+ IsTwoPhaseTransactionGidForSubid(subid, gxact->gid))
+ {
+ found = true;
+ break;
+ }
+ }
+ LWLockRelease(TwoPhaseStateLock);
+
+ return found;
+}
+
+/*
+ * TwoPhaseGetXidByLockingProc
+ * Return the oldest transaction ID from prepared transactions that are
+ * currently in the commit critical section.
+ *
+ * This function only considers transactions in the currently connected
+ * database. If no matching transactions are found, it returns
+ * InvalidTransactionId.
+ */
+TransactionId
+TwoPhaseGetOldestXidInCommit(void)
+{
+ TransactionId oldestRunningXid = InvalidTransactionId;
+
+ LWLockAcquire(TwoPhaseStateLock, LW_SHARED);
+
+ for (int i = 0; i < TwoPhaseState->numPrepXacts; i++)
+ {
+ GlobalTransaction gxact = TwoPhaseState->prepXacts[i];
+ PGPROC *commitproc;
+ TransactionId xid;
+
+ if (!gxact->valid)
+ continue;
+
+ if (gxact->locking_backend == INVALID_PROC_NUMBER)
+ continue;
+
+ /*
+ * Get the backend that is handling the transaction. It's safe to
+ * access this backend while holding TwoPhaseStateLock, as the backend
+ * can only be destroyed after either removing or unlocking the
+ * current global transaction, both of which require an exclusive
+ * TwoPhaseStateLock.
+ */
+ commitproc = GetPGProcByNumber(gxact->locking_backend);
+
+ if (MyDatabaseId != commitproc->databaseId)
+ continue;
+
+ if ((commitproc->delayChkptFlags & DELAY_CHKPT_IN_COMMIT) == 0)
+ continue;
+
+ xid = XidFromFullTransactionId(gxact->fxid);
+
+ if (!TransactionIdIsValid(oldestRunningXid) ||
+ TransactionIdPrecedes(xid, oldestRunningXid))
+ oldestRunningXid = xid;
+ }
+
+ LWLockRelease(TwoPhaseStateLock);
+
+ return oldestRunningXid;
+}
diff --git a/src/backend/access/transam/twophase_rmgr.c b/src/backend/access/transam/twophase_rmgr.c
index 15b797f34b3af..b638e0949e77e 100644
--- a/src/backend/access/transam/twophase_rmgr.c
+++ b/src/backend/access/transam/twophase_rmgr.c
@@ -3,7 +3,7 @@
* twophase_rmgr.c
* Two-phase-commit resource managers tables
*
- * Portions Copyright (c) 1996-2024, PostgreSQL Global Development Group
+ * Portions Copyright (c) 1996-2025, PostgreSQL Global Development Group
* Portions Copyright (c) 1994, Regents of the University of California
*
*
diff --git a/src/backend/access/transam/varsup.c b/src/backend/access/transam/varsup.c
index fb6a86afcb134..f8c4dada7c93a 100644
--- a/src/backend/access/transam/varsup.c
+++ b/src/backend/access/transam/varsup.c
@@ -3,7 +3,7 @@
* varsup.c
* postgres OID & XID variables support routines
*
- * Copyright (c) 2000-2024, PostgreSQL Global Development Group
+ * Copyright (c) 2000-2025, PostgreSQL Global Development Group
*
* IDENTIFICATION
* src/backend/access/transam/varsup.c
@@ -19,11 +19,11 @@
#include "access/transam.h"
#include "access/xact.h"
#include "access/xlogutils.h"
-#include "commands/dbcommands.h"
#include "miscadmin.h"
#include "postmaster/autovacuum.h"
#include "storage/pmsignal.h"
#include "storage/proc.h"
+#include "utils/lsyscache.h"
#include "utils/syscache.h"
@@ -153,14 +153,14 @@ GetNewTransactionId(bool isSubXact)
if (oldest_datname)
ereport(ERROR,
(errcode(ERRCODE_PROGRAM_LIMIT_EXCEEDED),
- errmsg("database is not accepting commands that assign new XIDs to avoid wraparound data loss in database \"%s\"",
+ errmsg("database is not accepting commands that assign new transaction IDs to avoid wraparound data loss in database \"%s\"",
oldest_datname),
errhint("Execute a database-wide VACUUM in that database.\n"
"You might also need to commit or roll back old prepared transactions, or drop stale replication slots.")));
else
ereport(ERROR,
(errcode(ERRCODE_PROGRAM_LIMIT_EXCEEDED),
- errmsg("database is not accepting commands that assign new XIDs to avoid wraparound data loss in database with OID %u",
+ errmsg("database is not accepting commands that assign new transaction IDs to avoid wraparound data loss in database with OID %u",
oldest_datoid),
errhint("Execute a database-wide VACUUM in that database.\n"
"You might also need to commit or roll back old prepared transactions, or drop stale replication slots.")));
@@ -175,7 +175,7 @@ GetNewTransactionId(bool isSubXact)
(errmsg("database \"%s\" must be vacuumed within %u transactions",
oldest_datname,
xidWrapLimit - xid),
- errhint("To avoid XID assignment failures, execute a database-wide VACUUM in that database.\n"
+ errhint("To avoid transaction ID assignment failures, execute a database-wide VACUUM in that database.\n"
"You might also need to commit or roll back old prepared transactions, or drop stale replication slots.")));
else
ereport(WARNING,
diff --git a/src/backend/access/transam/xact.c b/src/backend/access/transam/xact.c
index 4f4ce757623c9..b46e7e9c2a6b0 100644
--- a/src/backend/access/transam/xact.c
+++ b/src/backend/access/transam/xact.c
@@ -5,7 +5,7 @@
*
* See src/backend/access/transam/README for more information.
*
- * Portions Copyright (c) 1996-2024, PostgreSQL Global Development Group
+ * Portions Copyright (c) 1996-2025, PostgreSQL Global Development Group
* Portions Copyright (c) 1994, Regents of the University of California
*
*
@@ -51,6 +51,7 @@
#include "replication/origin.h"
#include "replication/snapbuild.h"
#include "replication/syncrep.h"
+#include "storage/aio_subsys.h"
#include "storage/condition_variable.h"
#include "storage/fd.h"
#include "storage/lmgr.h"
@@ -69,6 +70,7 @@
#include "utils/snapmgr.h"
#include "utils/timeout.h"
#include "utils/timestamp.h"
+#include "utils/typcache.h"
/*
* User-tweakable parameters
@@ -200,6 +202,7 @@ typedef struct TransactionStateData
int gucNestLevel; /* GUC context nesting depth */
MemoryContext curTransactionContext; /* my xact-lifetime context */
ResourceOwner curTransactionOwner; /* my query resources */
+ MemoryContext priorContext; /* CurrentMemoryContext before xact started */
TransactionId *childXids; /* subcommitted child XIDs, in XID order */
int nChildXids; /* # of subcommitted child XIDs */
int maxChildXids; /* allocated size of childXids[] */
@@ -646,7 +649,7 @@ AssignTransactionId(TransactionState s)
if (IsInParallelMode() || IsParallelWorker())
ereport(ERROR,
(errcode(ERRCODE_INVALID_TRANSACTION_STATE),
- errmsg("cannot assign XIDs during a parallel operation")));
+ errmsg("cannot assign transaction IDs during a parallel operation")));
/*
* Ensure parent(s) have XIDs, so that a child always has an XID later
@@ -768,8 +771,8 @@ AssignTransactionId(TransactionState s)
xlrec.nsubxacts = nUnreportedXids;
XLogBeginInsert();
- XLogRegisterData((char *) &xlrec, MinSizeOfXactAssignment);
- XLogRegisterData((char *) unreportedXids,
+ XLogRegisterData(&xlrec, MinSizeOfXactAssignment);
+ XLogRegisterData(unreportedXids,
nUnreportedXids * sizeof(TransactionId));
(void) XLogInsert(RM_XACT_ID, XLOG_XACT_ASSIGNMENT);
@@ -1174,6 +1177,11 @@ AtStart_Memory(void)
{
TransactionState s = CurrentTransactionState;
+ /*
+ * Remember the memory context that was active prior to transaction start.
+ */
+ s->priorContext = CurrentMemoryContext;
+
/*
* If this is the first time through, create a private context for
* AbortTransaction to work in. By reserving some space now, we can
@@ -1190,17 +1198,15 @@ AtStart_Memory(void)
32 * 1024);
/*
- * We shouldn't have a transaction context already.
- */
- Assert(TopTransactionContext == NULL);
-
- /*
- * Create a toplevel context for the transaction.
+ * Likewise, if this is the first time through, create a top-level context
+ * for transaction-local data. This context will be reset at transaction
+ * end, and then re-used in later transactions.
*/
- TopTransactionContext =
- AllocSetContextCreate(TopMemoryContext,
- "TopTransactionContext",
- ALLOCSET_DEFAULT_SIZES);
+ if (TopTransactionContext == NULL)
+ TopTransactionContext =
+ AllocSetContextCreate(TopMemoryContext,
+ "TopTransactionContext",
+ ALLOCSET_DEFAULT_SIZES);
/*
* In a top-level transaction, CurTransactionContext is the same as
@@ -1251,6 +1257,11 @@ AtSubStart_Memory(void)
Assert(CurTransactionContext != NULL);
+ /*
+ * Remember the context that was active prior to subtransaction start.
+ */
+ s->priorContext = CurrentMemoryContext;
+
/*
* Create a CurTransactionContext, which will be used to hold data that
* survives subtransaction commit but disappears on subtransaction abort.
@@ -1358,14 +1369,24 @@ RecordTransactionCommit(void)
/*
* Transactions without an assigned xid can contain invalidation
- * messages (e.g. explicit relcache invalidations or catcache
- * invalidations for inplace updates); standbys need to process those.
- * We can't emit a commit record without an xid, and we don't want to
- * force assigning an xid, because that'd be problematic for e.g.
- * vacuum. Hence we emit a bespoke record for the invalidations. We
- * don't want to use that in case a commit record is emitted, so they
- * happen synchronously with commits (besides not wanting to emit more
- * WAL records).
+ * messages. While inplace updates do this, this is not known to be
+ * necessary; see comment at inplace CacheInvalidateHeapTuple().
+ * Extensions might still rely on this capability, and standbys may
+ * need to process those invals. We can't emit a commit record
+ * without an xid, and we don't want to force assigning an xid,
+ * because that'd be problematic for e.g. vacuum. Hence we emit a
+ * bespoke record for the invalidations. We don't want to use that in
+ * case a commit record is emitted, so they happen synchronously with
+ * commits (besides not wanting to emit more WAL records).
+ *
+ * XXX Every known use of this capability is a defect. Since an XID
+ * isn't controlling visibility of the change that prompted invals,
+ * other sessions need the inval even if this transactions aborts.
+ *
+ * ON COMMIT DELETE ROWS does a nontransactional index_build(), which
+ * queues a relcache inval, including in transactions without an xid
+ * that had read the (empty) table. Standbys don't need any ON COMMIT
+ * DELETE ROWS invals, but we've not done the work to withhold them.
*/
if (nmsgs != 0)
{
@@ -1410,10 +1431,22 @@ RecordTransactionCommit(void)
* without holding the ProcArrayLock, since we're the only one
* modifying it. This makes checkpoint's determination of which xacts
* are delaying the checkpoint a bit fuzzy, but it doesn't matter.
+ *
+ * Note, it is important to get the commit timestamp after marking the
+ * transaction in the commit critical section. See
+ * RecordTransactionCommitPrepared.
*/
- Assert((MyProc->delayChkptFlags & DELAY_CHKPT_START) == 0);
+ Assert((MyProc->delayChkptFlags & DELAY_CHKPT_IN_COMMIT) == 0);
START_CRIT_SECTION();
- MyProc->delayChkptFlags |= DELAY_CHKPT_START;
+ MyProc->delayChkptFlags |= DELAY_CHKPT_IN_COMMIT;
+
+ Assert(xactStopTimestamp == 0);
+
+ /*
+ * Ensures the DELAY_CHKPT_IN_COMMIT flag write is globally visible
+ * before commit time is written.
+ */
+ pg_write_barrier();
/*
* Insert the commit XLOG record.
@@ -1516,7 +1549,7 @@ RecordTransactionCommit(void)
*/
if (markXidCommitted)
{
- MyProc->delayChkptFlags &= ~DELAY_CHKPT_START;
+ MyProc->delayChkptFlags &= ~DELAY_CHKPT_IN_COMMIT;
END_CRIT_SECTION();
}
@@ -1576,20 +1609,30 @@ AtCCI_LocalCache(void)
static void
AtCommit_Memory(void)
{
+ TransactionState s = CurrentTransactionState;
+
/*
- * Now that we're "out" of a transaction, have the system allocate things
- * in the top memory context instead of per-transaction contexts.
+ * Return to the memory context that was current before we started the
+ * transaction. (In principle, this could not be any of the contexts we
+ * are about to delete. If it somehow is, assertions in mcxt.c will
+ * complain.)
*/
- MemoryContextSwitchTo(TopMemoryContext);
+ MemoryContextSwitchTo(s->priorContext);
/*
- * Release all transaction-local memory.
+ * Release all transaction-local memory. TopTransactionContext survives
+ * but becomes empty; any sub-contexts go away.
*/
Assert(TopTransactionContext != NULL);
- MemoryContextDelete(TopTransactionContext);
- TopTransactionContext = NULL;
+ MemoryContextReset(TopTransactionContext);
+
+ /*
+ * Clear these pointers as a pro-forma matter. (Notionally, while
+ * TopTransactionContext still exists, it's currently not associated with
+ * this TransactionState struct.)
+ */
CurTransactionContext = NULL;
- CurrentTransactionState->curTransactionContext = NULL;
+ s->curTransactionContext = NULL;
}
/* ----------------------------------------------------------------
@@ -1942,13 +1985,18 @@ AtSubAbort_childXids(void)
static void
AtCleanup_Memory(void)
{
- Assert(CurrentTransactionState->parent == NULL);
+ TransactionState s = CurrentTransactionState;
+
+ /* Should be at top level */
+ Assert(s->parent == NULL);
/*
- * Now that we're "out" of a transaction, have the system allocate things
- * in the top memory context instead of per-transaction contexts.
+ * Return to the memory context that was current before we started the
+ * transaction. (In principle, this could not be any of the contexts we
+ * are about to delete. If it somehow is, assertions in mcxt.c will
+ * complain.)
*/
- MemoryContextSwitchTo(TopMemoryContext);
+ MemoryContextSwitchTo(s->priorContext);
/*
* Clear the special abort context for next time.
@@ -1957,13 +2005,20 @@ AtCleanup_Memory(void)
MemoryContextReset(TransactionAbortContext);
/*
- * Release all transaction-local memory.
+ * Release all transaction-local memory, the same as in AtCommit_Memory,
+ * except we must cope with the possibility that we didn't get as far as
+ * creating TopTransactionContext.
*/
if (TopTransactionContext != NULL)
- MemoryContextDelete(TopTransactionContext);
- TopTransactionContext = NULL;
+ MemoryContextReset(TopTransactionContext);
+
+ /*
+ * Clear these pointers as a pro-forma matter. (Notionally, while
+ * TopTransactionContext still exists, it's currently not associated with
+ * this TransactionState struct.)
+ */
CurTransactionContext = NULL;
- CurrentTransactionState->curTransactionContext = NULL;
+ s->curTransactionContext = NULL;
}
@@ -1982,8 +2037,15 @@ AtSubCleanup_Memory(void)
Assert(s->parent != NULL);
- /* Make sure we're not in an about-to-be-deleted context */
- MemoryContextSwitchTo(s->parent->curTransactionContext);
+ /*
+ * Return to the memory context that was current before we started the
+ * subtransaction. (In principle, this could not be any of the contexts
+ * we are about to delete. If it somehow is, assertions in mcxt.c will
+ * complain.)
+ */
+ MemoryContextSwitchTo(s->priorContext);
+
+ /* Update CurTransactionContext (might not be same as priorContext) */
CurTransactionContext = s->parent->curTransactionContext;
/*
@@ -2362,12 +2424,17 @@ CommitTransaction(void)
RESOURCE_RELEASE_BEFORE_LOCKS,
true, true);
+ AtEOXact_Aio(true);
+
/* Check we've released all buffer pins */
AtEOXact_Buffers(true);
/* Clean up the relation cache */
AtEOXact_RelationCache(true);
+ /* Clean up the type cache */
+ AtEOXact_TypeCache();
+
/*
* Make catalog changes visible to all backends. This has to happen after
* relcache references are dropped (see comments for
@@ -2460,7 +2527,7 @@ static void
PrepareTransaction(void)
{
TransactionState s = CurrentTransactionState;
- TransactionId xid = GetCurrentTransactionId();
+ FullTransactionId fxid = GetCurrentFullTransactionId();
GlobalTransaction gxact;
TimestampTz prepared_at;
@@ -2589,7 +2656,7 @@ PrepareTransaction(void)
* Reserve the GID for this transaction. This could fail if the requested
* GID is invalid or already in use.
*/
- gxact = MarkAsPreparing(xid, prepareGID, prepared_at,
+ gxact = MarkAsPreparing(fxid, prepareGID, prepared_at,
GetUserId(), MyDatabaseId);
prepareGID = NULL;
@@ -2639,7 +2706,7 @@ PrepareTransaction(void)
* ProcArrayClearTransaction(). Otherwise, a GetLockConflicts() would
* conclude "xact already committed or aborted" for our locks.
*/
- PostPrepare_Locks(xid);
+ PostPrepare_Locks(fxid);
/*
* Let others know about no transaction in progress by me. This has to be
@@ -2664,12 +2731,17 @@ PrepareTransaction(void)
RESOURCE_RELEASE_BEFORE_LOCKS,
true, true);
+ AtEOXact_Aio(true);
+
/* Check we've released all buffer pins */
AtEOXact_Buffers(true);
/* Clean up the relation cache */
AtEOXact_RelationCache(true);
+ /* Clean up the type cache */
+ AtEOXact_TypeCache();
+
/* notify doesn't need a postprepare call */
PostPrepare_PgStat();
@@ -2678,9 +2750,9 @@ PrepareTransaction(void)
PostPrepare_smgr();
- PostPrepare_MultiXact(xid);
+ PostPrepare_MultiXact(fxid);
- PostPrepare_PredicateLocks(xid);
+ PostPrepare_PredicateLocks(fxid);
ResourceOwnerRelease(TopTransactionResourceOwner,
RESOURCE_RELEASE_LOCKS,
@@ -2775,7 +2847,9 @@ AbortTransaction(void)
pgstat_report_wait_end();
pgstat_progress_end_command();
- /* Clean up buffer context locks, too */
+ pgaio_error_cleanup();
+
+ /* Clean up buffer content locks, too */
UnlockBuffers();
/* Reset WAL record construction state */
@@ -2905,8 +2979,10 @@ AbortTransaction(void)
ResourceOwnerRelease(TopTransactionResourceOwner,
RESOURCE_RELEASE_BEFORE_LOCKS,
false, true);
+ AtEOXact_Aio(false);
AtEOXact_Buffers(false);
AtEOXact_RelationCache(false);
+ AtEOXact_TypeCache();
AtEOXact_Inval(false);
AtEOXact_MultiXact();
ResourceOwnerRelease(TopTransactionResourceOwner,
@@ -3603,16 +3679,6 @@ PreventInTransactionBlock(bool isTopLevel, const char *stmtType)
errmsg("%s cannot run inside a subtransaction",
stmtType)));
- /*
- * inside a pipeline that has started an implicit transaction?
- */
- if (MyXactFlags & XACT_FLAGS_PIPELINING)
- ereport(ERROR,
- (errcode(ERRCODE_ACTIVE_SQL_TRANSACTION),
- /* translator: %s represents an SQL statement name */
- errmsg("%s cannot be executed within a pipeline",
- stmtType)));
-
/*
* inside a function call?
*/
@@ -3724,9 +3790,6 @@ IsInTransactionBlock(bool isTopLevel)
if (IsSubTransaction())
return true;
- if (MyXactFlags & XACT_FLAGS_PIPELINING)
- return true;
-
if (!isTopLevel)
return true;
@@ -4904,8 +4967,13 @@ AbortOutOfAnyTransaction(void)
/* Should be out of all subxacts now */
Assert(s->parent == NULL);
- /* If we didn't actually have anything to do, revert to TopMemoryContext */
- AtCleanup_Memory();
+ /*
+ * Revert to TopMemoryContext, to ensure we exit in a well-defined state
+ * whether there were any transactions to close or not. (Callers that
+ * don't intend to exit soon should switch to some other context to avoid
+ * long-term memory leaks.)
+ */
+ MemoryContextSwitchTo(TopMemoryContext);
}
/*
@@ -5104,6 +5172,7 @@ CommitSubTransaction(void)
true, false);
AtEOSubXact_RelationCache(true, s->subTransactionId,
s->parent->subTransactionId);
+ AtEOSubXact_TypeCache();
AtEOSubXact_Inval(true);
AtSubCommit_smgr();
@@ -5183,6 +5252,9 @@ AbortSubTransaction(void)
pgstat_report_wait_end();
pgstat_progress_end_command();
+
+ pgaio_error_cleanup();
+
UnlockBuffers();
/* Reset WAL record construction state */
@@ -5277,22 +5349,11 @@ AbortSubTransaction(void)
RESOURCE_RELEASE_BEFORE_LOCKS,
false, false);
+ AtEOXact_Aio(false);
AtEOSubXact_RelationCache(false, s->subTransactionId,
s->parent->subTransactionId);
-
-
- /*
- * AtEOSubXact_Inval sometimes needs to temporarily bump the refcount
- * on the relcache entries that it processes. We cannot use the
- * subtransaction's resource owner anymore, because we've already
- * started releasing it. But we can use the parent resource owner.
- */
- CurrentResourceOwner = s->parent->curTransactionOwner;
-
+ AtEOSubXact_TypeCache();
AtEOSubXact_Inval(false);
-
- CurrentResourceOwner = s->curTransactionOwner;
-
ResourceOwnerRelease(s->curTransactionOwner,
RESOURCE_RELEASE_LOCKS,
false, false);
@@ -5872,54 +5933,54 @@ XactLogCommitRecord(TimestampTz commit_time,
XLogBeginInsert();
- XLogRegisterData((char *) (&xlrec), sizeof(xl_xact_commit));
+ XLogRegisterData(&xlrec, sizeof(xl_xact_commit));
if (xl_xinfo.xinfo != 0)
- XLogRegisterData((char *) (&xl_xinfo.xinfo), sizeof(xl_xinfo.xinfo));
+ XLogRegisterData(&xl_xinfo.xinfo, sizeof(xl_xinfo.xinfo));
if (xl_xinfo.xinfo & XACT_XINFO_HAS_DBINFO)
- XLogRegisterData((char *) (&xl_dbinfo), sizeof(xl_dbinfo));
+ XLogRegisterData(&xl_dbinfo, sizeof(xl_dbinfo));
if (xl_xinfo.xinfo & XACT_XINFO_HAS_SUBXACTS)
{
- XLogRegisterData((char *) (&xl_subxacts),
+ XLogRegisterData(&xl_subxacts,
MinSizeOfXactSubxacts);
- XLogRegisterData((char *) subxacts,
+ XLogRegisterData(subxacts,
nsubxacts * sizeof(TransactionId));
}
if (xl_xinfo.xinfo & XACT_XINFO_HAS_RELFILELOCATORS)
{
- XLogRegisterData((char *) (&xl_relfilelocators),
+ XLogRegisterData(&xl_relfilelocators,
MinSizeOfXactRelfileLocators);
- XLogRegisterData((char *) rels,
+ XLogRegisterData(rels,
nrels * sizeof(RelFileLocator));
}
if (xl_xinfo.xinfo & XACT_XINFO_HAS_DROPPED_STATS)
{
- XLogRegisterData((char *) (&xl_dropped_stats),
+ XLogRegisterData(&xl_dropped_stats,
MinSizeOfXactStatsItems);
- XLogRegisterData((char *) droppedstats,
+ XLogRegisterData(droppedstats,
ndroppedstats * sizeof(xl_xact_stats_item));
}
if (xl_xinfo.xinfo & XACT_XINFO_HAS_INVALS)
{
- XLogRegisterData((char *) (&xl_invals), MinSizeOfXactInvals);
- XLogRegisterData((char *) msgs,
+ XLogRegisterData(&xl_invals, MinSizeOfXactInvals);
+ XLogRegisterData(msgs,
nmsgs * sizeof(SharedInvalidationMessage));
}
if (xl_xinfo.xinfo & XACT_XINFO_HAS_TWOPHASE)
{
- XLogRegisterData((char *) (&xl_twophase), sizeof(xl_xact_twophase));
+ XLogRegisterData(&xl_twophase, sizeof(xl_xact_twophase));
if (xl_xinfo.xinfo & XACT_XINFO_HAS_GID)
- XLogRegisterData(unconstify(char *, twophase_gid), strlen(twophase_gid) + 1);
+ XLogRegisterData(twophase_gid, strlen(twophase_gid) + 1);
}
if (xl_xinfo.xinfo & XACT_XINFO_HAS_ORIGIN)
- XLogRegisterData((char *) (&xl_origin), sizeof(xl_xact_origin));
+ XLogRegisterData(&xl_origin, sizeof(xl_xact_origin));
/* we allow filtering by xacts */
XLogSetRecordFlags(XLOG_INCLUDE_ORIGIN);
@@ -6025,47 +6086,47 @@ XactLogAbortRecord(TimestampTz abort_time,
XLogBeginInsert();
- XLogRegisterData((char *) (&xlrec), MinSizeOfXactAbort);
+ XLogRegisterData(&xlrec, MinSizeOfXactAbort);
if (xl_xinfo.xinfo != 0)
- XLogRegisterData((char *) (&xl_xinfo), sizeof(xl_xinfo));
+ XLogRegisterData(&xl_xinfo, sizeof(xl_xinfo));
if (xl_xinfo.xinfo & XACT_XINFO_HAS_DBINFO)
- XLogRegisterData((char *) (&xl_dbinfo), sizeof(xl_dbinfo));
+ XLogRegisterData(&xl_dbinfo, sizeof(xl_dbinfo));
if (xl_xinfo.xinfo & XACT_XINFO_HAS_SUBXACTS)
{
- XLogRegisterData((char *) (&xl_subxacts),
+ XLogRegisterData(&xl_subxacts,
MinSizeOfXactSubxacts);
- XLogRegisterData((char *) subxacts,
+ XLogRegisterData(subxacts,
nsubxacts * sizeof(TransactionId));
}
if (xl_xinfo.xinfo & XACT_XINFO_HAS_RELFILELOCATORS)
{
- XLogRegisterData((char *) (&xl_relfilelocators),
+ XLogRegisterData(&xl_relfilelocators,
MinSizeOfXactRelfileLocators);
- XLogRegisterData((char *) rels,
+ XLogRegisterData(rels,
nrels * sizeof(RelFileLocator));
}
if (xl_xinfo.xinfo & XACT_XINFO_HAS_DROPPED_STATS)
{
- XLogRegisterData((char *) (&xl_dropped_stats),
+ XLogRegisterData(&xl_dropped_stats,
MinSizeOfXactStatsItems);
- XLogRegisterData((char *) droppedstats,
+ XLogRegisterData(droppedstats,
ndroppedstats * sizeof(xl_xact_stats_item));
}
if (xl_xinfo.xinfo & XACT_XINFO_HAS_TWOPHASE)
{
- XLogRegisterData((char *) (&xl_twophase), sizeof(xl_xact_twophase));
+ XLogRegisterData(&xl_twophase, sizeof(xl_xact_twophase));
if (xl_xinfo.xinfo & XACT_XINFO_HAS_GID)
- XLogRegisterData(unconstify(char *, twophase_gid), strlen(twophase_gid) + 1);
+ XLogRegisterData(twophase_gid, strlen(twophase_gid) + 1);
}
if (xl_xinfo.xinfo & XACT_XINFO_HAS_ORIGIN)
- XLogRegisterData((char *) (&xl_origin), sizeof(xl_xact_origin));
+ XLogRegisterData(&xl_origin, sizeof(xl_xact_origin));
/* Include the replication origin */
XLogSetRecordFlags(XLOG_INCLUDE_ORIGIN);
@@ -6371,7 +6432,8 @@ xact_redo(XLogReaderState *record)
* gxact entry.
*/
LWLockAcquire(TwoPhaseStateLock, LW_EXCLUSIVE);
- PrepareRedoAdd(XLogRecGetData(record),
+ PrepareRedoAdd(InvalidFullTransactionId,
+ XLogRecGetData(record),
record->ReadRecPtr,
record->EndRecPtr,
XLogRecGetOrigin(record));
diff --git a/src/backend/access/transam/xlog.c b/src/backend/access/transam/xlog.c
index 330e058c5f28a..0baf0ac6160af 100644
--- a/src/backend/access/transam/xlog.c
+++ b/src/backend/access/transam/xlog.c
@@ -28,7 +28,7 @@
* the current system state, and for starting/stopping backups.
*
*
- * Portions Copyright (c) 1996-2024, PostgreSQL Global Development Group
+ * Portions Copyright (c) 1996-2025, PostgreSQL Global Development Group
* Portions Copyright (c) 1994, Regents of the University of California
*
* src/backend/access/transam/xlog.c
@@ -73,7 +73,6 @@
#include "pg_trace.h"
#include "pgstat.h"
#include "port/atomics.h"
-#include "port/pg_iovec.h"
#include "postmaster/bgwriter.h"
#include "postmaster/startup.h"
#include "postmaster/walsummarizer.h"
@@ -97,7 +96,7 @@
#include "utils/guc_hooks.h"
#include "utils/guc_tables.h"
#include "utils/injection_point.h"
-#include "utils/memutils.h"
+#include "utils/pgstat_internal.h"
#include "utils/ps_status.h"
#include "utils/relmapper.h"
#include "utils/snapmgr.h"
@@ -105,7 +104,9 @@
#include "utils/timestamp.h"
#include "utils/varlena.h"
-extern uint32 bootstrap_data_checksum_version;
+#ifdef WAL_DEBUG
+#include "utils/memutils.h"
+#endif
/* timeline ID to be used when bootstrapping */
#define BootstrapTimeLineID 1
@@ -454,7 +455,6 @@ typedef struct XLogCtlData
/* Protected by info_lck: */
XLogwrtRqst LogwrtRqst;
XLogRecPtr RedoRecPtr; /* a recent copy of Insert->RedoRecPtr */
- FullTransactionId ckptFullXid; /* nextXid of latest checkpoint */
XLogRecPtr asyncXactLSN; /* LSN of newest async commit/abort */
XLogRecPtr replicationSlotMinLSN; /* oldest LSN needed by any slot */
@@ -500,6 +500,11 @@ typedef struct XLogCtlData
* If we create a new timeline when the system was started up,
* PrevTimeLineID is the old timeline's ID that we forked off from.
* Otherwise it's equal to InsertTimeLineID.
+ *
+ * We set these fields while holding info_lck. Most that reads these
+ * values knows that recovery is no longer in progress and so can safely
+ * read the value without a lock, but code that could be run either during
+ * or after recovery can take info_lck while reading these values.
*/
TimeLineID InsertTimeLineID;
TimeLineID PrevTimeLineID;
@@ -549,7 +554,7 @@ typedef struct XLogCtlData
} XLogCtlData;
/*
- * Classification of XLogRecordInsert operations.
+ * Classification of XLogInsertRecord operations.
*/
typedef enum
{
@@ -683,11 +688,11 @@ static void ValidateXLOGDirectoryStructure(void);
static void CleanupBackupHistory(void);
static void UpdateMinRecoveryPoint(XLogRecPtr lsn, bool force);
static bool PerformRecoveryXLogAction(void);
-static void InitControlFile(uint64 sysidentifier);
+static void InitControlFile(uint64 sysidentifier, uint32 data_checksum_version);
static void WriteControlFile(void);
static void ReadControlFile(void);
static void UpdateControlFile(void);
-static char *str_time(pg_time_t tnow);
+static char *str_time(pg_time_t tnow, char *buf, size_t bufsize);
static int get_sync_bit(int method);
@@ -1012,7 +1017,7 @@ XLogInsertRecord(XLogRecData *rdata,
oldCxt = MemoryContextSwitchTo(walDebugCxt);
initStringInfo(&buf);
- appendStringInfo(&buf, "INSERT @ %X/%X: ", LSN_FORMAT_ARGS(EndPos));
+ appendStringInfo(&buf, "INSERT @ %X/%08X: ", LSN_FORMAT_ARGS(EndPos));
/*
* We have to piece together the WAL record data from the XLogRecData
@@ -1076,6 +1081,9 @@ XLogInsertRecord(XLogRecData *rdata,
pgWalUsage.wal_bytes += rechdr->xl_tot_len;
pgWalUsage.wal_records++;
pgWalUsage.wal_fpi += num_fpi;
+
+ /* Required for the flush of pending stats WAL data */
+ pgstat_report_fixed = true;
}
return EndPos;
@@ -1244,7 +1252,7 @@ CopyXLogRecordToWAL(int write_len, bool isLogSwitch, XLogRecData *rdata,
written = 0;
while (rdata != NULL)
{
- char *rdata_data = rdata->data;
+ const char *rdata_data = rdata->data;
int rdata_len = rdata->len;
while (rdata_len > freespace)
@@ -1533,8 +1541,8 @@ WaitXLogInsertionsToFinish(XLogRecPtr upto)
if (upto > reservedUpto)
{
ereport(LOG,
- (errmsg("request to flush past end of generated WAL; request %X/%X, current position %X/%X",
- LSN_FORMAT_ARGS(upto), LSN_FORMAT_ARGS(reservedUpto))));
+ errmsg("request to flush past end of generated WAL; request %X/%08X, current position %X/%08X",
+ LSN_FORMAT_ARGS(upto), LSN_FORMAT_ARGS(reservedUpto)));
upto = reservedUpto;
}
@@ -1700,7 +1708,7 @@ GetXLogBuffer(XLogRecPtr ptr, TimeLineID tli)
endptr = pg_atomic_read_u64(&XLogCtl->xlblocks[idx]);
if (expectedEndPtr != endptr)
- elog(PANIC, "could not find WAL buffer for %X/%X",
+ elog(PANIC, "could not find WAL buffer for %X/%08X",
LSN_FORMAT_ARGS(ptr));
}
else
@@ -1760,7 +1768,7 @@ WALReadFromBuffers(char *dstbuf, XLogRecPtr startptr, Size count,
inserted = pg_atomic_read_u64(&XLogCtl->logInsertResult);
if (startptr + count > inserted)
ereport(ERROR,
- errmsg("cannot read past end of generated WAL: requested %X/%X, current position %X/%X",
+ errmsg("cannot read past end of generated WAL: requested %X/%08X, current position %X/%08X",
LSN_FORMAT_ARGS(startptr + count),
LSN_FORMAT_ARGS(inserted)));
@@ -2052,8 +2060,14 @@ AdvanceXLInsertBuffer(XLogRecPtr upto, TimeLineID tli, bool opportunistic)
WriteRqst.Flush = 0;
XLogWrite(WriteRqst, tli, false);
LWLockRelease(WALWriteLock);
- PendingWalStats.wal_buffers_full++;
+ pgWalUsage.wal_buffers_full++;
TRACE_POSTGRESQL_WAL_BUFFER_WRITE_DIRTY_DONE();
+
+ /*
+ * Required for the flush of pending stats WAL data, per
+ * update of pgWalUsage.
+ */
+ pgstat_report_fixed = true;
}
/* Re-acquire WALBufMappingLock and retry */
LWLockAcquire(WALBufMappingLock, LW_EXCLUSIVE);
@@ -2084,7 +2098,7 @@ AdvanceXLInsertBuffer(XLogRecPtr upto, TimeLineID tli, bool opportunistic)
* Be sure to re-zero the buffer so that bytes beyond what we've
* written will look like zeroes and not valid XLOG records...
*/
- MemSet((char *) NewPage, 0, XLOG_BLCKSZ);
+ MemSet(NewPage, 0, XLOG_BLCKSZ);
/*
* Fill the new page's header
@@ -2143,7 +2157,7 @@ AdvanceXLInsertBuffer(XLogRecPtr upto, TimeLineID tli, bool opportunistic)
#ifdef WAL_DEBUG
if (XLOG_DEBUG && npages > 0)
{
- elog(DEBUG1, "initialized %d pages, up to %X/%X",
+ elog(DEBUG1, "initialized %d pages, up to %X/%08X",
npages, LSN_FORMAT_ARGS(NewPageEndPtr));
}
#endif
@@ -2208,25 +2222,6 @@ check_wal_segment_size(int *newval, void **extra, GucSource source)
return true;
}
-/*
- * GUC check_hook for max_slot_wal_keep_size
- *
- * We don't allow the value of max_slot_wal_keep_size other than -1 during the
- * binary upgrade. See start_postmaster() in pg_upgrade for more details.
- */
-bool
-check_max_slot_wal_keep_size(int *newval, void **extra, GucSource source)
-{
- if (IsBinaryUpgrade && *newval != -1)
- {
- GUC_check_errdetail("\"%s\" must be set to -1 during binary upgrade mode.",
- "max_slot_wal_keep_size");
- return false;
- }
-
- return true;
-}
-
/*
* At a checkpoint, how many WAL segments to recycle as preallocated future
* XLOG segments? Returns the highest segment that should be preallocated.
@@ -2354,7 +2349,7 @@ XLogWrite(XLogwrtRqst WriteRqst, TimeLineID tli, bool flexible)
XLogRecPtr EndPtr = pg_atomic_read_u64(&XLogCtl->xlblocks[curridx]);
if (LogwrtResult.Write >= EndPtr)
- elog(PANIC, "xlog write request %X/%X is past end of log %X/%X",
+ elog(PANIC, "xlog write request %X/%08X is past end of log %X/%08X",
LSN_FORMAT_ARGS(LogwrtResult.Write),
LSN_FORMAT_ARGS(EndPtr));
@@ -2430,29 +2425,17 @@ XLogWrite(XLogwrtRqst WriteRqst, TimeLineID tli, bool flexible)
{
errno = 0;
- /* Measure I/O timing to write WAL data */
- if (track_wal_io_timing)
- INSTR_TIME_SET_CURRENT(start);
- else
- INSTR_TIME_SET_ZERO(start);
+ /*
+ * Measure I/O timing to write WAL data, for pg_stat_io.
+ */
+ start = pgstat_prepare_io_time(track_wal_io_timing);
pgstat_report_wait_start(WAIT_EVENT_WAL_WRITE);
written = pg_pwrite(openLogFile, from, nleft, startoffset);
pgstat_report_wait_end();
- /*
- * Increment the I/O timing and the number of times WAL data
- * were written out to disk.
- */
- if (track_wal_io_timing)
- {
- instr_time end;
-
- INSTR_TIME_SET_CURRENT(end);
- INSTR_TIME_ACCUM_DIFF(PendingWalStats.wal_write_time, end, start);
- }
-
- PendingWalStats.wal_write++;
+ pgstat_count_io_op_time(IOOBJECT_WAL, IOCONTEXT_NORMAL,
+ IOOP_WRITE, start, 1, written);
if (written <= 0)
{
@@ -2665,8 +2648,14 @@ XLogSetAsyncXactLSN(XLogRecPtr asyncXactLSN)
wakeup = true;
}
- if (wakeup && ProcGlobal->walwriterLatch)
- SetLatch(ProcGlobal->walwriterLatch);
+ if (wakeup)
+ {
+ volatile PROC_HDR *procglobal = ProcGlobal;
+ ProcNumber walwriterProc = procglobal->walwriterProc;
+
+ if (walwriterProc != INVALID_PROC_NUMBER)
+ SetLatch(&GetPGProcByNumber(walwriterProc)->procLatch);
+ }
}
/*
@@ -2760,7 +2749,7 @@ UpdateMinRecoveryPoint(XLogRecPtr lsn, bool force)
newMinRecoveryPoint = GetCurrentReplayRecPtr(&newMinRecoveryPointTLI);
if (!force && newMinRecoveryPoint < lsn)
elog(WARNING,
- "xlog min recovery request %X/%X is past current point %X/%X",
+ "xlog min recovery request %X/%08X is past current point %X/%08X",
LSN_FORMAT_ARGS(lsn), LSN_FORMAT_ARGS(newMinRecoveryPoint));
/* update control file */
@@ -2773,9 +2762,9 @@ UpdateMinRecoveryPoint(XLogRecPtr lsn, bool force)
LocalMinRecoveryPointTLI = newMinRecoveryPointTLI;
ereport(DEBUG2,
- (errmsg_internal("updated min recovery point to %X/%X on timeline %u",
- LSN_FORMAT_ARGS(newMinRecoveryPoint),
- newMinRecoveryPointTLI)));
+ errmsg_internal("updated min recovery point to %X/%08X on timeline %u",
+ LSN_FORMAT_ARGS(newMinRecoveryPoint),
+ newMinRecoveryPointTLI));
}
}
LWLockRelease(ControlFileLock);
@@ -2813,7 +2802,7 @@ XLogFlush(XLogRecPtr record)
#ifdef WAL_DEBUG
if (XLOG_DEBUG)
- elog(LOG, "xlog flush request %X/%X; write %X/%X; flush %X/%X",
+ elog(LOG, "xlog flush request %X/%08X; write %X/%08X; flush %X/%08X",
LSN_FORMAT_ARGS(record),
LSN_FORMAT_ARGS(LogwrtResult.Write),
LSN_FORMAT_ARGS(LogwrtResult.Flush));
@@ -2946,7 +2935,7 @@ XLogFlush(XLogRecPtr record)
*/
if (LogwrtResult.Flush < record)
elog(ERROR,
- "xlog flush request %X/%X is not satisfied --- flushed only to %X/%X",
+ "xlog flush request %X/%08X is not satisfied --- flushed only to %X/%08X",
LSN_FORMAT_ARGS(record),
LSN_FORMAT_ARGS(LogwrtResult.Flush));
}
@@ -3073,7 +3062,7 @@ XLogBackgroundFlush(void)
#ifdef WAL_DEBUG
if (XLOG_DEBUG)
- elog(LOG, "xlog bg flush request write %X/%X; flush: %X/%X, current is write %X/%X; flush %X/%X",
+ elog(LOG, "xlog bg flush request write %X/%08X; flush: %X/%08X, current is write %X/%08X; flush %X/%08X",
LSN_FORMAT_ARGS(WriteRqst.Write),
LSN_FORMAT_ARGS(WriteRqst.Flush),
LSN_FORMAT_ARGS(LogwrtResult.Write),
@@ -3205,6 +3194,7 @@ XLogFileInitInternal(XLogSegNo logsegno, TimeLineID logtli,
int fd;
int save_errno;
int open_flags = O_RDWR | O_CREAT | O_EXCL | PG_BINARY;
+ instr_time io_start;
Assert(logtli != 0);
@@ -3248,6 +3238,9 @@ XLogFileInitInternal(XLogSegNo logsegno, TimeLineID logtli,
(errcode_for_file_access(),
errmsg("could not create file \"%s\": %m", tmppath)));
+ /* Measure I/O timing when initializing segment */
+ io_start = pgstat_prepare_io_time(track_wal_io_timing);
+
pgstat_report_wait_start(WAIT_EVENT_WAL_INIT_WRITE);
save_errno = 0;
if (wal_init_zero)
@@ -3283,6 +3276,14 @@ XLogFileInitInternal(XLogSegNo logsegno, TimeLineID logtli,
}
pgstat_report_wait_end();
+ /*
+ * A full segment worth of data is written when using wal_init_zero. One
+ * byte is written when not using it.
+ */
+ pgstat_count_io_op_time(IOOBJECT_WAL, IOCONTEXT_INIT, IOOP_WRITE,
+ io_start, 1,
+ wal_init_zero ? wal_segment_size : 1);
+
if (save_errno)
{
/*
@@ -3299,6 +3300,9 @@ XLogFileInitInternal(XLogSegNo logsegno, TimeLineID logtli,
errmsg("could not write to file \"%s\": %m", tmppath)));
}
+ /* Measure I/O timing when flushing segment */
+ io_start = pgstat_prepare_io_time(track_wal_io_timing);
+
pgstat_report_wait_start(WAIT_EVENT_WAL_INIT_SYNC);
if (pg_fsync(fd) != 0)
{
@@ -3311,6 +3315,9 @@ XLogFileInitInternal(XLogSegNo logsegno, TimeLineID logtli,
}
pgstat_report_wait_end();
+ pgstat_count_io_op_time(IOOBJECT_WAL, IOCONTEXT_INIT,
+ IOOP_FSYNC, io_start, 1, 0);
+
if (close(fd) != 0)
ereport(ERROR,
(errcode_for_file_access(),
@@ -4190,7 +4197,7 @@ CleanupBackupHistory(void)
*/
static void
-InitControlFile(uint64 sysidentifier)
+InitControlFile(uint64 sysidentifier, uint32 data_checksum_version)
{
char mock_auth_nonce[MOCK_AUTH_NONCE_LEN];
@@ -4221,7 +4228,7 @@ InitControlFile(uint64 sysidentifier)
ControlFile->wal_level = wal_level;
ControlFile->wal_log_hints = wal_log_hints;
ControlFile->track_commit_timestamp = track_commit_timestamp;
- ControlFile->data_checksum_version = bootstrap_data_checksum_version;
+ ControlFile->data_checksum_version = data_checksum_version;
}
static void
@@ -4250,12 +4257,39 @@ WriteControlFile(void)
ControlFile->toast_max_chunk_size = TOAST_MAX_CHUNK_SIZE;
ControlFile->loblksize = LOBLKSIZE;
- ControlFile->float8ByVal = FLOAT8PASSBYVAL;
+ ControlFile->float8ByVal = true; /* vestigial */
+
+ /*
+ * Initialize the default 'char' signedness.
+ *
+ * The signedness of the char type is implementation-defined. For instance
+ * on x86 architecture CPUs, the char data type is typically treated as
+ * signed by default, whereas on aarch architecture CPUs, it is typically
+ * treated as unsigned by default. In v17 or earlier, we accidentally let
+ * C implementation signedness affect persistent data. This led to
+ * inconsistent results when comparing char data across different
+ * platforms.
+ *
+ * This flag can be used as a hint to ensure consistent behavior for
+ * pre-v18 data files that store data sorted by the 'char' type on disk,
+ * especially in cross-platform replication scenarios.
+ *
+ * Newly created database clusters unconditionally set the default char
+ * signedness to true. pg_upgrade changes this flag for clusters that were
+ * initialized on signedness=false platforms. As a result,
+ * signedness=false setting will become rare over time. If we had known
+ * about this problem during the last development cycle that forced initdb
+ * (v8.3), we would have made all clusters signed or all clusters
+ * unsigned. Making pg_upgrade the only source of signedness=false will
+ * cause the population of database clusters to converge toward that
+ * retrospective ideal.
+ */
+ ControlFile->default_char_signedness = true;
/* Contents are protected with a CRC */
INIT_CRC32C(ControlFile->crc);
COMP_CRC32C(ControlFile->crc,
- (char *) ControlFile,
+ ControlFile,
offsetof(ControlFileData, crc));
FIN_CRC32C(ControlFile->crc);
@@ -4311,7 +4345,7 @@ ReadControlFile(void)
{
pg_crc32c crc;
int fd;
- static char wal_segsz_str[20];
+ char wal_segsz_str[20];
int r;
/*
@@ -4373,7 +4407,7 @@ ReadControlFile(void)
/* Now check the CRC. */
INIT_CRC32C(crc);
COMP_CRC32C(crc,
- (char *) ControlFile,
+ ControlFile,
offsetof(ControlFileData, crc));
FIN_CRC32C(crc);
@@ -4391,17 +4425,21 @@ ReadControlFile(void)
ereport(FATAL,
(errcode(ERRCODE_OBJECT_NOT_IN_PREREQUISITE_STATE),
errmsg("database files are incompatible with server"),
- errdetail("The database cluster was initialized with CATALOG_VERSION_NO %d,"
- " but the server was compiled with CATALOG_VERSION_NO %d.",
- ControlFile->catalog_version_no, CATALOG_VERSION_NO),
+ /* translator: %s is a variable name and %d is its value */
+ errdetail("The database cluster was initialized with %s %d,"
+ " but the server was compiled with %s %d.",
+ "CATALOG_VERSION_NO", ControlFile->catalog_version_no,
+ "CATALOG_VERSION_NO", CATALOG_VERSION_NO),
errhint("It looks like you need to initdb.")));
if (ControlFile->maxAlign != MAXIMUM_ALIGNOF)
ereport(FATAL,
(errcode(ERRCODE_OBJECT_NOT_IN_PREREQUISITE_STATE),
errmsg("database files are incompatible with server"),
- errdetail("The database cluster was initialized with MAXALIGN %d,"
- " but the server was compiled with MAXALIGN %d.",
- ControlFile->maxAlign, MAXIMUM_ALIGNOF),
+ /* translator: %s is a variable name and %d is its value */
+ errdetail("The database cluster was initialized with %s %d,"
+ " but the server was compiled with %s %d.",
+ "MAXALIGN", ControlFile->maxAlign,
+ "MAXALIGN", MAXIMUM_ALIGNOF),
errhint("It looks like you need to initdb.")));
if (ControlFile->floatFormat != FLOATFORMAT_VALUE)
ereport(FATAL,
@@ -4413,76 +4451,74 @@ ReadControlFile(void)
ereport(FATAL,
(errcode(ERRCODE_OBJECT_NOT_IN_PREREQUISITE_STATE),
errmsg("database files are incompatible with server"),
- errdetail("The database cluster was initialized with BLCKSZ %d,"
- " but the server was compiled with BLCKSZ %d.",
- ControlFile->blcksz, BLCKSZ),
+ /* translator: %s is a variable name and %d is its value */
+ errdetail("The database cluster was initialized with %s %d,"
+ " but the server was compiled with %s %d.",
+ "BLCKSZ", ControlFile->blcksz,
+ "BLCKSZ", BLCKSZ),
errhint("It looks like you need to recompile or initdb.")));
if (ControlFile->relseg_size != RELSEG_SIZE)
ereport(FATAL,
(errcode(ERRCODE_OBJECT_NOT_IN_PREREQUISITE_STATE),
errmsg("database files are incompatible with server"),
- errdetail("The database cluster was initialized with RELSEG_SIZE %d,"
- " but the server was compiled with RELSEG_SIZE %d.",
- ControlFile->relseg_size, RELSEG_SIZE),
+ /* translator: %s is a variable name and %d is its value */
+ errdetail("The database cluster was initialized with %s %d,"
+ " but the server was compiled with %s %d.",
+ "RELSEG_SIZE", ControlFile->relseg_size,
+ "RELSEG_SIZE", RELSEG_SIZE),
errhint("It looks like you need to recompile or initdb.")));
if (ControlFile->xlog_blcksz != XLOG_BLCKSZ)
ereport(FATAL,
(errcode(ERRCODE_OBJECT_NOT_IN_PREREQUISITE_STATE),
errmsg("database files are incompatible with server"),
- errdetail("The database cluster was initialized with XLOG_BLCKSZ %d,"
- " but the server was compiled with XLOG_BLCKSZ %d.",
- ControlFile->xlog_blcksz, XLOG_BLCKSZ),
+ /* translator: %s is a variable name and %d is its value */
+ errdetail("The database cluster was initialized with %s %d,"
+ " but the server was compiled with %s %d.",
+ "XLOG_BLCKSZ", ControlFile->xlog_blcksz,
+ "XLOG_BLCKSZ", XLOG_BLCKSZ),
errhint("It looks like you need to recompile or initdb.")));
if (ControlFile->nameDataLen != NAMEDATALEN)
ereport(FATAL,
(errcode(ERRCODE_OBJECT_NOT_IN_PREREQUISITE_STATE),
errmsg("database files are incompatible with server"),
- errdetail("The database cluster was initialized with NAMEDATALEN %d,"
- " but the server was compiled with NAMEDATALEN %d.",
- ControlFile->nameDataLen, NAMEDATALEN),
+ /* translator: %s is a variable name and %d is its value */
+ errdetail("The database cluster was initialized with %s %d,"
+ " but the server was compiled with %s %d.",
+ "NAMEDATALEN", ControlFile->nameDataLen,
+ "NAMEDATALEN", NAMEDATALEN),
errhint("It looks like you need to recompile or initdb.")));
if (ControlFile->indexMaxKeys != INDEX_MAX_KEYS)
ereport(FATAL,
(errcode(ERRCODE_OBJECT_NOT_IN_PREREQUISITE_STATE),
errmsg("database files are incompatible with server"),
- errdetail("The database cluster was initialized with INDEX_MAX_KEYS %d,"
- " but the server was compiled with INDEX_MAX_KEYS %d.",
- ControlFile->indexMaxKeys, INDEX_MAX_KEYS),
+ /* translator: %s is a variable name and %d is its value */
+ errdetail("The database cluster was initialized with %s %d,"
+ " but the server was compiled with %s %d.",
+ "INDEX_MAX_KEYS", ControlFile->indexMaxKeys,
+ "INDEX_MAX_KEYS", INDEX_MAX_KEYS),
errhint("It looks like you need to recompile or initdb.")));
if (ControlFile->toast_max_chunk_size != TOAST_MAX_CHUNK_SIZE)
ereport(FATAL,
(errcode(ERRCODE_OBJECT_NOT_IN_PREREQUISITE_STATE),
errmsg("database files are incompatible with server"),
- errdetail("The database cluster was initialized with TOAST_MAX_CHUNK_SIZE %d,"
- " but the server was compiled with TOAST_MAX_CHUNK_SIZE %d.",
- ControlFile->toast_max_chunk_size, (int) TOAST_MAX_CHUNK_SIZE),
+ /* translator: %s is a variable name and %d is its value */
+ errdetail("The database cluster was initialized with %s %d,"
+ " but the server was compiled with %s %d.",
+ "TOAST_MAX_CHUNK_SIZE", ControlFile->toast_max_chunk_size,
+ "TOAST_MAX_CHUNK_SIZE", (int) TOAST_MAX_CHUNK_SIZE),
errhint("It looks like you need to recompile or initdb.")));
if (ControlFile->loblksize != LOBLKSIZE)
ereport(FATAL,
(errcode(ERRCODE_OBJECT_NOT_IN_PREREQUISITE_STATE),
errmsg("database files are incompatible with server"),
- errdetail("The database cluster was initialized with LOBLKSIZE %d,"
- " but the server was compiled with LOBLKSIZE %d.",
- ControlFile->loblksize, (int) LOBLKSIZE),
+ /* translator: %s is a variable name and %d is its value */
+ errdetail("The database cluster was initialized with %s %d,"
+ " but the server was compiled with %s %d.",
+ "LOBLKSIZE", ControlFile->loblksize,
+ "LOBLKSIZE", (int) LOBLKSIZE),
errhint("It looks like you need to recompile or initdb.")));
-#ifdef USE_FLOAT8_BYVAL
- if (ControlFile->float8ByVal != true)
- ereport(FATAL,
- (errcode(ERRCODE_OBJECT_NOT_IN_PREREQUISITE_STATE),
- errmsg("database files are incompatible with server"),
- errdetail("The database cluster was initialized without USE_FLOAT8_BYVAL"
- " but the server was compiled with USE_FLOAT8_BYVAL."),
- errhint("It looks like you need to recompile or initdb.")));
-#else
- if (ControlFile->float8ByVal != false)
- ereport(FATAL,
- (errcode(ERRCODE_OBJECT_NOT_IN_PREREQUISITE_STATE),
- errmsg("database files are incompatible with server"),
- errdetail("The database cluster was initialized with USE_FLOAT8_BYVAL"
- " but the server was compiled without USE_FLOAT8_BYVAL."),
- errhint("It looks like you need to recompile or initdb.")));
-#endif
+ Assert(ControlFile->float8ByVal); /* vestigial, not worth an error msg */
wal_segment_size = ControlFile->xlog_seg_size;
@@ -4501,11 +4537,15 @@ ReadControlFile(void)
/* check and update variables dependent on wal_segment_size */
if (ConvertToXSegs(min_wal_size_mb, wal_segment_size) < 2)
ereport(ERROR, (errcode(ERRCODE_INVALID_PARAMETER_VALUE),
- errmsg("\"min_wal_size\" must be at least twice \"wal_segment_size\"")));
+ /* translator: both %s are GUC names */
+ errmsg("\"%s\" must be at least twice \"%s\"",
+ "min_wal_size", "wal_segment_size")));
if (ConvertToXSegs(max_wal_size_mb, wal_segment_size) < 2)
ereport(ERROR, (errcode(ERRCODE_INVALID_PARAMETER_VALUE),
- errmsg("\"max_wal_size\" must be at least twice \"wal_segment_size\"")));
+ /* translator: both %s are GUC names */
+ errmsg("\"%s\" must be at least twice \"%s\"",
+ "max_wal_size", "wal_segment_size")));
UsableBytesInSegment =
(wal_segment_size / XLOG_BLCKSZ * UsableBytesInPage) -
@@ -4558,6 +4598,19 @@ DataChecksumsEnabled(void)
return (ControlFile->data_checksum_version > 0);
}
+/*
+ * Return true if the cluster was initialized on a platform where the
+ * default signedness of char is "signed". This function exists for code
+ * that deals with pre-v18 data files that store data sorted by the 'char'
+ * type on disk (e.g., GIN and GiST indexes). See the comments in
+ * WriteControlFile() for details.
+ */
+bool
+GetDefaultCharSignedness(void)
+{
+ return ControlFile->default_char_signedness;
+}
+
/*
* Returns a fake LSN for unlogged relations.
*
@@ -4712,7 +4765,9 @@ check_wal_consistency_checking(char **newval, void **extra, GucSource source)
list_free(elemlist);
/* assign new value */
- *extra = guc_malloc(ERROR, (RM_MAX_ID + 1) * sizeof(bool));
+ *extra = guc_malloc(LOG, (RM_MAX_ID + 1) * sizeof(bool));
+ if (!*extra)
+ return false;
memcpy(*extra, newwalconsistency, (RM_MAX_ID + 1) * sizeof(bool));
return true;
}
@@ -4997,7 +5052,7 @@ XLOGShmemInit(void)
* and the initial XLOG segment.
*/
void
-BootStrapXLOG(void)
+BootStrapXLOG(uint32 data_checksum_version)
{
CheckPoint checkPoint;
char *buffer;
@@ -5045,6 +5100,7 @@ BootStrapXLOG(void)
checkPoint.ThisTimeLineID = BootstrapTimeLineID;
checkPoint.PrevTimeLineID = BootstrapTimeLineID;
checkPoint.fullPageWrites = fullPageWrites;
+ checkPoint.wal_level = wal_level;
checkPoint.nextXid =
FullTransactionIdFromEpochAndXid(0, FirstNormalTransactionId);
checkPoint.nextOid = FirstGenbkiObjectId;
@@ -5138,7 +5194,7 @@ BootStrapXLOG(void)
openLogFile = -1;
/* Now create pg_control */
- InitControlFile(sysidentifier);
+ InitControlFile(sysidentifier, data_checksum_version);
ControlFile->time = checkPoint.time;
ControlFile->checkPoint = checkPoint.redo;
ControlFile->checkPointCopy = checkPoint;
@@ -5162,11 +5218,9 @@ BootStrapXLOG(void)
}
static char *
-str_time(pg_time_t tnow)
+str_time(pg_time_t tnow, char *buf, size_t bufsize)
{
- static char buf[128];
-
- pg_strftime(buf, sizeof(buf),
+ pg_strftime(buf, bufsize,
"%Y-%m-%d %H:%M:%S %Z",
pg_localtime(&tnow, log_timezone));
@@ -5316,6 +5370,13 @@ CleanupAfterArchiveRecovery(TimeLineID EndOfLogTLI, XLogRecPtr EndOfLog,
char partialfname[MAXFNAMELEN];
char partialpath[MAXPGPATH];
+ /*
+ * If we're summarizing WAL, we can't rename the partial file
+ * until the summarizer finishes with it, else it will fail.
+ */
+ if (summarize_wal)
+ WaitForWalSummarization(EndOfLog);
+
XLogFilePath(origpath, EndOfLogTLI, endLogSegNo, wal_segment_size);
snprintf(partialfname, MAXFNAMELEN, "%s.partial", origfname);
snprintf(partialpath, MAXPGPATH, "%s.partial", origpath);
@@ -5362,7 +5423,7 @@ CheckRequiredParameterValues(void)
*/
if (ArchiveRecoveryRequested && EnableHotStandby)
{
- /* We ignore autovacuum_max_workers when we make this test. */
+ /* We ignore autovacuum_worker_slots when we make this test. */
RecoveryRequiresIntParameter("max_connections",
MaxConnections,
ControlFile->MaxConnections);
@@ -5402,6 +5463,7 @@ StartupXLOG(void)
XLogRecPtr missingContrecPtr;
TransactionId oldestActiveXID;
bool promoted = false;
+ char timebuf[128];
/*
* We should have an aux process resource owner to use, and we should not
@@ -5430,25 +5492,29 @@ StartupXLOG(void)
*/
ereport(IsPostmasterEnvironment ? LOG : NOTICE,
(errmsg("database system was shut down at %s",
- str_time(ControlFile->time))));
+ str_time(ControlFile->time,
+ timebuf, sizeof(timebuf)))));
break;
case DB_SHUTDOWNED_IN_RECOVERY:
ereport(LOG,
(errmsg("database system was shut down in recovery at %s",
- str_time(ControlFile->time))));
+ str_time(ControlFile->time,
+ timebuf, sizeof(timebuf)))));
break;
case DB_SHUTDOWNING:
ereport(LOG,
(errmsg("database system shutdown was interrupted; last known up at %s",
- str_time(ControlFile->time))));
+ str_time(ControlFile->time,
+ timebuf, sizeof(timebuf)))));
break;
case DB_IN_CRASH_RECOVERY:
ereport(LOG,
(errmsg("database system was interrupted while in recovery at %s",
- str_time(ControlFile->time)),
+ str_time(ControlFile->time,
+ timebuf, sizeof(timebuf))),
errhint("This probably means that some data is corrupted and"
" you will have to use the last backup for recovery.")));
break;
@@ -5456,7 +5522,8 @@ StartupXLOG(void)
case DB_IN_ARCHIVE_RECOVERY:
ereport(LOG,
(errmsg("database system was interrupted while in recovery at log time %s",
- str_time(ControlFile->checkPointCopy.time)),
+ str_time(ControlFile->checkPointCopy.time,
+ timebuf, sizeof(timebuf))),
errhint("If this has occurred more than once some data might be corrupted"
" and you might need to choose an earlier recovery target.")));
break;
@@ -5464,7 +5531,8 @@ StartupXLOG(void)
case DB_IN_PRODUCTION:
ereport(LOG,
(errmsg("database system was interrupted; last known up at %s",
- str_time(ControlFile->time))));
+ str_time(ControlFile->time,
+ timebuf, sizeof(timebuf)))));
break;
default:
@@ -5537,7 +5605,6 @@ StartupXLOG(void)
SetMultiXactIdLimit(checkPoint.oldestMulti, checkPoint.oldestMultiDB, true);
SetCommitTsLimit(checkPoint.oldestCommitTsXid,
checkPoint.newestCommitTsXid);
- XLogCtl->ckptFullXid = checkPoint.nextXid;
/*
* Clear out any old relcache cache files. This is *necessary* if we do
@@ -5777,6 +5844,9 @@ StartupXLOG(void)
RunningTransactionsData running;
TransactionId latestCompletedXid;
+ /* Update pg_subtrans entries for any prepared transactions */
+ StandbyRecoverPreparedTransactions();
+
/*
* Construct a RunningTransactions snapshot representing a
* shut down server, with only prepared transactions still
@@ -5785,7 +5855,7 @@ StartupXLOG(void)
*/
running.xcnt = nxids;
running.subxcnt = 0;
- running.subxid_overflow = false;
+ running.subxid_status = SUBXIDS_IN_SUBTRANS;
running.nextXid = XidFromFullTransactionId(checkPoint.nextXid);
running.oldestRunningXid = oldestActiveXID;
latestCompletedXid = XidFromFullTransactionId(checkPoint.nextXid);
@@ -5795,8 +5865,6 @@ StartupXLOG(void)
running.xids = xids;
ProcArrayApplyRecoveryInfo(&running);
-
- StandbyRecoverPreparedTransactions();
}
}
@@ -5945,8 +6013,10 @@ StartupXLOG(void)
}
/* Save the selected TimeLineID in shared memory, too */
+ SpinLockAcquire(&XLogCtl->info_lck);
XLogCtl->InsertTimeLineID = newTLI;
XLogCtl->PrevTimeLineID = endOfRecoveryInfo->lastRecTLI;
+ SpinLockRelease(&XLogCtl->info_lck);
/*
* Actually, if WAL ended in an incomplete record, skip the parts that
@@ -6057,7 +6127,7 @@ StartupXLOG(void)
/*
* Reload shared-memory state for prepared transactions. This needs to
* happen before renaming the last partial segment of the old timeline as
- * it may be possible that we have to recovery some transactions from it.
+ * it may be possible that we have to recover some transactions from it.
*/
RecoverPreparedTransactions();
@@ -6104,6 +6174,12 @@ StartupXLOG(void)
*/
CompleteCommitTsInitialization();
+ /* Clean up EndOfWalRecoveryInfo data to appease Valgrind leak checking */
+ if (endOfRecoveryInfo->lastPage)
+ pfree(endOfRecoveryInfo->lastPage);
+ pfree(endOfRecoveryInfo->recoveryStopReason);
+ pfree(endOfRecoveryInfo);
+
/*
* All done with end-of-recovery actions.
*
@@ -6273,7 +6349,7 @@ PerformRecoveryXLogAction(void)
else
{
RequestCheckpoint(CHECKPOINT_END_OF_RECOVERY |
- CHECKPOINT_IMMEDIATE |
+ CHECKPOINT_FAST |
CHECKPOINT_WAIT);
}
@@ -6481,6 +6557,25 @@ GetWALInsertionTimeLine(void)
return XLogCtl->InsertTimeLineID;
}
+/*
+ * GetWALInsertionTimeLineIfSet -- If the system is not in recovery, returns
+ * the WAL insertion timeline; else, returns 0. Wherever possible, use
+ * GetWALInsertionTimeLine() instead, since it's cheaper. Note that this
+ * function decides recovery has ended as soon as the insert TLI is set, which
+ * happens before we set XLogCtl->SharedRecoveryState to RECOVERY_STATE_DONE.
+ */
+TimeLineID
+GetWALInsertionTimeLineIfSet(void)
+{
+ TimeLineID insertTLI;
+
+ SpinLockAcquire(&XLogCtl->info_lck);
+ insertTLI = XLogCtl->InsertTimeLineID;
+ SpinLockRelease(&XLogCtl->info_lck);
+
+ return insertTLI;
+}
+
/*
* GetLastImportantRecPtr -- Returns the LSN of the last important record
* inserted. All records not explicitly marked as unimportant are considered
@@ -6563,7 +6658,7 @@ ShutdownXLOG(int code, Datum arg)
WalSndWaitStopping();
if (RecoveryInProgress())
- CreateRestartPoint(CHECKPOINT_IS_SHUTDOWN | CHECKPOINT_IMMEDIATE);
+ CreateRestartPoint(CHECKPOINT_IS_SHUTDOWN | CHECKPOINT_FAST);
else
{
/*
@@ -6575,7 +6670,7 @@ ShutdownXLOG(int code, Datum arg)
if (XLogArchivingActive())
RequestXLogSwitch(false);
- CreateCheckPoint(CHECKPOINT_IS_SHUTDOWN | CHECKPOINT_IMMEDIATE);
+ CreateCheckPoint(CHECKPOINT_IS_SHUTDOWN | CHECKPOINT_FAST);
}
}
@@ -6591,24 +6686,24 @@ LogCheckpointStart(int flags, bool restartpoint)
(errmsg("restartpoint starting:%s%s%s%s%s%s%s%s",
(flags & CHECKPOINT_IS_SHUTDOWN) ? " shutdown" : "",
(flags & CHECKPOINT_END_OF_RECOVERY) ? " end-of-recovery" : "",
- (flags & CHECKPOINT_IMMEDIATE) ? " immediate" : "",
+ (flags & CHECKPOINT_FAST) ? " fast" : "",
(flags & CHECKPOINT_FORCE) ? " force" : "",
(flags & CHECKPOINT_WAIT) ? " wait" : "",
(flags & CHECKPOINT_CAUSE_XLOG) ? " wal" : "",
(flags & CHECKPOINT_CAUSE_TIME) ? " time" : "",
- (flags & CHECKPOINT_FLUSH_ALL) ? " flush-all" : "")));
+ (flags & CHECKPOINT_FLUSH_UNLOGGED) ? " flush-unlogged" : "")));
else
ereport(LOG,
/* translator: the placeholders show checkpoint options */
(errmsg("checkpoint starting:%s%s%s%s%s%s%s%s",
(flags & CHECKPOINT_IS_SHUTDOWN) ? " shutdown" : "",
(flags & CHECKPOINT_END_OF_RECOVERY) ? " end-of-recovery" : "",
- (flags & CHECKPOINT_IMMEDIATE) ? " immediate" : "",
+ (flags & CHECKPOINT_FAST) ? " fast" : "",
(flags & CHECKPOINT_FORCE) ? " force" : "",
(flags & CHECKPOINT_WAIT) ? " wait" : "",
(flags & CHECKPOINT_CAUSE_XLOG) ? " wal" : "",
(flags & CHECKPOINT_CAUSE_TIME) ? " time" : "",
- (flags & CHECKPOINT_FLUSH_ALL) ? " flush-all" : "")));
+ (flags & CHECKPOINT_FLUSH_UNLOGGED) ? " flush-unlogged" : "")));
}
/*
@@ -6665,14 +6760,15 @@ LogCheckpointEnd(bool restartpoint)
*/
if (restartpoint)
ereport(LOG,
- (errmsg("restartpoint complete: wrote %d buffers (%.1f%%); "
- "%d WAL file(s) added, %d removed, %d recycled; "
- "write=%ld.%03d s, sync=%ld.%03d s, total=%ld.%03d s; "
- "sync files=%d, longest=%ld.%03d s, average=%ld.%03d s; "
- "distance=%d kB, estimate=%d kB; "
- "lsn=%X/%X, redo lsn=%X/%X",
+ (errmsg("restartpoint complete: wrote %d buffers (%.1f%%), "
+ "wrote %d SLRU buffers; %d WAL file(s) added, "
+ "%d removed, %d recycled; write=%ld.%03d s, "
+ "sync=%ld.%03d s, total=%ld.%03d s; sync files=%d, "
+ "longest=%ld.%03d s, average=%ld.%03d s; distance=%d kB, "
+ "estimate=%d kB; lsn=%X/%08X, redo lsn=%X/%08X",
CheckpointStats.ckpt_bufs_written,
(double) CheckpointStats.ckpt_bufs_written * 100 / NBuffers,
+ CheckpointStats.ckpt_slru_written,
CheckpointStats.ckpt_segs_added,
CheckpointStats.ckpt_segs_removed,
CheckpointStats.ckpt_segs_recycled,
@@ -6688,14 +6784,15 @@ LogCheckpointEnd(bool restartpoint)
LSN_FORMAT_ARGS(ControlFile->checkPointCopy.redo))));
else
ereport(LOG,
- (errmsg("checkpoint complete: wrote %d buffers (%.1f%%); "
- "%d WAL file(s) added, %d removed, %d recycled; "
- "write=%ld.%03d s, sync=%ld.%03d s, total=%ld.%03d s; "
- "sync files=%d, longest=%ld.%03d s, average=%ld.%03d s; "
- "distance=%d kB, estimate=%d kB; "
- "lsn=%X/%X, redo lsn=%X/%X",
+ (errmsg("checkpoint complete: wrote %d buffers (%.1f%%), "
+ "wrote %d SLRU buffers; %d WAL file(s) added, "
+ "%d removed, %d recycled; write=%ld.%03d s, "
+ "sync=%ld.%03d s, total=%ld.%03d s; sync files=%d, "
+ "longest=%ld.%03d s, average=%ld.%03d s; distance=%d kB, "
+ "estimate=%d kB; lsn=%X/%08X, redo lsn=%X/%08X",
CheckpointStats.ckpt_bufs_written,
(double) CheckpointStats.ckpt_bufs_written * 100 / NBuffers,
+ CheckpointStats.ckpt_slru_written,
CheckpointStats.ckpt_segs_added,
CheckpointStats.ckpt_segs_removed,
CheckpointStats.ckpt_segs_recycled,
@@ -6789,12 +6886,12 @@ update_checkpoint_display(int flags, bool restartpoint, bool reset)
* flags is a bitwise OR of the following:
* CHECKPOINT_IS_SHUTDOWN: checkpoint is for database shutdown.
* CHECKPOINT_END_OF_RECOVERY: checkpoint is for end of WAL recovery.
- * CHECKPOINT_IMMEDIATE: finish the checkpoint ASAP,
- * ignoring checkpoint_completion_target parameter.
+ * CHECKPOINT_FAST: finish the checkpoint ASAP, ignoring
+ * checkpoint_completion_target parameter.
* CHECKPOINT_FORCE: force a checkpoint even if no XLOG activity has occurred
* since the last one (implied by CHECKPOINT_IS_SHUTDOWN or
* CHECKPOINT_END_OF_RECOVERY).
- * CHECKPOINT_FLUSH_ALL: also flush buffers of unlogged tables.
+ * CHECKPOINT_FLUSH_UNLOGGED: also flush buffers of unlogged tables.
*
* Note: flags contains other bits, of interest here only for logging purposes.
* In particular note that this routine is synchronous and does not pay
@@ -6816,8 +6913,11 @@ update_checkpoint_display(int flags, bool restartpoint, bool reset)
* In this case, we only insert an XLOG_CHECKPOINT_SHUTDOWN record, and it's
* both the record marking the completion of the checkpoint and the location
* from which WAL replay would begin if needed.
+ *
+ * Returns true if a new checkpoint was performed, or false if it was skipped
+ * because the system was idle.
*/
-void
+bool
CreateCheckPoint(int flags)
{
bool shutdown;
@@ -6886,7 +6986,7 @@ CreateCheckPoint(int flags)
* starting snapshot of locks and transactions.
*/
if (!shutdown && XLogStandbyInfoActive())
- checkPoint.oldestActiveXid = GetOldestActiveTransactionId();
+ checkPoint.oldestActiveXid = GetOldestActiveTransactionId(false, true);
else
checkPoint.oldestActiveXid = InvalidTransactionId;
@@ -6909,7 +7009,7 @@ CreateCheckPoint(int flags)
END_CRIT_SECTION();
ereport(DEBUG1,
(errmsg_internal("checkpoint skipped because system is idle")));
- return;
+ return false;
}
}
@@ -6933,6 +7033,7 @@ CreateCheckPoint(int flags)
WALInsertLockAcquireExclusive();
checkPoint.fullPageWrites = Insert->fullPageWrites;
+ checkPoint.wal_level = wal_level;
if (shutdown)
{
@@ -6986,11 +7087,9 @@ CreateCheckPoint(int flags)
*/
if (!shutdown)
{
- int dummy = 0;
-
- /* Record must have payload to avoid assertion failure. */
+ /* Include WAL level in record for WAL summarizer's benefit. */
XLogBeginInsert();
- XLogRegisterData((char *) &dummy, sizeof(dummy));
+ XLogRegisterData(&wal_level, sizeof(wal_level));
(void) XLogInsert(RM_XLOG_ID, XLOG_CHECKPOINT_REDO);
/*
@@ -7094,6 +7193,13 @@ CreateCheckPoint(int flags)
{
do
{
+ /*
+ * Keep absorbing fsync requests while we wait. There could even
+ * be a deadlock if we don't, if the process that prevents the
+ * checkpoint is trying to add a request to the queue.
+ */
+ AbsorbSyncRequests();
+
pgstat_report_wait_start(WAIT_EVENT_CHECKPOINT_DELAY_START);
pg_usleep(10000L); /* wait for 10 msec */
pgstat_report_wait_end();
@@ -7109,6 +7215,8 @@ CreateCheckPoint(int flags)
{
do
{
+ AbsorbSyncRequests();
+
pgstat_report_wait_start(WAIT_EVENT_CHECKPOINT_DELAY_COMPLETE);
pg_usleep(10000L); /* wait for 10 msec */
pgstat_report_wait_end();
@@ -7134,7 +7242,7 @@ CreateCheckPoint(int flags)
* Now insert the checkpoint record into XLOG.
*/
XLogBeginInsert();
- XLogRegisterData((char *) (&checkPoint), sizeof(checkPoint));
+ XLogRegisterData(&checkPoint, sizeof(checkPoint));
recptr = XLogInsert(RM_XLOG_ID,
shutdown ? XLOG_CHECKPOINT_SHUTDOWN :
XLOG_CHECKPOINT_ONLINE);
@@ -7192,11 +7300,6 @@ CreateCheckPoint(int flags)
UpdateControlFile();
LWLockRelease(ControlFileLock);
- /* Update shared-memory copy of checkpoint XID/epoch */
- SpinLockAcquire(&XLogCtl->info_lck);
- XLogCtl->ckptFullXid = checkPoint.nextXid;
- SpinLockRelease(&XLogCtl->info_lck);
-
/*
* We are now done with critical updates; no need for system panic if we
* have trouble while fooling with old log segments.
@@ -7220,7 +7323,7 @@ CreateCheckPoint(int flags)
* until after the above call that flushes the XLOG_CHECKPOINT_ONLINE
* record.
*/
- SetWalSummarizerLatch();
+ WakeupWalSummarizer();
/*
* Let smgr do post-checkpoint cleanup (eg, deleting old files).
@@ -7234,13 +7337,17 @@ CreateCheckPoint(int flags)
if (PriorRedoPtr != InvalidXLogRecPtr)
UpdateCheckPointDistanceEstimate(RedoRecPtr - PriorRedoPtr);
+#ifdef USE_INJECTION_POINTS
+ INJECTION_POINT("checkpoint-before-old-wal-removal", NULL);
+#endif
+
/*
* Delete old log files, those no longer needed for last checkpoint to
* prevent the disk holding the xlog from growing full.
*/
XLByteToSeg(RedoRecPtr, _logSegNo, wal_segment_size);
KeepLogSeg(recptr, &_logSegNo);
- if (InvalidateObsoleteReplicationSlots(RS_INVAL_WAL_REMOVED,
+ if (InvalidateObsoleteReplicationSlots(RS_INVAL_WAL_REMOVED | RS_INVAL_IDLE_TIMEOUT,
_logSegNo, InvalidOid,
InvalidTransactionId))
{
@@ -7283,6 +7390,8 @@ CreateCheckPoint(int flags)
CheckpointStats.ckpt_segs_added,
CheckpointStats.ckpt_segs_removed,
CheckpointStats.ckpt_segs_recycled);
+
+ return true;
}
/*
@@ -7304,6 +7413,7 @@ CreateEndOfRecoveryRecord(void)
elog(ERROR, "can only be used to end recovery");
xlrec.end_time = GetCurrentTimestamp();
+ xlrec.wal_level = wal_level;
WALInsertLockAcquireExclusive();
xlrec.ThisTimeLineID = XLogCtl->InsertTimeLineID;
@@ -7313,7 +7423,7 @@ CreateEndOfRecoveryRecord(void)
START_CRIT_SECTION();
XLogBeginInsert();
- XLogRegisterData((char *) &xlrec, sizeof(xl_end_of_recovery));
+ XLogRegisterData(&xlrec, sizeof(xl_end_of_recovery));
recptr = XLogInsert(RM_XLOG_ID, XLOG_END_OF_RECOVERY);
XLogFlush(recptr);
@@ -7370,7 +7480,7 @@ CreateOverwriteContrecordRecord(XLogRecPtr aborted_lsn, XLogRecPtr pagePtr,
if (!RecoveryInProgress())
elog(ERROR, "can only be used at end of recovery");
if (pagePtr % XLOG_BLCKSZ != 0)
- elog(ERROR, "invalid position for missing continuation record %X/%X",
+ elog(ERROR, "invalid position for missing continuation record %X/%08X",
LSN_FORMAT_ARGS(pagePtr));
/* The current WAL insert position should be right after the page header */
@@ -7381,7 +7491,7 @@ CreateOverwriteContrecordRecord(XLogRecPtr aborted_lsn, XLogRecPtr pagePtr,
startPos += SizeOfXLogShortPHD;
recptr = GetXLogInsertRecPtr();
if (recptr != startPos)
- elog(ERROR, "invalid WAL insert position %X/%X for OVERWRITE_CONTRECORD",
+ elog(ERROR, "invalid WAL insert position %X/%08X for OVERWRITE_CONTRECORD",
LSN_FORMAT_ARGS(recptr));
START_CRIT_SECTION();
@@ -7406,12 +7516,12 @@ CreateOverwriteContrecordRecord(XLogRecPtr aborted_lsn, XLogRecPtr pagePtr,
XLogBeginInsert();
xlrec.overwritten_lsn = aborted_lsn;
xlrec.overwrite_time = GetCurrentTimestamp();
- XLogRegisterData((char *) &xlrec, sizeof(xl_overwrite_contrecord));
+ XLogRegisterData(&xlrec, sizeof(xl_overwrite_contrecord));
recptr = XLogInsert(RM_XLOG_ID, XLOG_OVERWRITE_CONTRECORD);
/* check that the record was inserted to the right place */
if (ProcLastRecPtr != startPos)
- elog(ERROR, "OVERWRITE_CONTRECORD was inserted to unexpected position %X/%X",
+ elog(ERROR, "OVERWRITE_CONTRECORD was inserted to unexpected position %X/%08X",
LSN_FORMAT_ARGS(ProcLastRecPtr));
XLogFlush(recptr);
@@ -7480,8 +7590,7 @@ RecoveryRestartPoint(const CheckPoint *checkPoint, XLogReaderState *record)
if (XLogHaveInvalidPages())
{
elog(DEBUG2,
- "could not record restart point at %X/%X because there "
- "are unresolved references to invalid pages",
+ "could not record restart point at %X/%08X because there are unresolved references to invalid pages",
LSN_FORMAT_ARGS(checkPoint->redo));
return;
}
@@ -7561,8 +7670,8 @@ CreateRestartPoint(int flags)
lastCheckPoint.redo <= ControlFile->checkPointCopy.redo)
{
ereport(DEBUG2,
- (errmsg_internal("skipping restartpoint, already performed at %X/%X",
- LSN_FORMAT_ARGS(lastCheckPoint.redo))));
+ errmsg_internal("skipping restartpoint, already performed at %X/%08X",
+ LSN_FORMAT_ARGS(lastCheckPoint.redo)));
UpdateMinRecoveryPoint(InvalidXLogRecPtr, true);
if (flags & CHECKPOINT_IS_SHUTDOWN)
@@ -7615,7 +7724,7 @@ CreateRestartPoint(int flags)
* This location needs to be after CheckPointGuts() to ensure that some
* work has already happened during this checkpoint.
*/
- INJECTION_POINT("create-restart-point");
+ INJECTION_POINT("create-restart-point", NULL);
/*
* Remember the prior checkpoint's redo ptr for
@@ -7692,7 +7801,7 @@ CreateRestartPoint(int flags)
replayPtr = GetXLogReplayRecPtr(&replayTLI);
endptr = (receivePtr < replayPtr) ? replayPtr : receivePtr;
KeepLogSeg(endptr, &_logSegNo);
- if (InvalidateObsoleteReplicationSlots(RS_INVAL_WAL_REMOVED,
+ if (InvalidateObsoleteReplicationSlots(RS_INVAL_WAL_REMOVED | RS_INVAL_IDLE_TIMEOUT,
_logSegNo, InvalidOid,
InvalidTransactionId))
{
@@ -7746,10 +7855,10 @@ CreateRestartPoint(int flags)
xtime = GetLatestXTime();
ereport((log_checkpoints ? LOG : DEBUG2),
- (errmsg("recovery restart point at %X/%X",
- LSN_FORMAT_ARGS(lastCheckPoint.redo)),
- xtime ? errdetail("Last completed transaction was at log time %s.",
- timestamptz_to_str(xtime)) : 0));
+ errmsg("recovery restart point at %X/%08X",
+ LSN_FORMAT_ARGS(lastCheckPoint.redo)),
+ xtime ? errdetail("Last completed transaction was at log time %s.",
+ timestamptz_to_str(xtime)) : 0);
/*
* Finally, execute archive_cleanup_command, if any.
@@ -7880,17 +7989,19 @@ KeepLogSeg(XLogRecPtr recptr, XLogSegNo *logSegNo)
XLByteToSeg(recptr, currSegNo, wal_segment_size);
segno = currSegNo;
- /*
- * Calculate how many segments are kept by slots first, adjusting for
- * max_slot_wal_keep_size.
- */
+ /* Calculate how many segments are kept by slots. */
keep = XLogGetReplicationSlotMinimumLSN();
if (keep != InvalidXLogRecPtr && keep < recptr)
{
XLByteToSeg(keep, segno, wal_segment_size);
- /* Cap by max_slot_wal_keep_size ... */
- if (max_slot_wal_keep_size_mb >= 0)
+ /*
+ * Account for max_slot_wal_keep_size to avoid keeping more than
+ * configured. However, don't do that during a binary upgrade: if
+ * slots were to be invalidated because of this, it would not be
+ * possible to preserve logical ones during the upgrade.
+ */
+ if (max_slot_wal_keep_size_mb >= 0 && !IsBinaryUpgrade)
{
uint64 slot_keep_segs;
@@ -7906,7 +8017,7 @@ KeepLogSeg(XLogRecPtr recptr, XLogSegNo *logSegNo)
* If WAL summarization is in use, don't remove WAL that has yet to be
* summarized.
*/
- keep = GetOldestUnsummarizedLSN(NULL, NULL, false);
+ keep = GetOldestUnsummarizedLSN(NULL, NULL);
if (keep != InvalidXLogRecPtr)
{
XLogSegNo unsummarized_segno;
@@ -7944,7 +8055,7 @@ void
XLogPutNextOid(Oid nextOid)
{
XLogBeginInsert();
- XLogRegisterData((char *) (&nextOid), sizeof(Oid));
+ XLogRegisterData(&nextOid, sizeof(Oid));
(void) XLogInsert(RM_XLOG_ID, XLOG_NEXTOID);
/*
@@ -8005,13 +8116,13 @@ XLogRestorePoint(const char *rpName)
strlcpy(xlrec.rp_name, rpName, MAXFNAMELEN);
XLogBeginInsert();
- XLogRegisterData((char *) &xlrec, sizeof(xl_restore_point));
+ XLogRegisterData(&xlrec, sizeof(xl_restore_point));
RecPtr = XLogInsert(RM_XLOG_ID, XLOG_RESTORE_POINT);
ereport(LOG,
- (errmsg("restore point \"%s\" created at %X/%X",
- rpName, LSN_FORMAT_ARGS(RecPtr))));
+ errmsg("restore point \"%s\" created at %X/%08X",
+ rpName, LSN_FORMAT_ARGS(RecPtr)));
return RecPtr;
}
@@ -8054,7 +8165,7 @@ XLogReportParameters(void)
xlrec.track_commit_timestamp = track_commit_timestamp;
XLogBeginInsert();
- XLogRegisterData((char *) &xlrec, sizeof(xlrec));
+ XLogRegisterData(&xlrec, sizeof(xlrec));
recptr = XLogInsert(RM_XLOG_ID, XLOG_PARAMETER_CHANGE);
XLogFlush(recptr);
@@ -8129,7 +8240,7 @@ UpdateFullPageWrites(void)
if (XLogStandbyInfoActive() && !recoveryInProgress)
{
XLogBeginInsert();
- XLogRegisterData((char *) (&fullPageWrites), sizeof(bool));
+ XLogRegisterData(&fullPageWrites, sizeof(bool));
XLogInsert(RM_XLOG_ID, XLOG_FPW_CHANGE);
}
@@ -8235,6 +8346,9 @@ xlog_redo(XLogReaderState *record)
oldestActiveXID = PrescanPreparedTransactions(&xids, &nxids);
+ /* Update pg_subtrans entries for any prepared transactions */
+ StandbyRecoverPreparedTransactions();
+
/*
* Construct a RunningTransactions snapshot representing a shut
* down server, with only prepared transactions still alive. We're
@@ -8243,7 +8357,7 @@ xlog_redo(XLogReaderState *record)
*/
running.xcnt = nxids;
running.subxcnt = 0;
- running.subxid_overflow = false;
+ running.subxid_status = SUBXIDS_IN_SUBTRANS;
running.nextXid = XidFromFullTransactionId(checkPoint.nextXid);
running.oldestRunningXid = oldestActiveXID;
latestCompletedXid = XidFromFullTransactionId(checkPoint.nextXid);
@@ -8253,8 +8367,6 @@ xlog_redo(XLogReaderState *record)
running.xids = xids;
ProcArrayApplyRecoveryInfo(&running);
-
- StandbyRecoverPreparedTransactions();
}
/* ControlFile->checkPointCopy always tracks the latest ckpt XID */
@@ -8262,11 +8374,6 @@ xlog_redo(XLogReaderState *record)
ControlFile->checkPointCopy.nextXid = checkPoint.nextXid;
LWLockRelease(ControlFileLock);
- /* Update shared-memory copy of checkpoint XID/epoch */
- SpinLockAcquire(&XLogCtl->info_lck);
- XLogCtl->ckptFullXid = checkPoint.nextXid;
- SpinLockRelease(&XLogCtl->info_lck);
-
/*
* We should've already switched to the new TLI before replaying this
* record.
@@ -8278,6 +8385,14 @@ xlog_redo(XLogReaderState *record)
checkPoint.ThisTimeLineID, replayTLI)));
RecoveryRestartPoint(&checkPoint, record);
+
+ /*
+ * After replaying a checkpoint record, free all smgr objects.
+ * Otherwise we would never do so for dropped relations, as the
+ * startup does not process shared invalidation messages or call
+ * AtEOXact_SMgr().
+ */
+ smgrdestroyall();
}
else if (info == XLOG_CHECKPOINT_ONLINE)
{
@@ -8323,11 +8438,6 @@ xlog_redo(XLogReaderState *record)
ControlFile->checkPointCopy.nextXid = checkPoint.nextXid;
LWLockRelease(ControlFileLock);
- /* Update shared-memory copy of checkpoint XID/epoch */
- SpinLockAcquire(&XLogCtl->info_lck);
- XLogCtl->ckptFullXid = checkPoint.nextXid;
- SpinLockRelease(&XLogCtl->info_lck);
-
/* TLI should not change in an on-line checkpoint */
(void) GetCurrentReplayRecPtr(&replayTLI);
if (checkPoint.ThisTimeLineID != replayTLI)
@@ -8336,6 +8446,14 @@ xlog_redo(XLogReaderState *record)
checkPoint.ThisTimeLineID, replayTLI)));
RecoveryRestartPoint(&checkPoint, record);
+
+ /*
+ * After replaying a checkpoint record, free all smgr objects.
+ * Otherwise we would never do so for dropped relations, as the
+ * startup does not process shared invalidation messages or call
+ * AtEOXact_SMgr().
+ */
+ smgrdestroyall();
}
else if (info == XLOG_OVERWRITE_CONTRECORD)
{
@@ -8616,11 +8734,10 @@ issue_xlog_fsync(int fd, XLogSegNo segno, TimeLineID tli)
wal_sync_method == WAL_SYNC_METHOD_OPEN_DSYNC)
return;
- /* Measure I/O timing to sync the WAL file */
- if (track_wal_io_timing)
- INSTR_TIME_SET_CURRENT(start);
- else
- INSTR_TIME_SET_ZERO(start);
+ /*
+ * Measure I/O timing to sync the WAL file for pg_stat_io.
+ */
+ start = pgstat_prepare_io_time(track_wal_io_timing);
pgstat_report_wait_start(WAIT_EVENT_WAL_SYNC);
switch (wal_sync_method)
@@ -8666,18 +8783,8 @@ issue_xlog_fsync(int fd, XLogSegNo segno, TimeLineID tli)
pgstat_report_wait_end();
- /*
- * Increment the I/O timing and the number of times WAL files were synced.
- */
- if (track_wal_io_timing)
- {
- instr_time end;
-
- INSTR_TIME_SET_CURRENT(end);
- INSTR_TIME_ACCUM_DIFF(PendingWalStats.wal_sync_time, end, start);
- }
-
- PendingWalStats.wal_sync++;
+ pgstat_count_io_op_time(IOOBJECT_WAL, IOCONTEXT_NORMAL, IOOP_FSYNC,
+ start, 1, 0);
}
/*
@@ -8686,9 +8793,8 @@ issue_xlog_fsync(int fd, XLogSegNo segno, TimeLineID tli)
* backup state and tablespace map.
*
* Input parameters are "state" (the backup state), "fast" (if true, we do
- * the checkpoint in immediate mode to make it faster), and "tablespaces"
- * (if non-NULL, indicates a list of tablespaceinfo structs describing the
- * cluster's tablespaces.).
+ * the checkpoint in fast mode), and "tablespaces" (if non-NULL, indicates a
+ * list of tablespaceinfo structs describing the cluster's tablespaces.).
*
* The tablespace map contents are appended to passed-in parameter
* tablespace_map and the caller is responsible for including it in the backup
@@ -8733,7 +8839,7 @@ do_pg_backup_start(const char *backupidstr, bool fast, List **tablespaces,
errmsg("backup label too long (max %d bytes)",
MAXPGPATH)));
- memcpy(state->name, backupidstr, strlen(backupidstr));
+ strlcpy(state->name, backupidstr, sizeof(state->name));
/*
* Mark backup active in shared memory. We must do full-page WAL writes
@@ -8765,7 +8871,7 @@ do_pg_backup_start(const char *backupidstr, bool fast, List **tablespaces,
* work correctly, it is critical that sessionBackupState is only updated
* after this block is over.
*/
- PG_ENSURE_ERROR_CLEANUP(do_pg_abort_backup, DatumGetBool(true));
+ PG_ENSURE_ERROR_CLEANUP(do_pg_abort_backup, BoolGetDatum(true));
{
bool gotUniqueStartpoint = false;
DIR *tblspcdir;
@@ -8816,11 +8922,11 @@ do_pg_backup_start(const char *backupidstr, bool fast, List **tablespaces,
* during recovery means that checkpointer is running, we can use
* RequestCheckpoint() to establish a restartpoint.
*
- * We use CHECKPOINT_IMMEDIATE only if requested by user (via
- * passing fast = true). Otherwise this can take awhile.
+ * We use CHECKPOINT_FAST only if requested by user (via passing
+ * fast = true). Otherwise this can take awhile.
*/
RequestCheckpoint(CHECKPOINT_FORCE | CHECKPOINT_WAIT |
- (fast ? CHECKPOINT_IMMEDIATE : 0));
+ (fast ? CHECKPOINT_FAST : 0));
/*
* Now we need to fetch the checkpoint record location, and also
@@ -8894,10 +9000,10 @@ do_pg_backup_start(const char *backupidstr, bool fast, List **tablespaces,
datadirpathlen = strlen(DataDir);
/* Collect information about all tablespaces */
- tblspcdir = AllocateDir("pg_tblspc");
- while ((de = ReadDir(tblspcdir, "pg_tblspc")) != NULL)
+ tblspcdir = AllocateDir(PG_TBLSPC_DIR);
+ while ((de = ReadDir(tblspcdir, PG_TBLSPC_DIR)) != NULL)
{
- char fullpath[MAXPGPATH + 10];
+ char fullpath[MAXPGPATH + sizeof(PG_TBLSPC_DIR)];
char linkpath[MAXPGPATH];
char *relpath = NULL;
char *s;
@@ -8920,7 +9026,7 @@ do_pg_backup_start(const char *backupidstr, bool fast, List **tablespaces,
if (*badp != '\0' || errno == EINVAL || errno == ERANGE)
continue;
- snprintf(fullpath, sizeof(fullpath), "pg_tblspc/%s", de->d_name);
+ snprintf(fullpath, sizeof(fullpath), "%s/%s", PG_TBLSPC_DIR, de->d_name);
de_type = get_dirent_type(fullpath, de, false, ERROR);
@@ -8981,8 +9087,8 @@ do_pg_backup_start(const char *backupidstr, bool fast, List **tablespaces,
* In this case, we store a relative path rather than an
* absolute path into the tablespaceinfo.
*/
- snprintf(linkpath, sizeof(linkpath), "pg_tblspc/%s",
- de->d_name);
+ snprintf(linkpath, sizeof(linkpath), "%s/%s",
+ PG_TBLSPC_DIR, de->d_name);
relpath = pstrdup(linkpath);
}
else
@@ -9004,7 +9110,7 @@ do_pg_backup_start(const char *backupidstr, bool fast, List **tablespaces,
state->starttime = (pg_time_t) time(NULL);
}
- PG_END_ENSURE_ERROR_CLEANUP(do_pg_abort_backup, DatumGetBool(true));
+ PG_END_ENSURE_ERROR_CLEANUP(do_pg_abort_backup, BoolGetDatum(true));
state->started_in_recovery = backup_started_in_recovery;
@@ -9061,7 +9167,7 @@ do_pg_backup_stop(BackupState *state, bool waitforarchive)
ereport(ERROR,
(errcode(ERRCODE_OBJECT_NOT_IN_PREREQUISITE_STATE),
errmsg("WAL level not sufficient for making an online backup"),
- errhint("wal_level must be set to \"replica\" or \"logical\" at server start.")));
+ errhint("\"wal_level\" must be set to \"replica\" or \"logical\" at server start.")));
/*
* OK to update backup counter and session-level lock.
@@ -9168,7 +9274,7 @@ do_pg_backup_stop(BackupState *state, bool waitforarchive)
* Write the backup-end xlog record
*/
XLogBeginInsert();
- XLogRegisterData((char *) (&state->startpoint),
+ XLogRegisterData(&state->startpoint,
sizeof(state->startpoint));
state->stoppoint = XLogInsert(RM_XLOG_ID, XLOG_BACKUP_END);
@@ -9344,7 +9450,7 @@ register_persistent_abort_backup_handler(void)
if (already_done)
return;
- before_shmem_exit(do_pg_abort_backup, DatumGetBool(false));
+ before_shmem_exit(do_pg_abort_backup, BoolGetDatum(false));
already_done = true;
}
diff --git a/src/backend/access/transam/xlogarchive.c b/src/backend/access/transam/xlogarchive.c
index 81999b48200be..1ef1713c91a49 100644
--- a/src/backend/access/transam/xlogarchive.c
+++ b/src/backend/access/transam/xlogarchive.c
@@ -4,7 +4,7 @@
* Functions for archiving WAL files and restoring from the archive.
*
*
- * Portions Copyright (c) 1996-2024, PostgreSQL Global Development Group
+ * Portions Copyright (c) 1996-2025, PostgreSQL Global Development Group
* Portions Copyright (c) 1994, Regents of the University of California
*
* src/backend/access/transam/xlogarchive.c
diff --git a/src/backend/access/transam/xlogbackup.c b/src/backend/access/transam/xlogbackup.c
index 5171668cddc17..cda4b38b7d67d 100644
--- a/src/backend/access/transam/xlogbackup.c
+++ b/src/backend/access/transam/xlogbackup.c
@@ -3,7 +3,7 @@
* xlogbackup.c
* Internal routines for base backups.
*
- * Portions Copyright (c) 1996-2024, PostgreSQL Global Development Group
+ * Portions Copyright (c) 1996-2025, PostgreSQL Global Development Group
* Portions Copyright (c) 1994, Regents of the University of California
*
* IDENTIFICATION
@@ -42,7 +42,7 @@ build_backup_content(BackupState *state, bool ishistoryfile)
XLByteToSeg(state->startpoint, startsegno, wal_segment_size);
XLogFileName(startxlogfile, state->starttli, startsegno, wal_segment_size);
- appendStringInfo(result, "START WAL LOCATION: %X/%X (file %s)\n",
+ appendStringInfo(result, "START WAL LOCATION: %X/%08X (file %s)\n",
LSN_FORMAT_ARGS(state->startpoint), startxlogfile);
if (ishistoryfile)
@@ -52,11 +52,11 @@ build_backup_content(BackupState *state, bool ishistoryfile)
XLByteToSeg(state->stoppoint, stopsegno, wal_segment_size);
XLogFileName(stopxlogfile, state->stoptli, stopsegno, wal_segment_size);
- appendStringInfo(result, "STOP WAL LOCATION: %X/%X (file %s)\n",
+ appendStringInfo(result, "STOP WAL LOCATION: %X/%08X (file %s)\n",
LSN_FORMAT_ARGS(state->stoppoint), stopxlogfile);
}
- appendStringInfo(result, "CHECKPOINT LOCATION: %X/%X\n",
+ appendStringInfo(result, "CHECKPOINT LOCATION: %X/%08X\n",
LSN_FORMAT_ARGS(state->checkpointloc));
appendStringInfoString(result, "BACKUP METHOD: streamed\n");
appendStringInfo(result, "BACKUP FROM: %s\n",
@@ -81,7 +81,7 @@ build_backup_content(BackupState *state, bool ishistoryfile)
Assert(XLogRecPtrIsInvalid(state->istartpoint) == (state->istarttli == 0));
if (!XLogRecPtrIsInvalid(state->istartpoint))
{
- appendStringInfo(result, "INCREMENTAL FROM LSN: %X/%X\n",
+ appendStringInfo(result, "INCREMENTAL FROM LSN: %X/%08X\n",
LSN_FORMAT_ARGS(state->istartpoint));
appendStringInfo(result, "INCREMENTAL FROM TLI: %u\n",
state->istarttli);
diff --git a/src/backend/access/transam/xlogfuncs.c b/src/backend/access/transam/xlogfuncs.c
index 4e46baaebdf7a..8c3090165f001 100644
--- a/src/backend/access/transam/xlogfuncs.c
+++ b/src/backend/access/transam/xlogfuncs.c
@@ -7,7 +7,7 @@
* This file contains WAL control and information functions.
*
*
- * Portions Copyright (c) 1996-2024, PostgreSQL Global Development Group
+ * Portions Copyright (c) 1996-2025, PostgreSQL Global Development Group
* Portions Copyright (c) 1994, Regents of the University of California
*
* src/backend/access/transam/xlogfuncs.c
@@ -28,6 +28,7 @@
#include "pgstat.h"
#include "replication/walreceiver.h"
#include "storage/fd.h"
+#include "storage/latch.h"
#include "storage/standby.h"
#include "utils/builtins.h"
#include "utils/memutils.h"
diff --git a/src/backend/access/transam/xloginsert.c b/src/backend/access/transam/xloginsert.c
index 90476015347ad..c7571429e8e97 100644
--- a/src/backend/access/transam/xloginsert.c
+++ b/src/backend/access/transam/xloginsert.c
@@ -9,7 +9,7 @@
* of XLogRecData structs by a call to XLogRecordAssemble(). See
* access/transam/README for details.
*
- * Portions Copyright (c) 1996-2024, PostgreSQL Global Development Group
+ * Portions Copyright (c) 1996-2025, PostgreSQL Global Development Group
* Portions Copyright (c) 1994, Regents of the University of California
*
* src/backend/access/transam/xloginsert.c
@@ -72,7 +72,7 @@ typedef struct
RelFileLocator rlocator; /* identifies the relation and block */
ForkNumber forkno;
BlockNumber block;
- Page page; /* page content */
+ const PageData *page; /* page content */
uint32 rdata_len; /* total length of data in rdata chain */
XLogRecData *rdata_head; /* head of the chain of data registered with
* this block */
@@ -138,8 +138,8 @@ static XLogRecData *XLogRecordAssemble(RmgrId rmid, uint8 info,
XLogRecPtr RedoRecPtr, bool doPageWrites,
XLogRecPtr *fpw_lsn, int *num_fpi,
bool *topxid_included);
-static bool XLogCompressBackupBlock(char *page, uint16 hole_offset,
- uint16 hole_length, char *dest, uint16 *dlen);
+static bool XLogCompressBackupBlock(const PageData *page, uint16 hole_offset,
+ uint16 hole_length, void *dest, uint16 *dlen);
/*
* Begin constructing a WAL record. This must be called before the
@@ -307,7 +307,7 @@ XLogRegisterBuffer(uint8 block_id, Buffer buffer, uint8 flags)
*/
void
XLogRegisterBlock(uint8 block_id, RelFileLocator *rlocator, ForkNumber forknum,
- BlockNumber blknum, Page page, uint8 flags)
+ BlockNumber blknum, const PageData *page, uint8 flags)
{
registered_buffer *regbuf;
@@ -361,7 +361,7 @@ XLogRegisterBlock(uint8 block_id, RelFileLocator *rlocator, ForkNumber forknum,
* XLogRecGetData().
*/
void
-XLogRegisterData(char *data, uint32 len)
+XLogRegisterData(const void *data, uint32 len)
{
XLogRecData *rdata;
@@ -402,7 +402,7 @@ XLogRegisterData(char *data, uint32 len)
* limited)
*/
void
-XLogRegisterBufData(uint8 block_id, char *data, uint32 len)
+XLogRegisterBufData(uint8 block_id, const void *data, uint32 len)
{
registered_buffer *regbuf;
XLogRecData *rdata;
@@ -529,6 +529,18 @@ XLogInsert(RmgrId rmid, uint8 info)
return EndPos;
}
+/*
+ * Simple wrapper to XLogInsert to insert a WAL record with elementary
+ * contents (only an int64 is supported as value currently).
+ */
+XLogRecPtr
+XLogSimpleInsertInt64(RmgrId rmid, uint8 info, int64 value)
+{
+ XLogBeginInsert();
+ XLogRegisterData(&value, sizeof(value));
+ return XLogInsert(rmid, info);
+}
+
/*
* Assemble a WAL record from the registered data and buffers into an
* XLogRecData chain, ready for insertion with XLogInsertRecord().
@@ -648,7 +660,7 @@ XLogRecordAssemble(RmgrId rmid, uint8 info,
if (include_image)
{
- Page page = regbuf->page;
+ const PageData *page = regbuf->page;
uint16 compressed_len = 0;
/*
@@ -869,8 +881,8 @@ XLogRecordAssemble(RmgrId rmid, uint8 info,
if (mainrdata_len > PG_UINT32_MAX)
ereport(ERROR,
(errmsg_internal("too much WAL data"),
- errdetail_internal("Main data length is %llu bytes for a maximum of %u bytes.",
- (unsigned long long) mainrdata_len,
+ errdetail_internal("Main data length is %" PRIu64 " bytes for a maximum of %u bytes.",
+ mainrdata_len,
PG_UINT32_MAX)));
mainrdata_len_4b = (uint32) mainrdata_len;
@@ -915,8 +927,8 @@ XLogRecordAssemble(RmgrId rmid, uint8 info,
if (total_len > XLogRecordMaxSize)
ereport(ERROR,
(errmsg_internal("oversized WAL record"),
- errdetail_internal("WAL record would be %llu bytes (of maximum %u bytes); rmid %u flags %u.",
- (unsigned long long) total_len, XLogRecordMaxSize, rmid, info)));
+ errdetail_internal("WAL record would be %" PRIu64 " bytes (of maximum %u bytes); rmid %u flags %u.",
+ total_len, XLogRecordMaxSize, rmid, info)));
/*
* Fill in the fields in the record header. Prev-link is filled in later,
@@ -941,23 +953,23 @@ XLogRecordAssemble(RmgrId rmid, uint8 info,
* the length of compressed block image.
*/
static bool
-XLogCompressBackupBlock(char *page, uint16 hole_offset, uint16 hole_length,
- char *dest, uint16 *dlen)
+XLogCompressBackupBlock(const PageData *page, uint16 hole_offset, uint16 hole_length,
+ void *dest, uint16 *dlen)
{
int32 orig_len = BLCKSZ - hole_length;
int32 len = -1;
int32 extra_bytes = 0;
- char *source;
+ const void *source;
PGAlignedBlock tmp;
if (hole_length != 0)
{
/* must skip the hole */
- source = tmp.data;
- memcpy(source, page, hole_offset);
- memcpy(source + hole_offset,
+ memcpy(tmp.data, page, hole_offset);
+ memcpy(tmp.data + hole_offset,
page + (hole_offset + hole_length),
BLCKSZ - (hole_length + hole_offset));
+ source = tmp.data;
/*
* Extra data needs to be stored in WAL record for the compressed
diff --git a/src/backend/access/transam/xlogprefetcher.c b/src/backend/access/transam/xlogprefetcher.c
index 84023d61baf30..ed3aacabc986e 100644
--- a/src/backend/access/transam/xlogprefetcher.c
+++ b/src/backend/access/transam/xlogprefetcher.c
@@ -3,7 +3,7 @@
* xlogprefetcher.c
* Prefetching support for recovery.
*
- * Portions Copyright (c) 2022-2024, PostgreSQL Global Development Group
+ * Portions Copyright (c) 2022-2025, PostgreSQL Global Development Group
* Portions Copyright (c) 1994, Regents of the University of California
*
*
@@ -362,17 +362,15 @@ XLogPrefetcher *
XLogPrefetcherAllocate(XLogReaderState *reader)
{
XLogPrefetcher *prefetcher;
- static HASHCTL hash_table_ctl = {
- .keysize = sizeof(RelFileLocator),
- .entrysize = sizeof(XLogPrefetcherFilter)
- };
+ HASHCTL ctl;
prefetcher = palloc0(sizeof(XLogPrefetcher));
-
prefetcher->reader = reader;
+
+ ctl.keysize = sizeof(RelFileLocator);
+ ctl.entrysize = sizeof(XLogPrefetcherFilter);
prefetcher->filter_table = hash_create("XLogPrefetcherFilterTable", 1024,
- &hash_table_ctl,
- HASH_ELEM | HASH_BLOBS);
+ &ctl, HASH_ELEM | HASH_BLOBS);
dlist_init(&prefetcher->filter_queue);
SharedStats->wal_distance = 0;
@@ -548,7 +546,7 @@ XLogPrefetcherNextBlock(uintptr_t pgsr_private, XLogRecPtr *lsn)
#ifdef XLOGPREFETCHER_DEBUG_LEVEL
elog(XLOGPREFETCHER_DEBUG_LEVEL,
- "suppressing all readahead until %X/%X is replayed due to possible TLI change",
+ "suppressing all readahead until %X/%08X is replayed due to possible TLI change",
LSN_FORMAT_ARGS(record->lsn));
#endif
@@ -581,7 +579,7 @@ XLogPrefetcherNextBlock(uintptr_t pgsr_private, XLogRecPtr *lsn)
#ifdef XLOGPREFETCHER_DEBUG_LEVEL
elog(XLOGPREFETCHER_DEBUG_LEVEL,
- "suppressing prefetch in database %u until %X/%X is replayed due to raw file copy",
+ "suppressing prefetch in database %u until %X/%08X is replayed due to raw file copy",
rlocator.dbOid,
LSN_FORMAT_ARGS(record->lsn));
#endif
@@ -609,7 +607,7 @@ XLogPrefetcherNextBlock(uintptr_t pgsr_private, XLogRecPtr *lsn)
#ifdef XLOGPREFETCHER_DEBUG_LEVEL
elog(XLOGPREFETCHER_DEBUG_LEVEL,
- "suppressing prefetch in relation %u/%u/%u until %X/%X is replayed, which creates the relation",
+ "suppressing prefetch in relation %u/%u/%u until %X/%08X is replayed, which creates the relation",
xlrec->rlocator.spcOid,
xlrec->rlocator.dbOid,
xlrec->rlocator.relNumber,
@@ -632,7 +630,7 @@ XLogPrefetcherNextBlock(uintptr_t pgsr_private, XLogRecPtr *lsn)
#ifdef XLOGPREFETCHER_DEBUG_LEVEL
elog(XLOGPREFETCHER_DEBUG_LEVEL,
- "suppressing prefetch in relation %u/%u/%u from block %u until %X/%X is replayed, which truncates the relation",
+ "suppressing prefetch in relation %u/%u/%u from block %u until %X/%08X is replayed, which truncates the relation",
xlrec->rlocator.spcOid,
xlrec->rlocator.dbOid,
xlrec->rlocator.relNumber,
@@ -731,7 +729,7 @@ XLogPrefetcherNextBlock(uintptr_t pgsr_private, XLogRecPtr *lsn)
{
#ifdef XLOGPREFETCHER_DEBUG_LEVEL
elog(XLOGPREFETCHER_DEBUG_LEVEL,
- "suppressing all prefetch in relation %u/%u/%u until %X/%X is replayed, because the relation does not exist on disk",
+ "suppressing all prefetch in relation %u/%u/%u until %X/%08X is replayed, because the relation does not exist on disk",
reln->smgr_rlocator.locator.spcOid,
reln->smgr_rlocator.locator.dbOid,
reln->smgr_rlocator.locator.relNumber,
@@ -752,7 +750,7 @@ XLogPrefetcherNextBlock(uintptr_t pgsr_private, XLogRecPtr *lsn)
{
#ifdef XLOGPREFETCHER_DEBUG_LEVEL
elog(XLOGPREFETCHER_DEBUG_LEVEL,
- "suppressing prefetch in relation %u/%u/%u from block %u until %X/%X is replayed, because the relation is too small",
+ "suppressing prefetch in relation %u/%u/%u from block %u until %X/%08X is replayed, because the relation is too small",
reln->smgr_rlocator.locator.spcOid,
reln->smgr_rlocator.locator.dbOid,
reln->smgr_rlocator.locator.relNumber,
@@ -930,7 +928,7 @@ XLogPrefetcherIsFiltered(XLogPrefetcher *prefetcher, RelFileLocator rlocator,
{
#ifdef XLOGPREFETCHER_DEBUG_LEVEL
elog(XLOGPREFETCHER_DEBUG_LEVEL,
- "prefetch of %u/%u/%u block %u suppressed; filtering until LSN %X/%X is replayed (blocks >= %u filtered)",
+ "prefetch of %u/%u/%u block %u suppressed; filtering until LSN %X/%08X is replayed (blocks >= %u filtered)",
rlocator.spcOid, rlocator.dbOid, rlocator.relNumber, blockno,
LSN_FORMAT_ARGS(filter->filter_until_replayed),
filter->filter_from_block);
@@ -946,7 +944,7 @@ XLogPrefetcherIsFiltered(XLogPrefetcher *prefetcher, RelFileLocator rlocator,
{
#ifdef XLOGPREFETCHER_DEBUG_LEVEL
elog(XLOGPREFETCHER_DEBUG_LEVEL,
- "prefetch of %u/%u/%u block %u suppressed; filtering until LSN %X/%X is replayed (whole database)",
+ "prefetch of %u/%u/%u block %u suppressed; filtering until LSN %X/%08X is replayed (whole database)",
rlocator.spcOid, rlocator.dbOid, rlocator.relNumber, blockno,
LSN_FORMAT_ARGS(filter->filter_until_replayed));
#endif
@@ -1085,7 +1083,7 @@ check_recovery_prefetch(int *new_value, void **extra, GucSource source)
#ifndef USE_PREFETCH
if (*new_value == RECOVERY_PREFETCH_ON)
{
- GUC_check_errdetail("\"recovery_prefetch\" is not supported on platforms that lack posix_fadvise().");
+ GUC_check_errdetail("\"recovery_prefetch\" is not supported on platforms that lack support for issuing read-ahead advice.");
return false;
}
#endif
diff --git a/src/backend/access/transam/xlogreader.c b/src/backend/access/transam/xlogreader.c
index 37d2a57961d0d..dcc8d4f9c1b0b 100644
--- a/src/backend/access/transam/xlogreader.c
+++ b/src/backend/access/transam/xlogreader.c
@@ -3,7 +3,7 @@
* xlogreader.c
* Generic XLog reading facility
*
- * Portions Copyright (c) 2013-2024, PostgreSQL Global Development Group
+ * Portions Copyright (c) 2013-2025, PostgreSQL Global Development Group
*
* IDENTIFICATION
* src/backend/access/transam/xlogreader.c
@@ -35,6 +35,7 @@
#ifndef FRONTEND
#include "pgstat.h"
+#include "storage/bufmgr.h"
#else
#include "common/logging.h"
#endif
@@ -616,7 +617,7 @@ XLogDecodeNextRecord(XLogReaderState *state, bool nonblocking)
}
else if (targetRecOff < pageHeaderSize)
{
- report_invalid_record(state, "invalid record offset at %X/%X: expected at least %u, got %u",
+ report_invalid_record(state, "invalid record offset at %X/%08X: expected at least %u, got %u",
LSN_FORMAT_ARGS(RecPtr),
pageHeaderSize, targetRecOff);
goto err;
@@ -625,7 +626,7 @@ XLogDecodeNextRecord(XLogReaderState *state, bool nonblocking)
if ((((XLogPageHeader) state->readBuf)->xlp_info & XLP_FIRST_IS_CONTRECORD) &&
targetRecOff == pageHeaderSize)
{
- report_invalid_record(state, "contrecord is requested by %X/%X",
+ report_invalid_record(state, "contrecord is requested by %X/%08X",
LSN_FORMAT_ARGS(RecPtr));
goto err;
}
@@ -666,7 +667,7 @@ XLogDecodeNextRecord(XLogReaderState *state, bool nonblocking)
if (total_len < SizeOfXLogRecord)
{
report_invalid_record(state,
- "invalid record length at %X/%X: expected at least %u, got %u",
+ "invalid record length at %X/%08X: expected at least %u, got %u",
LSN_FORMAT_ARGS(RecPtr),
(uint32) SizeOfXLogRecord, total_len);
goto err;
@@ -722,11 +723,12 @@ XLogDecodeNextRecord(XLogReaderState *state, bool nonblocking)
/* Calculate pointer to beginning of next page */
targetPagePtr += XLOG_BLCKSZ;
- /* Wait for the next page to become available */
- readOff = ReadPageInternal(state, targetPagePtr,
- Min(total_len - gotlen + SizeOfXLogShortPHD,
- XLOG_BLCKSZ));
-
+ /*
+ * Read the page header before processing the record data, so we
+ * can handle the case where the previous record ended as being a
+ * partial one.
+ */
+ readOff = ReadPageInternal(state, targetPagePtr, SizeOfXLogShortPHD);
if (readOff == XLREAD_WOULDBLOCK)
return XLREAD_WOULDBLOCK;
else if (readOff < 0)
@@ -755,7 +757,7 @@ XLogDecodeNextRecord(XLogReaderState *state, bool nonblocking)
if (!(pageHeader->xlp_info & XLP_FIRST_IS_CONTRECORD))
{
report_invalid_record(state,
- "there is no contrecord flag at %X/%X",
+ "there is no contrecord flag at %X/%08X",
LSN_FORMAT_ARGS(RecPtr));
goto err;
}
@@ -768,13 +770,22 @@ XLogDecodeNextRecord(XLogReaderState *state, bool nonblocking)
total_len != (pageHeader->xlp_rem_len + gotlen))
{
report_invalid_record(state,
- "invalid contrecord length %u (expected %lld) at %X/%X",
+ "invalid contrecord length %u (expected %lld) at %X/%08X",
pageHeader->xlp_rem_len,
((long long) total_len) - gotlen,
LSN_FORMAT_ARGS(RecPtr));
goto err;
}
+ /* Wait for the next page to become available */
+ readOff = ReadPageInternal(state, targetPagePtr,
+ Min(total_len - gotlen + SizeOfXLogShortPHD,
+ XLOG_BLCKSZ));
+ if (readOff == XLREAD_WOULDBLOCK)
+ return XLREAD_WOULDBLOCK;
+ else if (readOff < 0)
+ goto err;
+
/* Append the continuation from this page to the buffer */
pageHeaderSize = XLogPageHeaderSize(pageHeader);
@@ -793,7 +804,7 @@ XLogDecodeNextRecord(XLogReaderState *state, bool nonblocking)
readOff = ReadPageInternal(state, targetPagePtr,
pageHeaderSize + len);
- memcpy(buffer, (char *) contdata, len);
+ memcpy(buffer, contdata, len);
buffer += len;
gotlen += len;
@@ -946,9 +957,9 @@ XLogDecodeNextRecord(XLogReaderState *state, bool nonblocking)
XLogReaderInvalReadState(state);
/*
- * If an error was written to errmsg_buf, it'll be returned to the caller
- * of XLogReadRecord() after all successfully decoded records from the
- * read queue.
+ * If an error was written to errormsg_buf, it'll be returned to the
+ * caller of XLogReadRecord() after all successfully decoded records from
+ * the read queue.
*/
return XLREAD_FAIL;
@@ -1131,7 +1142,7 @@ ValidXLogRecordHeader(XLogReaderState *state, XLogRecPtr RecPtr,
if (record->xl_tot_len < SizeOfXLogRecord)
{
report_invalid_record(state,
- "invalid record length at %X/%X: expected at least %u, got %u",
+ "invalid record length at %X/%08X: expected at least %u, got %u",
LSN_FORMAT_ARGS(RecPtr),
(uint32) SizeOfXLogRecord, record->xl_tot_len);
return false;
@@ -1139,7 +1150,7 @@ ValidXLogRecordHeader(XLogReaderState *state, XLogRecPtr RecPtr,
if (!RmgrIdIsValid(record->xl_rmid))
{
report_invalid_record(state,
- "invalid resource manager ID %u at %X/%X",
+ "invalid resource manager ID %u at %X/%08X",
record->xl_rmid, LSN_FORMAT_ARGS(RecPtr));
return false;
}
@@ -1152,7 +1163,7 @@ ValidXLogRecordHeader(XLogReaderState *state, XLogRecPtr RecPtr,
if (!(record->xl_prev < RecPtr))
{
report_invalid_record(state,
- "record with incorrect prev-link %X/%X at %X/%X",
+ "record with incorrect prev-link %X/%08X at %X/%08X",
LSN_FORMAT_ARGS(record->xl_prev),
LSN_FORMAT_ARGS(RecPtr));
return false;
@@ -1168,7 +1179,7 @@ ValidXLogRecordHeader(XLogReaderState *state, XLogRecPtr RecPtr,
if (record->xl_prev != PrevRecPtr)
{
report_invalid_record(state,
- "record with incorrect prev-link %X/%X at %X/%X",
+ "record with incorrect prev-link %X/%08X at %X/%08X",
LSN_FORMAT_ARGS(record->xl_prev),
LSN_FORMAT_ARGS(RecPtr));
return false;
@@ -1206,7 +1217,7 @@ ValidXLogRecord(XLogReaderState *state, XLogRecord *record, XLogRecPtr recptr)
if (!EQ_CRC32C(record->xl_crc, crc))
{
report_invalid_record(state,
- "incorrect resource manager data checksum in record at %X/%X",
+ "incorrect resource manager data checksum in record at %X/%08X",
LSN_FORMAT_ARGS(recptr));
return false;
}
@@ -1240,7 +1251,7 @@ XLogReaderValidatePageHeader(XLogReaderState *state, XLogRecPtr recptr,
XLogFileName(fname, state->seg.ws_tli, segno, state->segcxt.ws_segsize);
report_invalid_record(state,
- "invalid magic number %04X in WAL segment %s, LSN %X/%X, offset %u",
+ "invalid magic number %04X in WAL segment %s, LSN %X/%08X, offset %u",
hdr->xlp_magic,
fname,
LSN_FORMAT_ARGS(recptr),
@@ -1255,7 +1266,7 @@ XLogReaderValidatePageHeader(XLogReaderState *state, XLogRecPtr recptr,
XLogFileName(fname, state->seg.ws_tli, segno, state->segcxt.ws_segsize);
report_invalid_record(state,
- "invalid info bits %04X in WAL segment %s, LSN %X/%X, offset %u",
+ "invalid info bits %04X in WAL segment %s, LSN %X/%08X, offset %u",
hdr->xlp_info,
fname,
LSN_FORMAT_ARGS(recptr),
@@ -1271,9 +1282,9 @@ XLogReaderValidatePageHeader(XLogReaderState *state, XLogRecPtr recptr,
longhdr->xlp_sysid != state->system_identifier)
{
report_invalid_record(state,
- "WAL file is from different database system: WAL file database system identifier is %llu, pg_control database system identifier is %llu",
- (unsigned long long) longhdr->xlp_sysid,
- (unsigned long long) state->system_identifier);
+ "WAL file is from different database system: WAL file database system identifier is %" PRIu64 ", pg_control database system identifier is %" PRIu64,
+ longhdr->xlp_sysid,
+ state->system_identifier);
return false;
}
else if (longhdr->xlp_seg_size != state->segcxt.ws_segsize)
@@ -1297,7 +1308,7 @@ XLogReaderValidatePageHeader(XLogReaderState *state, XLogRecPtr recptr,
/* hmm, first page of file doesn't have a long header? */
report_invalid_record(state,
- "invalid info bits %04X in WAL segment %s, LSN %X/%X, offset %u",
+ "invalid info bits %04X in WAL segment %s, LSN %X/%08X, offset %u",
hdr->xlp_info,
fname,
LSN_FORMAT_ARGS(recptr),
@@ -1317,7 +1328,7 @@ XLogReaderValidatePageHeader(XLogReaderState *state, XLogRecPtr recptr,
XLogFileName(fname, state->seg.ws_tli, segno, state->segcxt.ws_segsize);
report_invalid_record(state,
- "unexpected pageaddr %X/%X in WAL segment %s, LSN %X/%X, offset %u",
+ "unexpected pageaddr %X/%08X in WAL segment %s, LSN %X/%08X, offset %u",
LSN_FORMAT_ARGS(hdr->xlp_pageaddr),
fname,
LSN_FORMAT_ARGS(recptr),
@@ -1343,7 +1354,7 @@ XLogReaderValidatePageHeader(XLogReaderState *state, XLogRecPtr recptr,
XLogFileName(fname, state->seg.ws_tli, segno, state->segcxt.ws_segsize);
report_invalid_record(state,
- "out-of-sequence timeline ID %u (after %u) in WAL segment %s, LSN %X/%X, offset %u",
+ "out-of-sequence timeline ID %u (after %u) in WAL segment %s, LSN %X/%08X, offset %u",
hdr->xlp_tli,
state->latestPageTLI,
fname,
@@ -1507,6 +1518,9 @@ WALRead(XLogReaderState *state,
char *p;
XLogRecPtr recptr;
Size nbytes;
+#ifndef FRONTEND
+ instr_time io_start;
+#endif
p = buf;
recptr = startptr;
@@ -1552,6 +1566,9 @@ WALRead(XLogReaderState *state,
segbytes = nbytes;
#ifndef FRONTEND
+ /* Measure I/O timing when reading segment */
+ io_start = pgstat_prepare_io_time(track_wal_io_timing);
+
pgstat_report_wait_start(WAIT_EVENT_WAL_READ);
#endif
@@ -1561,6 +1578,9 @@ WALRead(XLogReaderState *state,
#ifndef FRONTEND
pgstat_report_wait_end();
+
+ pgstat_count_io_op_time(IOOBJECT_WAL, IOCONTEXT_NORMAL, IOOP_READ,
+ io_start, 1, readbytes);
#endif
if (readbytes <= 0)
@@ -1746,7 +1766,7 @@ DecodeXLogRecord(XLogReaderState *state,
if (block_id <= decoded->max_block_id)
{
report_invalid_record(state,
- "out-of-order block_id %u at %X/%X",
+ "out-of-order block_id %u at %X/%08X",
block_id,
LSN_FORMAT_ARGS(state->ReadRecPtr));
goto err;
@@ -1770,14 +1790,14 @@ DecodeXLogRecord(XLogReaderState *state,
if (blk->has_data && blk->data_len == 0)
{
report_invalid_record(state,
- "BKPBLOCK_HAS_DATA set, but no data included at %X/%X",
+ "BKPBLOCK_HAS_DATA set, but no data included at %X/%08X",
LSN_FORMAT_ARGS(state->ReadRecPtr));
goto err;
}
if (!blk->has_data && blk->data_len != 0)
{
report_invalid_record(state,
- "BKPBLOCK_HAS_DATA not set, but data length is %u at %X/%X",
+ "BKPBLOCK_HAS_DATA not set, but data length is %u at %X/%08X",
(unsigned int) blk->data_len,
LSN_FORMAT_ARGS(state->ReadRecPtr));
goto err;
@@ -1813,7 +1833,7 @@ DecodeXLogRecord(XLogReaderState *state,
blk->bimg_len == BLCKSZ))
{
report_invalid_record(state,
- "BKPIMAGE_HAS_HOLE set, but hole offset %u length %u block image length %u at %X/%X",
+ "BKPIMAGE_HAS_HOLE set, but hole offset %u length %u block image length %u at %X/%08X",
(unsigned int) blk->hole_offset,
(unsigned int) blk->hole_length,
(unsigned int) blk->bimg_len,
@@ -1829,7 +1849,7 @@ DecodeXLogRecord(XLogReaderState *state,
(blk->hole_offset != 0 || blk->hole_length != 0))
{
report_invalid_record(state,
- "BKPIMAGE_HAS_HOLE not set, but hole offset %u length %u at %X/%X",
+ "BKPIMAGE_HAS_HOLE not set, but hole offset %u length %u at %X/%08X",
(unsigned int) blk->hole_offset,
(unsigned int) blk->hole_length,
LSN_FORMAT_ARGS(state->ReadRecPtr));
@@ -1843,7 +1863,7 @@ DecodeXLogRecord(XLogReaderState *state,
blk->bimg_len == BLCKSZ)
{
report_invalid_record(state,
- "BKPIMAGE_COMPRESSED set, but block image length %u at %X/%X",
+ "BKPIMAGE_COMPRESSED set, but block image length %u at %X/%08X",
(unsigned int) blk->bimg_len,
LSN_FORMAT_ARGS(state->ReadRecPtr));
goto err;
@@ -1858,7 +1878,7 @@ DecodeXLogRecord(XLogReaderState *state,
blk->bimg_len != BLCKSZ)
{
report_invalid_record(state,
- "neither BKPIMAGE_HAS_HOLE nor BKPIMAGE_COMPRESSED set, but block image length is %u at %X/%X",
+ "neither BKPIMAGE_HAS_HOLE nor BKPIMAGE_COMPRESSED set, but block image length is %u at %X/%08X",
(unsigned int) blk->data_len,
LSN_FORMAT_ARGS(state->ReadRecPtr));
goto err;
@@ -1874,7 +1894,7 @@ DecodeXLogRecord(XLogReaderState *state,
if (rlocator == NULL)
{
report_invalid_record(state,
- "BKPBLOCK_SAME_REL set but no previous rel at %X/%X",
+ "BKPBLOCK_SAME_REL set but no previous rel at %X/%08X",
LSN_FORMAT_ARGS(state->ReadRecPtr));
goto err;
}
@@ -1886,7 +1906,7 @@ DecodeXLogRecord(XLogReaderState *state,
else
{
report_invalid_record(state,
- "invalid block_id %u at %X/%X",
+ "invalid block_id %u at %X/%08X",
block_id, LSN_FORMAT_ARGS(state->ReadRecPtr));
goto err;
}
@@ -1953,7 +1973,7 @@ DecodeXLogRecord(XLogReaderState *state,
shortdata_err:
report_invalid_record(state,
- "record with invalid length at %X/%X",
+ "record with invalid length at %X/%08X",
LSN_FORMAT_ARGS(state->ReadRecPtr));
err:
*errormsg = state->errormsg_buf;
@@ -2063,14 +2083,14 @@ RestoreBlockImage(XLogReaderState *record, uint8 block_id, char *page)
!record->record->blocks[block_id].in_use)
{
report_invalid_record(record,
- "could not restore image at %X/%X with invalid block %d specified",
+ "could not restore image at %X/%08X with invalid block %d specified",
LSN_FORMAT_ARGS(record->ReadRecPtr),
block_id);
return false;
}
if (!record->record->blocks[block_id].has_image)
{
- report_invalid_record(record, "could not restore image at %X/%X with invalid state, block %d",
+ report_invalid_record(record, "could not restore image at %X/%08X with invalid state, block %d",
LSN_FORMAT_ARGS(record->ReadRecPtr),
block_id);
return false;
@@ -2097,7 +2117,7 @@ RestoreBlockImage(XLogReaderState *record, uint8 block_id, char *page)
bkpb->bimg_len, BLCKSZ - bkpb->hole_length) <= 0)
decomp_success = false;
#else
- report_invalid_record(record, "could not restore image at %X/%X compressed with %s not supported by build, block %d",
+ report_invalid_record(record, "could not restore image at %X/%08X compressed with %s not supported by build, block %d",
LSN_FORMAT_ARGS(record->ReadRecPtr),
"LZ4",
block_id);
@@ -2114,7 +2134,7 @@ RestoreBlockImage(XLogReaderState *record, uint8 block_id, char *page)
if (ZSTD_isError(decomp_result))
decomp_success = false;
#else
- report_invalid_record(record, "could not restore image at %X/%X compressed with %s not supported by build, block %d",
+ report_invalid_record(record, "could not restore image at %X/%08X compressed with %s not supported by build, block %d",
LSN_FORMAT_ARGS(record->ReadRecPtr),
"zstd",
block_id);
@@ -2123,7 +2143,7 @@ RestoreBlockImage(XLogReaderState *record, uint8 block_id, char *page)
}
else
{
- report_invalid_record(record, "could not restore image at %X/%X compressed with unknown method, block %d",
+ report_invalid_record(record, "could not restore image at %X/%08X compressed with unknown method, block %d",
LSN_FORMAT_ARGS(record->ReadRecPtr),
block_id);
return false;
@@ -2131,7 +2151,7 @@ RestoreBlockImage(XLogReaderState *record, uint8 block_id, char *page)
if (!decomp_success)
{
- report_invalid_record(record, "could not decompress image at %X/%X, block %d",
+ report_invalid_record(record, "could not decompress image at %X/%08X, block %d",
LSN_FORMAT_ARGS(record->ReadRecPtr),
block_id);
return false;
@@ -2166,28 +2186,14 @@ RestoreBlockImage(XLogReaderState *record, uint8 block_id, char *page)
FullTransactionId
XLogRecGetFullXid(XLogReaderState *record)
{
- TransactionId xid,
- next_xid;
- uint32 epoch;
-
/*
* This function is only safe during replay, because it depends on the
* replay state. See AdvanceNextFullTransactionIdPastXid() for more.
*/
Assert(AmStartupProcess() || !IsUnderPostmaster);
- xid = XLogRecGetXid(record);
- next_xid = XidFromFullTransactionId(TransamVariables->nextXid);
- epoch = EpochFromFullTransactionId(TransamVariables->nextXid);
-
- /*
- * If xid is numerically greater than next_xid, it has to be from the last
- * epoch.
- */
- if (unlikely(xid > next_xid))
- --epoch;
-
- return FullTransactionIdFromEpochAndXid(epoch, xid);
+ return FullTransactionIdFromAllowableAt(TransamVariables->nextXid,
+ XLogRecGetXid(record));
}
#endif
diff --git a/src/backend/access/transam/xlogrecovery.c b/src/backend/access/transam/xlogrecovery.c
index b45b833172005..346319338a0ee 100644
--- a/src/backend/access/transam/xlogrecovery.c
+++ b/src/backend/access/transam/xlogrecovery.c
@@ -14,7 +14,7 @@
* for interrogating recovery state and controlling the recovery process.
*
*
- * Portions Copyright (c) 1996-2024, PostgreSQL Global Development Group
+ * Portions Copyright (c) 1996-2025, PostgreSQL Global Development Group
* Portions Copyright (c) 1994, Regents of the University of California
*
* src/backend/access/transam/xlogrecovery.c
@@ -60,6 +60,7 @@
#include "utils/datetime.h"
#include "utils/fmgrprotos.h"
#include "utils/guc_hooks.h"
+#include "utils/pgstat_internal.h"
#include "utils/pg_lsn.h"
#include "utils/ps_status.h"
#include "utils/pg_rusage.h"
@@ -290,6 +291,11 @@ static bool backupEndRequired = false;
* Consistent state means that the system is internally consistent, all
* the WAL has been replayed up to a certain point, and importantly, there
* is no trace of later actions on disk.
+ *
+ * This flag is used only by the startup process and postmaster. When
+ * minRecoveryPoint is reached, the startup process sets it to true and
+ * sends a PMSIGNAL_RECOVERY_CONSISTENT signal to the postmaster,
+ * which then sets it to true upon receiving the signal.
*/
bool reachedConsistency = false;
@@ -429,9 +435,9 @@ static int emode_for_corrupt_record(int emode, XLogRecPtr RecPtr);
static XLogRecord *ReadCheckpointRecord(XLogPrefetcher *xlogprefetcher,
XLogRecPtr RecPtr, TimeLineID replayTLI);
static bool rescanLatestTimeLine(TimeLineID replayTLI, XLogRecPtr replayLSN);
-static int XLogFileRead(XLogSegNo segno, int emode, TimeLineID tli,
+static int XLogFileRead(XLogSegNo segno, TimeLineID tli,
XLogSource source, bool notfoundOk);
-static int XLogFileReadAnyTLI(XLogSegNo segno, int emode, XLogSource source);
+static int XLogFileReadAnyTLI(XLogSegNo segno, XLogSource source);
static bool CheckForStandbyTrigger(void);
static void SetPromoteIsTriggered(void);
@@ -614,10 +620,10 @@ InitWalRecovery(ControlFileData *ControlFile, bool *wasShutdown_ptr,
* than ControlFile->checkPoint is used.
*/
ereport(LOG,
- (errmsg("starting backup recovery with redo LSN %X/%X, checkpoint LSN %X/%X, on timeline ID %u",
- LSN_FORMAT_ARGS(RedoStartLSN),
- LSN_FORMAT_ARGS(CheckPointLoc),
- CheckPointTLI)));
+ errmsg("starting backup recovery with redo LSN %X/%08X, checkpoint LSN %X/%08X, on timeline ID %u",
+ LSN_FORMAT_ARGS(RedoStartLSN),
+ LSN_FORMAT_ARGS(CheckPointLoc),
+ CheckPointTLI));
/*
* When a backup_label file is present, we want to roll forward from
@@ -630,8 +636,8 @@ InitWalRecovery(ControlFileData *ControlFile, bool *wasShutdown_ptr,
memcpy(&checkPoint, XLogRecGetData(xlogreader), sizeof(CheckPoint));
wasShutdown = ((record->xl_info & ~XLR_INFO_MASK) == XLOG_CHECKPOINT_SHUTDOWN);
ereport(DEBUG1,
- (errmsg_internal("checkpoint record is at %X/%X",
- LSN_FORMAT_ARGS(CheckPointLoc))));
+ errmsg_internal("checkpoint record is at %X/%08X",
+ LSN_FORMAT_ARGS(CheckPointLoc)));
InRecovery = true; /* force recovery even if SHUTDOWNED */
/*
@@ -646,23 +652,23 @@ InitWalRecovery(ControlFileData *ControlFile, bool *wasShutdown_ptr,
if (!ReadRecord(xlogprefetcher, LOG, false,
checkPoint.ThisTimeLineID))
ereport(FATAL,
- (errmsg("could not find redo location %X/%X referenced by checkpoint record at %X/%X",
- LSN_FORMAT_ARGS(checkPoint.redo), LSN_FORMAT_ARGS(CheckPointLoc)),
- errhint("If you are restoring from a backup, touch \"%s/recovery.signal\" or \"%s/standby.signal\" and add required recovery options.\n"
- "If you are not restoring from a backup, try removing the file \"%s/backup_label\".\n"
- "Be careful: removing \"%s/backup_label\" will result in a corrupt cluster if restoring from a backup.",
- DataDir, DataDir, DataDir, DataDir)));
+ errmsg("could not find redo location %X/%08X referenced by checkpoint record at %X/%08X",
+ LSN_FORMAT_ARGS(checkPoint.redo), LSN_FORMAT_ARGS(CheckPointLoc)),
+ errhint("If you are restoring from a backup, touch \"%s/recovery.signal\" or \"%s/standby.signal\" and add required recovery options.\n"
+ "If you are not restoring from a backup, try removing the file \"%s/backup_label\".\n"
+ "Be careful: removing \"%s/backup_label\" will result in a corrupt cluster if restoring from a backup.",
+ DataDir, DataDir, DataDir, DataDir));
}
}
else
{
ereport(FATAL,
- (errmsg("could not locate required checkpoint record at %X/%X",
- LSN_FORMAT_ARGS(CheckPointLoc)),
- errhint("If you are restoring from a backup, touch \"%s/recovery.signal\" or \"%s/standby.signal\" and add required recovery options.\n"
- "If you are not restoring from a backup, try removing the file \"%s/backup_label\".\n"
- "Be careful: removing \"%s/backup_label\" will result in a corrupt cluster if restoring from a backup.",
- DataDir, DataDir, DataDir, DataDir)));
+ errmsg("could not locate required checkpoint record at %X/%08X",
+ LSN_FORMAT_ARGS(CheckPointLoc)),
+ errhint("If you are restoring from a backup, touch \"%s/recovery.signal\" or \"%s/standby.signal\" and add required recovery options.\n"
+ "If you are not restoring from a backup, try removing the file \"%s/backup_label\".\n"
+ "Be careful: removing \"%s/backup_label\" will result in a corrupt cluster if restoring from a backup.",
+ DataDir, DataDir, DataDir, DataDir));
wasShutdown = false; /* keep compiler quiet */
}
@@ -676,7 +682,7 @@ InitWalRecovery(ControlFileData *ControlFile, bool *wasShutdown_ptr,
tablespaceinfo *ti = lfirst(lc);
char *linkloc;
- linkloc = psprintf("pg_tblspc/%u", ti->oid);
+ linkloc = psprintf("%s/%u", PG_TBLSPC_DIR, ti->oid);
/*
* Remove the existing symlink if any and Create the symlink
@@ -767,8 +773,8 @@ InitWalRecovery(ControlFileData *ControlFile, bool *wasShutdown_ptr,
*/
if (!XLogRecPtrIsInvalid(ControlFile->backupStartPoint))
ereport(LOG,
- (errmsg("restarting backup recovery with redo LSN %X/%X",
- LSN_FORMAT_ARGS(ControlFile->backupStartPoint))));
+ errmsg("restarting backup recovery with redo LSN %X/%08X",
+ LSN_FORMAT_ARGS(ControlFile->backupStartPoint)));
/* Get the last valid checkpoint record. */
CheckPointLoc = ControlFile->checkPoint;
@@ -780,8 +786,8 @@ InitWalRecovery(ControlFileData *ControlFile, bool *wasShutdown_ptr,
if (record != NULL)
{
ereport(DEBUG1,
- (errmsg_internal("checkpoint record is at %X/%X",
- LSN_FORMAT_ARGS(CheckPointLoc))));
+ errmsg_internal("checkpoint record is at %X/%08X",
+ LSN_FORMAT_ARGS(CheckPointLoc)));
}
else
{
@@ -792,8 +798,8 @@ InitWalRecovery(ControlFileData *ControlFile, bool *wasShutdown_ptr,
* simplify processing around checkpoints.
*/
ereport(PANIC,
- (errmsg("could not locate a valid checkpoint record at %X/%X",
- LSN_FORMAT_ARGS(CheckPointLoc))));
+ errmsg("could not locate a valid checkpoint record at %X/%08X",
+ LSN_FORMAT_ARGS(CheckPointLoc)));
}
memcpy(&checkPoint, XLogRecGetData(xlogreader), sizeof(CheckPoint));
wasShutdown = ((record->xl_info & ~XLR_INFO_MASK) == XLOG_CHECKPOINT_SHUTDOWN);
@@ -818,8 +824,8 @@ InitWalRecovery(ControlFileData *ControlFile, bool *wasShutdown_ptr,
recoveryTargetName)));
else if (recoveryTarget == RECOVERY_TARGET_LSN)
ereport(LOG,
- (errmsg("starting point-in-time recovery to WAL location (LSN) \"%X/%X\"",
- LSN_FORMAT_ARGS(recoveryTargetLSN))));
+ errmsg("starting point-in-time recovery to WAL location (LSN) \"%X/%08X\"",
+ LSN_FORMAT_ARGS(recoveryTargetLSN)));
else if (recoveryTarget == RECOVERY_TARGET_IMMEDIATE)
ereport(LOG,
(errmsg("starting point-in-time recovery to earliest consistent point")));
@@ -844,13 +850,15 @@ InitWalRecovery(ControlFileData *ControlFile, bool *wasShutdown_ptr,
* tliSwitchPoint will throw an error if the checkpoint's timeline is
* not in expectedTLEs at all.
*/
- switchpoint = tliSwitchPoint(ControlFile->checkPointCopy.ThisTimeLineID, expectedTLEs, NULL);
+ switchpoint = tliSwitchPoint(CheckPointTLI, expectedTLEs, NULL);
ereport(FATAL,
(errmsg("requested timeline %u is not a child of this server's history",
recoveryTargetTLI),
- errdetail("Latest checkpoint is at %X/%X on timeline %u, but in the history of the requested timeline, the server forked off from that timeline at %X/%X.",
- LSN_FORMAT_ARGS(ControlFile->checkPoint),
- ControlFile->checkPointCopy.ThisTimeLineID,
+ /* translator: %s is a backup_label file or a pg_control file */
+ errdetail("Latest checkpoint in file \"%s\" is at %X/%08X on timeline %u, but in the history of the requested timeline, the server forked off from that timeline at %X/%08X.",
+ haveBackupLabel ? "backup_label" : "pg_control",
+ LSN_FORMAT_ARGS(CheckPointLoc),
+ CheckPointTLI,
LSN_FORMAT_ARGS(switchpoint))));
}
@@ -862,15 +870,15 @@ InitWalRecovery(ControlFileData *ControlFile, bool *wasShutdown_ptr,
tliOfPointInHistory(ControlFile->minRecoveryPoint - 1, expectedTLEs) !=
ControlFile->minRecoveryPointTLI)
ereport(FATAL,
- (errmsg("requested timeline %u does not contain minimum recovery point %X/%X on timeline %u",
- recoveryTargetTLI,
- LSN_FORMAT_ARGS(ControlFile->minRecoveryPoint),
- ControlFile->minRecoveryPointTLI)));
+ errmsg("requested timeline %u does not contain minimum recovery point %X/%08X on timeline %u",
+ recoveryTargetTLI,
+ LSN_FORMAT_ARGS(ControlFile->minRecoveryPoint),
+ ControlFile->minRecoveryPointTLI));
ereport(DEBUG1,
- (errmsg_internal("redo record is at %X/%X; shutdown %s",
- LSN_FORMAT_ARGS(checkPoint.redo),
- wasShutdown ? "true" : "false")));
+ errmsg_internal("redo record is at %X/%08X; shutdown %s",
+ LSN_FORMAT_ARGS(checkPoint.redo),
+ wasShutdown ? "true" : "false"));
ereport(DEBUG1,
(errmsg_internal("next transaction ID: " UINT64_FORMAT "; next OID: %u",
U64FromFullTransactionId(checkPoint.nextXid),
@@ -1245,14 +1253,14 @@ read_backup_label(XLogRecPtr *checkPointLoc, TimeLineID *backupLabelTLI,
* is pretty crude, but we are not expecting any variability in the file
* format).
*/
- if (fscanf(lfp, "START WAL LOCATION: %X/%X (file %08X%16s)%c",
+ if (fscanf(lfp, "START WAL LOCATION: %X/%08X (file %08X%16s)%c",
&hi, &lo, &tli_from_walseg, startxlogfilename, &ch) != 5 || ch != '\n')
ereport(FATAL,
(errcode(ERRCODE_OBJECT_NOT_IN_PREREQUISITE_STATE),
errmsg("invalid data in file \"%s\"", BACKUP_LABEL_FILE)));
RedoStartLSN = ((uint64) hi) << 32 | lo;
RedoStartTLI = tli_from_walseg;
- if (fscanf(lfp, "CHECKPOINT LOCATION: %X/%X%c",
+ if (fscanf(lfp, "CHECKPOINT LOCATION: %X/%08X%c",
&hi, &lo, &ch) != 3 || ch != '\n')
ereport(FATAL,
(errcode(ERRCODE_OBJECT_NOT_IN_PREREQUISITE_STATE),
@@ -1324,7 +1332,7 @@ read_backup_label(XLogRecPtr *checkPointLoc, TimeLineID *backupLabelTLI,
tli_from_file, BACKUP_LABEL_FILE)));
}
- if (fscanf(lfp, "INCREMENTAL FROM LSN: %X/%X\n", &hi, &lo) > 0)
+ if (fscanf(lfp, "INCREMENTAL FROM LSN: %X/%08X\n", &hi, &lo) > 0)
ereport(FATAL,
(errcode(ERRCODE_OBJECT_NOT_IN_PREREQUISITE_STATE),
errmsg("this is an incremental backup, not a data directory"),
@@ -1618,6 +1626,7 @@ ShutdownWalRecovery(void)
close(readFile);
readFile = -1;
}
+ pfree(xlogreader->private_data);
XLogReaderFree(xlogreader);
XLogPrefetcherFree(xlogprefetcher);
@@ -1714,8 +1723,8 @@ PerformWalRecovery(void)
if (record->xl_rmid != RM_XLOG_ID ||
(record->xl_info & ~XLR_INFO_MASK) != XLOG_CHECKPOINT_REDO)
ereport(FATAL,
- (errmsg("unexpected record type found at redo point %X/%X",
- LSN_FORMAT_ARGS(xlogreader->ReadRecPtr))));
+ errmsg("unexpected record type found at redo point %X/%08X",
+ LSN_FORMAT_ARGS(xlogreader->ReadRecPtr)));
}
else
{
@@ -1737,8 +1746,8 @@ PerformWalRecovery(void)
RmgrStartup();
ereport(LOG,
- (errmsg("redo starts at %X/%X",
- LSN_FORMAT_ARGS(xlogreader->ReadRecPtr))));
+ errmsg("redo starts at %X/%08X",
+ LSN_FORMAT_ARGS(xlogreader->ReadRecPtr)));
/* Prepare to report progress of the redo phase. */
if (!StandbyMode)
@@ -1750,7 +1759,7 @@ PerformWalRecovery(void)
do
{
if (!StandbyMode)
- ereport_startup_progress("redo in progress, elapsed time: %ld.%02d s, current LSN: %X/%X",
+ ereport_startup_progress("redo in progress, elapsed time: %ld.%02d s, current LSN: %X/%08X",
LSN_FORMAT_ARGS(xlogreader->ReadRecPtr));
#ifdef WAL_DEBUG
@@ -1759,7 +1768,7 @@ PerformWalRecovery(void)
StringInfoData buf;
initStringInfo(&buf);
- appendStringInfo(&buf, "REDO @ %X/%X; LSN %X/%X: ",
+ appendStringInfo(&buf, "REDO @ %X/%08X; LSN %X/%08X: ",
LSN_FORMAT_ARGS(xlogreader->ReadRecPtr),
LSN_FORMAT_ARGS(xlogreader->EndRecPtr));
xlog_outrec(&buf, xlogreader);
@@ -1771,7 +1780,7 @@ PerformWalRecovery(void)
#endif
/* Handle interrupt signals of startup process */
- HandleStartupProcInterrupts();
+ ProcessStartupProcInterrupts();
/*
* Pause WAL replay, if requested by a hot-standby session via
@@ -1872,9 +1881,9 @@ PerformWalRecovery(void)
RmgrCleanup();
ereport(LOG,
- (errmsg("redo done at %X/%X system usage: %s",
- LSN_FORMAT_ARGS(xlogreader->ReadRecPtr),
- pg_rusage_show(&ru0))));
+ errmsg("redo done at %X/%08X system usage: %s",
+ LSN_FORMAT_ARGS(xlogreader->ReadRecPtr),
+ pg_rusage_show(&ru0)));
xtime = GetLatestXTime();
if (xtime)
ereport(LOG,
@@ -1898,7 +1907,8 @@ PerformWalRecovery(void)
recoveryTarget != RECOVERY_TARGET_UNSET &&
!reachedRecoveryTarget)
ereport(FATAL,
- (errmsg("recovery ended before configured recovery target was reached")));
+ (errcode(ERRCODE_CONFIG_FILE_ERROR),
+ errmsg("recovery ended before configured recovery target was reached")));
}
/*
@@ -1912,7 +1922,7 @@ ApplyWalRecord(XLogReaderState *xlogreader, XLogRecord *record, TimeLineID *repl
/* Setup error traceback support for ereport() */
errcallback.callback = rm_redo_error_callback;
- errcallback.arg = (void *) xlogreader;
+ errcallback.arg = xlogreader;
errcallback.previous = error_context_stack;
error_context_stack = &errcallback;
@@ -2083,7 +2093,7 @@ xlogrecovery_redo(XLogReaderState *record, TimeLineID replayTLI)
memcpy(&xlrec, XLogRecGetData(record), sizeof(xl_overwrite_contrecord));
if (xlrec.overwritten_lsn != record->overwrittenRecPtr)
- elog(FATAL, "mismatching overwritten LSN %X/%X -> %X/%X",
+ elog(FATAL, "mismatching overwritten LSN %X/%08X -> %X/%08X",
LSN_FORMAT_ARGS(xlrec.overwritten_lsn),
LSN_FORMAT_ARGS(record->overwrittenRecPtr));
@@ -2092,9 +2102,9 @@ xlogrecovery_redo(XLogReaderState *record, TimeLineID replayTLI)
missingContrecPtr = InvalidXLogRecPtr;
ereport(LOG,
- (errmsg("successfully skipped missing contrecord at %X/%X, overwritten at %s",
- LSN_FORMAT_ARGS(xlrec.overwritten_lsn),
- timestamptz_to_str(xlrec.overwrite_time))));
+ errmsg("successfully skipped missing contrecord at %X/%08X, overwritten at %s",
+ LSN_FORMAT_ARGS(xlrec.overwritten_lsn),
+ timestamptz_to_str(xlrec.overwrite_time)));
/* Verifying the record should only happen once */
record->overwrittenRecPtr = InvalidXLogRecPtr;
@@ -2120,7 +2130,7 @@ xlogrecovery_redo(XLogReaderState *record, TimeLineID replayTLI)
backupEndPoint = lsn;
}
else
- elog(DEBUG1, "saw end-of-backup record for backup starting at %X/%X, waiting for %X/%X",
+ elog(DEBUG1, "saw end-of-backup record for backup starting at %X/%08X, waiting for %X/%08X",
LSN_FORMAT_ARGS(startpoint), LSN_FORMAT_ARGS(backupStartPoint));
}
}
@@ -2145,23 +2155,24 @@ CheckTablespaceDirectory(void)
DIR *dir;
struct dirent *de;
- dir = AllocateDir("pg_tblspc");
- while ((de = ReadDir(dir, "pg_tblspc")) != NULL)
+ dir = AllocateDir(PG_TBLSPC_DIR);
+ while ((de = ReadDir(dir, PG_TBLSPC_DIR)) != NULL)
{
- char path[MAXPGPATH + 10];
+ char path[MAXPGPATH + sizeof(PG_TBLSPC_DIR)];
/* Skip entries of non-oid names */
if (strspn(de->d_name, "0123456789") != strlen(de->d_name))
continue;
- snprintf(path, sizeof(path), "pg_tblspc/%s", de->d_name);
+ snprintf(path, sizeof(path), "%s/%s", PG_TBLSPC_DIR, de->d_name);
if (get_dirent_type(path, de, false, ERROR) != PGFILETYPE_LNK)
ereport(allow_in_place_tablespaces ? WARNING : PANIC,
(errcode(ERRCODE_DATA_CORRUPTED),
errmsg("unexpected directory entry \"%s\" found in %s",
- de->d_name, "pg_tblspc/"),
- errdetail("All directory entries in pg_tblspc/ should be symbolic links."),
+ de->d_name, PG_TBLSPC_DIR),
+ errdetail("All directory entries in %s/ should be symbolic links.",
+ PG_TBLSPC_DIR),
errhint("Remove those directories, or set \"allow_in_place_tablespaces\" to ON transiently to let recovery complete.")));
}
}
@@ -2214,9 +2225,9 @@ CheckRecoveryConsistency(void)
backupEndRequired = false;
ereport(LOG,
- (errmsg("completed backup recovery with redo LSN %X/%X and end LSN %X/%X",
- LSN_FORMAT_ARGS(saveBackupStartPoint),
- LSN_FORMAT_ARGS(saveBackupEndPoint))));
+ errmsg("completed backup recovery with redo LSN %X/%08X and end LSN %X/%08X",
+ LSN_FORMAT_ARGS(saveBackupStartPoint),
+ LSN_FORMAT_ARGS(saveBackupEndPoint)));
}
/*
@@ -2243,9 +2254,10 @@ CheckRecoveryConsistency(void)
CheckTablespaceDirectory();
reachedConsistency = true;
+ SendPostmasterSignal(PMSIGNAL_RECOVERY_CONSISTENT);
ereport(LOG,
- (errmsg("consistent recovery state reached at %X/%X",
- LSN_FORMAT_ARGS(lastReplayedEndRecPtr))));
+ errmsg("consistent recovery state reached at %X/%08X",
+ LSN_FORMAT_ARGS(lastReplayedEndRecPtr)));
}
/*
@@ -2282,7 +2294,7 @@ rm_redo_error_callback(void *arg)
xlog_block_info(&buf, record);
/* translator: %s is a WAL record description */
- errcontext("WAL redo at %X/%X for %s",
+ errcontext("WAL redo at %X/%08X for %s",
LSN_FORMAT_ARGS(record->ReadRecPtr),
buf.data);
@@ -2317,7 +2329,7 @@ xlog_outdesc(StringInfo buf, XLogReaderState *record)
static void
xlog_outrec(StringInfo buf, XLogReaderState *record)
{
- appendStringInfo(buf, "prev %X/%X; xid %u",
+ appendStringInfo(buf, "prev %X/%08X; xid %u",
LSN_FORMAT_ARGS(XLogRecGetPrev(record)),
XLogRecGetXid(record));
@@ -2405,10 +2417,10 @@ checkTimeLineSwitch(XLogRecPtr lsn, TimeLineID newTLI, TimeLineID prevTLI,
lsn < minRecoveryPoint &&
newTLI > minRecoveryPointTLI)
ereport(PANIC,
- (errmsg("unexpected timeline ID %u in checkpoint record, before reaching minimum recovery point %X/%X on timeline %u",
- newTLI,
- LSN_FORMAT_ARGS(minRecoveryPoint),
- minRecoveryPointTLI)));
+ errmsg("unexpected timeline ID %u in checkpoint record, before reaching minimum recovery point %X/%08X on timeline %u",
+ newTLI,
+ LSN_FORMAT_ARGS(minRecoveryPoint),
+ minRecoveryPointTLI));
/* Looks good */
}
@@ -2610,8 +2622,8 @@ recoveryStopsBefore(XLogReaderState *record)
recoveryStopTime = 0;
recoveryStopName[0] = '\0';
ereport(LOG,
- (errmsg("recovery stopping before WAL location (LSN) \"%X/%X\"",
- LSN_FORMAT_ARGS(recoveryStopLSN))));
+ errmsg("recovery stopping before WAL location (LSN) \"%X/%08X\"",
+ LSN_FORMAT_ARGS(recoveryStopLSN)));
return true;
}
@@ -2778,8 +2790,8 @@ recoveryStopsAfter(XLogReaderState *record)
recoveryStopTime = 0;
recoveryStopName[0] = '\0';
ereport(LOG,
- (errmsg("recovery stopping after WAL location (LSN) \"%X/%X\"",
- LSN_FORMAT_ARGS(recoveryStopLSN))));
+ errmsg("recovery stopping after WAL location (LSN) \"%X/%08X\"",
+ LSN_FORMAT_ARGS(recoveryStopLSN)));
return true;
}
@@ -2899,7 +2911,7 @@ getRecoveryStopReason(void)
timestamptz_to_str(recoveryStopTime));
else if (recoveryTarget == RECOVERY_TARGET_LSN)
snprintf(reason, sizeof(reason),
- "%s LSN %X/%X\n",
+ "%s LSN %X/%08X\n",
recoveryStopAfter ? "after" : "before",
LSN_FORMAT_ARGS(recoveryStopLSN));
else if (recoveryTarget == RECOVERY_TARGET_NAME)
@@ -2944,7 +2956,7 @@ recoveryPausesHere(bool endOfRecovery)
/* loop until recoveryPauseState is set to RECOVERY_NOT_PAUSED */
while (GetRecoveryPauseState() != RECOVERY_NOT_PAUSED)
{
- HandleStartupProcInterrupts();
+ ProcessStartupProcInterrupts();
if (CheckForStandbyTrigger())
return;
@@ -3033,7 +3045,7 @@ recoveryApplyDelay(XLogReaderState *record)
ResetLatch(&XLogRecoveryCtl->recoveryWakeupLatch);
/* This might change recovery_min_apply_delay. */
- HandleStartupProcInterrupts();
+ ProcessStartupProcInterrupts();
if (CheckForStandbyTrigger())
break;
@@ -3202,11 +3214,11 @@ ReadRecord(XLogPrefetcher *xlogprefetcher, int emode,
XLogFileName(fname, xlogreader->seg.ws_tli, segno,
wal_segment_size);
ereport(emode_for_corrupt_record(emode, xlogreader->EndRecPtr),
- (errmsg("unexpected timeline ID %u in WAL segment %s, LSN %X/%X, offset %u",
- xlogreader->latestPageTLI,
- fname,
- LSN_FORMAT_ARGS(xlogreader->latestPagePtr),
- offset)));
+ errmsg("unexpected timeline ID %u in WAL segment %s, LSN %X/%08X, offset %u",
+ xlogreader->latestPageTLI,
+ fname,
+ LSN_FORMAT_ARGS(xlogreader->latestPagePtr),
+ offset));
record = NULL;
}
@@ -3304,6 +3316,7 @@ XLogPageRead(XLogReaderState *xlogreader, XLogRecPtr targetPagePtr, int reqLen,
uint32 targetPageOff;
XLogSegNo targetSegNo PG_USED_FOR_ASSERTS_ONLY;
int r;
+ instr_time io_start;
XLByteToSeg(targetPagePtr, targetSegNo, wal_segment_size);
targetPageOff = XLogSegmentOffset(targetPagePtr, wal_segment_size);
@@ -3396,6 +3409,9 @@ XLogPageRead(XLogReaderState *xlogreader, XLogRecPtr targetPagePtr, int reqLen,
/* Read the requested page */
readOff = targetPageOff;
+ /* Measure I/O timing when reading segment */
+ io_start = pgstat_prepare_io_time(track_wal_io_timing);
+
pgstat_report_wait_start(WAIT_EVENT_WAL_READ);
r = pg_pread(readFile, readBuf, XLOG_BLCKSZ, (off_t) readOff);
if (r != XLOG_BLCKSZ)
@@ -3404,26 +3420,33 @@ XLogPageRead(XLogReaderState *xlogreader, XLogRecPtr targetPagePtr, int reqLen,
int save_errno = errno;
pgstat_report_wait_end();
+
+ pgstat_count_io_op_time(IOOBJECT_WAL, IOCONTEXT_NORMAL, IOOP_READ,
+ io_start, 1, r);
+
XLogFileName(fname, curFileTLI, readSegNo, wal_segment_size);
if (r < 0)
{
errno = save_errno;
ereport(emode_for_corrupt_record(emode, targetPagePtr + reqLen),
(errcode_for_file_access(),
- errmsg("could not read from WAL segment %s, LSN %X/%X, offset %u: %m",
+ errmsg("could not read from WAL segment %s, LSN %X/%08X, offset %u: %m",
fname, LSN_FORMAT_ARGS(targetPagePtr),
readOff)));
}
else
ereport(emode_for_corrupt_record(emode, targetPagePtr + reqLen),
(errcode(ERRCODE_DATA_CORRUPTED),
- errmsg("could not read from WAL segment %s, LSN %X/%X, offset %u: read %d of %zu",
+ errmsg("could not read from WAL segment %s, LSN %X/%08X, offset %u: read %d of %zu",
fname, LSN_FORMAT_ARGS(targetPagePtr),
readOff, r, (Size) XLOG_BLCKSZ)));
goto next_record_is_invalid;
}
pgstat_report_wait_end();
+ pgstat_count_io_op_time(IOOBJECT_WAL, IOCONTEXT_NORMAL, IOOP_READ,
+ io_start, 1, r);
+
Assert(targetSegNo == readSegNo);
Assert(targetPageOff == readOff);
Assert(reqLen <= readLen);
@@ -3436,12 +3459,12 @@ XLogPageRead(XLogReaderState *xlogreader, XLogRecPtr targetPagePtr, int reqLen,
* validates the page header anyway, and would propagate the failure up to
* ReadRecord(), which would retry. However, there's a corner case with
* continuation records, if a record is split across two pages such that
- * we would need to read the two pages from different sources. For
- * example, imagine a scenario where a streaming replica is started up,
- * and replay reaches a record that's split across two WAL segments. The
- * first page is only available locally, in pg_wal, because it's already
- * been recycled on the primary. The second page, however, is not present
- * in pg_wal, and we should stream it from the primary. There is a
+ * we would need to read the two pages from different sources across two
+ * WAL segments.
+ *
+ * The first page is only available locally, in pg_wal, because it's
+ * already been recycled on the primary. The second page, however, is not
+ * present in pg_wal, and we should stream it from the primary. There is a
* recycled WAL segment present in pg_wal, with garbage contents, however.
* We would read the first page from the local WAL segment, but when
* reading the second page, we would read the bogus, recycled, WAL
@@ -3463,6 +3486,7 @@ XLogPageRead(XLogReaderState *xlogreader, XLogRecPtr targetPagePtr, int reqLen,
* responsible for the validation.
*/
if (StandbyMode &&
+ (targetPagePtr % wal_segment_size) == 0 &&
!XLogReaderValidatePageHeader(xlogreader, targetPagePtr, readBuf))
{
/*
@@ -3695,7 +3719,7 @@ WaitForWALToBecomeAvailable(XLogRecPtr RecPtr, bool randAccess,
wait_time = wal_retrieve_retry_interval -
TimestampDifferenceMilliseconds(last_fail_time, now);
- elog(LOG, "waiting for WAL to become available at %X/%X",
+ elog(LOG, "waiting for WAL to become available at %X/%08X",
LSN_FORMAT_ARGS(RecPtr));
/* Do background tasks that might benefit us later. */
@@ -3710,7 +3734,7 @@ WaitForWALToBecomeAvailable(XLogRecPtr RecPtr, bool randAccess,
now = GetCurrentTimestamp();
/* Handle interrupt signals of startup process */
- HandleStartupProcInterrupts();
+ ProcessStartupProcInterrupts();
}
last_fail_time = now;
currentSource = XLOG_FROM_ARCHIVE;
@@ -3767,7 +3791,7 @@ WaitForWALToBecomeAvailable(XLogRecPtr RecPtr, bool randAccess,
* Try to restore the file from archive, or read an existing
* file from pg_wal.
*/
- readFile = XLogFileReadAnyTLI(readSegNo, DEBUG2,
+ readFile = XLogFileReadAnyTLI(readSegNo,
currentSource == XLOG_FROM_ARCHIVE ? XLOG_FROM_ANY :
currentSource);
if (readFile >= 0)
@@ -3841,7 +3865,7 @@ WaitForWALToBecomeAvailable(XLogRecPtr RecPtr, bool randAccess,
tli = tliOfPointInHistory(tliRecPtr, expectedTLEs);
if (curFileTLI > 0 && tli < curFileTLI)
- elog(ERROR, "according to history file, WAL location %X/%X belongs to timeline %u, but previous recovered WAL file came from timeline %u",
+ elog(ERROR, "according to history file, WAL location %X/%08X belongs to timeline %u, but previous recovered WAL file came from timeline %u",
LSN_FORMAT_ARGS(tliRecPtr),
tli, curFileTLI);
}
@@ -3916,8 +3940,7 @@ WaitForWALToBecomeAvailable(XLogRecPtr RecPtr, bool randAccess,
{
if (!expectedTLEs)
expectedTLEs = readTimeLineHistory(recoveryTargetTLI);
- readFile = XLogFileRead(readSegNo, PANIC,
- receiveTLI,
+ readFile = XLogFileRead(readSegNo, receiveTLI,
XLOG_FROM_STREAM, false);
Assert(readFile >= 0);
}
@@ -4001,7 +4024,7 @@ WaitForWALToBecomeAvailable(XLogRecPtr RecPtr, bool randAccess,
* This possibly-long loop needs to handle interrupts of startup
* process.
*/
- HandleStartupProcInterrupts();
+ ProcessStartupProcInterrupts();
}
return XLREAD_FAIL; /* not reached */
@@ -4155,10 +4178,10 @@ rescanLatestTimeLine(TimeLineID replayTLI, XLogRecPtr replayLSN)
if (currentTle->end < replayLSN)
{
ereport(LOG,
- (errmsg("new timeline %u forked off current database system timeline %u before current recovery point %X/%X",
- newtarget,
- replayTLI,
- LSN_FORMAT_ARGS(replayLSN))));
+ errmsg("new timeline %u forked off current database system timeline %u before current recovery point %X/%08X",
+ newtarget,
+ replayTLI,
+ LSN_FORMAT_ARGS(replayLSN)));
return false;
}
@@ -4188,7 +4211,7 @@ rescanLatestTimeLine(TimeLineID replayTLI, XLogRecPtr replayLSN)
* Otherwise, it's assumed to be already available in pg_wal.
*/
static int
-XLogFileRead(XLogSegNo segno, int emode, TimeLineID tli,
+XLogFileRead(XLogSegNo segno, TimeLineID tli,
XLogSource source, bool notfoundOk)
{
char xlogfname[MAXFNAMELEN];
@@ -4270,7 +4293,7 @@ XLogFileRead(XLogSegNo segno, int emode, TimeLineID tli,
* This version searches for the segment with any TLI listed in expectedTLEs.
*/
static int
-XLogFileReadAnyTLI(XLogSegNo segno, int emode, XLogSource source)
+XLogFileReadAnyTLI(XLogSegNo segno, XLogSource source)
{
char path[MAXPGPATH];
ListCell *cell;
@@ -4334,8 +4357,7 @@ XLogFileReadAnyTLI(XLogSegNo segno, int emode, XLogSource source)
if (source == XLOG_FROM_ANY || source == XLOG_FROM_ARCHIVE)
{
- fd = XLogFileRead(segno, emode, tli,
- XLOG_FROM_ARCHIVE, true);
+ fd = XLogFileRead(segno, tli, XLOG_FROM_ARCHIVE, true);
if (fd != -1)
{
elog(DEBUG1, "got WAL segment from archive");
@@ -4347,8 +4369,7 @@ XLogFileReadAnyTLI(XLogSegNo segno, int emode, XLogSource source)
if (source == XLOG_FROM_ANY || source == XLOG_FROM_PG_WAL)
{
- fd = XLogFileRead(segno, emode, tli,
- XLOG_FROM_PG_WAL, true);
+ fd = XLogFileRead(segno, tli, XLOG_FROM_PG_WAL, true);
if (fd != -1)
{
if (!expectedTLEs)
@@ -4361,7 +4382,7 @@ XLogFileReadAnyTLI(XLogSegNo segno, int emode, XLogSource source)
/* Couldn't find it. For simplicity, complain about front timeline */
XLogFilePath(path, recoveryTargetTLI, segno, wal_segment_size);
errno = ENOENT;
- ereport(emode,
+ ereport(DEBUG2,
(errcode_for_file_access(),
errmsg("could not open file \"%s\": %m", path)));
return -1;
@@ -4681,7 +4702,7 @@ RecoveryRequiresIntParameter(const char *param_name, int currValue, int minValue
while (GetRecoveryPauseState() != RECOVERY_NOT_PAUSED)
{
- HandleStartupProcInterrupts();
+ ProcessStartupProcInterrupts();
if (CheckForStandbyTrigger())
{
@@ -4740,7 +4761,7 @@ bool
check_primary_slot_name(char **newval, void **extra, GucSource source)
{
if (*newval && strcmp(*newval, "") != 0 &&
- !ReplicationSlotValidateName(*newval, WARNING))
+ !ReplicationSlotValidateName(*newval, false, WARNING))
return false;
return true;
@@ -4764,8 +4785,7 @@ check_primary_slot_name(char **newval, void **extra, GucSource source)
* that we have odd behaviors such as unexpected GUC ordering dependencies.
*/
-static void
-pg_attribute_noreturn()
+pg_noreturn static void
error_multiple_recovery_targets(void)
{
ereport(ERROR,
@@ -4814,15 +4834,17 @@ check_recovery_target_lsn(char **newval, void **extra, GucSource source)
{
XLogRecPtr lsn;
XLogRecPtr *myextra;
- bool have_error = false;
+ ErrorSaveContext escontext = {T_ErrorSaveContext};
- lsn = pg_lsn_in_internal(*newval, &have_error);
- if (have_error)
+ lsn = pg_lsn_in_safe(*newval, (Node *) &escontext);
+ if (escontext.error_occurred)
return false;
- myextra = (XLogRecPtr *) guc_malloc(ERROR, sizeof(XLogRecPtr));
+ myextra = (XLogRecPtr *) guc_malloc(LOG, sizeof(XLogRecPtr));
+ if (!myextra)
+ return false;
*myextra = lsn;
- *extra = (void *) myextra;
+ *extra = myextra;
}
return true;
}
@@ -4934,7 +4956,7 @@ check_recovery_target_time(char **newval, void **extra, GucSource source)
if (tm2timestamp(tm, fsec, &tz, ×tamp) != 0)
{
- GUC_check_errdetail("timestamp out of range: \"%s\"", str);
+ GUC_check_errdetail("Timestamp out of range: \"%s\".", str);
return false;
}
}
@@ -4973,20 +4995,34 @@ check_recovery_target_timeline(char **newval, void **extra, GucSource source)
rttg = RECOVERY_TARGET_TIMELINE_LATEST;
else
{
+ char *endp;
+ uint64 timeline;
+
rttg = RECOVERY_TARGET_TIMELINE_NUMERIC;
errno = 0;
- strtoul(*newval, NULL, 0);
- if (errno == EINVAL || errno == ERANGE)
+ timeline = strtou64(*newval, &endp, 0);
+
+ if (*endp != '\0' || errno == EINVAL || errno == ERANGE)
{
- GUC_check_errdetail("\"recovery_target_timeline\" is not a valid number.");
+ GUC_check_errdetail("\"%s\" is not a valid number.",
+ "recovery_target_timeline");
+ return false;
+ }
+
+ if (timeline < 1 || timeline > PG_UINT32_MAX)
+ {
+ GUC_check_errdetail("\"%s\" must be between %u and %u.",
+ "recovery_target_timeline", 1, UINT_MAX);
return false;
}
}
- myextra = (RecoveryTargetTimeLineGoal *) guc_malloc(ERROR, sizeof(RecoveryTargetTimeLineGoal));
+ myextra = (RecoveryTargetTimeLineGoal *) guc_malloc(LOG, sizeof(RecoveryTargetTimeLineGoal));
+ if (!myextra)
+ return false;
*myextra = rttg;
- *extra = (void *) myextra;
+ *extra = myextra;
return true;
}
@@ -5020,9 +5056,11 @@ check_recovery_target_xid(char **newval, void **extra, GucSource source)
if (errno == EINVAL || errno == ERANGE)
return false;
- myextra = (TransactionId *) guc_malloc(ERROR, sizeof(TransactionId));
+ myextra = (TransactionId *) guc_malloc(LOG, sizeof(TransactionId));
+ if (!myextra)
+ return false;
*myextra = xid;
- *extra = (void *) myextra;
+ *extra = myextra;
}
return true;
}
diff --git a/src/backend/access/transam/xlogstats.c b/src/backend/access/transam/xlogstats.c
index 2b33decd5a19b..f92d9e13b174e 100644
--- a/src/backend/access/transam/xlogstats.c
+++ b/src/backend/access/transam/xlogstats.c
@@ -3,7 +3,7 @@
* xlogstats.c
* Functions for WAL Statitstics
*
- * Copyright (c) 2022-2024, PostgreSQL Global Development Group
+ * Copyright (c) 2022-2025, PostgreSQL Global Development Group
*
* IDENTIFICATION
* src/backend/access/transam/xlogstats.c
diff --git a/src/backend/access/transam/xlogutils.c b/src/backend/access/transam/xlogutils.c
index 5295b85fe078c..38176d9688e4c 100644
--- a/src/backend/access/transam/xlogutils.c
+++ b/src/backend/access/transam/xlogutils.c
@@ -8,7 +8,7 @@
* None of this code is used during normal system operation.
*
*
- * Portions Copyright (c) 1996-2024, PostgreSQL Global Development Group
+ * Portions Copyright (c) 1996-2025, PostgreSQL Global Development Group
* Portions Copyright (c) 1994, Regents of the University of California
*
* src/backend/access/transam/xlogutils.c
@@ -86,15 +86,14 @@ static void
report_invalid_page(int elevel, RelFileLocator locator, ForkNumber forkno,
BlockNumber blkno, bool present)
{
- char *path = relpathperm(locator, forkno);
+ RelPathStr path = relpathperm(locator, forkno);
if (present)
elog(elevel, "page %u of relation %s is uninitialized",
- blkno, path);
+ blkno, path.str);
else
elog(elevel, "page %u of relation %s does not exist",
- blkno, path);
- pfree(path);
+ blkno, path.str);
}
/* Log a reference to an invalid page */
@@ -180,14 +179,9 @@ forget_invalid_pages(RelFileLocator locator, ForkNumber forkno,
hentry->key.forkno == forkno &&
hentry->key.blkno >= minblkno)
{
- if (message_level_is_interesting(DEBUG2))
- {
- char *path = relpathperm(hentry->key.locator, forkno);
-
- elog(DEBUG2, "page %u of relation %s has been dropped",
- hentry->key.blkno, path);
- pfree(path);
- }
+ elog(DEBUG2, "page %u of relation %s has been dropped",
+ hentry->key.blkno,
+ relpathperm(hentry->key.locator, forkno).str);
if (hash_search(invalid_page_tab,
&hentry->key,
@@ -213,14 +207,9 @@ forget_invalid_pages_db(Oid dbid)
{
if (hentry->key.locator.dbOid == dbid)
{
- if (message_level_is_interesting(DEBUG2))
- {
- char *path = relpathperm(hentry->key.locator, hentry->key.forkno);
-
- elog(DEBUG2, "page %u of relation %s has been dropped",
- hentry->key.blkno, path);
- pfree(path);
- }
+ elog(DEBUG2, "page %u of relation %s has been dropped",
+ hentry->key.blkno,
+ relpathperm(hentry->key.locator, hentry->key.forkno).str);
if (hash_search(invalid_page_tab,
&hentry->key,
@@ -534,7 +523,7 @@ XLogReadBufferExtended(RelFileLocator rlocator, ForkNumber forknum,
if (mode == RBM_NORMAL)
{
/* check that page has been initialized */
- Page page = (Page) BufferGetPage(buffer);
+ Page page = BufferGetPage(buffer);
/*
* We assume that PageIsNew is safe without a lock. During recovery,
@@ -806,7 +795,7 @@ XLogReadDetermineTimeline(XLogReaderState *state, XLogRecPtr wantPage,
list_free_deep(timelineHistory);
- elog(DEBUG3, "switched to timeline %u valid until %X/%X",
+ elog(DEBUG3, "switched to timeline %u valid until %X/%08X",
state->currTLI,
LSN_FORMAT_ARGS(state->currTLIValidUntil));
}
@@ -851,11 +840,6 @@ wal_segment_close(XLogReaderState *state)
*
* Public because it would likely be very helpful for someone writing another
* output method outside walsender, e.g. in a bgworker.
- *
- * TODO: The walsender has its own version of this, but it relies on the
- * walsender's latch being set whenever WAL is flushed. No such infrastructure
- * exists for normal backends, so we have to do a check/sleep/repeat style of
- * loop for now.
*/
int
read_local_xlog_page(XLogReaderState *state, XLogRecPtr targetPagePtr,
@@ -895,7 +879,14 @@ read_local_xlog_page_guts(XLogReaderState *state, XLogRecPtr targetPagePtr,
loc = targetPagePtr + reqLen;
- /* Loop waiting for xlog to be available if necessary */
+ /*
+ * Loop waiting for xlog to be available if necessary
+ *
+ * TODO: The walsender has its own version of this function, which uses a
+ * condition variable to wake up whenever WAL is flushed. We could use the
+ * same infrastructure here, instead of the check/sleep/repeat style of
+ * loop.
+ */
while (1)
{
/*
diff --git a/src/backend/archive/meson.build b/src/backend/archive/meson.build
index 51a71673e65f4..2c3ad10199457 100644
--- a/src/backend/archive/meson.build
+++ b/src/backend/archive/meson.build
@@ -1,4 +1,4 @@
-# Copyright (c) 2023-2024, PostgreSQL Global Development Group
+# Copyright (c) 2023-2025, PostgreSQL Global Development Group
backend_sources += files(
'shell_archive.c'
diff --git a/src/backend/archive/shell_archive.c b/src/backend/archive/shell_archive.c
index 506c5a30ad209..828723afe4769 100644
--- a/src/backend/archive/shell_archive.c
+++ b/src/backend/archive/shell_archive.c
@@ -6,7 +6,7 @@
* archive_command GUC) to copy write-ahead log files. It is used as the
* default, but other modules may define their own custom archiving logic.
*
- * Copyright (c) 2022-2024, PostgreSQL Global Development Group
+ * Copyright (c) 2022-2025, PostgreSQL Global Development Group
*
* IDENTIFICATION
* src/backend/archive/shell_archive.c
@@ -48,7 +48,7 @@ shell_archive_configured(ArchiveModuleState *state)
if (XLogArchiveCommand[0] != '\0')
return true;
- arch_module_check_errdetail("%s is not set.",
+ arch_module_check_errdetail("\"%s\" is not set.",
"archive_command");
return false;
}
diff --git a/src/backend/backup/backup_manifest.c b/src/backend/backup/backup_manifest.c
index b360a135472e9..d05252f383c80 100644
--- a/src/backend/backup/backup_manifest.c
+++ b/src/backend/backup/backup_manifest.c
@@ -3,7 +3,7 @@
* backup_manifest.c
* code for generating and sending a backup manifest
*
- * Portions Copyright (c) 2010-2024, PostgreSQL Global Development Group
+ * Portions Copyright (c) 2010-2025, PostgreSQL Global Development Group
*
* IDENTIFICATION
* src/backend/backup/backup_manifest.c
@@ -16,6 +16,7 @@
#include "access/xlog.h"
#include "backup/backup_manifest.h"
#include "backup/basebackup_sink.h"
+#include "common/relpath.h"
#include "mb/pg_wchar.h"
#include "utils/builtins.h"
#include "utils/json.h"
@@ -117,7 +118,7 @@ AddFileToBackupManifest(backup_manifest_info *manifest, Oid spcoid,
*/
if (OidIsValid(spcoid))
{
- snprintf(pathbuf, sizeof(pathbuf), "pg_tblspc/%u/%s", spcoid,
+ snprintf(pathbuf, sizeof(pathbuf), "%s/%u/%s", PG_TBLSPC_DIR, spcoid,
pathname);
pathname = pathbuf;
}
@@ -148,7 +149,7 @@ AddFileToBackupManifest(backup_manifest_info *manifest, Oid spcoid,
pg_verify_mbstr(PG_UTF8, pathname, pathlen, true))
{
appendStringInfoString(&buf, "{ \"Path\": ");
- escape_json(&buf, pathname);
+ escape_json_with_len(&buf, pathname, pathlen);
appendStringInfoString(&buf, ", ");
}
else
@@ -280,7 +281,7 @@ AddWALInfoToBackupManifest(backup_manifest_info *manifest, XLogRecPtr startptr,
}
AppendToManifest(manifest,
- "%s{ \"Timeline\": %u, \"Start-LSN\": \"%X/%X\", \"End-LSN\": \"%X/%X\" }",
+ "%s{ \"Timeline\": %u, \"Start-LSN\": \"%X/%08X\", \"End-LSN\": \"%X/%08X\" }",
first_wal_range ? "" : ",\n",
entry->tli,
LSN_FORMAT_ARGS(tl_beginptr),
diff --git a/src/backend/backup/basebackup.c b/src/backend/backup/basebackup.c
index 9a2bf59e84ee4..bb7d90aa5d963 100644
--- a/src/backend/backup/basebackup.c
+++ b/src/backend/backup/basebackup.c
@@ -3,7 +3,7 @@
* basebackup.c
* code for taking a base backup and streaming it to a standby
*
- * Portions Copyright (c) 2010-2024, PostgreSQL Global Development Group
+ * Portions Copyright (c) 2010-2025, PostgreSQL Global Development Group
*
* IDENTIFICATION
* src/backend/backup/basebackup.c
@@ -33,9 +33,9 @@
#include "nodes/pg_list.h"
#include "pgstat.h"
#include "pgtar.h"
-#include "port.h"
#include "postmaster/syslogger.h"
#include "postmaster/walsummarizer.h"
+#include "replication/slot.h"
#include "replication/walsender.h"
#include "replication/walsender_private.h"
#include "storage/bufpage.h"
@@ -161,7 +161,7 @@ static const char *const excludeDirContents[] =
* even if the intention is to restore to another primary. See backup.sgml
* for a more detailed description.
*/
- "pg_replslot",
+ PG_REPLSLOT_DIR,
/* Contents removed on startup, see dsm_cleanup_for_mmap(). */
PG_DYNSHMEM_DIR,
@@ -249,8 +249,10 @@ perform_base_backup(basebackup_options *opt, bbsink *sink,
state.bytes_total_is_valid = false;
/* we're going to use a BufFile, so we need a ResourceOwner */
- Assert(CurrentResourceOwner == NULL);
- CurrentResourceOwner = ResourceOwnerCreate(NULL, "base backup");
+ Assert(AuxProcessResourceOwner != NULL);
+ Assert(CurrentResourceOwner == AuxProcessResourceOwner ||
+ CurrentResourceOwner == NULL);
+ CurrentResourceOwner = AuxProcessResourceOwner;
backup_started_in_recovery = RecoveryInProgress();
@@ -671,7 +673,7 @@ perform_base_backup(basebackup_options *opt, bbsink *sink,
FreeBackupManifest(&manifest);
/* clean up the resource owner we created */
- WalSndResourceCleanup(true);
+ ReleaseAuxProcessResources(true);
basebackup_progress_done();
}
@@ -1046,7 +1048,7 @@ SendBaseBackup(BaseBackupCmd *cmd, IncrementalBackupInfo *ib)
sink = bbsink_zstd_new(sink, &opt.compression_specification);
/* Set up progress reporting. */
- sink = bbsink_progress_new(sink, opt.progress);
+ sink = bbsink_progress_new(sink, opt.progress, opt.incremental);
/*
* Perform the base backup, but make sure we clean up the bbsink even if
@@ -1347,7 +1349,7 @@ sendDir(bbsink *sink, const char *path, int basepathlen, bool sizeonly,
snprintf(pathbuf, sizeof(pathbuf), "%s/%s", path, de->d_name);
/* Skip pg_control here to back up it last */
- if (strcmp(pathbuf, "./global/pg_control") == 0)
+ if (strcmp(pathbuf, "./" XLOG_CONTROL_FILE) == 0)
continue;
if (lstat(pathbuf, &statbuf) != 0)
@@ -1487,7 +1489,7 @@ sendDir(bbsink *sink, const char *path, int basepathlen, bool sizeonly,
if (OidIsValid(spcoid))
{
relspcoid = spcoid;
- lookup_path = psprintf("pg_tblspc/%u/%s", spcoid,
+ lookup_path = psprintf("%s/%u/%s", PG_TBLSPC_DIR, spcoid,
tarfilename);
}
else
@@ -1815,6 +1817,7 @@ sendFile(bbsink *sink, const char *readfilename, const char *tarfilename,
checksum_failures,
readfilename, checksum_failures)));
+ pgstat_prepare_report_checksum_failure(dboid);
pgstat_report_checksum_failures_in_db(dboid, checksum_failures);
}
@@ -2045,12 +2048,14 @@ _tarWriteHeader(bbsink *sink, const char *filename, const char *linktarget,
break;
case TAR_NAME_TOO_LONG:
ereport(ERROR,
- (errmsg("file name too long for tar format: \"%s\"",
+ (errcode(ERRCODE_PROGRAM_LIMIT_EXCEEDED),
+ errmsg("file name too long for tar format: \"%s\"",
filename)));
break;
case TAR_SYMLINK_TOO_LONG:
ereport(ERROR,
- (errmsg("symbolic link target too long for tar format: "
+ (errcode(ERRCODE_PROGRAM_LIMIT_EXCEEDED),
+ errmsg("symbolic link target too long for tar format: "
"file name \"%s\", target \"%s\"",
filename, linktarget)));
break;
diff --git a/src/backend/backup/basebackup_copy.c b/src/backend/backup/basebackup_copy.c
index 0b4ee5f2a29f6..eb45d3bcb663b 100644
--- a/src/backend/backup/basebackup_copy.c
+++ b/src/backend/backup/basebackup_copy.c
@@ -16,7 +16,7 @@
* An older method that sent each archive using a separate COPY OUT
* operation is no longer supported.
*
- * Portions Copyright (c) 2010-2024, PostgreSQL Global Development Group
+ * Portions Copyright (c) 2010-2025, PostgreSQL Global Development Group
*
* IDENTIFICATION
* src/backend/backup/basebackup_copy.c
@@ -143,7 +143,7 @@ bbsink_copystream_begin_backup(bbsink *sink)
buf = palloc(mysink->base.bbs_buffer_length + MAXIMUM_ALIGNOF);
mysink->msgbuffer = buf + (MAXIMUM_ALIGNOF - 1);
mysink->base.bbs_buffer = buf + MAXIMUM_ALIGNOF;
- mysink->msgbuffer[0] = 'd'; /* archive or manifest data */
+ mysink->msgbuffer[0] = PqMsg_CopyData; /* archive or manifest data */
/* Tell client the backup start location. */
SendXlogRecPtrResult(state->startptr, state->starttli);
@@ -170,7 +170,7 @@ bbsink_copystream_begin_archive(bbsink *sink, const char *archive_name)
ti = list_nth(state->tablespaces, state->tablespace_num);
pq_beginmessage(&buf, PqMsg_CopyData);
- pq_sendbyte(&buf, 'n'); /* New archive */
+ pq_sendbyte(&buf, PqBackupMsg_NewArchive);
pq_sendstring(&buf, archive_name);
pq_sendstring(&buf, ti->path == NULL ? "" : ti->path);
pq_endmessage(&buf);
@@ -191,7 +191,7 @@ bbsink_copystream_archive_contents(bbsink *sink, size_t len)
if (mysink->send_to_client)
{
/* Add one because we're also sending a leading type byte. */
- pq_putmessage('d', mysink->msgbuffer, len + 1);
+ pq_putmessage(PqMsg_CopyData, mysink->msgbuffer, len + 1);
}
/* Consider whether to send a progress report to the client. */
@@ -221,7 +221,7 @@ bbsink_copystream_archive_contents(bbsink *sink, size_t len)
mysink->last_progress_report_time = now;
pq_beginmessage(&buf, PqMsg_CopyData);
- pq_sendbyte(&buf, 'p'); /* Progress report */
+ pq_sendbyte(&buf, PqBackupMsg_ProgressReport);
pq_sendint64(&buf, state->bytes_done);
pq_endmessage(&buf);
pq_flush_if_writable();
@@ -247,7 +247,7 @@ bbsink_copystream_end_archive(bbsink *sink)
mysink->bytes_done_at_last_time_check = state->bytes_done;
mysink->last_progress_report_time = GetCurrentTimestamp();
pq_beginmessage(&buf, PqMsg_CopyData);
- pq_sendbyte(&buf, 'p'); /* Progress report */
+ pq_sendbyte(&buf, PqBackupMsg_ProgressReport);
pq_sendint64(&buf, state->bytes_done);
pq_endmessage(&buf);
pq_flush_if_writable();
@@ -262,7 +262,7 @@ bbsink_copystream_begin_manifest(bbsink *sink)
StringInfoData buf;
pq_beginmessage(&buf, PqMsg_CopyData);
- pq_sendbyte(&buf, 'm'); /* Manifest */
+ pq_sendbyte(&buf, PqBackupMsg_Manifest);
pq_endmessage(&buf);
}
@@ -277,7 +277,7 @@ bbsink_copystream_manifest_contents(bbsink *sink, size_t len)
if (mysink->send_to_client)
{
/* Add one because we're also sending a leading type byte. */
- pq_putmessage('d', mysink->msgbuffer, len + 1);
+ pq_putmessage(PqMsg_CopyData, mysink->msgbuffer, len + 1);
}
}
@@ -361,7 +361,7 @@ SendXlogRecPtrResult(XLogRecPtr ptr, TimeLineID tli)
tstate = begin_tup_output_tupdesc(dest, tupdesc, &TTSOpsVirtual);
/* Data row */
- values[0] = CStringGetTextDatum(psprintf("%X/%X", LSN_FORMAT_ARGS(ptr)));
+ values[0] = CStringGetTextDatum(psprintf("%X/%08X", LSN_FORMAT_ARGS(ptr)));
values[1] = Int64GetDatum(tli);
do_tup_output(tstate, values, nulls);
diff --git a/src/backend/backup/basebackup_gzip.c b/src/backend/backup/basebackup_gzip.c
index 2b6dc656f9384..c4cbb5f527644 100644
--- a/src/backend/backup/basebackup_gzip.c
+++ b/src/backend/backup/basebackup_gzip.c
@@ -3,7 +3,7 @@
* basebackup_gzip.c
* Basebackup sink implementing gzip compression.
*
- * Portions Copyright (c) 2010-2024, PostgreSQL Global Development Group
+ * Portions Copyright (c) 2010-2025, PostgreSQL Global Development Group
*
* IDENTIFICATION
* src/backend/backup/basebackup_gzip.c
diff --git a/src/backend/backup/basebackup_incremental.c b/src/backend/backup/basebackup_incremental.c
index 4ad9d7cad00e0..a0d48ff0fefa9 100644
--- a/src/backend/backup/basebackup_incremental.c
+++ b/src/backend/backup/basebackup_incremental.c
@@ -10,7 +10,7 @@
* backup manifest supplied by the user taking the incremental backup
* and extract the required information from it.
*
- * Portions Copyright (c) 2010-2024, PostgreSQL Global Development Group
+ * Portions Copyright (c) 2010-2025, PostgreSQL Global Development Group
*
* IDENTIFICATION
* src/backend/backup/basebackup_incremental.c
@@ -27,9 +27,7 @@
#include "common/hashfn.h"
#include "common/int.h"
#include "common/parse_manifest.h"
-#include "datatype/timestamp.h"
#include "postmaster/walsummarizer.h"
-#include "utils/timestamp.h"
#define BLOCKS_PER_READ 512
@@ -58,7 +56,7 @@ typedef struct
{
uint32 status;
const char *path;
- size_t size;
+ uint64 size;
} backup_file_entry;
static uint32 hash_string_pointer(const char *s);
@@ -132,8 +130,8 @@ static void manifest_process_version(JsonManifestParseContext *context,
static void manifest_process_system_identifier(JsonManifestParseContext *context,
uint64 manifest_system_identifier);
static void manifest_process_file(JsonManifestParseContext *context,
- char *pathname,
- size_t size,
+ const char *pathname,
+ uint64 size,
pg_checksum_type checksum_type,
int checksum_length,
uint8 *checksum_payload);
@@ -141,9 +139,9 @@ static void manifest_process_wal_range(JsonManifestParseContext *context,
TimeLineID tli,
XLogRecPtr start_lsn,
XLogRecPtr end_lsn);
-static void manifest_report_error(JsonManifestParseContext *ib,
- const char *fmt,...)
- pg_attribute_printf(2, 3) pg_attribute_noreturn();
+pg_noreturn static void manifest_report_error(JsonManifestParseContext *context,
+ const char *fmt,...)
+ pg_attribute_printf(2, 3);
static int compare_block_numbers(const void *a, const void *b);
/*
@@ -207,8 +205,8 @@ AppendIncrementalManifestData(IncrementalBackupInfo *ib, const char *data,
* time for an incremental parse. We'll do all but the last MIN_CHUNK
* so that we have enough left for the final piece.
*/
- json_parse_manifest_incremental_chunk(
- ib->inc_state, ib->buf.data, ib->buf.len - MIN_CHUNK, false);
+ json_parse_manifest_incremental_chunk(ib->inc_state, ib->buf.data,
+ ib->buf.len - MIN_CHUNK, false);
/* now remove what we just parsed */
memmove(ib->buf.data, ib->buf.data + (ib->buf.len - MIN_CHUNK),
MIN_CHUNK + 1);
@@ -234,8 +232,8 @@ FinalizeIncrementalManifest(IncrementalBackupInfo *ib)
oldcontext = MemoryContextSwitchTo(ib->mcxt);
/* Parse the last chunk of the manifest */
- json_parse_manifest_incremental_chunk(
- ib->inc_state, ib->buf.data, ib->buf.len, true);
+ json_parse_manifest_incremental_chunk(ib->inc_state, ib->buf.data,
+ ib->buf.len, true);
/* Done with the buffer, so release memory. */
pfree(ib->buf.data);
@@ -277,12 +275,6 @@ PrepareForIncrementalBackup(IncrementalBackupInfo *ib,
TimeLineID earliest_wal_range_tli = 0;
XLogRecPtr earliest_wal_range_start_lsn = InvalidXLogRecPtr;
TimeLineID latest_wal_range_tli = 0;
- XLogRecPtr summarized_lsn;
- XLogRecPtr pending_lsn;
- XLogRecPtr prior_pending_lsn = InvalidXLogRecPtr;
- int deadcycles = 0;
- TimestampTz initial_time,
- current_time;
Assert(ib->buf.data == NULL);
@@ -417,7 +409,7 @@ PrepareForIncrementalBackup(IncrementalBackupInfo *ib,
if (range->start_lsn < tlep[i]->begin)
ereport(ERROR,
(errcode(ERRCODE_OBJECT_NOT_IN_PREREQUISITE_STATE),
- errmsg("manifest requires WAL from initial timeline %u starting at %X/%X, but that timeline begins at %X/%X",
+ errmsg("manifest requires WAL from initial timeline %u starting at %X/%08X, but that timeline begins at %X/%08X",
range->tli,
LSN_FORMAT_ARGS(range->start_lsn),
LSN_FORMAT_ARGS(tlep[i]->begin))));
@@ -427,7 +419,7 @@ PrepareForIncrementalBackup(IncrementalBackupInfo *ib,
if (range->start_lsn != tlep[i]->begin)
ereport(ERROR,
(errcode(ERRCODE_OBJECT_NOT_IN_PREREQUISITE_STATE),
- errmsg("manifest requires WAL from continuation timeline %u starting at %X/%X, but that timeline begins at %X/%X",
+ errmsg("manifest requires WAL from continuation timeline %u starting at %X/%08X, but that timeline begins at %X/%08X",
range->tli,
LSN_FORMAT_ARGS(range->start_lsn),
LSN_FORMAT_ARGS(tlep[i]->begin))));
@@ -438,17 +430,18 @@ PrepareForIncrementalBackup(IncrementalBackupInfo *ib,
if (range->end_lsn > backup_state->startpoint)
ereport(ERROR,
(errcode(ERRCODE_OBJECT_NOT_IN_PREREQUISITE_STATE),
- errmsg("manifest requires WAL from final timeline %u ending at %X/%X, but this backup starts at %X/%X",
+ errmsg("manifest requires WAL from final timeline %u ending at %X/%08X, but this backup starts at %X/%08X",
range->tli,
LSN_FORMAT_ARGS(range->end_lsn),
- LSN_FORMAT_ARGS(backup_state->startpoint))));
+ LSN_FORMAT_ARGS(backup_state->startpoint)),
+ errhint("This can happen for incremental backups on a standby if there was little activity since the previous backup.")));
}
else
{
if (range->end_lsn != tlep[i]->end)
ereport(ERROR,
(errcode(ERRCODE_OBJECT_NOT_IN_PREREQUISITE_STATE),
- errmsg("manifest requires WAL from non-final timeline %u ending at %X/%X, but this server switched timelines at %X/%X",
+ errmsg("manifest requires WAL from non-final timeline %u ending at %X/%08X, but this server switched timelines at %X/%08X",
range->tli,
LSN_FORMAT_ARGS(range->end_lsn),
LSN_FORMAT_ARGS(tlep[i]->end))));
@@ -457,85 +450,13 @@ PrepareForIncrementalBackup(IncrementalBackupInfo *ib,
}
/*
- * Wait for WAL summarization to catch up to the backup start LSN (but
- * time out if it doesn't do so quickly enough).
+ * Wait for WAL summarization to catch up to the backup start LSN. This
+ * will throw an error if the WAL summarizer appears to be stuck. If WAL
+ * summarization gets disabled while we're waiting, this will return
+ * immediately, and we'll error out further down if the WAL summaries are
+ * incomplete.
*/
- initial_time = current_time = GetCurrentTimestamp();
- while (1)
- {
- long timeout_in_ms = 10000;
- long elapsed_seconds;
-
- /*
- * Align the wait time to prevent drift. This doesn't really matter,
- * but we'd like the warnings about how long we've been waiting to say
- * 10 seconds, 20 seconds, 30 seconds, 40 seconds ... without ever
- * drifting to something that is not a multiple of ten.
- */
- timeout_in_ms -=
- TimestampDifferenceMilliseconds(initial_time, current_time) %
- timeout_in_ms;
-
- /* Wait for up to 10 seconds. */
- summarized_lsn = WaitForWalSummarization(backup_state->startpoint,
- timeout_in_ms, &pending_lsn);
-
- /* If WAL summarization has progressed sufficiently, stop waiting. */
- if (summarized_lsn >= backup_state->startpoint)
- break;
-
- /*
- * Keep track of the number of cycles during which there has been no
- * progression of pending_lsn. If pending_lsn is not advancing, that
- * means that not only are no new files appearing on disk, but we're
- * not even incorporating new records into the in-memory state.
- */
- if (pending_lsn > prior_pending_lsn)
- {
- prior_pending_lsn = pending_lsn;
- deadcycles = 0;
- }
- else
- ++deadcycles;
-
- /*
- * If we've managed to wait for an entire minute without the WAL
- * summarizer absorbing a single WAL record, error out; probably
- * something is wrong.
- *
- * We could consider also erroring out if the summarizer is taking too
- * long to catch up, but it's not clear what rate of progress would be
- * acceptable and what would be too slow. So instead, we just try to
- * error out in the case where there's no progress at all. That seems
- * likely to catch a reasonable number of the things that can go wrong
- * in practice (e.g. the summarizer process is completely hung, say
- * because somebody hooked up a debugger to it or something) without
- * giving up too quickly when the system is just slow.
- */
- if (deadcycles >= 6)
- ereport(ERROR,
- (errcode(ERRCODE_OBJECT_NOT_IN_PREREQUISITE_STATE),
- errmsg("WAL summarization is not progressing"),
- errdetail("Summarization is needed through %X/%X, but is stuck at %X/%X on disk and %X/%X in memory.",
- LSN_FORMAT_ARGS(backup_state->startpoint),
- LSN_FORMAT_ARGS(summarized_lsn),
- LSN_FORMAT_ARGS(pending_lsn))));
-
- /*
- * Otherwise, just let the user know what's happening.
- */
- current_time = GetCurrentTimestamp();
- elapsed_seconds =
- TimestampDifferenceMilliseconds(initial_time, current_time) / 1000;
- ereport(WARNING,
- (errcode(ERRCODE_OBJECT_NOT_IN_PREREQUISITE_STATE),
- errmsg("still waiting for WAL summarization through %X/%X after %ld seconds",
- LSN_FORMAT_ARGS(backup_state->startpoint),
- elapsed_seconds),
- errdetail("Summarization has reached %X/%X on disk and %X/%X in memory.",
- LSN_FORMAT_ARGS(summarized_lsn),
- LSN_FORMAT_ARGS(pending_lsn))));
- }
+ WaitForWalSummarization(backup_state->startpoint);
/*
* Retrieve a list of all WAL summaries on any timeline that overlap with
@@ -601,18 +522,18 @@ PrepareForIncrementalBackup(IncrementalBackupInfo *ib,
if (XLogRecPtrIsInvalid(tli_missing_lsn))
ereport(ERROR,
(errcode(ERRCODE_OBJECT_NOT_IN_PREREQUISITE_STATE),
- errmsg("WAL summaries are required on timeline %u from %X/%X to %X/%X, but no summaries for that timeline and LSN range exist",
+ errmsg("WAL summaries are required on timeline %u from %X/%08X to %X/%08X, but no summaries for that timeline and LSN range exist",
tle->tli,
LSN_FORMAT_ARGS(tli_start_lsn),
LSN_FORMAT_ARGS(tli_end_lsn))));
else
ereport(ERROR,
(errcode(ERRCODE_OBJECT_NOT_IN_PREREQUISITE_STATE),
- errmsg("WAL summaries are required on timeline %u from %X/%X to %X/%X, but the summaries for that timeline and LSN range are incomplete",
+ errmsg("WAL summaries are required on timeline %u from %X/%08X to %X/%08X, but the summaries for that timeline and LSN range are incomplete",
tle->tli,
LSN_FORMAT_ARGS(tli_start_lsn),
LSN_FORMAT_ARGS(tli_end_lsn)),
- errdetail("The first unsummarized LSN in this range is %X/%X.",
+ errdetail("The first unsummarized LSN in this range is %X/%08X.",
LSN_FORMAT_ARGS(tli_missing_lsn))));
}
@@ -704,23 +625,21 @@ char *
GetIncrementalFilePath(Oid dboid, Oid spcoid, RelFileNumber relfilenumber,
ForkNumber forknum, unsigned segno)
{
- char *path;
+ RelPathStr path;
char *lastslash;
char *ipath;
path = GetRelationPath(dboid, spcoid, relfilenumber, INVALID_PROC_NUMBER,
forknum);
- lastslash = strrchr(path, '/');
+ lastslash = strrchr(path.str, '/');
Assert(lastslash != NULL);
*lastslash = '\0';
if (segno > 0)
- ipath = psprintf("%s/INCREMENTAL.%s.%u", path, lastslash + 1, segno);
+ ipath = psprintf("%s/INCREMENTAL.%s.%u", path.str, lastslash + 1, segno);
else
- ipath = psprintf("%s/INCREMENTAL.%s", path, lastslash + 1);
-
- pfree(path);
+ ipath = psprintf("%s/INCREMENTAL.%s", path.str, lastslash + 1);
return ipath;
}
@@ -944,7 +863,7 @@ GetFileBackupMethod(IncrementalBackupInfo *ib, const char *path,
* number of blocks. The header is rounded to a multiple of BLCKSZ, but
* only if the file will store some block data.
*/
-extern size_t
+size_t
GetIncrementalHeaderSize(unsigned num_blocks_required)
{
size_t result;
@@ -972,7 +891,7 @@ GetIncrementalHeaderSize(unsigned num_blocks_required)
/*
* Compute the size for an incremental file containing a given number of blocks.
*/
-extern size_t
+size_t
GetIncrementalFileSize(unsigned num_blocks_required)
{
size_t result;
@@ -1030,9 +949,9 @@ manifest_process_system_identifier(JsonManifestParseContext *context,
if (manifest_system_identifier != system_identifier)
context->error_cb(context,
- "manifest system identifier is %llu, but database system identifier is %llu",
- (unsigned long long) manifest_system_identifier,
- (unsigned long long) system_identifier);
+ "system identifier in backup manifest is %" PRIu64 ", but database system identifier is %" PRIu64,
+ manifest_system_identifier,
+ system_identifier);
}
/*
@@ -1043,7 +962,7 @@ manifest_process_system_identifier(JsonManifestParseContext *context,
*/
static void
manifest_process_file(JsonManifestParseContext *context,
- char *pathname, size_t size,
+ const char *pathname, uint64 size,
pg_checksum_type checksum_type,
int checksum_length,
uint8 *checksum_payload)
diff --git a/src/backend/backup/basebackup_lz4.c b/src/backend/backup/basebackup_lz4.c
index aa440aa55dc6f..c5ceccb846f57 100644
--- a/src/backend/backup/basebackup_lz4.c
+++ b/src/backend/backup/basebackup_lz4.c
@@ -3,7 +3,7 @@
* basebackup_lz4.c
* Basebackup sink implementing lz4 compression.
*
- * Portions Copyright (c) 2010-2024, PostgreSQL Global Development Group
+ * Portions Copyright (c) 2010-2025, PostgreSQL Global Development Group
*
* IDENTIFICATION
* src/backend/backup/basebackup_lz4.c
diff --git a/src/backend/backup/basebackup_progress.c b/src/backend/backup/basebackup_progress.c
index 8ff6c6073336a..dac205936229b 100644
--- a/src/backend/backup/basebackup_progress.c
+++ b/src/backend/backup/basebackup_progress.c
@@ -22,7 +22,7 @@
* the logic directly into that file as it's fairly simple, but it seems
* cleaner to have everything related to progress reporting in one place.)
*
- * Portions Copyright (c) 2010-2024, PostgreSQL Global Development Group
+ * Portions Copyright (c) 2010-2025, PostgreSQL Global Development Group
*
* IDENTIFICATION
* src/backend/backup/basebackup_progress.c
@@ -56,7 +56,7 @@ static const bbsink_ops bbsink_progress_ops = {
* forwards data to a successor sink.
*/
bbsink *
-bbsink_progress_new(bbsink *next, bool estimate_backup_size)
+bbsink_progress_new(bbsink *next, bool estimate_backup_size, bool incremental)
{
bbsink *sink;
@@ -69,10 +69,15 @@ bbsink_progress_new(bbsink *next, bool estimate_backup_size)
/*
* Report that a base backup is in progress, and set the total size of the
* backup to -1, which will get translated to NULL. If we're estimating
- * the backup size, we'll insert the real estimate when we have it.
+ * the backup size, we'll insert the real estimate when we have it. Also,
+ * the backup type is set.
*/
pgstat_progress_start_command(PROGRESS_COMMAND_BASEBACKUP, InvalidOid);
pgstat_progress_update_param(PROGRESS_BASEBACKUP_BACKUP_TOTAL, -1);
+ pgstat_progress_update_param(PROGRESS_BASEBACKUP_BACKUP_TYPE,
+ incremental
+ ? PROGRESS_BASEBACKUP_BACKUP_TYPE_INCREMENTAL
+ : PROGRESS_BASEBACKUP_BACKUP_TYPE_FULL);
return sink;
}
diff --git a/src/backend/backup/basebackup_sink.c b/src/backend/backup/basebackup_sink.c
index 3c51619075865..e962f8f0b8d62 100644
--- a/src/backend/backup/basebackup_sink.c
+++ b/src/backend/backup/basebackup_sink.c
@@ -3,7 +3,7 @@
* basebackup_sink.c
* Default implementations for bbsink (basebackup sink) callbacks.
*
- * Portions Copyright (c) 2010-2024, PostgreSQL Global Development Group
+ * Portions Copyright (c) 2010-2025, PostgreSQL Global Development Group
*
* src/backend/backup/basebackup_sink.c
*
diff --git a/src/backend/backup/basebackup_target.c b/src/backend/backup/basebackup_target.c
index bb50bdfe1d7a1..84b1309d3bdc8 100644
--- a/src/backend/backup/basebackup_target.c
+++ b/src/backend/backup/basebackup_target.c
@@ -6,7 +6,7 @@
* Furthermore, new targets can be defined by extensions. This file
* contains code to support that functionality.
*
- * Portions Copyright (c) 2010-2024, PostgreSQL Global Development Group
+ * Portions Copyright (c) 2010-2025, PostgreSQL Global Development Group
*
* IDENTIFICATION
* src/backend/backup/basebackup_target.c
diff --git a/src/backend/backup/basebackup_throttle.c b/src/backend/backup/basebackup_throttle.c
index 4477945e61334..b2b743238f9d0 100644
--- a/src/backend/backup/basebackup_throttle.c
+++ b/src/backend/backup/basebackup_throttle.c
@@ -5,7 +5,7 @@
* next base backup sink in the chain at a rate no greater than the
* configured maximum.
*
- * Portions Copyright (c) 2010-2024, PostgreSQL Global Development Group
+ * Portions Copyright (c) 2010-2025, PostgreSQL Global Development Group
*
* IDENTIFICATION
* src/backend/backup/basebackup_throttle.c
diff --git a/src/backend/backup/basebackup_zstd.c b/src/backend/backup/basebackup_zstd.c
index 6741fcaf96d5d..18b2e8fb0b3b6 100644
--- a/src/backend/backup/basebackup_zstd.c
+++ b/src/backend/backup/basebackup_zstd.c
@@ -3,7 +3,7 @@
* basebackup_zstd.c
* Basebackup sink implementing zstd compression.
*
- * Portions Copyright (c) 2010-2024, PostgreSQL Global Development Group
+ * Portions Copyright (c) 2010-2025, PostgreSQL Global Development Group
*
* IDENTIFICATION
* src/backend/backup/basebackup_zstd.c
@@ -34,7 +34,7 @@ typedef struct bbsink_zstd
static void bbsink_zstd_begin_backup(bbsink *sink);
static void bbsink_zstd_begin_archive(bbsink *sink, const char *archive_name);
-static void bbsink_zstd_archive_contents(bbsink *sink, size_t avail_in);
+static void bbsink_zstd_archive_contents(bbsink *sink, size_t len);
static void bbsink_zstd_manifest_contents(bbsink *sink, size_t len);
static void bbsink_zstd_end_archive(bbsink *sink);
static void bbsink_zstd_cleanup(bbsink *sink);
diff --git a/src/backend/backup/meson.build b/src/backend/backup/meson.build
index 79e1f83f8fb03..460025a3046ba 100644
--- a/src/backend/backup/meson.build
+++ b/src/backend/backup/meson.build
@@ -1,4 +1,4 @@
-# Copyright (c) 2022-2024, PostgreSQL Global Development Group
+# Copyright (c) 2022-2025, PostgreSQL Global Development Group
backend_sources += files(
'backup_manifest.c',
diff --git a/src/backend/backup/walsummary.c b/src/backend/backup/walsummary.c
index 322ae3c3ad115..c7a2c65cc6a7a 100644
--- a/src/backend/backup/walsummary.c
+++ b/src/backend/backup/walsummary.c
@@ -3,7 +3,7 @@
* walsummary.c
* Functions for accessing and managing WAL summary data.
*
- * Portions Copyright (c) 2010-2024, PostgreSQL Global Development Group
+ * Portions Copyright (c) 2010-2025, PostgreSQL Global Development Group
*
* src/backend/backup/walsummary.c
*
diff --git a/src/backend/backup/walsummaryfuncs.c b/src/backend/backup/walsummaryfuncs.c
index f082488b33f19..d6dd131da145b 100644
--- a/src/backend/backup/walsummaryfuncs.c
+++ b/src/backend/backup/walsummaryfuncs.c
@@ -3,7 +3,7 @@
* walsummaryfuncs.c
* SQL-callable functions for accessing WAL summary data.
*
- * Portions Copyright (c) 2010-2024, PostgreSQL Global Development Group
+ * Portions Copyright (c) 2010-2025, PostgreSQL Global Development Group
*
* src/backend/backup/walsummaryfuncs.c
*
@@ -92,7 +92,7 @@ pg_wal_summary_contents(PG_FUNCTION_ARGS)
if (raw_tli < 1 || raw_tli > PG_INT32_MAX)
ereport(ERROR,
errcode(ERRCODE_INVALID_PARAMETER_VALUE),
- errmsg("invalid timeline %lld", (long long) raw_tli));
+ errmsg("invalid timeline %" PRId64, raw_tli));
/* Prepare to read the specified WAL summary file. */
ws.tli = (TimeLineID) raw_tli;
@@ -118,6 +118,23 @@ pg_wal_summary_contents(PG_FUNCTION_ARGS)
values[2] = ObjectIdGetDatum(rlocator.dbOid);
values[3] = Int16GetDatum((int16) forknum);
+ /*
+ * If the limit block is not InvalidBlockNumber, emit an extra row
+ * with that block number and limit_block = true.
+ *
+ * There is no point in doing this when the limit_block is
+ * InvalidBlockNumber, because no block with that number or any higher
+ * number can ever exist.
+ */
+ if (BlockNumberIsValid(limit_block))
+ {
+ values[4] = Int64GetDatum((int64) limit_block);
+ values[5] = BoolGetDatum(true);
+
+ tuple = heap_form_tuple(rsi->setDesc, values, nulls);
+ tuplestore_puttuple(rsi->setResult, tuple);
+ }
+
/* Loop over blocks within the current relation fork. */
while (1)
{
@@ -143,23 +160,6 @@ pg_wal_summary_contents(PG_FUNCTION_ARGS)
tuple = heap_form_tuple(rsi->setDesc, values, nulls);
tuplestore_puttuple(rsi->setResult, tuple);
}
-
- /*
- * If the limit block is not InvalidBlockNumber, emit an extra row
- * with that block number and limit_block = true.
- *
- * There is no point in doing this when the limit_block is
- * InvalidBlockNumber, because no block with that number or any
- * higher number can ever exist.
- */
- if (BlockNumberIsValid(limit_block))
- {
- values[4] = Int64GetDatum((int64) limit_block);
- values[5] = BoolGetDatum(true);
-
- tuple = heap_form_tuple(rsi->setDesc, values, nulls);
- tuplestore_puttuple(rsi->setResult, tuple);
- }
}
}
diff --git a/src/backend/bootstrap/bootparse.y b/src/backend/bootstrap/bootparse.y
index 3c9c1da0216db..9833f52c1bed6 100644
--- a/src/backend/bootstrap/bootparse.y
+++ b/src/backend/bootstrap/bootparse.y
@@ -4,7 +4,7 @@
* bootparse.y
* yacc grammar for the "bootstrap" mode (BKI file format)
*
- * Portions Copyright (c) 1996-2024, PostgreSQL Global Development Group
+ * Portions Copyright (c) 1996-2025, PostgreSQL Global Development Group
* Portions Copyright (c) 1994, Regents of the University of California
*
*
@@ -32,6 +32,8 @@
#include "nodes/makefuncs.h"
#include "utils/memutils.h"
+#include "bootparse.h"
+
/*
* Bison doesn't allocate anything that needs to live across parser calls,
@@ -75,6 +77,9 @@ static int num_columns_read = 0;
%}
+%parse-param {yyscan_t yyscanner}
+%lex-param {yyscan_t yyscanner}
+%pure-parser
%expect 0
%name-prefix="boot_yy"
@@ -135,6 +140,8 @@ Boot_OpenStmt:
do_start();
boot_openrel($2);
do_end();
+
+ (void) yynerrs; /* suppress compiler warning */
}
;
diff --git a/src/backend/bootstrap/bootscanner.l b/src/backend/bootstrap/bootscanner.l
index 31d63ff301596..50713912fb149 100644
--- a/src/backend/bootstrap/bootscanner.l
+++ b/src/backend/bootstrap/bootscanner.l
@@ -4,7 +4,7 @@
* bootscanner.l
* a lexical scanner for the bootstrap parser
*
- * Portions Copyright (c) 1996-2024, PostgreSQL Global Development Group
+ * Portions Copyright (c) 1996-2025, PostgreSQL Global Development Group
* Portions Copyright (c) 1994, Regents of the University of California
*
*
@@ -39,17 +39,19 @@ fprintf_to_ereport(const char *fmt, const char *msg)
ereport(ERROR, (errmsg_internal("%s", msg)));
}
-
-static int yyline = 1; /* line number for error reporting */
-
%}
+%option reentrant
+%option bison-bridge
%option 8bit
%option never-interactive
%option nodefault
%option noinput
%option nounput
%option noyywrap
+%option noyyalloc
+%option noyyrealloc
+%option noyyfree
%option warn
%option prefix="boot_yy"
@@ -58,7 +60,7 @@ id [-A-Za-z0-9_]+
sid \'([^']|\'\')*\'
/*
- * Keyword tokens return the keyword text (as a constant string) in boot_yylval.kw,
+ * Keyword tokens return the keyword text (as a constant string) in yylval->kw,
* just in case that's needed because we want to treat the keyword as an
* unreserved identifier. Note that _null_ is not treated as a keyword
* for this purpose; it's the one "reserved word" in the bootstrap syntax.
@@ -66,23 +68,23 @@ sid \'([^']|\'\')*\'
* Notice that all the keywords are case-sensitive, and for historical
* reasons some must be upper case.
*
- * String tokens return a palloc'd string in boot_yylval.str.
+ * String tokens return a palloc'd string in yylval->str.
*/
%%
-open { boot_yylval.kw = "open"; return OPEN; }
+open { yylval->kw = "open"; return OPEN; }
-close { boot_yylval.kw = "close"; return XCLOSE; }
+close { yylval->kw = "close"; return XCLOSE; }
-create { boot_yylval.kw = "create"; return XCREATE; }
+create { yylval->kw = "create"; return XCREATE; }
-OID { boot_yylval.kw = "OID"; return OBJ_ID; }
-bootstrap { boot_yylval.kw = "bootstrap"; return XBOOTSTRAP; }
-shared_relation { boot_yylval.kw = "shared_relation"; return XSHARED_RELATION; }
-rowtype_oid { boot_yylval.kw = "rowtype_oid"; return XROWTYPE_OID; }
+OID { yylval->kw = "OID"; return OBJ_ID; }
+bootstrap { yylval->kw = "bootstrap"; return XBOOTSTRAP; }
+shared_relation { yylval->kw = "shared_relation"; return XSHARED_RELATION; }
+rowtype_oid { yylval->kw = "rowtype_oid"; return XROWTYPE_OID; }
-insert { boot_yylval.kw = "insert"; return INSERT_TUPLE; }
+insert { yylval->kw = "insert"; return INSERT_TUPLE; }
_null_ { return NULLVAL; }
@@ -91,35 +93,35 @@ _null_ { return NULLVAL; }
"(" { return LPAREN; }
")" { return RPAREN; }
-[\n] { yyline++; }
+[\n] { yylineno++; }
[\r\t ] ;
^\#[^\n]* ; /* drop everything after "#" for comments */
-declare { boot_yylval.kw = "declare"; return XDECLARE; }
-build { boot_yylval.kw = "build"; return XBUILD; }
-indices { boot_yylval.kw = "indices"; return INDICES; }
-unique { boot_yylval.kw = "unique"; return UNIQUE; }
-index { boot_yylval.kw = "index"; return INDEX; }
-on { boot_yylval.kw = "on"; return ON; }
-using { boot_yylval.kw = "using"; return USING; }
-toast { boot_yylval.kw = "toast"; return XTOAST; }
-FORCE { boot_yylval.kw = "FORCE"; return XFORCE; }
-NOT { boot_yylval.kw = "NOT"; return XNOT; }
-NULL { boot_yylval.kw = "NULL"; return XNULL; }
+declare { yylval->kw = "declare"; return XDECLARE; }
+build { yylval->kw = "build"; return XBUILD; }
+indices { yylval->kw = "indices"; return INDICES; }
+unique { yylval->kw = "unique"; return UNIQUE; }
+index { yylval->kw = "index"; return INDEX; }
+on { yylval->kw = "on"; return ON; }
+using { yylval->kw = "using"; return USING; }
+toast { yylval->kw = "toast"; return XTOAST; }
+FORCE { yylval->kw = "FORCE"; return XFORCE; }
+NOT { yylval->kw = "NOT"; return XNOT; }
+NULL { yylval->kw = "NULL"; return XNULL; }
{id} {
- boot_yylval.str = pstrdup(yytext);
+ yylval->str = pstrdup(yytext);
return ID;
}
{sid} {
/* strip quotes and escapes */
- boot_yylval.str = DeescapeQuotedString(yytext);
+ yylval->str = DeescapeQuotedString(yytext);
return ID;
}
. {
- elog(ERROR, "syntax error at line %d: unexpected character \"%s\"", yyline, yytext);
+ elog(ERROR, "syntax error at line %d: unexpected character \"%s\"", yylineno, yytext);
}
%%
@@ -127,7 +129,37 @@ NULL { boot_yylval.kw = "NULL"; return XNULL; }
/* LCOV_EXCL_STOP */
void
-boot_yyerror(const char *message)
+boot_yyerror(yyscan_t yyscanner, const char *message)
+{
+ struct yyguts_t *yyg = (struct yyguts_t *) yyscanner; /* needed for yylineno
+ * macro */
+
+ elog(ERROR, "%s at line %d", message, yylineno);
+}
+
+/*
+ * Interface functions to make flex use palloc() instead of malloc().
+ * It'd be better to make these static, but flex insists otherwise.
+ */
+
+void *
+yyalloc(yy_size_t size, yyscan_t yyscanner)
+{
+ return palloc(size);
+}
+
+void *
+yyrealloc(void *ptr, yy_size_t size, yyscan_t yyscanner)
+{
+ if (ptr)
+ return repalloc(ptr, size);
+ else
+ return palloc(size);
+}
+
+void
+yyfree(void *ptr, yyscan_t yyscanner)
{
- elog(ERROR, "%s at line %d", message, yyline);
+ if (ptr)
+ pfree(ptr);
}
diff --git a/src/backend/bootstrap/bootstrap.c b/src/backend/bootstrap/bootstrap.c
index 986f6f1d9ca07..fc8638c1b61b6 100644
--- a/src/backend/bootstrap/bootstrap.c
+++ b/src/backend/bootstrap/bootstrap.c
@@ -4,7 +4,7 @@
* routines to support running postgres in 'bootstrap' mode
* bootstrap mode is used to create the initial template database
*
- * Portions Copyright (c) 1996-2024, PostgreSQL Global Development Group
+ * Portions Copyright (c) 1996-2025, PostgreSQL Global Development Group
* Portions Copyright (c) 1994, Regents of the University of California
*
* IDENTIFICATION
@@ -31,6 +31,7 @@
#include "miscadmin.h"
#include "nodes/makefuncs.h"
#include "pg_getopt.h"
+#include "postmaster/postmaster.h"
#include "storage/bufpage.h"
#include "storage/ipc.h"
#include "storage/proc.h"
@@ -41,8 +42,6 @@
#include "utils/rel.h"
#include "utils/relmapper.h"
-uint32 bootstrap_data_checksum_version = 0; /* No checksum */
-
static void CheckerModeMain(void);
static void bootstrap_signals(void);
@@ -110,6 +109,8 @@ static const struct typinfo TypInfo[] = {
F_REGROLEIN, F_REGROLEOUT},
{"regnamespace", REGNAMESPACEOID, 0, 4, true, TYPALIGN_INT, TYPSTORAGE_PLAIN, InvalidOid,
F_REGNAMESPACEIN, F_REGNAMESPACEOUT},
+ {"regdatabase", REGDATABASEOID, 0, 4, true, TYPALIGN_INT, TYPSTORAGE_PLAIN, InvalidOid,
+ F_REGDATABASEIN, F_REGDATABASEOUT},
{"text", TEXTOID, 0, -1, false, TYPALIGN_INT, TYPSTORAGE_EXTENDED, DEFAULT_COLLATION_OID,
F_TEXTIN, F_TEXTOUT},
{"oid", OIDOID, 0, 4, true, TYPALIGN_INT, TYPSTORAGE_PLAIN, InvalidOid,
@@ -202,6 +203,8 @@ BootstrapModeMain(int argc, char *argv[], bool check_only)
char *progname = argv[0];
int flag;
char *userDoption = NULL;
+ uint32 bootstrap_data_checksum_version = 0; /* No checksum */
+ yyscan_t scanner;
Assert(!IsUnderPostmaster);
@@ -224,8 +227,21 @@ BootstrapModeMain(int argc, char *argv[], bool check_only)
case 'B':
SetConfigOption("shared_buffers", optarg, PGC_POSTMASTER, PGC_S_ARGV);
break;
- case 'c':
case '-':
+
+ /*
+ * Error if the user misplaced a special must-be-first option
+ * for dispatching to a subprogram. parse_dispatch_option()
+ * returns DISPATCH_POSTMASTER if it doesn't find a match, so
+ * error for anything else.
+ */
+ if (parse_dispatch_option(optarg) != DISPATCH_POSTMASTER)
+ ereport(ERROR,
+ (errcode(ERRCODE_SYNTAX_ERROR),
+ errmsg("--%s must be first argument", optarg)));
+
+ /* FALLTHROUGH */
+ case 'c':
{
char *name,
*value;
@@ -310,8 +326,23 @@ BootstrapModeMain(int argc, char *argv[], bool check_only)
InitializeMaxBackends();
+ /*
+ * Even though bootstrapping runs in single-process mode, initialize
+ * postmaster child slots array so that --check can detect running out of
+ * shared memory or other resources if max_connections is set too high.
+ */
+ InitPostmasterChildSlots();
+
+ InitializeFastPathLocks();
+
CreateSharedMemoryAndSemaphores();
+ /*
+ * Estimate number of openable files. This is essential too in --check
+ * mode, because on some platforms semaphores count as open files.
+ */
+ set_max_safe_fds();
+
/*
* XXX: It might make sense to move this into its own function at some
* point. Right now it seems like it'd cause more code duplication than
@@ -332,7 +363,7 @@ BootstrapModeMain(int argc, char *argv[], bool check_only)
BaseInit();
bootstrap_signals();
- BootStrapXLOG();
+ BootStrapXLOG(bootstrap_data_checksum_version);
/*
* To ensure that src/common/link-canary.c is linked into the backend, we
@@ -350,11 +381,14 @@ BootstrapModeMain(int argc, char *argv[], bool check_only)
Nulls[i] = false;
}
+ if (boot_yylex_init(&scanner) != 0)
+ elog(ERROR, "yylex_init() failed: %m");
+
/*
* Process bootstrap input.
*/
StartTransactionCommand();
- boot_yyparse();
+ boot_yyparse(scanner);
CommitTransactionCommand();
/*
@@ -431,8 +465,8 @@ boot_openrel(char *relname)
{
if (attrtypes[i] == NULL)
attrtypes[i] = AllocateAttribute();
- memmove((char *) attrtypes[i],
- (char *) TupleDescAttr(boot_reldesc->rd_att, i),
+ memmove(attrtypes[i],
+ TupleDescAttr(boot_reldesc->rd_att, i),
ATTRIBUTE_FIXED_PART_SIZE);
{
@@ -548,7 +582,6 @@ DefineAttr(char *name, char *type, int attnum, int nullness)
if (OidIsValid(attrtypes[attnum]->attcollation))
attrtypes[attnum]->attcollation = C_COLLATION_OID;
- attrtypes[attnum]->attcacheoff = -1;
attrtypes[attnum]->atttypmod = -1;
attrtypes[attnum]->attislocal = true;
diff --git a/src/backend/bootstrap/meson.build b/src/backend/bootstrap/meson.build
index a8f821e98b445..29726c1ab4ff1 100644
--- a/src/backend/bootstrap/meson.build
+++ b/src/backend/bootstrap/meson.build
@@ -1,4 +1,4 @@
-# Copyright (c) 2022-2024, PostgreSQL Global Development Group
+# Copyright (c) 2022-2025, PostgreSQL Global Development Group
backend_sources += files(
'bootstrap.c')
diff --git a/src/backend/catalog/Catalog.pm b/src/backend/catalog/Catalog.pm
index 8e709524cba65..5a912549b82c0 100644
--- a/src/backend/catalog/Catalog.pm
+++ b/src/backend/catalog/Catalog.pm
@@ -4,7 +4,7 @@
# Perl module that extracts info from catalog files into Perl
# data structures
#
-# Portions Copyright (c) 1996-2024, PostgreSQL Global Development Group
+# Portions Copyright (c) 1996-2025, PostgreSQL Global Development Group
# Portions Copyright (c) 1994, Regents of the University of California
#
# src/backend/catalog/Catalog.pm
diff --git a/src/backend/catalog/Makefile b/src/backend/catalog/Makefile
index 1589a75fd5332..c090094ed08d5 100644
--- a/src/backend/catalog/Makefile
+++ b/src/backend/catalog/Makefile
@@ -2,7 +2,7 @@
#
# Makefile for backend/catalog
#
-# Portions Copyright (c) 1996-2024, PostgreSQL Global Development Group
+# Portions Copyright (c) 1996-2025, PostgreSQL Global Development Group
# Portions Copyright (c) 1994, Regents of the University of California
#
# src/backend/catalog/Makefile
diff --git a/src/backend/catalog/aclchk.c b/src/backend/catalog/aclchk.c
index 143876b77ff8e..cd139bd65a668 100644
--- a/src/backend/catalog/aclchk.c
+++ b/src/backend/catalog/aclchk.c
@@ -3,7 +3,7 @@
* aclchk.c
* Routines to check access control permissions.
*
- * Portions Copyright (c) 1996-2024, PostgreSQL Global Development Group
+ * Portions Copyright (c) 1996-2025, PostgreSQL Global Development Group
* Portions Copyright (c) 1994, Regents of the University of California
*
*
@@ -64,7 +64,6 @@
#include "catalog/pg_proc.h"
#include "catalog/pg_tablespace.h"
#include "catalog/pg_type.h"
-#include "commands/dbcommands.h"
#include "commands/defrem.h"
#include "commands/event_trigger.h"
#include "commands/extension.h"
@@ -75,6 +74,7 @@
#include "nodes/makefuncs.h"
#include "parser/parse_func.h"
#include "parser/parse_type.h"
+#include "storage/lmgr.h"
#include "utils/acl.h"
#include "utils/aclchk_internal.h"
#include "utils/builtins.h"
@@ -165,9 +165,9 @@ static AclMode pg_type_aclmask_ext(Oid type_oid, Oid roleid,
AclMode mask, AclMaskHow how,
bool *is_missing);
static void recordExtensionInitPriv(Oid objoid, Oid classoid, int objsubid,
- Oid ownerId, Acl *new_acl);
+ Acl *new_acl);
static void recordExtensionInitPrivWorker(Oid objoid, Oid classoid, int objsubid,
- Oid ownerId, Acl *new_acl);
+ Acl *new_acl);
/*
@@ -659,146 +659,90 @@ ExecGrantStmt_oids(InternalGrant *istmt)
*
* Turn a list of object names of a given type into an Oid list.
*
- * XXX: This function doesn't take any sort of locks on the objects whose
- * names it looks up. In the face of concurrent DDL, we might easily latch
- * onto an old version of an object, causing the GRANT or REVOKE statement
- * to fail.
+ * XXX This function intentionally takes only an AccessShareLock. In the face
+ * of concurrent DDL, we might easily latch onto an old version of an object,
+ * causing the GRANT or REVOKE statement to fail. But it does prevent the
+ * object from disappearing altogether. To do better, we would need to use a
+ * self-exclusive lock, perhaps ShareUpdateExclusiveLock, here and before
+ * *every* CatalogTupleUpdate() of a row that GRANT/REVOKE can affect.
+ * Besides that additional work, this could have operational costs. For
+ * example, it would make GRANT ALL TABLES IN SCHEMA terminate every
+ * autovacuum running in the schema and consume a shared lock table entry per
+ * table in the schema. The user-visible benefit of that additional work is
+ * just changing "ERROR: tuple concurrently updated" to blocking. That's not
+ * nothing, but it might not outweigh autovacuum termination and lock table
+ * consumption spikes.
*/
static List *
objectNamesToOids(ObjectType objtype, List *objnames, bool is_grant)
{
List *objects = NIL;
ListCell *cell;
+ const LOCKMODE lockmode = AccessShareLock;
Assert(objnames != NIL);
switch (objtype)
{
- case OBJECT_TABLE:
- case OBJECT_SEQUENCE:
- foreach(cell, objnames)
- {
- RangeVar *relvar = (RangeVar *) lfirst(cell);
- Oid relOid;
-
- relOid = RangeVarGetRelid(relvar, NoLock, false);
- objects = lappend_oid(objects, relOid);
- }
- break;
- case OBJECT_DATABASE:
- foreach(cell, objnames)
- {
- char *dbname = strVal(lfirst(cell));
- Oid dbid;
-
- dbid = get_database_oid(dbname, false);
- objects = lappend_oid(objects, dbid);
- }
- break;
- case OBJECT_DOMAIN:
- case OBJECT_TYPE:
- foreach(cell, objnames)
- {
- List *typname = (List *) lfirst(cell);
- Oid oid;
-
- oid = typenameTypeId(NULL, makeTypeNameFromNameList(typname));
- objects = lappend_oid(objects, oid);
- }
- break;
- case OBJECT_FUNCTION:
- foreach(cell, objnames)
- {
- ObjectWithArgs *func = (ObjectWithArgs *) lfirst(cell);
- Oid funcid;
+ default:
- funcid = LookupFuncWithArgs(OBJECT_FUNCTION, func, false);
- objects = lappend_oid(objects, funcid);
- }
- break;
- case OBJECT_LANGUAGE:
+ /*
+ * For most object types, we use get_object_address() directly.
+ */
foreach(cell, objnames)
{
- char *langname = strVal(lfirst(cell));
- Oid oid;
+ ObjectAddress address;
- oid = get_language_oid(langname, false);
- objects = lappend_oid(objects, oid);
+ address = get_object_address(objtype, lfirst(cell), NULL, lockmode, false);
+ objects = lappend_oid(objects, address.objectId);
}
break;
- case OBJECT_LARGEOBJECT:
- foreach(cell, objnames)
- {
- Oid lobjOid = oidparse(lfirst(cell));
-
- if (!LargeObjectExists(lobjOid))
- ereport(ERROR,
- (errcode(ERRCODE_UNDEFINED_OBJECT),
- errmsg("large object %u does not exist",
- lobjOid)));
- objects = lappend_oid(objects, lobjOid);
- }
- break;
- case OBJECT_SCHEMA:
- foreach(cell, objnames)
- {
- char *nspname = strVal(lfirst(cell));
- Oid oid;
+ case OBJECT_TABLE:
+ case OBJECT_SEQUENCE:
- oid = get_namespace_oid(nspname, false);
- objects = lappend_oid(objects, oid);
- }
- break;
- case OBJECT_PROCEDURE:
+ /*
+ * Here, we don't use get_object_address(). It requires that the
+ * specified object type match the actual type of the object, but
+ * in GRANT/REVOKE, all table-like things are addressed as TABLE.
+ */
foreach(cell, objnames)
{
- ObjectWithArgs *func = (ObjectWithArgs *) lfirst(cell);
- Oid procid;
+ RangeVar *relvar = (RangeVar *) lfirst(cell);
+ Oid relOid;
- procid = LookupFuncWithArgs(OBJECT_PROCEDURE, func, false);
- objects = lappend_oid(objects, procid);
+ relOid = RangeVarGetRelid(relvar, lockmode, false);
+ objects = lappend_oid(objects, relOid);
}
break;
- case OBJECT_ROUTINE:
- foreach(cell, objnames)
- {
- ObjectWithArgs *func = (ObjectWithArgs *) lfirst(cell);
- Oid routid;
- routid = LookupFuncWithArgs(OBJECT_ROUTINE, func, false);
- objects = lappend_oid(objects, routid);
- }
- break;
- case OBJECT_TABLESPACE:
- foreach(cell, objnames)
- {
- char *spcname = strVal(lfirst(cell));
- Oid spcoid;
+ case OBJECT_DOMAIN:
+ case OBJECT_TYPE:
- spcoid = get_tablespace_oid(spcname, false);
- objects = lappend_oid(objects, spcoid);
- }
- break;
- case OBJECT_FDW:
+ /*
+ * The parse representation of types and domains in privilege
+ * targets is different from that expected by get_object_address()
+ * (for parse conflict reasons), so we have to do a bit of
+ * conversion here.
+ */
foreach(cell, objnames)
{
- char *fdwname = strVal(lfirst(cell));
- Oid fdwid = get_foreign_data_wrapper_oid(fdwname, false);
+ List *typname = (List *) lfirst(cell);
+ TypeName *tn = makeTypeNameFromNameList(typname);
+ ObjectAddress address;
+ Relation relation;
- objects = lappend_oid(objects, fdwid);
+ address = get_object_address(objtype, (Node *) tn, &relation, lockmode, false);
+ Assert(relation == NULL);
+ objects = lappend_oid(objects, address.objectId);
}
break;
- case OBJECT_FOREIGN_SERVER:
- foreach(cell, objnames)
- {
- char *srvname = strVal(lfirst(cell));
- Oid srvid = get_foreign_server_oid(srvname, false);
- objects = lappend_oid(objects, srvid);
- }
- break;
case OBJECT_PARAMETER_ACL:
+
+ /*
+ * Parameters are handled completely differently.
+ */
foreach(cell, objnames)
{
/*
@@ -829,9 +773,6 @@ objectNamesToOids(ObjectType objtype, List *objnames, bool is_grant)
objects = lappend_oid(objects, parameterId);
}
break;
- default:
- elog(ERROR, "unrecognized GrantStmt.objtype: %d",
- (int) objtype);
}
return objects;
@@ -1077,6 +1018,10 @@ ExecAlterDefaultPrivilegesStmt(ParseState *pstate, AlterDefaultPrivilegesStmt *s
all_privileges = ACL_ALL_RIGHTS_SCHEMA;
errormsg = gettext_noop("invalid privilege type %s for schema");
break;
+ case OBJECT_LARGEOBJECT:
+ all_privileges = ACL_ALL_RIGHTS_LARGEOBJECT;
+ errormsg = gettext_noop("invalid privilege type %s for large object");
+ break;
default:
elog(ERROR, "unrecognized GrantStmt.objtype: %d",
(int) action->objtype);
@@ -1268,6 +1213,16 @@ SetDefaultACL(InternalDefaultACL *iacls)
this_privileges = ACL_ALL_RIGHTS_SCHEMA;
break;
+ case OBJECT_LARGEOBJECT:
+ if (OidIsValid(iacls->nspid))
+ ereport(ERROR,
+ (errcode(ERRCODE_INVALID_GRANT_OPERATION),
+ errmsg("cannot use IN SCHEMA clause when using GRANT/REVOKE ON LARGE OBJECTS")));
+ objtype = DEFACLOBJ_LARGEOBJECT;
+ if (iacls->all_privs && this_privileges == ACL_NO_RIGHTS)
+ this_privileges = ACL_ALL_RIGHTS_LARGEOBJECT;
+ break;
+
default:
elog(ERROR, "unrecognized object type: %d",
(int) iacls->objtype);
@@ -1511,6 +1466,9 @@ RemoveRoleFromObjectACL(Oid roleid, Oid classid, Oid objid)
case DEFACLOBJ_NAMESPACE:
iacls.objtype = OBJECT_SCHEMA;
break;
+ case DEFACLOBJ_LARGEOBJECT:
+ iacls.objtype = OBJECT_LARGEOBJECT;
+ break;
default:
/* Shouldn't get here */
elog(ERROR, "unexpected default ACL type: %d",
@@ -1802,7 +1760,7 @@ ExecGrant_Attribute(InternalGrant *istmt, Oid relOid, const char *relname,
CatalogTupleUpdate(attRelation, &newtuple->t_self, newtuple);
/* Update initial privileges for extensions */
- recordExtensionInitPriv(relOid, RelationRelationId, attnum, ownerId,
+ recordExtensionInitPriv(relOid, RelationRelationId, attnum,
ACL_NUM(new_acl) > 0 ? new_acl : NULL);
/* Update the shared dependency ACL info */
@@ -1848,7 +1806,7 @@ ExecGrant_Relation(InternalGrant *istmt)
HeapTuple tuple;
ListCell *cell_colprivs;
- tuple = SearchSysCache1(RELOID, ObjectIdGetDatum(relOid));
+ tuple = SearchSysCacheLocked1(RELOID, ObjectIdGetDatum(relOid));
if (!HeapTupleIsValid(tuple))
elog(ERROR, "cache lookup failed for relation %u", relOid);
pg_class_tuple = (Form_pg_class) GETSTRUCT(tuple);
@@ -2060,10 +2018,10 @@ ExecGrant_Relation(InternalGrant *istmt)
values, nulls, replaces);
CatalogTupleUpdate(relation, &newtuple->t_self, newtuple);
+ UnlockTuple(relation, &tuple->t_self, InplaceUpdateTupleLock);
/* Update initial privileges for extensions */
- recordExtensionInitPriv(relOid, RelationRelationId, 0,
- ownerId, new_acl);
+ recordExtensionInitPriv(relOid, RelationRelationId, 0, new_acl);
/* Update the shared dependency ACL info */
updateAclDependencies(RelationRelationId, relOid, 0,
@@ -2073,6 +2031,8 @@ ExecGrant_Relation(InternalGrant *istmt)
pfree(new_acl);
}
+ else
+ UnlockTuple(relation, &tuple->t_self, InplaceUpdateTupleLock);
/*
* Handle column-level privileges, if any were specified or implied.
@@ -2186,7 +2146,7 @@ ExecGrant_common(InternalGrant *istmt, Oid classid, AclMode default_privs,
Oid *oldmembers;
Oid *newmembers;
- tuple = SearchSysCache1(cacheid, ObjectIdGetDatum(objectid));
+ tuple = SearchSysCacheLocked1(cacheid, ObjectIdGetDatum(objectid));
if (!HeapTupleIsValid(tuple))
elog(ERROR, "cache lookup failed for %s %u", get_object_class_descr(classid), objectid);
@@ -2262,9 +2222,10 @@ ExecGrant_common(InternalGrant *istmt, Oid classid, AclMode default_privs,
nulls, replaces);
CatalogTupleUpdate(relation, &newtuple->t_self, newtuple);
+ UnlockTuple(relation, &tuple->t_self, InplaceUpdateTupleLock);
/* Update initial privileges for extensions */
- recordExtensionInitPriv(objectid, classid, 0, ownerId, new_acl);
+ recordExtensionInitPriv(objectid, classid, 0, new_acl);
/* Update the shared dependency ACL info */
updateAclDependencies(classid,
@@ -2416,8 +2377,7 @@ ExecGrant_Largeobject(InternalGrant *istmt)
CatalogTupleUpdate(relation, &newtuple->t_self, newtuple);
/* Update initial privileges for extensions */
- recordExtensionInitPriv(loid, LargeObjectRelationId, 0,
- ownerId, new_acl);
+ recordExtensionInitPriv(loid, LargeObjectRelationId, 0, new_acl);
/* Update the shared dependency ACL info */
updateAclDependencies(LargeObjectRelationId,
@@ -2455,14 +2415,6 @@ ExecGrant_Type_check(InternalGrant *istmt, HeapTuple tuple)
(errcode(ERRCODE_INVALID_GRANT_OPERATION),
errmsg("cannot set privileges of multirange types"),
errhint("Set the privileges of the range type instead.")));
-
- /* Used GRANT DOMAIN on a non-domain? */
- if (istmt->objtype == OBJECT_DOMAIN &&
- pg_type_tuple->typtype != TYPTYPE_DOMAIN)
- ereport(ERROR,
- (errcode(ERRCODE_WRONG_OBJECT_TYPE),
- errmsg("\"%s\" is not a domain",
- NameStr(pg_type_tuple->typname))));
}
static void
@@ -2589,7 +2541,7 @@ ExecGrant_Parameter(InternalGrant *istmt)
/* Update initial privileges for extensions */
recordExtensionInitPriv(parameterId, ParameterAclRelationId, 0,
- ownerId, new_acl);
+ new_acl);
/* Update the shared dependency ACL info */
updateAclDependencies(ParameterAclRelationId, parameterId, 0,
@@ -2643,8 +2595,6 @@ string_to_privilege(const char *privname)
return ACL_ALTER_SYSTEM;
if (strcmp(privname, "maintain") == 0)
return ACL_MAINTAIN;
- if (strcmp(privname, "rule") == 0)
- return 0; /* ignore old RULE privileges */
ereport(ERROR,
(errcode(ERRCODE_SYNTAX_ERROR),
errmsg("unrecognized privilege type \"%s\"", privname)));
@@ -3084,10 +3034,6 @@ pg_aclmask(ObjectType objtype, Oid object_oid, AttrNumber attnum, Oid roleid,
* Exported routines for examining a user's privileges for various objects
*
* See aclmask() for a description of the common API for these functions.
- *
- * Note: we give lookup failure the full ereport treatment because the
- * has_xxx_privilege() family of functions allow users to pass any random
- * OID to these functions.
* ****************************************************************
*/
@@ -3154,10 +3100,8 @@ object_aclmask_ext(Oid classid, Oid objectid, Oid roleid,
return 0;
}
else
- ereport(ERROR,
- (errcode(ERRCODE_UNDEFINED_OBJECT),
- errmsg("%s with OID %u does not exist",
- get_object_class_descr(classid), objectid)));
+ elog(ERROR, "cache lookup failed for %s %u",
+ get_object_class_descr(classid), objectid);
}
ownerId = DatumGetObjectId(SysCacheGetAttrNotNull(cacheid,
@@ -3448,7 +3392,7 @@ pg_class_aclmask_ext(Oid table_oid, Oid roleid, AclMode mask,
* Check if ACL_MAINTAIN is being checked and, if so, and not already set
* as part of the result, then check if the user is a member of the
* pg_maintain role, which allows VACUUM, ANALYZE, CLUSTER, REFRESH
- * MATERIALIZED VIEW, and REINDEX on all relations.
+ * MATERIALIZED VIEW, REINDEX, and LOCK TABLE on all relations.
*/
if (mask & ACL_MAINTAIN &&
!(result & ACL_MAINTAIN) &&
@@ -4162,9 +4106,8 @@ object_ownercheck(Oid classid, Oid objectid, Oid roleid)
tuple = SearchSysCache1(cacheid, ObjectIdGetDatum(objectid));
if (!HeapTupleIsValid(tuple))
- ereport(ERROR,
- (errcode(ERRCODE_UNDEFINED_OBJECT),
- errmsg("%s with OID %u does not exist", get_object_class_descr(classid), objectid)));
+ elog(ERROR, "cache lookup failed for %s %u",
+ get_object_class_descr(classid), objectid);
ownerId = DatumGetObjectId(SysCacheGetAttrNotNull(cacheid,
tuple,
@@ -4193,9 +4136,8 @@ object_ownercheck(Oid classid, Oid objectid, Oid roleid)
tuple = systable_getnext(scan);
if (!HeapTupleIsValid(tuple))
- ereport(ERROR,
- (errcode(ERRCODE_UNDEFINED_OBJECT),
- errmsg("%s with OID %u does not exist", get_object_class_descr(classid), objectid)));
+ elog(ERROR, "could not find tuple for %s %u",
+ get_object_class_descr(classid), objectid);
ownerId = DatumGetObjectId(heap_getattr(tuple,
get_object_attnum_owner(classid),
@@ -4338,6 +4280,10 @@ get_user_default_acl(ObjectType objtype, Oid ownerId, Oid nsp_oid)
defaclobjtype = DEFACLOBJ_NAMESPACE;
break;
+ case OBJECT_LARGEOBJECT:
+ defaclobjtype = DEFACLOBJ_LARGEOBJECT;
+ break;
+
default:
return NULL;
}
@@ -4477,7 +4423,6 @@ recordExtObjInitPriv(Oid objoid, Oid classoid)
}
recordExtensionInitPrivWorker(objoid, classoid, curr_att,
- pg_class_tuple->relowner,
DatumGetAclP(attaclDatum));
ReleaseSysCache(attTuple);
@@ -4490,7 +4435,6 @@ recordExtObjInitPriv(Oid objoid, Oid classoid)
/* Add the record, if any, for the top-level object */
if (!isNull)
recordExtensionInitPrivWorker(objoid, classoid, 0,
- pg_class_tuple->relowner,
DatumGetAclP(aclDatum));
ReleaseSysCache(tuple);
@@ -4501,7 +4445,6 @@ recordExtObjInitPriv(Oid objoid, Oid classoid)
Datum aclDatum;
bool isNull;
HeapTuple tuple;
- Form_pg_largeobject_metadata form_lo_meta;
ScanKeyData entry[1];
SysScanDesc scan;
Relation relation;
@@ -4526,7 +4469,6 @@ recordExtObjInitPriv(Oid objoid, Oid classoid)
tuple = systable_getnext(scan);
if (!HeapTupleIsValid(tuple))
elog(ERROR, "could not find tuple for large object %u", objoid);
- form_lo_meta = (Form_pg_largeobject_metadata) GETSTRUCT(tuple);
aclDatum = heap_getattr(tuple,
Anum_pg_largeobject_metadata_lomacl,
@@ -4535,7 +4477,6 @@ recordExtObjInitPriv(Oid objoid, Oid classoid)
/* Add the record, if any, for the top-level object */
if (!isNull)
recordExtensionInitPrivWorker(objoid, classoid, 0,
- form_lo_meta->lomowner,
DatumGetAclP(aclDatum));
systable_endscan(scan);
@@ -4544,7 +4485,6 @@ recordExtObjInitPriv(Oid objoid, Oid classoid)
else if (get_object_attnum_acl(classoid) != InvalidAttrNumber)
{
int cacheid;
- Oid ownerId;
Datum aclDatum;
bool isNull;
HeapTuple tuple;
@@ -4555,9 +4495,6 @@ recordExtObjInitPriv(Oid objoid, Oid classoid)
elog(ERROR, "cache lookup failed for %s %u",
get_object_class_descr(classoid), objoid);
- ownerId = DatumGetObjectId(SysCacheGetAttrNotNull(cacheid,
- tuple,
- get_object_attnum_owner(classoid)));
aclDatum = SysCacheGetAttr(cacheid, tuple,
get_object_attnum_acl(classoid),
&isNull);
@@ -4565,7 +4502,7 @@ recordExtObjInitPriv(Oid objoid, Oid classoid)
/* Add the record, if any, for the top-level object */
if (!isNull)
recordExtensionInitPrivWorker(objoid, classoid, 0,
- ownerId, DatumGetAclP(aclDatum));
+ DatumGetAclP(aclDatum));
ReleaseSysCache(tuple);
}
@@ -4578,8 +4515,6 @@ recordExtObjInitPriv(Oid objoid, Oid classoid)
void
removeExtObjInitPriv(Oid objoid, Oid classoid)
{
- Oid ownerId;
-
/*
* If this is a relation then we need to see if there are any sub-objects
* (eg: columns) for it and, if so, be sure to call
@@ -4594,7 +4529,6 @@ removeExtObjInitPriv(Oid objoid, Oid classoid)
if (!HeapTupleIsValid(tuple))
elog(ERROR, "cache lookup failed for relation %u", objoid);
pg_class_tuple = (Form_pg_class) GETSTRUCT(tuple);
- ownerId = pg_class_tuple->relowner;
/*
* Indexes don't have permissions, neither do the pg_class rows for
@@ -4631,8 +4565,7 @@ removeExtObjInitPriv(Oid objoid, Oid classoid)
/* when removing, remove all entries, even dropped columns */
- recordExtensionInitPrivWorker(objoid, classoid, curr_att,
- ownerId, NULL);
+ recordExtensionInitPrivWorker(objoid, classoid, curr_att, NULL);
ReleaseSysCache(attTuple);
}
@@ -4640,35 +4573,9 @@ removeExtObjInitPriv(Oid objoid, Oid classoid)
ReleaseSysCache(tuple);
}
- else
- {
- /* Must find out the owner's OID the hard way */
- AttrNumber ownerattnum;
- int cacheid;
- HeapTuple tuple;
-
- /*
- * If the object is of a kind that has no owner, it should not have
- * any pg_init_privs entry either.
- */
- ownerattnum = get_object_attnum_owner(classoid);
- if (ownerattnum == InvalidAttrNumber)
- return;
- cacheid = get_object_catcache_oid(classoid);
- tuple = SearchSysCache1(cacheid, ObjectIdGetDatum(objoid));
- if (!HeapTupleIsValid(tuple))
- elog(ERROR, "cache lookup failed for %s %u",
- get_object_class_descr(classoid), objoid);
-
- ownerId = DatumGetObjectId(SysCacheGetAttrNotNull(cacheid,
- tuple,
- ownerattnum));
-
- ReleaseSysCache(tuple);
- }
/* Remove the record, if any, for the top-level object */
- recordExtensionInitPrivWorker(objoid, classoid, 0, ownerId, NULL);
+ recordExtensionInitPrivWorker(objoid, classoid, 0, NULL);
}
/*
@@ -4680,8 +4587,7 @@ removeExtObjInitPriv(Oid objoid, Oid classoid)
* Pass in the object OID, the OID of the class (the OID of the table which
* the object is defined in) and the 'sub' id of the object (objsubid), if
* any. If there is no 'sub' id (they are currently only used for columns of
- * tables) then pass in '0'. Also pass the OID of the object's owner.
- * Finally, pass in the complete ACL to store.
+ * tables) then pass in '0'. Finally, pass in the complete ACL to store.
*
* If an ACL already exists for this object/sub-object then we will replace
* it with what is passed in.
@@ -4690,8 +4596,7 @@ removeExtObjInitPriv(Oid objoid, Oid classoid)
* removed, if one is found.
*/
static void
-recordExtensionInitPriv(Oid objoid, Oid classoid, int objsubid,
- Oid ownerId, Acl *new_acl)
+recordExtensionInitPriv(Oid objoid, Oid classoid, int objsubid, Acl *new_acl)
{
/*
* Generally, we only record the initial privileges when an extension is
@@ -4704,7 +4609,7 @@ recordExtensionInitPriv(Oid objoid, Oid classoid, int objsubid,
if (!creating_extension && !binary_upgrade_record_init_privs)
return;
- recordExtensionInitPrivWorker(objoid, classoid, objsubid, ownerId, new_acl);
+ recordExtensionInitPrivWorker(objoid, classoid, objsubid, new_acl);
}
/*
@@ -4721,7 +4626,7 @@ recordExtensionInitPriv(Oid objoid, Oid classoid, int objsubid,
*/
static void
recordExtensionInitPrivWorker(Oid objoid, Oid classoid, int objsubid,
- Oid ownerId, Acl *new_acl)
+ Acl *new_acl)
{
Relation relation;
ScanKeyData key[3];
@@ -4771,19 +4676,16 @@ recordExtensionInitPrivWorker(Oid objoid, Oid classoid, int objsubid,
/* Update pg_shdepend for roles mentioned in the old/new ACLs. */
oldAclDatum = heap_getattr(oldtuple, Anum_pg_init_privs_initprivs,
RelationGetDescr(relation), &isNull);
- if (!isNull)
- old_acl = DatumGetAclP(oldAclDatum);
- else
- old_acl = NULL; /* this case shouldn't happen, probably */
+ Assert(!isNull);
+ old_acl = DatumGetAclP(oldAclDatum);
noldmembers = aclmembers(old_acl, &oldmembers);
updateInitAclDependencies(classoid, objoid, objsubid,
- ownerId,
noldmembers, oldmembers,
nnewmembers, newmembers);
/* If we have a new ACL to set, then update the row with it. */
- if (new_acl)
+ if (new_acl && ACL_NUM(new_acl) != 0)
{
values[Anum_pg_init_privs_initprivs - 1] = PointerGetDatum(new_acl);
replace[Anum_pg_init_privs_initprivs - 1] = true;
@@ -4795,7 +4697,7 @@ recordExtensionInitPrivWorker(Oid objoid, Oid classoid, int objsubid,
}
else
{
- /* new_acl is NULL, so delete the entry we found. */
+ /* new_acl is NULL/empty, so delete the entry we found. */
CatalogTupleDelete(relation, &oldtuple->t_self);
}
}
@@ -4810,7 +4712,7 @@ recordExtensionInitPrivWorker(Oid objoid, Oid classoid, int objsubid,
* If we are passed in a NULL ACL and no entry exists, we can just
* fall through and do nothing.
*/
- if (new_acl)
+ if (new_acl && ACL_NUM(new_acl) != 0)
{
/* No entry found, so add it. */
values[Anum_pg_init_privs_objoid - 1] = ObjectIdGetDatum(objoid);
@@ -4832,7 +4734,6 @@ recordExtensionInitPrivWorker(Oid objoid, Oid classoid, int objsubid,
oldmembers = NULL;
updateInitAclDependencies(classoid, objoid, objsubid,
- ownerId,
noldmembers, oldmembers,
nnewmembers, newmembers);
}
@@ -4846,6 +4747,115 @@ recordExtensionInitPrivWorker(Oid objoid, Oid classoid, int objsubid,
table_close(relation, RowExclusiveLock);
}
+/*
+ * ReplaceRoleInInitPriv
+ *
+ * Used by shdepReassignOwned to replace mentions of a role in pg_init_privs.
+ */
+void
+ReplaceRoleInInitPriv(Oid oldroleid, Oid newroleid,
+ Oid classid, Oid objid, int32 objsubid)
+{
+ Relation rel;
+ ScanKeyData key[3];
+ SysScanDesc scan;
+ HeapTuple oldtuple;
+ Datum oldAclDatum;
+ bool isNull;
+ Acl *old_acl;
+ Acl *new_acl;
+ HeapTuple newtuple;
+ int noldmembers;
+ int nnewmembers;
+ Oid *oldmembers;
+ Oid *newmembers;
+
+ /* Search for existing pg_init_privs entry for the target object. */
+ rel = table_open(InitPrivsRelationId, RowExclusiveLock);
+
+ ScanKeyInit(&key[0],
+ Anum_pg_init_privs_objoid,
+ BTEqualStrategyNumber, F_OIDEQ,
+ ObjectIdGetDatum(objid));
+ ScanKeyInit(&key[1],
+ Anum_pg_init_privs_classoid,
+ BTEqualStrategyNumber, F_OIDEQ,
+ ObjectIdGetDatum(classid));
+ ScanKeyInit(&key[2],
+ Anum_pg_init_privs_objsubid,
+ BTEqualStrategyNumber, F_INT4EQ,
+ Int32GetDatum(objsubid));
+
+ scan = systable_beginscan(rel, InitPrivsObjIndexId, true,
+ NULL, 3, key);
+
+ /* There should exist only one entry or none. */
+ oldtuple = systable_getnext(scan);
+
+ if (!HeapTupleIsValid(oldtuple))
+ {
+ /*
+ * Hmm, why are we here if there's no entry? But pack up and go away
+ * quietly.
+ */
+ systable_endscan(scan);
+ table_close(rel, RowExclusiveLock);
+ return;
+ }
+
+ /* Get a writable copy of the existing ACL. */
+ oldAclDatum = heap_getattr(oldtuple, Anum_pg_init_privs_initprivs,
+ RelationGetDescr(rel), &isNull);
+ Assert(!isNull);
+ old_acl = DatumGetAclPCopy(oldAclDatum);
+
+ /*
+ * Generate new ACL. This usage of aclnewowner is a bit off-label when
+ * oldroleid isn't the owner; but it does the job fine.
+ */
+ new_acl = aclnewowner(old_acl, oldroleid, newroleid);
+
+ /*
+ * If we end with an empty ACL, delete the pg_init_privs entry. (That
+ * probably can't happen here, but we may as well cover the case.)
+ */
+ if (new_acl == NULL || ACL_NUM(new_acl) == 0)
+ {
+ CatalogTupleDelete(rel, &oldtuple->t_self);
+ }
+ else
+ {
+ Datum values[Natts_pg_init_privs] = {0};
+ bool nulls[Natts_pg_init_privs] = {0};
+ bool replaces[Natts_pg_init_privs] = {0};
+
+ /* Update existing entry. */
+ values[Anum_pg_init_privs_initprivs - 1] = PointerGetDatum(new_acl);
+ replaces[Anum_pg_init_privs_initprivs - 1] = true;
+
+ newtuple = heap_modify_tuple(oldtuple, RelationGetDescr(rel),
+ values, nulls, replaces);
+ CatalogTupleUpdate(rel, &newtuple->t_self, newtuple);
+ }
+
+ /*
+ * Update the shared dependency ACL info.
+ */
+ noldmembers = aclmembers(old_acl, &oldmembers);
+ nnewmembers = aclmembers(new_acl, &newmembers);
+
+ updateInitAclDependencies(classid, objid, objsubid,
+ noldmembers, oldmembers,
+ nnewmembers, newmembers);
+
+ systable_endscan(scan);
+
+ /* prevent error when processing objects multiple times */
+ CommandCounterIncrement();
+
+ table_close(rel, RowExclusiveLock);
+}
+
/*
* RemoveRoleFromInitPriv
*
@@ -4907,10 +4917,8 @@ RemoveRoleFromInitPriv(Oid roleid, Oid classid, Oid objid, int32 objsubid)
/* Get a writable copy of the existing ACL. */
oldAclDatum = heap_getattr(oldtuple, Anum_pg_init_privs_initprivs,
RelationGetDescr(rel), &isNull);
- if (!isNull)
- old_acl = DatumGetAclPCopy(oldAclDatum);
- else
- old_acl = NULL; /* this case shouldn't happen, probably */
+ Assert(!isNull);
+ old_acl = DatumGetAclPCopy(oldAclDatum);
/*
* We need the members of both old and new ACLs so we can correct the
@@ -4972,7 +4980,6 @@ RemoveRoleFromInitPriv(Oid roleid, Oid classid, Oid objid, int32 objsubid)
nnewmembers = aclmembers(new_acl, &newmembers);
updateInitAclDependencies(classid, objid, objsubid,
- ownerId,
noldmembers, oldmembers,
nnewmembers, newmembers);
diff --git a/src/backend/catalog/catalog.c b/src/backend/catalog/catalog.c
index 32170083fa315..59caae8f1bc23 100644
--- a/src/backend/catalog/catalog.c
+++ b/src/backend/catalog/catalog.c
@@ -5,7 +5,7 @@
* bits of hard-wired knowledge
*
*
- * Portions Copyright (c) 1996-2024, PostgreSQL Global Development Group
+ * Portions Copyright (c) 1996-2025, PostgreSQL Global Development Group
* Portions Copyright (c) 1994, Regents of the University of California
*
*
@@ -34,6 +34,7 @@
#include "catalog/pg_namespace.h"
#include "catalog/pg_parameter_acl.h"
#include "catalog/pg_replication_origin.h"
+#include "catalog/pg_seclabel.h"
#include "catalog/pg_shdepend.h"
#include "catalog/pg_shdescription.h"
#include "catalog/pg_shseclabel.h"
@@ -135,6 +136,66 @@ IsCatalogRelationOid(Oid relid)
return (relid < (Oid) FirstUnpinnedObjectId);
}
+/*
+ * IsCatalogTextUniqueIndexOid
+ * True iff the relation identified by this OID is a catalog UNIQUE index
+ * having a column of type "text".
+ *
+ * The relcache must not use these indexes. Inserting into any UNIQUE
+ * index compares index keys while holding BUFFER_LOCK_EXCLUSIVE.
+ * bttextcmp() can search the COLLOID catcache. Depending on concurrent
+ * invalidation traffic, catcache can reach relcache builds. A backend
+ * would self-deadlock on LWLocks if the relcache build read the
+ * exclusive-locked buffer.
+ *
+ * To avoid being itself the cause of self-deadlock, this doesn't read
+ * catalogs. Instead, it uses a hard-coded list with a supporting
+ * regression test.
+ */
+bool
+IsCatalogTextUniqueIndexOid(Oid relid)
+{
+ switch (relid)
+ {
+ case ParameterAclParnameIndexId:
+ case ReplicationOriginNameIndex:
+ case SecLabelObjectIndexId:
+ case SharedSecLabelObjectIndexId:
+ return true;
+ }
+ return false;
+}
+
+/*
+ * IsInplaceUpdateRelation
+ * True iff core code performs inplace updates on the relation.
+ *
+ * This is used for assertions and for making the executor follow the
+ * locking protocol described at README.tuplock section "Locking to write
+ * inplace-updated tables". Extensions may inplace-update other heap
+ * tables, but concurrent SQL UPDATE on the same table may overwrite
+ * those modifications.
+ *
+ * The executor can assume these are not partitions or partitioned and
+ * have no triggers.
+ */
+bool
+IsInplaceUpdateRelation(Relation relation)
+{
+ return IsInplaceUpdateOid(RelationGetRelid(relation));
+}
+
+/*
+ * IsInplaceUpdateOid
+ * Like the above, but takes an OID as argument.
+ */
+bool
+IsInplaceUpdateOid(Oid relid)
+{
+ return (relid == RelationRelationId ||
+ relid == DatabaseRelationId);
+}
+
/*
* IsToastRelation
* True iff relation is a TOAST support relation (or index).
@@ -279,16 +340,12 @@ IsSharedRelation(Oid relationId)
relationId == TablespaceOidIndexId)
return true;
/* These are their toast tables and toast indexes */
- if (relationId == PgAuthidToastTable ||
- relationId == PgAuthidToastIndex ||
- relationId == PgDatabaseToastTable ||
+ if (relationId == PgDatabaseToastTable ||
relationId == PgDatabaseToastIndex ||
relationId == PgDbRoleSettingToastTable ||
relationId == PgDbRoleSettingToastIndex ||
relationId == PgParameterAclToastTable ||
relationId == PgParameterAclToastIndex ||
- relationId == PgReplicationOriginToastTable ||
- relationId == PgReplicationOriginToastIndex ||
relationId == PgShdescriptionToastTable ||
relationId == PgShdescriptionToastIndex ||
relationId == PgShseclabelToastTable ||
@@ -446,10 +503,10 @@ GetNewOidWithIndex(Relation relation, Oid indexId, AttrNumber oidcolumn)
ereport(LOG,
(errmsg("still searching for an unused OID in relation \"%s\"",
RelationGetRelationName(relation)),
- errdetail_plural("OID candidates have been checked %llu time, but no unused OID has been found yet.",
- "OID candidates have been checked %llu times, but no unused OID has been found yet.",
+ errdetail_plural("OID candidates have been checked %" PRIu64 " time, but no unused OID has been found yet.",
+ "OID candidates have been checked %" PRIu64 " times, but no unused OID has been found yet.",
retries,
- (unsigned long long) retries)));
+ retries)));
/*
* Double the number of retries to do before logging next until it
@@ -471,10 +528,10 @@ GetNewOidWithIndex(Relation relation, Oid indexId, AttrNumber oidcolumn)
if (retries > GETNEWOID_LOG_THRESHOLD)
{
ereport(LOG,
- (errmsg_plural("new OID has been assigned in relation \"%s\" after %llu retry",
- "new OID has been assigned in relation \"%s\" after %llu retries",
+ (errmsg_plural("new OID has been assigned in relation \"%s\" after %" PRIu64 " retry",
+ "new OID has been assigned in relation \"%s\" after %" PRIu64 " retries",
retries,
- RelationGetRelationName(relation), (unsigned long long) retries)));
+ RelationGetRelationName(relation), retries)));
}
return newOid;
@@ -500,7 +557,7 @@ RelFileNumber
GetNewRelFileNumber(Oid reltablespace, Relation pg_class, char relpersistence)
{
RelFileLocatorBackend rlocator;
- char *rpath;
+ RelPathStr rpath;
bool collides;
ProcNumber procNumber;
@@ -552,7 +609,7 @@ GetNewRelFileNumber(Oid reltablespace, Relation pg_class, char relpersistence)
/* Check for existing file of same name */
rpath = relpath(rlocator, MAIN_FORKNUM);
- if (access(rpath, F_OK) == 0)
+ if (access(rpath.str, F_OK) == 0)
{
/* definite collision */
collides = true;
@@ -568,8 +625,6 @@ GetNewRelFileNumber(Oid reltablespace, Relation pg_class, char relpersistence)
*/
collides = false;
}
-
- pfree(rpath);
} while (collides);
return rlocator.locator.relNumber;
diff --git a/src/backend/catalog/dependency.c b/src/backend/catalog/dependency.c
index d4b5b2ade10a3..7dded634eb810 100644
--- a/src/backend/catalog/dependency.c
+++ b/src/backend/catalog/dependency.c
@@ -4,7 +4,7 @@
* Routines to support inter-object dependencies.
*
*
- * Portions Copyright (c) 1996-2024, PostgreSQL Global Development Group
+ * Portions Copyright (c) 1996-2025, PostgreSQL Global Development Group
* Portions Copyright (c) 1994, Regents of the University of California
*
* IDENTIFICATION
@@ -1326,7 +1326,9 @@ deleteOneObject(const ObjectAddress *object, Relation *depRel, int flags)
/*
* Delete any comments, security labels, or initial privileges associated
* with this object. (This is a convenient place to do these things,
- * rather than having every object type know to do it.)
+ * rather than having every object type know to do it.) As above, all
+ * these functions must remove records for sub-objects too if the subid is
+ * zero.
*/
DeleteComments(object->objectId, object->classId, object->objectSubId);
DeleteSecurityLabel(object);
@@ -1848,6 +1850,17 @@ find_expr_references_walker(Node *node,
errmsg("constant of the type %s cannot be used here",
"regrole")));
break;
+
+ /*
+ * Dependencies for regdatabase should be shared among all
+ * databases, so explicitly inhibit to have dependencies.
+ */
+ case REGDATABASEOID:
+ ereport(ERROR,
+ (errcode(ERRCODE_FEATURE_NOT_SUPPORTED),
+ errmsg("constant of the type %s cannot be used here",
+ "regdatabase")));
+ break;
}
}
return false;
@@ -2189,7 +2202,22 @@ find_expr_references_walker(Node *node,
}
context->rtables = list_delete_first(context->rtables);
break;
+ case RTE_NAMEDTUPLESTORE:
+
+ /*
+ * Cataloged objects cannot depend on tuplestores, because
+ * those have no cataloged representation. For now we can
+ * call the tuplestore a "transition table" because that's
+ * the only kind exposed to SQL, but someday we might have
+ * to work harder.
+ */
+ ereport(ERROR,
+ (errcode(ERRCODE_FEATURE_NOT_SUPPORTED),
+ errmsg("transition table \"%s\" cannot be referenced in a persistent object",
+ rte->eref->aliasname)));
+ break;
default:
+ /* Other RTE types can be ignored here */
break;
}
}
@@ -2238,7 +2266,7 @@ find_expr_references_walker(Node *node,
context->rtables = lcons(query->rtable, context->rtables);
result = query_tree_walker(query,
find_expr_references_walker,
- (void *) context,
+ context,
QTW_IGNORE_JOINALIASES |
QTW_EXAMINE_SORTGROUP);
context->rtables = list_delete_first(context->rtables);
@@ -2308,7 +2336,7 @@ find_expr_references_walker(Node *node,
}
return expression_tree_walker(node, find_expr_references_walker,
- (void *) context);
+ context);
}
/*
@@ -2784,6 +2812,7 @@ DeleteInitPrivs(const ObjectAddress *object)
{
Relation relation;
ScanKeyData key[3];
+ int nkeys;
SysScanDesc scan;
HeapTuple oldtuple;
@@ -2797,13 +2826,19 @@ DeleteInitPrivs(const ObjectAddress *object)
Anum_pg_init_privs_classoid,
BTEqualStrategyNumber, F_OIDEQ,
ObjectIdGetDatum(object->classId));
- ScanKeyInit(&key[2],
- Anum_pg_init_privs_objsubid,
- BTEqualStrategyNumber, F_INT4EQ,
- Int32GetDatum(object->objectSubId));
+ if (object->objectSubId != 0)
+ {
+ ScanKeyInit(&key[2],
+ Anum_pg_init_privs_objsubid,
+ BTEqualStrategyNumber, F_INT4EQ,
+ Int32GetDatum(object->objectSubId));
+ nkeys = 3;
+ }
+ else
+ nkeys = 2;
scan = systable_beginscan(relation, InitPrivsObjIndexId, true,
- NULL, 3, key);
+ NULL, nkeys, key);
while (HeapTupleIsValid(oldtuple = systable_getnext(scan)))
CatalogTupleDelete(relation, &oldtuple->t_self);
diff --git a/src/backend/catalog/genbki.pl b/src/backend/catalog/genbki.pl
index 94afdc5491dd8..6c02aee726754 100644
--- a/src/backend/catalog/genbki.pl
+++ b/src/backend/catalog/genbki.pl
@@ -6,7 +6,7 @@
# headers from specially formatted header files and data files.
# postgres.bki is used to initialize the postgres template database.
#
-# Portions Copyright (c) 1996-2024, PostgreSQL Global Development Group
+# Portions Copyright (c) 1996-2025, PostgreSQL Global Development Group
# Portions Copyright (c) 1994, Regents of the University of California
#
# src/backend/catalog/genbki.pl
@@ -480,6 +480,8 @@
EOM
+ printf $def "/* Macros related to the structure of $catname */\n\n";
+
# Emit OID macros for catalog's OID and rowtype OID, if wanted
printf $def "#define %s %s\n",
$catalog->{relation_oid_macro}, $catalog->{relation_oid}
@@ -561,6 +563,7 @@
print $def "\n#define Natts_$catname $attnum\n\n";
# Emit client code copied from source header
+ printf $def "/* Definitions copied from ${catname}.h */\n\n";
foreach my $line (@{ $catalog->{client_code} })
{
print $def $line;
@@ -573,6 +576,9 @@
print $bki "open $catname\n";
}
+ printf $def
+ "\n/* OID symbols for objects defined in ${catname}.dat */\n\n";
+
# For pg_attribute.h, we generate data entries ourselves.
if ($catname eq 'pg_attribute')
{
@@ -1048,8 +1054,7 @@ sub morph_row_for_schemapg
}
# Expand booleans from 'f'/'t' to 'false'/'true'.
- # Some values might be other macros (eg FLOAT8PASSBYVAL),
- # don't change.
+ # Some values might be other macros, if so don't change.
elsif ($atttype eq 'bool')
{
$row->{$attname} = 'true' if $row->{$attname} eq 't';
@@ -1156,7 +1161,7 @@ sub print_boilerplate
* %s
* %s
*
- * Portions Copyright (c) 1996-2024, PostgreSQL Global Development Group
+ * Portions Copyright (c) 1996-2025, PostgreSQL Global Development Group
* Portions Copyright (c) 1994, Regents of the University of California
*
* NOTES
diff --git a/src/backend/catalog/heap.c b/src/backend/catalog/heap.c
index a122bbffce771..fd6537567ea27 100644
--- a/src/backend/catalog/heap.c
+++ b/src/backend/catalog/heap.c
@@ -3,7 +3,7 @@
* heap.c
* code to create and destroy POSTGRES heap relations
*
- * Portions Copyright (c) 1996-2024, PostgreSQL Global Development Group
+ * Portions Copyright (c) 1996-2025, PostgreSQL Global Development Group
* Portions Copyright (c) 1994, Regents of the University of California
*
*
@@ -69,6 +69,7 @@
#include "pgstat.h"
#include "storage/lmgr.h"
#include "storage/predicate.h"
+#include "utils/array.h"
#include "utils/builtins.h"
#include "utils/fmgroids.h"
#include "utils/inval.h"
@@ -102,12 +103,13 @@ static ObjectAddress AddNewRelationType(const char *typeName,
Oid new_array_type);
static void RelationRemoveInheritance(Oid relid);
static Oid StoreRelCheck(Relation rel, const char *ccname, Node *expr,
- bool is_validated, bool is_local, int inhcount,
- bool is_no_inherit, bool is_internal);
+ bool is_enforced, bool is_validated, bool is_local,
+ int16 inhcount, bool is_no_inherit, bool is_internal);
static void StoreConstraints(Relation rel, List *cooked_constraints,
bool is_internal);
static bool MergeWithExistingConstraint(Relation rel, const char *ccname, Node *expr,
bool allow_merge, bool is_local,
+ bool is_enforced,
bool is_initially_valid,
bool is_no_inherit);
static void SetRelationNumChecks(Relation rel, int numchecks);
@@ -144,7 +146,6 @@ static const FormData_pg_attribute a1 = {
.atttypid = TIDOID,
.attlen = sizeof(ItemPointerData),
.attnum = SelfItemPointerAttributeNumber,
- .attcacheoff = -1,
.atttypmod = -1,
.attbyval = false,
.attalign = TYPALIGN_SHORT,
@@ -158,7 +159,6 @@ static const FormData_pg_attribute a2 = {
.atttypid = XIDOID,
.attlen = sizeof(TransactionId),
.attnum = MinTransactionIdAttributeNumber,
- .attcacheoff = -1,
.atttypmod = -1,
.attbyval = true,
.attalign = TYPALIGN_INT,
@@ -172,7 +172,6 @@ static const FormData_pg_attribute a3 = {
.atttypid = CIDOID,
.attlen = sizeof(CommandId),
.attnum = MinCommandIdAttributeNumber,
- .attcacheoff = -1,
.atttypmod = -1,
.attbyval = true,
.attalign = TYPALIGN_INT,
@@ -186,7 +185,6 @@ static const FormData_pg_attribute a4 = {
.atttypid = XIDOID,
.attlen = sizeof(TransactionId),
.attnum = MaxTransactionIdAttributeNumber,
- .attcacheoff = -1,
.atttypmod = -1,
.attbyval = true,
.attalign = TYPALIGN_INT,
@@ -200,7 +198,6 @@ static const FormData_pg_attribute a5 = {
.atttypid = CIDOID,
.attlen = sizeof(CommandId),
.attnum = MaxCommandIdAttributeNumber,
- .attcacheoff = -1,
.atttypmod = -1,
.attbyval = true,
.attalign = TYPALIGN_INT,
@@ -220,7 +217,6 @@ static const FormData_pg_attribute a6 = {
.atttypid = OIDOID,
.attlen = sizeof(Oid),
.attnum = TableOidAttributeNumber,
- .attcacheoff = -1,
.atttypmod = -1,
.attbyval = true,
.attalign = TYPALIGN_INT,
@@ -433,7 +429,7 @@ heap_create(const char *relname,
* 6) AddNewAttributeTuples() is called to register the
* new relation's schema in pg_attribute.
*
- * 7) StoreConstraints is called () - vadim 08/22/97
+ * 7) StoreConstraints() is called - vadim 08/22/97
*
* 8) the relations are closed and the new relation's oid
* is returned.
@@ -512,7 +508,7 @@ CheckAttributeNamesTypes(TupleDesc tupdesc, char relkind,
TupleDescAttr(tupdesc, i)->atttypid,
TupleDescAttr(tupdesc, i)->attcollation,
NIL, /* assume we're creating a new rowtype */
- flags);
+ flags | (TupleDescAttr(tupdesc, i)->attgenerated == ATTRIBUTE_GENERATED_VIRTUAL ? CHKATYPE_IS_VIRTUAL : 0));
}
}
@@ -587,6 +583,17 @@ CheckAttributeType(const char *attname,
}
else if (att_typtype == TYPTYPE_DOMAIN)
{
+ /*
+ * Prevent virtual generated columns from having a domain type. We
+ * would have to enforce domain constraints when columns underlying
+ * the generated column change. This could possibly be implemented,
+ * but it's not.
+ */
+ if (flags & CHKATYPE_IS_VIRTUAL)
+ ereport(ERROR,
+ errcode(ERRCODE_FEATURE_NOT_SUPPORTED),
+ errmsg("virtual generated column \"%s\" cannot have a domain type", attname));
+
/*
* If it's a domain, recurse to check its base type.
*/
@@ -657,6 +664,15 @@ CheckAttributeType(const char *attname,
flags);
}
+ /*
+ * For consistency with check_virtual_generated_security().
+ */
+ if ((flags & CHKATYPE_IS_VIRTUAL) && atttypid >= FirstUnpinnedObjectId)
+ ereport(ERROR,
+ errcode(ERRCODE_FEATURE_NOT_SUPPORTED),
+ errmsg("virtual generated column \"%s\" cannot have a user-defined type", attname),
+ errdetail("Virtual generated columns that make use of user-defined types are not yet supported."));
+
/*
* This might not be strictly invalid per SQL standard, but it is pretty
* useless, and it cannot be dumped, so we must disallow it.
@@ -684,11 +700,10 @@ CheckAttributeType(const char *attname,
* Construct and insert a set of tuples in pg_attribute.
*
* Caller has already opened and locked pg_attribute. tupdesc contains the
- * attributes to insert. attcacheoff is always initialized to -1.
- * tupdesc_extra supplies the values for certain variable-length/nullable
- * pg_attribute fields and must contain the same number of elements as tupdesc
- * or be NULL. The other variable-length fields of pg_attribute are always
- * initialized to null values.
+ * attributes to insert. tupdesc_extra supplies the values for certain
+ * variable-length/nullable pg_attribute fields and must contain the same
+ * number of elements as tupdesc or be NULL. The other variable-length fields
+ * of pg_attribute are always initialized to null values.
*
* indstate is the index state for CatalogTupleInsertWithInfo. It can be
* passed as NULL, in which case we'll fetch the necessary info. (Don't do
@@ -740,7 +755,6 @@ InsertPgAttributeTuples(Relation pg_attribute_rel,
slot[slotCount]->tts_values[Anum_pg_attribute_atttypid - 1] = ObjectIdGetDatum(attrs->atttypid);
slot[slotCount]->tts_values[Anum_pg_attribute_attlen - 1] = Int16GetDatum(attrs->attlen);
slot[slotCount]->tts_values[Anum_pg_attribute_attnum - 1] = Int16GetDatum(attrs->attnum);
- slot[slotCount]->tts_values[Anum_pg_attribute_attcacheoff - 1] = Int32GetDatum(-1);
slot[slotCount]->tts_values[Anum_pg_attribute_atttypmod - 1] = Int32GetDatum(attrs->atttypmod);
slot[slotCount]->tts_values[Anum_pg_attribute_attndims - 1] = Int16GetDatum(attrs->attndims);
slot[slotCount]->tts_values[Anum_pg_attribute_attbyval - 1] = BoolGetDatum(attrs->attbyval);
@@ -839,18 +853,19 @@ AddNewAttributeTuples(Oid new_rel_oid,
/* add dependencies on their datatypes and collations */
for (int i = 0; i < natts; i++)
{
+ Form_pg_attribute attr = TupleDescAttr(tupdesc, i);
+
/* Add dependency info */
ObjectAddressSubSet(myself, RelationRelationId, new_rel_oid, i + 1);
- ObjectAddressSet(referenced, TypeRelationId,
- tupdesc->attrs[i].atttypid);
+ ObjectAddressSet(referenced, TypeRelationId, attr->atttypid);
recordDependencyOn(&myself, &referenced, DEPENDENCY_NORMAL);
/* The default collation is pinned, so don't bother recording it */
- if (OidIsValid(tupdesc->attrs[i].attcollation) &&
- tupdesc->attrs[i].attcollation != DEFAULT_COLLATION_OID)
+ if (OidIsValid(attr->attcollation) &&
+ attr->attcollation != DEFAULT_COLLATION_OID)
{
ObjectAddressSet(referenced, CollationRelationId,
- tupdesc->attrs[i].attcollation);
+ attr->attcollation);
recordDependencyOn(&myself, &referenced, DEPENDENCY_NORMAL);
}
}
@@ -919,6 +934,7 @@ InsertPgClassTuple(Relation pg_class_desc,
values[Anum_pg_class_relpages - 1] = Int32GetDatum(rd_rel->relpages);
values[Anum_pg_class_reltuples - 1] = Float4GetDatum(rd_rel->reltuples);
values[Anum_pg_class_relallvisible - 1] = Int32GetDatum(rd_rel->relallvisible);
+ values[Anum_pg_class_relallfrozen - 1] = Int32GetDatum(rd_rel->relallfrozen);
values[Anum_pg_class_reltoastrelid - 1] = ObjectIdGetDatum(rd_rel->reltoastrelid);
values[Anum_pg_class_relhasindex - 1] = BoolGetDatum(rd_rel->relhasindex);
values[Anum_pg_class_relisshared - 1] = BoolGetDatum(rd_rel->relisshared);
@@ -989,6 +1005,7 @@ AddNewRelationTuple(Relation pg_class_desc,
new_rel_reltup->relpages = 0;
new_rel_reltup->reltuples = -1;
new_rel_reltup->relallvisible = 0;
+ new_rel_reltup->relallfrozen = 0;
/* Sequences always have a known size */
if (relkind == RELKIND_SEQUENCE)
@@ -1092,6 +1109,7 @@ AddNewRelationType(const char *typeName,
* if false, relacl is always set NULL
* allow_system_table_mods: true to allow creation in system namespaces
* is_internal: is this a system-generated catalog?
+ * relrewrite: link to original relation during a table rewrite
*
* Output parameters:
* typaddress: if not null, gets the object address of the new pg_type entry
@@ -1249,6 +1267,13 @@ heap_create_with_catalog(const char *relname,
relpersistence);
}
+ /*
+ * Other sessions' catalog scans can't find this until we commit. Hence,
+ * it doesn't hurt to hold AccessExclusiveLock. Do it here so callers
+ * can't accidentally vary in their lock mode or acquisition timing.
+ */
+ LockRelationOid(relid, AccessExclusiveLock);
+
/*
* Determine the relation's initial permissions.
*/
@@ -1463,9 +1488,11 @@ heap_create_with_catalog(const char *relname,
* access method is.
*
* No need to add an explicit dependency for the toast table, as the
- * main table depends on it.
+ * main table depends on it. Partitioned tables may not have an
+ * access method set.
*/
- if (RELKIND_HAS_TABLE_AM(relkind) && relkind != RELKIND_TOASTVALUE)
+ if ((RELKIND_HAS_TABLE_AM(relkind) && relkind != RELKIND_TOASTVALUE) ||
+ (relkind == RELKIND_PARTITIONED_TABLE && OidIsValid(accessmtd)))
{
ObjectAddressSet(referenced, AccessMethodRelationId, accessmtd);
add_exact_object_address(&referenced, addrs);
@@ -1479,7 +1506,7 @@ heap_create_with_catalog(const char *relname,
InvokeObjectPostCreateHookArg(RelationRelationId, relid, 0, is_internal);
/*
- * Store any supplied constraints and defaults.
+ * Store any supplied CHECK constraints and defaults.
*
* NB: this may do a CommandCounterIncrement and rebuild the relcache
* entry, so the relation must be valid and self-consistent at this point.
@@ -1994,6 +2021,60 @@ RelationClearMissing(Relation rel)
table_close(attr_rel, RowExclusiveLock);
}
+/*
+ * StoreAttrMissingVal
+ *
+ * Set the missing value of a single attribute.
+ */
+void
+StoreAttrMissingVal(Relation rel, AttrNumber attnum, Datum missingval)
+{
+ Datum valuesAtt[Natts_pg_attribute] = {0};
+ bool nullsAtt[Natts_pg_attribute] = {0};
+ bool replacesAtt[Natts_pg_attribute] = {0};
+ Relation attrrel;
+ Form_pg_attribute attStruct;
+ HeapTuple atttup,
+ newtup;
+
+ /* This is only supported for plain tables */
+ Assert(rel->rd_rel->relkind == RELKIND_RELATION);
+
+ /* Fetch the pg_attribute row */
+ attrrel = table_open(AttributeRelationId, RowExclusiveLock);
+
+ atttup = SearchSysCache2(ATTNUM,
+ ObjectIdGetDatum(RelationGetRelid(rel)),
+ Int16GetDatum(attnum));
+ if (!HeapTupleIsValid(atttup)) /* shouldn't happen */
+ elog(ERROR, "cache lookup failed for attribute %d of relation %u",
+ attnum, RelationGetRelid(rel));
+ attStruct = (Form_pg_attribute) GETSTRUCT(atttup);
+
+ /* Make a one-element array containing the value */
+ missingval = PointerGetDatum(construct_array(&missingval,
+ 1,
+ attStruct->atttypid,
+ attStruct->attlen,
+ attStruct->attbyval,
+ attStruct->attalign));
+
+ /* Update the pg_attribute row */
+ valuesAtt[Anum_pg_attribute_atthasmissing - 1] = BoolGetDatum(true);
+ replacesAtt[Anum_pg_attribute_atthasmissing - 1] = true;
+
+ valuesAtt[Anum_pg_attribute_attmissingval - 1] = missingval;
+ replacesAtt[Anum_pg_attribute_attmissingval - 1] = true;
+
+ newtup = heap_modify_tuple(atttup, RelationGetDescr(attrrel),
+ valuesAtt, nullsAtt, replacesAtt);
+ CatalogTupleUpdate(attrrel, &newtup->t_self, newtup);
+
+ /* clean up */
+ ReleaseSysCache(atttup);
+ table_close(attrrel, RowExclusiveLock);
+}
+
/*
* SetAttrMissing
*
@@ -2064,8 +2145,8 @@ SetAttrMissing(Oid relid, char *attname, char *value)
*/
static Oid
StoreRelCheck(Relation rel, const char *ccname, Node *expr,
- bool is_validated, bool is_local, int inhcount,
- bool is_no_inherit, bool is_internal)
+ bool is_enforced, bool is_validated, bool is_local,
+ int16 inhcount, bool is_no_inherit, bool is_internal)
{
char *ccbin;
List *varList;
@@ -2130,6 +2211,7 @@ StoreRelCheck(Relation rel, const char *ccname, Node *expr,
CONSTRAINT_CHECK, /* Constraint Type */
false, /* Is Deferrable */
false, /* Is Deferred */
+ is_enforced, /* Is Enforced */
is_validated,
InvalidOid, /* no parent constraint */
RelationGetRelid(rel), /* relation */
@@ -2155,6 +2237,7 @@ StoreRelCheck(Relation rel, const char *ccname, Node *expr,
is_local, /* conislocal */
inhcount, /* coninhcount */
is_no_inherit, /* connoinherit */
+ false, /* conperiod */
is_internal); /* internally constructed? */
pfree(ccbin);
@@ -2163,7 +2246,58 @@ StoreRelCheck(Relation rel, const char *ccname, Node *expr,
}
/*
- * Store defaults and constraints (passed as a list of CookedConstraint).
+ * Store a not-null constraint for the given relation
+ *
+ * The OID of the new constraint is returned.
+ */
+static Oid
+StoreRelNotNull(Relation rel, const char *nnname, AttrNumber attnum,
+ bool is_validated, bool is_local, int inhcount,
+ bool is_no_inherit)
+{
+ Oid constrOid;
+
+ Assert(attnum > InvalidAttrNumber);
+
+ constrOid =
+ CreateConstraintEntry(nnname,
+ RelationGetNamespace(rel),
+ CONSTRAINT_NOTNULL,
+ false,
+ false,
+ true, /* Is Enforced */
+ is_validated,
+ InvalidOid,
+ RelationGetRelid(rel),
+ &attnum,
+ 1,
+ 1,
+ InvalidOid, /* not a domain constraint */
+ InvalidOid, /* no associated index */
+ InvalidOid, /* Foreign key fields */
+ NULL,
+ NULL,
+ NULL,
+ NULL,
+ 0,
+ ' ',
+ ' ',
+ NULL,
+ 0,
+ ' ',
+ NULL, /* not an exclusion constraint */
+ NULL,
+ NULL,
+ is_local,
+ inhcount,
+ is_no_inherit,
+ false,
+ false);
+ return constrOid;
+}
+
+/*
+ * Store defaults and CHECK constraints (passed as a list of CookedConstraint).
*
* Each CookedConstraint struct is modified to store the new catalog tuple OID.
*
@@ -2196,16 +2330,17 @@ StoreConstraints(Relation rel, List *cooked_constraints, bool is_internal)
{
case CONSTR_DEFAULT:
con->conoid = StoreAttrDefault(rel, con->attnum, con->expr,
- is_internal, false);
+ is_internal);
break;
case CONSTR_CHECK:
con->conoid =
StoreRelCheck(rel, con->name, con->expr,
- !con->skip_validation, con->is_local,
- con->inhcount, con->is_no_inherit,
- is_internal);
+ con->is_enforced, !con->skip_validation,
+ con->is_local, con->inhcount,
+ con->is_no_inherit, is_internal);
numchecks++;
break;
+
default:
elog(ERROR, "unrecognized constraint type: %d",
(int) con->contype);
@@ -2234,7 +2369,7 @@ StoreConstraints(Relation rel, List *cooked_constraints, bool is_internal)
* cooked CHECK constraints
*
* All entries in newColDefaults will be processed. Entries in newConstraints
- * will be processed only if they are CONSTR_CHECK type.
+ * will be processed only if they are CONSTR_CHECK or CONSTR_NOTNULL types.
*
* Returns a list of CookedConstraint nodes that shows the cooked form of
* the default and constraint expressions added to the relation.
@@ -2263,6 +2398,7 @@ AddRelationNewConstraints(Relation rel,
ParseNamespaceItem *nsitem;
int numchecks;
List *checknames;
+ List *nnnames;
Node *expr;
CookedConstraint *cooked;
@@ -2321,13 +2457,7 @@ AddRelationNewConstraints(Relation rel,
castNode(Const, expr)->constisnull))
continue;
- /* If the DEFAULT is volatile we cannot use a missing value */
- if (colDef->missingMode &&
- contain_volatile_functions_after_planning((Expr *) expr))
- colDef->missingMode = false;
-
- defOid = StoreAttrDefault(rel, colDef->attnum, expr, is_internal,
- colDef->missingMode);
+ defOid = StoreAttrDefault(rel, colDef->attnum, expr, is_internal);
cooked = (CookedConstraint *) palloc(sizeof(CookedConstraint));
cooked->contype = CONSTR_DEFAULT;
@@ -2335,6 +2465,7 @@ AddRelationNewConstraints(Relation rel,
cooked->name = NULL;
cooked->attnum = colDef->attnum;
cooked->expr = expr;
+ cooked->is_enforced = true;
cooked->skip_validation = false;
cooked->is_local = is_local;
cooked->inhcount = is_local ? 0 : 1;
@@ -2347,6 +2478,7 @@ AddRelationNewConstraints(Relation rel,
*/
numchecks = numoldchecks;
checknames = NIL;
+ nnnames = NIL;
foreach_node(Constraint, cdef, newConstraints)
{
Oid constrOid;
@@ -2401,10 +2533,11 @@ AddRelationNewConstraints(Relation rel,
* Check against pre-existing constraints. If we are allowed
* to merge with an existing constraint, there's no more to do
* here. (We omit the duplicate constraint from the result,
- * which is what ATAddCheckConstraint wants.)
+ * which is what ATAddCheckNNConstraint wants.)
*/
if (MergeWithExistingConstraint(rel, ccname, expr,
allow_merge, is_local,
+ cdef->is_enforced,
cdef->initially_valid,
cdef->is_no_inherit))
continue;
@@ -2453,8 +2586,10 @@ AddRelationNewConstraints(Relation rel,
* OK, store it.
*/
constrOid =
- StoreRelCheck(rel, ccname, expr, cdef->initially_valid, is_local,
- is_local ? 0 : 1, cdef->is_no_inherit, is_internal);
+ StoreRelCheck(rel, ccname, expr, cdef->is_enforced,
+ cdef->initially_valid, is_local,
+ is_local ? 0 : 1, cdef->is_no_inherit,
+ is_internal);
numchecks++;
@@ -2464,12 +2599,90 @@ AddRelationNewConstraints(Relation rel,
cooked->name = ccname;
cooked->attnum = 0;
cooked->expr = expr;
+ cooked->is_enforced = cdef->is_enforced;
cooked->skip_validation = cdef->skip_validation;
cooked->is_local = is_local;
cooked->inhcount = is_local ? 0 : 1;
cooked->is_no_inherit = cdef->is_no_inherit;
cookedConstraints = lappend(cookedConstraints, cooked);
}
+ else if (cdef->contype == CONSTR_NOTNULL)
+ {
+ CookedConstraint *nncooked;
+ AttrNumber colnum;
+ int16 inhcount = is_local ? 0 : 1;
+ char *nnname;
+
+ /* Determine which column to modify */
+ colnum = get_attnum(RelationGetRelid(rel), strVal(linitial(cdef->keys)));
+ if (colnum == InvalidAttrNumber)
+ ereport(ERROR,
+ errcode(ERRCODE_UNDEFINED_COLUMN),
+ errmsg("column \"%s\" of relation \"%s\" does not exist",
+ strVal(linitial(cdef->keys)), RelationGetRelationName(rel)));
+ if (colnum < InvalidAttrNumber)
+ ereport(ERROR,
+ errcode(ERRCODE_FEATURE_NOT_SUPPORTED),
+ errmsg("cannot add not-null constraint on system column \"%s\"",
+ strVal(linitial(cdef->keys))));
+
+ Assert(cdef->initially_valid != cdef->skip_validation);
+
+ /*
+ * If the column already has a not-null constraint, we don't want
+ * to add another one; adjust inheritance status as needed. This
+ * also checks whether the existing constraint matches the
+ * requested validity.
+ */
+ if (AdjustNotNullInheritance(RelationGetRelid(rel), colnum,
+ is_local, cdef->is_no_inherit,
+ cdef->skip_validation))
+ continue;
+
+ /*
+ * If a constraint name is specified, check that it isn't already
+ * used. Otherwise, choose a non-conflicting one ourselves.
+ */
+ if (cdef->conname)
+ {
+ if (ConstraintNameIsUsed(CONSTRAINT_RELATION,
+ RelationGetRelid(rel),
+ cdef->conname))
+ ereport(ERROR,
+ errcode(ERRCODE_DUPLICATE_OBJECT),
+ errmsg("constraint \"%s\" for relation \"%s\" already exists",
+ cdef->conname, RelationGetRelationName(rel)));
+ nnname = cdef->conname;
+ }
+ else
+ nnname = ChooseConstraintName(RelationGetRelationName(rel),
+ strVal(linitial(cdef->keys)),
+ "not_null",
+ RelationGetNamespace(rel),
+ nnnames);
+ nnnames = lappend(nnnames, nnname);
+
+ constrOid =
+ StoreRelNotNull(rel, nnname, colnum,
+ cdef->initially_valid,
+ is_local,
+ inhcount,
+ cdef->is_no_inherit);
+
+ nncooked = (CookedConstraint *) palloc(sizeof(CookedConstraint));
+ nncooked->contype = CONSTR_NOTNULL;
+ nncooked->conoid = constrOid;
+ nncooked->name = nnname;
+ nncooked->attnum = colnum;
+ nncooked->expr = NULL;
+ nncooked->is_enforced = true;
+ nncooked->skip_validation = cdef->skip_validation;
+ nncooked->is_local = is_local;
+ nncooked->inhcount = inhcount;
+ nncooked->is_no_inherit = cdef->is_no_inherit;
+
+ cookedConstraints = lappend(cookedConstraints, nncooked);
+ }
}
/*
@@ -2497,6 +2710,7 @@ AddRelationNewConstraints(Relation rel,
static bool
MergeWithExistingConstraint(Relation rel, const char *ccname, Node *expr,
bool allow_merge, bool is_local,
+ bool is_enforced,
bool is_initially_valid,
bool is_no_inherit)
{
@@ -2587,12 +2801,24 @@ MergeWithExistingConstraint(Relation rel, const char *ccname, Node *expr,
* If the child constraint is "not valid" then cannot merge with a
* valid parent constraint.
*/
- if (is_initially_valid && !con->convalidated)
+ if (is_initially_valid && con->conenforced && !con->convalidated)
ereport(ERROR,
(errcode(ERRCODE_INVALID_OBJECT_DEFINITION),
errmsg("constraint \"%s\" conflicts with NOT VALID constraint on relation \"%s\"",
ccname, RelationGetRelationName(rel))));
+ /*
+ * A non-enforced child constraint cannot be merged with an enforced
+ * parent constraint. However, the reverse is allowed, where the child
+ * constraint is enforced.
+ */
+ if ((!is_local && is_enforced && !con->conenforced) ||
+ (is_local && !is_enforced && con->conenforced))
+ ereport(ERROR,
+ (errcode(ERRCODE_INVALID_OBJECT_DEFINITION),
+ errmsg("constraint \"%s\" conflicts with NOT ENFORCED constraint on relation \"%s\"",
+ ccname, RelationGetRelationName(rel))));
+
/* OK to update the tuple */
ereport(NOTICE,
(errmsg("merging constraint \"%s\" with inherited definition",
@@ -2615,10 +2841,8 @@ MergeWithExistingConstraint(Relation rel, const char *ccname, Node *expr,
{
if (is_local)
con->conislocal = true;
- else
- con->coninhcount++;
-
- if (con->coninhcount < 0)
+ else if (pg_add_s16_overflow(con->coninhcount, 1,
+ &con->coninhcount))
ereport(ERROR,
errcode(ERRCODE_PROGRAM_LIMIT_EXCEEDED),
errmsg("too many inheritance parents"));
@@ -2630,6 +2854,19 @@ MergeWithExistingConstraint(Relation rel, const char *ccname, Node *expr,
con->connoinherit = true;
}
+ /*
+ * If the child constraint is required to be enforced while the parent
+ * constraint is not, this should be allowed by marking the child
+ * constraint as enforced. In the reverse case, an error would have
+ * already been thrown before reaching this point.
+ */
+ if (is_enforced && !con->conenforced)
+ {
+ Assert(is_local);
+ con->conenforced = true;
+ con->convalidated = true;
+ }
+
CatalogTupleUpdate(conDesc, &tup->t_self, tup);
}
@@ -2639,6 +2876,262 @@ MergeWithExistingConstraint(Relation rel, const char *ccname, Node *expr,
return found;
}
+/*
+ * Create the not-null constraints when creating a new relation
+ *
+ * These come from two sources: the 'constraints' list (of Constraint) is
+ * specified directly by the user; the 'old_notnulls' list (of
+ * CookedConstraint) comes from inheritance. We create one constraint
+ * for each column, giving priority to user-specified ones, and setting
+ * inhcount according to how many parents cause each column to get a
+ * not-null constraint. If a user-specified name clashes with another
+ * user-specified name, an error is raised.
+ *
+ * Returns a list of AttrNumber for columns that need to have the attnotnull
+ * flag set.
+ */
+List *
+AddRelationNotNullConstraints(Relation rel, List *constraints,
+ List *old_notnulls)
+{
+ List *givennames;
+ List *nnnames;
+ List *nncols = NIL;
+
+ /*
+ * We track two lists of names: nnnames keeps all the constraint names,
+ * givennames tracks user-generated names. The distinction is important,
+ * because we must raise error for user-generated name conflicts, but for
+ * system-generated name conflicts we just generate another.
+ */
+ nnnames = NIL;
+ givennames = NIL;
+
+ /*
+ * First, create all not-null constraints that are directly specified by
+ * the user. Note that inheritance might have given us another source for
+ * each, so we must scan the old_notnulls list and increment inhcount for
+ * each element with identical attnum. We delete from there any element
+ * that we process.
+ *
+ * We don't use foreach() here because we have two nested loops over the
+ * constraint list, with possible element deletions in the inner one. If
+ * we used foreach_delete_current() it could only fix up the state of one
+ * of the loops, so it seems cleaner to use looping over list indexes for
+ * both loops. Note that any deletion will happen beyond where the outer
+ * loop is, so its index never needs adjustment.
+ */
+ for (int outerpos = 0; outerpos < list_length(constraints); outerpos++)
+ {
+ Constraint *constr;
+ AttrNumber attnum;
+ char *conname;
+ int inhcount = 0;
+
+ constr = list_nth_node(Constraint, constraints, outerpos);
+
+ Assert(constr->contype == CONSTR_NOTNULL);
+
+ attnum = get_attnum(RelationGetRelid(rel),
+ strVal(linitial(constr->keys)));
+ if (attnum == InvalidAttrNumber)
+ ereport(ERROR,
+ errcode(ERRCODE_UNDEFINED_COLUMN),
+ errmsg("column \"%s\" of relation \"%s\" does not exist",
+ strVal(linitial(constr->keys)),
+ RelationGetRelationName(rel)));
+ if (attnum < InvalidAttrNumber)
+ ereport(ERROR,
+ errcode(ERRCODE_FEATURE_NOT_SUPPORTED),
+ errmsg("cannot add not-null constraint on system column \"%s\"",
+ strVal(linitial(constr->keys))));
+
+ /*
+ * A column can only have one not-null constraint, so discard any
+ * additional ones that appear for columns we already saw; but check
+ * that the NO INHERIT flags match.
+ */
+ for (int restpos = outerpos + 1; restpos < list_length(constraints);)
+ {
+ Constraint *other;
+
+ other = list_nth_node(Constraint, constraints, restpos);
+ if (strcmp(strVal(linitial(constr->keys)),
+ strVal(linitial(other->keys))) == 0)
+ {
+ if (other->is_no_inherit != constr->is_no_inherit)
+ ereport(ERROR,
+ errcode(ERRCODE_SYNTAX_ERROR),
+ errmsg("conflicting NO INHERIT declaration for not-null constraint on column \"%s\"",
+ strVal(linitial(constr->keys))));
+
+ /*
+ * Preserve constraint name if one is specified, but raise an
+ * error if conflicting ones are specified.
+ */
+ if (other->conname)
+ {
+ if (!constr->conname)
+ constr->conname = pstrdup(other->conname);
+ else if (strcmp(constr->conname, other->conname) != 0)
+ ereport(ERROR,
+ errcode(ERRCODE_SYNTAX_ERROR),
+ errmsg("conflicting not-null constraint names \"%s\" and \"%s\"",
+ constr->conname, other->conname));
+ }
+
+ /* XXX do we need to verify any other fields? */
+ constraints = list_delete_nth_cell(constraints, restpos);
+ }
+ else
+ restpos++;
+ }
+
+ /*
+ * Search in the list of inherited constraints for any entries on the
+ * same column; determine an inheritance count from that. Also, if at
+ * least one parent has a constraint for this column, then we must not
+ * accept a user specification for a NO INHERIT one. Any constraint
+ * from parents that we process here is deleted from the list: we no
+ * longer need to process it in the loop below.
+ */
+ foreach_ptr(CookedConstraint, old, old_notnulls)
+ {
+ if (old->attnum == attnum)
+ {
+ /*
+ * If we get a constraint from the parent, having a local NO
+ * INHERIT one doesn't work.
+ */
+ if (constr->is_no_inherit)
+ ereport(ERROR,
+ (errcode(ERRCODE_DATATYPE_MISMATCH),
+ errmsg("cannot define not-null constraint with NO INHERIT on column \"%s\"",
+ strVal(linitial(constr->keys))),
+ errdetail("The column has an inherited not-null constraint.")));
+
+ inhcount++;
+ old_notnulls = foreach_delete_current(old_notnulls, old);
+ }
+ }
+
+ /*
+ * Determine a constraint name, which may have been specified by the
+ * user, or raise an error if a conflict exists with another
+ * user-specified name.
+ */
+ if (constr->conname)
+ {
+ foreach_ptr(char, thisname, givennames)
+ {
+ if (strcmp(thisname, constr->conname) == 0)
+ ereport(ERROR,
+ errcode(ERRCODE_DUPLICATE_OBJECT),
+ errmsg("constraint \"%s\" for relation \"%s\" already exists",
+ constr->conname,
+ RelationGetRelationName(rel)));
+ }
+
+ conname = constr->conname;
+ givennames = lappend(givennames, conname);
+ }
+ else
+ conname = ChooseConstraintName(RelationGetRelationName(rel),
+ get_attname(RelationGetRelid(rel),
+ attnum, false),
+ "not_null",
+ RelationGetNamespace(rel),
+ nnnames);
+ nnnames = lappend(nnnames, conname);
+
+ StoreRelNotNull(rel, conname,
+ attnum, true, true,
+ inhcount, constr->is_no_inherit);
+
+ nncols = lappend_int(nncols, attnum);
+ }
+
+ /*
+ * If any column remains in the old_notnulls list, we must create a not-
+ * null constraint marked not-local for that column. Because multiple
+ * parents could specify a not-null constraint for the same column, we
+ * must count how many there are and set an appropriate inhcount
+ * accordingly, deleting elements we've already processed.
+ *
+ * We don't use foreach() here because we have two nested loops over the
+ * constraint list, with possible element deletions in the inner one. If
+ * we used foreach_delete_current() it could only fix up the state of one
+ * of the loops, so it seems cleaner to use looping over list indexes for
+ * both loops. Note that any deletion will happen beyond where the outer
+ * loop is, so its index never needs adjustment.
+ */
+ for (int outerpos = 0; outerpos < list_length(old_notnulls); outerpos++)
+ {
+ CookedConstraint *cooked;
+ char *conname = NULL;
+ int inhcount = 1;
+
+ cooked = (CookedConstraint *) list_nth(old_notnulls, outerpos);
+ Assert(cooked->contype == CONSTR_NOTNULL);
+ Assert(cooked->name);
+
+ /*
+ * Preserve the first non-conflicting constraint name we come across.
+ */
+ if (conname == NULL)
+ conname = cooked->name;
+
+ for (int restpos = outerpos + 1; restpos < list_length(old_notnulls);)
+ {
+ CookedConstraint *other;
+
+ other = (CookedConstraint *) list_nth(old_notnulls, restpos);
+ Assert(other->name);
+ if (other->attnum == cooked->attnum)
+ {
+ if (conname == NULL)
+ conname = other->name;
+
+ inhcount++;
+ old_notnulls = list_delete_nth_cell(old_notnulls, restpos);
+ }
+ else
+ restpos++;
+ }
+
+ /* If we got a name, make sure it isn't one we've already used */
+ if (conname != NULL)
+ {
+ foreach_ptr(char, thisname, nnnames)
+ {
+ if (strcmp(thisname, conname) == 0)
+ {
+ conname = NULL;
+ break;
+ }
+ }
+ }
+
+ /* and choose a name, if needed */
+ if (conname == NULL)
+ conname = ChooseConstraintName(RelationGetRelationName(rel),
+ get_attname(RelationGetRelid(rel),
+ cooked->attnum, false),
+ "not_null",
+ RelationGetNamespace(rel),
+ nnnames);
+ nnnames = lappend(nnnames, conname);
+
+ /* ignore the origin constraint's is_local and inhcount */
+ StoreRelNotNull(rel, conname, cooked->attnum, true,
+ false, inhcount, false);
+
+ nncols = lappend_int(nncols, cooked->attnum);
+ }
+
+ return nncols;
+}
+
/*
* Update the count of constraints in the relation's pg_class tuple.
*
@@ -2722,7 +3215,7 @@ check_nested_generated_walker(Node *node, void *context)
}
else
return expression_tree_walker(node, check_nested_generated_walker,
- (void *) context);
+ context);
}
static void
@@ -2731,6 +3224,86 @@ check_nested_generated(ParseState *pstate, Node *node)
check_nested_generated_walker(node, pstate);
}
+/*
+ * Check security of virtual generated column expression.
+ *
+ * Just like selecting from a view is exploitable (CVE-2024-7348), selecting
+ * from a table with virtual generated columns is exploitable. Users who are
+ * concerned about this can avoid selecting from views, but telling them to
+ * avoid selecting from tables is less practical.
+ *
+ * To address this, this restricts generation expressions for virtual
+ * generated columns are restricted to using built-in functions and types. We
+ * assume that built-in functions and types cannot be exploited for this
+ * purpose. Note the overall security also requires that all functions in use
+ * a immutable. (For example, there are some built-in non-immutable functions
+ * that can run arbitrary SQL.) The immutability is checked elsewhere, since
+ * that is a property that needs to hold independent of security
+ * considerations.
+ *
+ * In the future, this could be expanded by some new mechanism to declare
+ * other functions and types as safe or trusted for this purpose, but that is
+ * to be designed.
+ */
+
+/*
+ * Callback for check_functions_in_node() that determines whether a function
+ * is user-defined.
+ */
+static bool
+contains_user_functions_checker(Oid func_id, void *context)
+{
+ return (func_id >= FirstUnpinnedObjectId);
+}
+
+/*
+ * Checks for all the things we don't want in the generation expressions of
+ * virtual generated columns for security reasons. Errors out if it finds
+ * one.
+ */
+static bool
+check_virtual_generated_security_walker(Node *node, void *context)
+{
+ ParseState *pstate = context;
+
+ if (node == NULL)
+ return false;
+
+ if (!IsA(node, List))
+ {
+ if (check_functions_in_node(node, contains_user_functions_checker, NULL))
+ ereport(ERROR,
+ errcode(ERRCODE_FEATURE_NOT_SUPPORTED),
+ errmsg("generation expression uses user-defined function"),
+ errdetail("Virtual generated columns that make use of user-defined functions are not yet supported."),
+ parser_errposition(pstate, exprLocation(node)));
+
+ /*
+ * check_functions_in_node() doesn't check some node types (see
+ * comment there). We handle CoerceToDomain and MinMaxExpr by
+ * checking for built-in types. The other listed node types cannot
+ * call user-definable SQL-visible functions.
+ *
+ * We furthermore need this type check to handle built-in, immutable
+ * polymorphic functions such as array_eq().
+ */
+ if (exprType(node) >= FirstUnpinnedObjectId)
+ ereport(ERROR,
+ errcode(ERRCODE_FEATURE_NOT_SUPPORTED),
+ errmsg("generation expression uses user-defined type"),
+ errdetail("Virtual generated columns that make use of user-defined types are not yet supported."),
+ parser_errposition(pstate, exprLocation(node)));
+ }
+
+ return expression_tree_walker(node, check_virtual_generated_security_walker, context);
+}
+
+static void
+check_virtual_generated_security(ParseState *pstate, Node *node)
+{
+ check_virtual_generated_security_walker(node, pstate);
+}
+
/*
* Take a raw default and convert it to a cooked format ready for
* storage.
@@ -2770,6 +3343,10 @@ cookDefault(ParseState *pstate,
ereport(ERROR,
(errcode(ERRCODE_INVALID_OBJECT_DEFINITION),
errmsg("generation expression is not immutable")));
+
+ /* Check security of expressions for virtual generated column */
+ if (attgenerated == ATTRIBUTE_GENERATED_VIRTUAL)
+ check_virtual_generated_security(pstate, expr);
}
else
{
@@ -3512,6 +4089,14 @@ StorePartitionBound(Relation rel, Relation parent, PartitionBoundSpec *bound)
new_val, new_null, new_repl);
/* Also set the flag */
((Form_pg_class) GETSTRUCT(newtuple))->relispartition = true;
+
+ /*
+ * We already checked for no inheritance children, but reset
+ * relhassubclass in case it was left over.
+ */
+ if (rel->rd_rel->relkind == RELKIND_RELATION && rel->rd_rel->relhassubclass)
+ ((Form_pg_class) GETSTRUCT(newtuple))->relhassubclass = false;
+
CatalogTupleUpdate(classRel, &newtuple->t_self, newtuple);
heap_freetuple(newtuple);
table_close(classRel, RowExclusiveLock);
diff --git a/src/backend/catalog/index.c b/src/backend/catalog/index.c
index 55fdde4b242ae..c4029a4f3d310 100644
--- a/src/backend/catalog/index.c
+++ b/src/backend/catalog/index.c
@@ -3,7 +3,7 @@
* index.c
* code to create and destroy POSTGRES index relations
*
- * Portions Copyright (c) 1996-2024, PostgreSQL Global Development Group
+ * Portions Copyright (c) 1996-2025, PostgreSQL Global Development Group
* Portions Copyright (c) 1994, Regents of the University of California
*
*
@@ -63,6 +63,7 @@
#include "optimizer/optimizer.h"
#include "parser/parser.h"
#include "pgstat.h"
+#include "postmaster/autovacuum.h"
#include "rewrite/rewriteManip.h"
#include "storage/bufmgr.h"
#include "storage/lmgr.h"
@@ -320,7 +321,6 @@ ConstructTupleDescriptor(Relation heapRelation,
MemSet(to, 0, ATTRIBUTE_FIXED_PART_SIZE);
to->attnum = i + 1;
- to->attcacheoff = -1;
to->attislocal = true;
to->attcollation = (i < numkeyatts) ? collationIds[i] : InvalidOid;
@@ -477,6 +477,8 @@ ConstructTupleDescriptor(Relation heapRelation,
ReleaseSysCache(tuple);
}
+
+ populate_compact_attribute(indexTupDesc, i);
}
pfree(amroutine);
@@ -798,11 +800,11 @@ index_create(Relation heapRelation,
errmsg("user-defined indexes on system catalog tables are not supported")));
/*
- * Btree text_pattern_ops uses text_eq as the equality operator, which is
- * fine as long as the collation is deterministic; text_eq then reduces to
+ * Btree text_pattern_ops uses texteq as the equality operator, which is
+ * fine as long as the collation is deterministic; texteq then reduces to
* bitwise equality and so it is semantically compatible with the other
* operators and functions in that opclass. But with a nondeterministic
- * collation, text_eq could yield results that are incompatible with the
+ * collation, texteq could yield results that are incompatible with the
* actual behavior of the index (which is determined by the opclass's
* comparison function). We prevent such problems by refusing creation of
* an index with that opclass and a nondeterministic collation.
@@ -812,7 +814,7 @@ index_create(Relation heapRelation,
* opclasses as incompatible with nondeterminism; but for now, this small
* hack suffices.
*
- * Another solution is to use a special operator, not text_eq, as the
+ * Another solution is to use a special operator, not texteq, as the
* equality opclass member; but that is undesirable because it would
* prevent index usage in many queries that work fine today.
*/
@@ -1058,6 +1060,7 @@ index_create(Relation heapRelation,
if (OidIsValid(parentIndexRelid))
{
StoreSingleInheritance(indexRelationId, parentIndexRelid, 1);
+ LockRelationOid(parentIndexRelid, ShareUpdateExclusiveLock);
SetRelationHasSubclass(parentIndexRelid, true);
}
@@ -1393,7 +1396,8 @@ index_concurrently_create_copy(Relation heapRelation, Oid oldIndexId,
oldInfo->ii_NullsNotDistinct,
false, /* not ready for inserts */
true,
- indexRelation->rd_indam->amsummarizing);
+ indexRelation->rd_indam->amsummarizing,
+ oldInfo->ii_WithoutOverlaps);
/*
* Extract the list of column names and the column numbers for the new
@@ -1873,6 +1877,7 @@ index_concurrently_set_dead(Oid heapId, Oid indexId)
* INDEX_CONSTR_CREATE_UPDATE_INDEX: update the pg_index row
* INDEX_CONSTR_CREATE_REMOVE_OLD_DEPS: remove existing dependencies
* of index on table's columns
+ * INDEX_CONSTR_CREATE_WITHOUT_OVERLAPS: constraint uses WITHOUT OVERLAPS
* allow_system_table_mods: allow table to be a system catalog
* is_internal: index is constructed due to internal process
*/
@@ -1896,11 +1901,13 @@ index_constraint_create(Relation heapRelation,
bool mark_as_primary;
bool islocal;
bool noinherit;
- int inhcount;
+ bool is_without_overlaps;
+ int16 inhcount;
deferrable = (constr_flags & INDEX_CONSTR_CREATE_DEFERRABLE) != 0;
initdeferred = (constr_flags & INDEX_CONSTR_CREATE_INIT_DEFERRED) != 0;
mark_as_primary = (constr_flags & INDEX_CONSTR_CREATE_MARK_AS_PRIMARY) != 0;
+ is_without_overlaps = (constr_flags & INDEX_CONSTR_CREATE_WITHOUT_OVERLAPS) != 0;
/* constraint creation support doesn't work while bootstrapping */
Assert(!IsBootstrapProcessingMode());
@@ -1952,6 +1959,7 @@ index_constraint_create(Relation heapRelation,
constraintType,
deferrable,
initdeferred,
+ true, /* Is Enforced */
true,
parentConstraintId,
RelationGetRelid(heapRelation),
@@ -1977,6 +1985,7 @@ index_constraint_create(Relation heapRelation,
islocal,
inhcount,
noinherit,
+ is_without_overlaps,
is_internal);
/*
@@ -2270,9 +2279,17 @@ index_drop(Oid indexId, bool concurrent, bool concurrent_lock_mode)
*/
WaitForLockers(heaplocktag, AccessExclusiveLock, true);
+ /*
+ * Updating pg_index might involve TOAST table access, so ensure we
+ * have a valid snapshot.
+ */
+ PushActiveSnapshot(GetTransactionSnapshot());
+
/* Finish invalidation of index and mark it as dead */
index_concurrently_set_dead(heapId, indexId);
+ PopActiveSnapshot();
+
/*
* Again, commit the transaction to make the pg_index update visible
* to other sessions.
@@ -2320,6 +2337,12 @@ index_drop(Oid indexId, bool concurrent, bool concurrent_lock_mode)
RelationForgetRelation(indexId);
+ /*
+ * Updating pg_index might involve TOAST table access, so ensure we have a
+ * valid snapshot.
+ */
+ PushActiveSnapshot(GetTransactionSnapshot());
+
/*
* fix INDEX relation, and check for expressional index
*/
@@ -2337,6 +2360,8 @@ index_drop(Oid indexId, bool concurrent, bool concurrent_lock_mode)
ReleaseSysCache(tuple);
table_close(indexRelation, RowExclusiveLock);
+ PopActiveSnapshot();
+
/*
* if it has any expression columns, we might have stored statistics about
* them.
@@ -2426,7 +2451,8 @@ BuildIndexInfo(Relation index)
indexStruct->indnullsnotdistinct,
indexStruct->indisready,
false,
- index->rd_indam->amsummarizing);
+ index->rd_indam->amsummarizing,
+ indexStruct->indisexclusion && indexStruct->indisunique);
/* fill in attribute numbers */
for (i = 0; i < numAtts; i++)
@@ -2485,7 +2511,8 @@ BuildDummyIndexInfo(Relation index)
indexStruct->indnullsnotdistinct,
indexStruct->indisready,
false,
- index->rd_indam->amsummarizing);
+ index->rd_indam->amsummarizing,
+ indexStruct->indisexclusion && indexStruct->indisunique);
/* fill in attribute numbers */
for (i = 0; i < numAtts; i++)
@@ -2630,8 +2657,9 @@ CompareIndexInfo(const IndexInfo *info1, const IndexInfo *info2,
* Add extra state to IndexInfo record
*
* For unique indexes, we usually don't want to add info to the IndexInfo for
- * checking uniqueness, since the B-Tree AM handles that directly. However,
- * in the case of speculative insertion, additional support is required.
+ * checking uniqueness, since the B-Tree AM handles that directly. However, in
+ * the case of speculative insertion and conflict detection in logical
+ * replication, additional support is required.
*
* Do this processing here rather than in BuildIndexInfo() to not incur the
* overhead in the common non-speculative cases.
@@ -2650,9 +2678,6 @@ BuildSpeculativeIndexInfo(Relation index, IndexInfo *ii)
*/
Assert(ii->ii_Unique);
- if (index->rd_rel->relam != BTREE_AM_OID)
- elog(ERROR, "unexpected non-btree speculative unique index");
-
ii->ii_UniqueOps = (Oid *) palloc(sizeof(Oid) * indnkeyatts);
ii->ii_UniqueProcs = (Oid *) palloc(sizeof(Oid) * indnkeyatts);
ii->ii_UniqueStrats = (uint16 *) palloc(sizeof(uint16) * indnkeyatts);
@@ -2664,7 +2689,11 @@ BuildSpeculativeIndexInfo(Relation index, IndexInfo *ii)
/* We need the func OIDs and strategy numbers too */
for (i = 0; i < indnkeyatts; i++)
{
- ii->ii_UniqueStrats[i] = BTEqualStrategyNumber;
+ ii->ii_UniqueStrats[i] =
+ IndexAmTranslateCompareType(COMPARE_EQ,
+ index->rd_rel->relam,
+ index->rd_opfamily[i],
+ false);
ii->ii_UniqueOps[i] =
get_opfamily_member(index->rd_opfamily[i],
index->rd_opcintype[i],
@@ -2765,8 +2794,8 @@ FormIndexDatum(IndexInfo *indexInfo,
* hasindex: set relhasindex to this value
* reltuples: if >= 0, set reltuples to this value; else no change
*
- * If reltuples >= 0, relpages and relallvisible are also updated (using
- * RelationGetNumberOfBlocks() and visibilitymap_count()).
+ * If reltuples >= 0, relpages, relallvisible, and relallfrozen are also
+ * updated (using RelationGetNumberOfBlocks() and visibilitymap_count()).
*
* NOTE: an important side-effect of this operation is that an SI invalidation
* message is sent out to all backends --- including me --- causing relcache
@@ -2781,12 +2810,73 @@ index_update_stats(Relation rel,
bool hasindex,
double reltuples)
{
+ bool update_stats;
+ BlockNumber relpages = 0; /* keep compiler quiet */
+ BlockNumber relallvisible = 0;
+ BlockNumber relallfrozen = 0;
Oid relid = RelationGetRelid(rel);
Relation pg_class;
+ ScanKeyData key[1];
HeapTuple tuple;
+ void *state;
Form_pg_class rd_rel;
bool dirty;
+ /*
+ * As a special hack, if we are dealing with an empty table and the
+ * existing reltuples is -1, we leave that alone. This ensures that
+ * creating an index as part of CREATE TABLE doesn't cause the table to
+ * prematurely look like it's been vacuumed. The rd_rel we modify may
+ * differ from rel->rd_rel due to e.g. commit of concurrent GRANT, but the
+ * commands that change reltuples take locks conflicting with ours. (Even
+ * if a command changed reltuples under a weaker lock, this affects only
+ * statistics for an empty table.)
+ */
+ if (reltuples == 0 && rel->rd_rel->reltuples < 0)
+ reltuples = -1;
+
+ /*
+ * Don't update statistics during binary upgrade, because the indexes are
+ * created before the data is moved into place.
+ */
+ update_stats = reltuples >= 0 && !IsBinaryUpgrade;
+
+ /*
+ * If autovacuum is off, user may not be expecting table relstats to
+ * change. This can be important when restoring a dump that includes
+ * statistics, as the table statistics may be restored before the index is
+ * created, and we want to preserve the restored table statistics.
+ */
+ if (rel->rd_rel->relkind == RELKIND_RELATION ||
+ rel->rd_rel->relkind == RELKIND_TOASTVALUE ||
+ rel->rd_rel->relkind == RELKIND_MATVIEW)
+ {
+ if (AutoVacuumingActive())
+ {
+ StdRdOptions *options = (StdRdOptions *) rel->rd_options;
+
+ if (options != NULL && !options->autovacuum.enabled)
+ update_stats = false;
+ }
+ else
+ update_stats = false;
+ }
+
+ /*
+ * Finish I/O and visibility map buffer locks before
+ * systable_inplace_update_begin() locks the pg_class buffer. The rd_rel
+ * we modify may differ from rel->rd_rel due to e.g. commit of concurrent
+ * GRANT, but no command changes a relkind from non-index to index. (Even
+ * if one did, relallvisible doesn't break functionality.)
+ */
+ if (update_stats)
+ {
+ relpages = RelationGetNumberOfBlocks(rel);
+
+ if (rel->rd_rel->relkind != RELKIND_INDEX)
+ visibilitymap_count(rel, &relallvisible, &relallfrozen);
+ }
+
/*
* We always update the pg_class row using a non-transactional,
* overwrite-in-place update. There are several reasons for this:
@@ -2817,33 +2907,12 @@ index_update_stats(Relation rel,
pg_class = table_open(RelationRelationId, RowExclusiveLock);
- /*
- * Make a copy of the tuple to update. Normally we use the syscache, but
- * we can't rely on that during bootstrap or while reindexing pg_class
- * itself.
- */
- if (IsBootstrapProcessingMode() ||
- ReindexIsProcessingHeap(RelationRelationId))
- {
- /* don't assume syscache will work */
- TableScanDesc pg_class_scan;
- ScanKeyData key[1];
-
- ScanKeyInit(&key[0],
- Anum_pg_class_oid,
- BTEqualStrategyNumber, F_OIDEQ,
- ObjectIdGetDatum(relid));
-
- pg_class_scan = table_beginscan_catalog(pg_class, 1, key);
- tuple = heap_getnext(pg_class_scan, ForwardScanDirection);
- tuple = heap_copytuple(tuple);
- table_endscan(pg_class_scan);
- }
- else
- {
- /* normal case, use syscache */
- tuple = SearchSysCacheCopy1(RELOID, ObjectIdGetDatum(relid));
- }
+ ScanKeyInit(&key[0],
+ Anum_pg_class_oid,
+ BTEqualStrategyNumber, F_OIDEQ,
+ ObjectIdGetDatum(relid));
+ systable_inplace_update_begin(pg_class, ClassOidIndexId, true, NULL,
+ 1, key, &tuple, &state);
if (!HeapTupleIsValid(tuple))
elog(ERROR, "could not find tuple for relation %u", relid);
@@ -2852,15 +2921,6 @@ index_update_stats(Relation rel,
/* Should this be a more comprehensive test? */
Assert(rd_rel->relkind != RELKIND_PARTITIONED_INDEX);
- /*
- * As a special hack, if we are dealing with an empty table and the
- * existing reltuples is -1, we leave that alone. This ensures that
- * creating an index as part of CREATE TABLE doesn't cause the table to
- * prematurely look like it's been vacuumed.
- */
- if (reltuples == 0 && rd_rel->reltuples < 0)
- reltuples = -1;
-
/* Apply required updates, if any, to copied tuple */
dirty = false;
@@ -2870,20 +2930,8 @@ index_update_stats(Relation rel,
dirty = true;
}
- /*
- * Avoid updating statistics during binary upgrade, because the indexes
- * are created before the data is moved into place.
- */
- if (reltuples >= 0 && !IsBinaryUpgrade)
+ if (update_stats)
{
- BlockNumber relpages = RelationGetNumberOfBlocks(rel);
- BlockNumber relallvisible;
-
- if (rd_rel->relkind != RELKIND_INDEX)
- visibilitymap_count(rel, &relallvisible, NULL);
- else /* don't bother for indexes */
- relallvisible = 0;
-
if (rd_rel->relpages != (int32) relpages)
{
rd_rel->relpages = (int32) relpages;
@@ -2899,6 +2947,11 @@ index_update_stats(Relation rel,
rd_rel->relallvisible = (int32) relallvisible;
dirty = true;
}
+ if (rd_rel->relallfrozen != (int32) relallfrozen)
+ {
+ rd_rel->relallfrozen = (int32) relallfrozen;
+ dirty = true;
+ }
}
/*
@@ -2906,12 +2959,20 @@ index_update_stats(Relation rel,
*/
if (dirty)
{
- heap_inplace_update(pg_class, tuple);
- /* the above sends a cache inval message */
+ systable_inplace_update_finish(state, tuple);
+ /* the above sends transactional and immediate cache inval messages */
}
else
{
- /* no need to change tuple, but force relcache inval anyway */
+ systable_inplace_update_cancel(state);
+
+ /*
+ * While we didn't change relhasindex, CREATE INDEX needs a
+ * transactional inval for when the new index's catalog rows become
+ * visible. Other CREATE INDEX and REINDEX code happens to also queue
+ * this inval, but keep this in case rare callers rely on this part of
+ * our API contract.
+ */
CacheInvalidateRelcacheByTuple(tuple);
}
@@ -2959,7 +3020,7 @@ index_build(Relation heapRelation,
/*
* Determine worker process details for parallel CREATE INDEX. Currently,
- * only btree has support for parallel builds.
+ * only btree, GIN, and BRIN have support for parallel builds.
*
* Note that planner considers parallel safety for us.
*/
@@ -3222,7 +3283,6 @@ IndexCheckExclusion(Relation heapRelation,
indexInfo->ii_PredicateState = NULL;
}
-
/*
* validate_index - support code for concurrent index builds
*
@@ -3366,7 +3426,7 @@ validate_index(Oid heapId, Oid indexId, Snapshot snapshot)
/* ambulkdelete updates progress metrics */
(void) index_bulk_delete(&ivinfo, NULL,
- validate_index_callback, (void *) &state);
+ validate_index_callback, &state);
/* Execute the sort */
{
@@ -3999,6 +4059,14 @@ reindex_relation(const ReindexStmt *stmt, Oid relid, int flags,
errmsg("cannot reindex invalid index \"%s.%s\" on TOAST table, skipping",
get_namespace_name(indexNamespaceId),
get_rel_name(indexOid))));
+
+ /*
+ * Remove this invalid toast index from the reindex pending list,
+ * as it is skipped here due to the hard failure that would happen
+ * in reindex_index(), should we try to process it.
+ */
+ if (flags & REINDEX_REL_SUPPRESS_INDEX_USE)
+ RemoveReindexPending(indexOid);
continue;
}
diff --git a/src/backend/catalog/indexing.c b/src/backend/catalog/indexing.c
index d0d1abda58af3..25c4b6bdc87f0 100644
--- a/src/backend/catalog/indexing.c
+++ b/src/backend/catalog/indexing.c
@@ -4,7 +4,7 @@
* This file contains routines to support indexes defined on system
* catalogs.
*
- * Portions Copyright (c) 1996-2024, PostgreSQL Global Development Group
+ * Portions Copyright (c) 1996-2025, PostgreSQL Global Development Group
* Portions Copyright (c) 1994, Regents of the University of California
*
*
diff --git a/src/backend/catalog/information_schema.sql b/src/backend/catalog/information_schema.sql
index c4145131ce413..a7bffca93d1da 100644
--- a/src/backend/catalog/information_schema.sql
+++ b/src/backend/catalog/information_schema.sql
@@ -2,7 +2,7 @@
* SQL Information Schema
* as defined in ISO/IEC 9075-11:2023
*
- * Copyright (c) 2003-2024, PostgreSQL Global Development Group
+ * Copyright (c) 2003-2025, PostgreSQL Global Development Group
*
* src/backend/catalog/information_schema.sql
*
@@ -440,9 +440,8 @@ CREATE VIEW check_constraints AS
WHERE pg_has_role(coalesce(c.relowner, t.typowner), 'USAGE')
AND con.contype = 'c'
- UNION
- -- not-null constraints on domains
-
+ UNION ALL
+ -- not-null constraints
SELECT current_database()::information_schema.sql_identifier AS constraint_catalog,
rs.nspname::information_schema.sql_identifier AS constraint_schema,
con.conname::information_schema.sql_identifier AS constraint_name,
@@ -453,24 +452,7 @@ CREATE VIEW check_constraints AS
LEFT JOIN pg_type t ON t.oid = con.contypid
LEFT JOIN pg_attribute at ON (con.conrelid = at.attrelid AND con.conkey[1] = at.attnum)
WHERE pg_has_role(coalesce(c.relowner, t.typowner), 'USAGE'::text)
- AND con.contype = 'n'
-
- UNION
- -- not-null constraints on relations
-
- SELECT CAST(current_database() AS sql_identifier) AS constraint_catalog,
- CAST(n.nspname AS sql_identifier) AS constraint_schema,
- CAST(CAST(n.oid AS text) || '_' || CAST(r.oid AS text) || '_' || CAST(a.attnum AS text) || '_not_null' AS sql_identifier) AS constraint_name, -- XXX
- CAST(a.attname || ' IS NOT NULL' AS character_data)
- AS check_clause
- FROM pg_namespace n, pg_class r, pg_attribute a
- WHERE n.oid = r.relnamespace
- AND r.oid = a.attrelid
- AND a.attnum > 0
- AND NOT a.attisdropped
- AND a.attnotnull
- AND r.relkind IN ('r', 'p')
- AND pg_has_role(r.relowner, 'USAGE');
+ AND con.contype = 'n';
GRANT SELECT ON check_constraints TO PUBLIC;
@@ -839,6 +821,20 @@ CREATE VIEW constraint_column_usage AS
UNION ALL
+ /* not-null constraints */
+ SELECT DISTINCT nr.nspname, r.relname, r.relowner, a.attname, nc.nspname, c.conname
+ FROM pg_namespace nr, pg_class r, pg_attribute a, pg_namespace nc, pg_constraint c
+ WHERE nr.oid = r.relnamespace
+ AND r.oid = a.attrelid
+ AND r.oid = c.conrelid
+ AND a.attnum = c.conkey[1]
+ AND c.connamespace = nc.oid
+ AND c.contype = 'n'
+ AND r.relkind in ('r', 'p')
+ AND not a.attisdropped
+
+ UNION ALL
+
/* unique/primary key/foreign key constraints */
SELECT nr.nspname, r.relname, r.relowner, a.attname, nc.nspname, c.conname
FROM pg_namespace nr, pg_class r, pg_attribute a, pg_namespace nc,
@@ -1839,6 +1835,7 @@ CREATE VIEW table_constraints AS
CAST(r.relname AS sql_identifier) AS table_name,
CAST(
CASE c.contype WHEN 'c' THEN 'CHECK'
+ WHEN 'n' THEN 'CHECK'
WHEN 'f' THEN 'FOREIGN KEY'
WHEN 'p' THEN 'PRIMARY KEY'
WHEN 'u' THEN 'UNIQUE' END
@@ -1847,7 +1844,7 @@ CREATE VIEW table_constraints AS
AS is_deferrable,
CAST(CASE WHEN c.condeferred THEN 'YES' ELSE 'NO' END AS yes_or_no)
AS initially_deferred,
- CAST('YES' AS yes_or_no) AS enforced,
+ CAST(CASE WHEN c.conenforced THEN 'YES' ELSE 'NO' END AS yes_or_no) AS enforced,
CAST(CASE WHEN c.contype = 'u'
THEN CASE WHEN (SELECT NOT indnullsnotdistinct FROM pg_index WHERE indexrelid = conindid) THEN 'YES' ELSE 'NO' END
END
@@ -1863,38 +1860,6 @@ CREATE VIEW table_constraints AS
AND c.contype NOT IN ('t', 'x') -- ignore nonstandard constraints
AND r.relkind IN ('r', 'p')
AND (NOT pg_is_other_temp_schema(nr.oid))
- AND (pg_has_role(r.relowner, 'USAGE')
- -- SELECT privilege omitted, per SQL standard
- OR has_table_privilege(r.oid, 'INSERT, UPDATE, DELETE, TRUNCATE, REFERENCES, TRIGGER')
- OR has_any_column_privilege(r.oid, 'INSERT, UPDATE, REFERENCES') )
-
- UNION ALL
-
- -- not-null constraints
-
- SELECT CAST(current_database() AS sql_identifier) AS constraint_catalog,
- CAST(nr.nspname AS sql_identifier) AS constraint_schema,
- CAST(CAST(nr.oid AS text) || '_' || CAST(r.oid AS text) || '_' || CAST(a.attnum AS text) || '_not_null' AS sql_identifier) AS constraint_name, -- XXX
- CAST(current_database() AS sql_identifier) AS table_catalog,
- CAST(nr.nspname AS sql_identifier) AS table_schema,
- CAST(r.relname AS sql_identifier) AS table_name,
- CAST('CHECK' AS character_data) AS constraint_type,
- CAST('NO' AS yes_or_no) AS is_deferrable,
- CAST('NO' AS yes_or_no) AS initially_deferred,
- CAST('YES' AS yes_or_no) AS enforced,
- CAST(NULL AS yes_or_no) AS nulls_distinct
-
- FROM pg_namespace nr,
- pg_class r,
- pg_attribute a
-
- WHERE nr.oid = r.relnamespace
- AND r.oid = a.attrelid
- AND a.attnotnull
- AND a.attnum > 0
- AND NOT a.attisdropped
- AND r.relkind IN ('r', 'p')
- AND (NOT pg_is_other_temp_schema(nr.oid))
AND (pg_has_role(r.relowner, 'USAGE')
-- SELECT privilege omitted, per SQL standard
OR has_table_privilege(r.oid, 'INSERT, UPDATE, DELETE, TRUNCATE, REFERENCES, TRIGGER')
diff --git a/src/backend/catalog/meson.build b/src/backend/catalog/meson.build
index 2f3ded8a0e7c4..1958ea9238a76 100644
--- a/src/backend/catalog/meson.build
+++ b/src/backend/catalog/meson.build
@@ -1,4 +1,4 @@
-# Copyright (c) 2022-2024, PostgreSQL Global Development Group
+# Copyright (c) 2022-2025, PostgreSQL Global Development Group
backend_sources += files(
'aclchk.c',
diff --git a/src/backend/catalog/namespace.c b/src/backend/catalog/namespace.c
index a2510cf80c6fa..8bd4d6c3d4346 100644
--- a/src/backend/catalog/namespace.c
+++ b/src/backend/catalog/namespace.c
@@ -9,7 +9,7 @@
* and implementing search-path-controlled searches.
*
*
- * Portions Copyright (c) 1996-2024, PostgreSQL Global Development Group
+ * Portions Copyright (c) 1996-2025, PostgreSQL Global Development Group
* Portions Copyright (c) 1994, Regents of the University of California
*
* IDENTIFICATION
@@ -41,7 +41,6 @@
#include "catalog/pg_ts_parser.h"
#include "catalog/pg_ts_template.h"
#include "catalog/pg_type.h"
-#include "commands/dbcommands.h"
#include "common/hashfn_unstable.h"
#include "funcapi.h"
#include "mb/pg_wchar.h"
@@ -230,7 +229,7 @@ static void AccessTempTableNamespace(bool force);
static void InitTempTableNamespace(void);
static void RemoveTempRelations(Oid tempNamespaceId);
static void RemoveTempRelationsCallback(int code, Datum arg);
-static void NamespaceCallback(Datum arg, int cacheid, uint32 hashvalue);
+static void InvalidationCallback(Datum arg, int cacheid, uint32 hashvalue);
static bool MatchNamedCall(HeapTuple proctup, int nargs, List *argnames,
bool include_out_arguments, int pronargs,
int **argnumbers);
@@ -305,17 +304,32 @@ static SearchPathCacheEntry *LastSearchPathCacheEntry = NULL;
static void
spcache_init(void)
{
- Assert(SearchPathCacheContext);
-
if (SearchPathCache && searchPathCacheValid &&
SearchPathCache->members < SPCACHE_RESET_THRESHOLD)
return;
- /* make sure we don't leave dangling pointers if nsphash_create fails */
+ searchPathCacheValid = false;
+ baseSearchPathValid = false;
+
+ /*
+ * Make sure we don't leave dangling pointers if a failure happens during
+ * initialization.
+ */
SearchPathCache = NULL;
LastSearchPathCacheEntry = NULL;
- MemoryContextReset(SearchPathCacheContext);
+ if (SearchPathCacheContext == NULL)
+ {
+ /* Make the context we'll keep search path cache hashtable in */
+ SearchPathCacheContext = AllocSetContextCreate(TopMemoryContext,
+ "search_path processing cache",
+ ALLOCSET_DEFAULT_SIZES);
+ }
+ else
+ {
+ MemoryContextReset(SearchPathCacheContext);
+ }
+
/* arbitrary initial starting size of 16 elements */
SearchPathCache = nsphash_create(SearchPathCacheContext, 16, NULL);
searchPathCacheValid = true;
@@ -4742,22 +4756,31 @@ InitializeSearchPath(void)
}
else
{
- /* Make the context we'll keep search path cache hashtable in */
- SearchPathCacheContext = AllocSetContextCreate(TopMemoryContext,
- "search_path processing cache",
- ALLOCSET_DEFAULT_SIZES);
-
/*
* In normal mode, arrange for a callback on any syscache invalidation
- * of pg_namespace or pg_authid rows. (Changing a role name may affect
- * the meaning of the special string $user.)
+ * that will affect the search_path cache.
*/
+
+ /* namespace name or ACLs may have changed */
CacheRegisterSyscacheCallback(NAMESPACEOID,
- NamespaceCallback,
+ InvalidationCallback,
(Datum) 0);
+
+ /* role name may affect the meaning of "$user" */
CacheRegisterSyscacheCallback(AUTHOID,
- NamespaceCallback,
+ InvalidationCallback,
+ (Datum) 0);
+
+ /* role membership may affect ACLs */
+ CacheRegisterSyscacheCallback(AUTHMEMROLEMEM,
+ InvalidationCallback,
(Datum) 0);
+
+ /* database owner may affect ACLs */
+ CacheRegisterSyscacheCallback(DATABASEOID,
+ InvalidationCallback,
+ (Datum) 0);
+
/* Force search path to be recomputed on next use */
baseSearchPathValid = false;
searchPathCacheValid = false;
@@ -4765,11 +4788,11 @@ InitializeSearchPath(void)
}
/*
- * NamespaceCallback
+ * InvalidationCallback
* Syscache inval callback function
*/
static void
-NamespaceCallback(Datum arg, int cacheid, uint32 hashvalue)
+InvalidationCallback(Datum arg, int cacheid, uint32 hashvalue)
{
/*
* Force search path to be recomputed on next use, also invalidating the
diff --git a/src/backend/catalog/objectaccess.c b/src/backend/catalog/objectaccess.c
index 0e606ddd895f3..0853983f5e165 100644
--- a/src/backend/catalog/objectaccess.c
+++ b/src/backend/catalog/objectaccess.c
@@ -3,7 +3,7 @@
* objectaccess.c
* functions for object_access_hook on various events
*
- * Portions Copyright (c) 1996-2024, PostgreSQL Global Development Group
+ * Portions Copyright (c) 1996-2025, PostgreSQL Global Development Group
* Portions Copyright (c) 1994, Regents of the University of California
*
* -------------------------------------------------------------------------
@@ -42,7 +42,7 @@ RunObjectPostCreateHook(Oid classId, Oid objectId, int subId,
(*object_access_hook) (OAT_POST_CREATE,
classId, objectId, subId,
- (void *) &pc_arg);
+ &pc_arg);
}
/*
@@ -64,7 +64,7 @@ RunObjectDropHook(Oid classId, Oid objectId, int subId,
(*object_access_hook) (OAT_DROP,
classId, objectId, subId,
- (void *) &drop_arg);
+ &drop_arg);
}
/*
@@ -103,7 +103,7 @@ RunObjectPostAlterHook(Oid classId, Oid objectId, int subId,
(*object_access_hook) (OAT_POST_ALTER,
classId, objectId, subId,
- (void *) &pa_arg);
+ &pa_arg);
}
/*
@@ -125,7 +125,7 @@ RunNamespaceSearchHook(Oid objectId, bool ereport_on_violation)
(*object_access_hook) (OAT_NAMESPACE_SEARCH,
NamespaceRelationId, objectId, 0,
- (void *) &ns_arg);
+ &ns_arg);
return ns_arg.result;
}
@@ -168,7 +168,7 @@ RunObjectPostCreateHookStr(Oid classId, const char *objectName, int subId,
(*object_access_hook_str) (OAT_POST_CREATE,
classId, objectName, subId,
- (void *) &pc_arg);
+ &pc_arg);
}
/*
@@ -190,7 +190,7 @@ RunObjectDropHookStr(Oid classId, const char *objectName, int subId,
(*object_access_hook_str) (OAT_DROP,
classId, objectName, subId,
- (void *) &drop_arg);
+ &drop_arg);
}
/*
@@ -229,7 +229,7 @@ RunObjectPostAlterHookStr(Oid classId, const char *objectName, int subId,
(*object_access_hook_str) (OAT_POST_ALTER,
classId, objectName, subId,
- (void *) &pa_arg);
+ &pa_arg);
}
/*
@@ -251,7 +251,7 @@ RunNamespaceSearchHookStr(const char *objectName, bool ereport_on_violation)
(*object_access_hook_str) (OAT_NAMESPACE_SEARCH,
NamespaceRelationId, objectName, 0,
- (void *) &ns_arg);
+ &ns_arg);
return ns_arg.result;
}
diff --git a/src/backend/catalog/objectaddress.c b/src/backend/catalog/objectaddress.c
index 7b536ac6fdeec..91f3018fd0a8c 100644
--- a/src/backend/catalog/objectaddress.c
+++ b/src/backend/catalog/objectaddress.c
@@ -3,7 +3,7 @@
* objectaddress.c
* functions for working with ObjectAddresses
*
- * Portions Copyright (c) 1996-2024, PostgreSQL Global Development Group
+ * Portions Copyright (c) 1996-2025, PostgreSQL Global Development Group
* Portions Copyright (c) 1994, Regents of the University of California
*
*
@@ -62,7 +62,6 @@
#include "catalog/pg_ts_template.h"
#include "catalog/pg_type.h"
#include "catalog/pg_user_mapping.h"
-#include "commands/dbcommands.h"
#include "commands/defrem.h"
#include "commands/event_trigger.h"
#include "commands/extension.h"
@@ -896,7 +895,8 @@ static void getRelationIdentity(StringInfo buffer, Oid relid, List **object,
*
* If the object is a relation or a child object of a relation (e.g. an
* attribute or constraint), the relation is also opened and *relp receives
- * the open relcache entry pointer; otherwise, *relp is set to NULL. This
+ * the open relcache entry pointer; otherwise, *relp is set to NULL.
+ * (relp can be NULL if the caller never passes a relation-related object.) This
* is a bit grotty but it makes life simpler, since the caller will
* typically need the relcache entry too. Caller must close the relcache
* entry when done with it. The relation is locked with the specified lockmode
@@ -1204,8 +1204,12 @@ get_object_address(ObjectType objtype, Node *object,
old_address = address;
}
+ /* relp must be given if it's a relation */
+ Assert(!relation || relp);
+
/* Return the object address and the relation. */
- *relp = relation;
+ if (relp)
+ *relp = relation;
return address;
}
@@ -2000,16 +2004,20 @@ get_object_address_defacl(List *object, bool missing_ok)
case DEFACLOBJ_NAMESPACE:
objtype_str = "schemas";
break;
+ case DEFACLOBJ_LARGEOBJECT:
+ objtype_str = "large objects";
+ break;
default:
ereport(ERROR,
(errcode(ERRCODE_INVALID_PARAMETER_VALUE),
errmsg("unrecognized default ACL object type \"%c\"", objtype),
- errhint("Valid object types are \"%c\", \"%c\", \"%c\", \"%c\", \"%c\".",
+ errhint("Valid object types are \"%c\", \"%c\", \"%c\", \"%c\", \"%c\", \"%c\".",
DEFACLOBJ_RELATION,
DEFACLOBJ_SEQUENCE,
DEFACLOBJ_FUNCTION,
DEFACLOBJ_TYPE,
- DEFACLOBJ_NAMESPACE)));
+ DEFACLOBJ_NAMESPACE,
+ DEFACLOBJ_LARGEOBJECT)));
}
/*
@@ -2779,6 +2787,22 @@ get_object_property_data(Oid class_id)
*/
HeapTuple
get_catalog_object_by_oid(Relation catalog, AttrNumber oidcol, Oid objectId)
+{
+ return
+ get_catalog_object_by_oid_extended(catalog, oidcol, objectId, false);
+}
+
+/*
+ * Same as get_catalog_object_by_oid(), but with an additional "locktup"
+ * argument controlling whether to acquire a LOCKTAG_TUPLE at mode
+ * InplaceUpdateTupleLock. See README.tuplock section "Locking to write
+ * inplace-updated tables".
+ */
+HeapTuple
+get_catalog_object_by_oid_extended(Relation catalog,
+ AttrNumber oidcol,
+ Oid objectId,
+ bool locktup)
{
HeapTuple tuple;
Oid classId = RelationGetRelid(catalog);
@@ -2786,7 +2810,12 @@ get_catalog_object_by_oid(Relation catalog, AttrNumber oidcol, Oid objectId)
if (oidCacheId > 0)
{
- tuple = SearchSysCacheCopy1(oidCacheId, ObjectIdGetDatum(objectId));
+ if (locktup)
+ tuple = SearchSysCacheLockedCopy1(oidCacheId,
+ ObjectIdGetDatum(objectId));
+ else
+ tuple = SearchSysCacheCopy1(oidCacheId,
+ ObjectIdGetDatum(objectId));
if (!HeapTupleIsValid(tuple)) /* should not happen */
return NULL;
}
@@ -2811,6 +2840,10 @@ get_catalog_object_by_oid(Relation catalog, AttrNumber oidcol, Oid objectId)
systable_endscan(scan);
return NULL;
}
+
+ if (locktup)
+ LockTuple(catalog, &tuple->t_self, InplaceUpdateTupleLock);
+
tuple = heap_copytuple(tuple);
systable_endscan(scan);
@@ -3230,6 +3263,12 @@ getObjectDescription(const ObjectAddress *object, bool missing_ok)
initStringInfo(&opfam);
getOpFamilyDescription(&opfam, amopForm->amopfamily, false);
+ /*
+ * We use FORMAT_TYPE_ALLOW_INVALID here so as not to fail
+ * completely if the type links are dangling, which is a form
+ * of catalog corruption that could occur due to old bugs.
+ */
+
/*------
translator: %d is the operator strategy (a number), the
first two %s's are data type names, the third %s is the
@@ -3237,8 +3276,10 @@ getObjectDescription(const ObjectAddress *object, bool missing_ok)
textual form of the operator with arguments. */
appendStringInfo(&buffer, _("operator %d (%s, %s) of %s: %s"),
amopForm->amopstrategy,
- format_type_be(amopForm->amoplefttype),
- format_type_be(amopForm->amoprighttype),
+ format_type_extended(amopForm->amoplefttype,
+ -1, FORMAT_TYPE_ALLOW_INVALID),
+ format_type_extended(amopForm->amoprighttype,
+ -1, FORMAT_TYPE_ALLOW_INVALID),
opfam.data,
format_operator(amopForm->amopopr));
@@ -3287,6 +3328,12 @@ getObjectDescription(const ObjectAddress *object, bool missing_ok)
initStringInfo(&opfam);
getOpFamilyDescription(&opfam, amprocForm->amprocfamily, false);
+ /*
+ * We use FORMAT_TYPE_ALLOW_INVALID here so as not to fail
+ * completely if the type links are dangling, which is a form
+ * of catalog corruption that could occur due to old bugs.
+ */
+
/*------
translator: %d is the function number, the first two %s's
are data type names, the third %s is the description of the
@@ -3294,8 +3341,10 @@ getObjectDescription(const ObjectAddress *object, bool missing_ok)
function with arguments. */
appendStringInfo(&buffer, _("function %d (%s, %s) of %s: %s"),
amprocForm->amprocnum,
- format_type_be(amprocForm->amproclefttype),
- format_type_be(amprocForm->amprocrighttype),
+ format_type_extended(amprocForm->amproclefttype,
+ -1, FORMAT_TYPE_ALLOW_INVALID),
+ format_type_extended(amprocForm->amprocrighttype,
+ -1, FORMAT_TYPE_ALLOW_INVALID),
opfam.data,
format_procedure(amprocForm->amproc));
@@ -3798,6 +3847,12 @@ getObjectDescription(const ObjectAddress *object, bool missing_ok)
_("default privileges on new schemas belonging to role %s"),
rolename);
break;
+ case DEFACLOBJ_LARGEOBJECT:
+ Assert(!nspname);
+ appendStringInfo(&buffer,
+ _("default privileges on new large objects belonging to role %s"),
+ rolename);
+ break;
default:
/* shouldn't get here */
if (nspname)
@@ -4227,8 +4282,8 @@ pg_identify_object(PG_FUNCTION_ARGS)
nspAttnum = get_object_attnum_namespace(address.classId);
if (nspAttnum != InvalidAttrNumber)
{
- schema_oid = heap_getattr(objtup, nspAttnum,
- RelationGetDescr(catalog), &isnull);
+ schema_oid = DatumGetObjectId(heap_getattr(objtup, nspAttnum,
+ RelationGetDescr(catalog), &isnull));
if (isnull)
elog(ERROR, "invalid null namespace in object %u/%u/%d",
address.classId, address.objectId, address.objectSubId);
@@ -4362,6 +4417,75 @@ pg_identify_object_as_address(PG_FUNCTION_ARGS)
PG_RETURN_DATUM(HeapTupleGetDatum(htup));
}
+/*
+ * SQL-level callable function to obtain the ACL of a specified object, given
+ * its catalog OID, object OID and sub-object ID.
+ */
+Datum
+pg_get_acl(PG_FUNCTION_ARGS)
+{
+ Oid classId = PG_GETARG_OID(0);
+ Oid objectId = PG_GETARG_OID(1);
+ int32 objsubid = PG_GETARG_INT32(2);
+ Oid catalogId;
+ AttrNumber Anum_acl;
+ Datum datum;
+ bool isnull;
+ HeapTuple tup;
+
+ /* for "pinned" items in pg_depend, return null */
+ if (!OidIsValid(classId) && !OidIsValid(objectId))
+ PG_RETURN_NULL();
+
+ /* for large objects, the catalog to look at is pg_largeobject_metadata */
+ catalogId = (classId == LargeObjectRelationId) ?
+ LargeObjectMetadataRelationId : classId;
+ Anum_acl = get_object_attnum_acl(catalogId);
+
+ /* return NULL if no ACL field for this catalog */
+ if (Anum_acl == InvalidAttrNumber)
+ PG_RETURN_NULL();
+
+ /*
+ * If dealing with a relation's attribute (objsubid is set), the ACL is
+ * retrieved from pg_attribute.
+ */
+ if (classId == RelationRelationId && objsubid != 0)
+ {
+ AttrNumber attnum = (AttrNumber) objsubid;
+
+ tup = SearchSysCacheCopyAttNum(objectId, attnum);
+
+ if (!HeapTupleIsValid(tup))
+ PG_RETURN_NULL();
+
+ datum = SysCacheGetAttr(ATTNUM, tup, Anum_pg_attribute_attacl,
+ &isnull);
+ }
+ else
+ {
+ Relation rel;
+
+ rel = table_open(catalogId, AccessShareLock);
+
+ tup = get_catalog_object_by_oid(rel, get_object_attnum_oid(catalogId),
+ objectId);
+ if (!HeapTupleIsValid(tup))
+ {
+ table_close(rel, AccessShareLock);
+ PG_RETURN_NULL();
+ }
+
+ datum = heap_getattr(tup, Anum_acl, RelationGetDescr(rel), &isnull);
+ table_close(rel, AccessShareLock);
+ }
+
+ if (isnull)
+ PG_RETURN_NULL();
+
+ PG_RETURN_DATUM(datum);
+}
+
/*
* Return a palloc'ed string that describes the type of object that the
* passed address is for.
@@ -5651,6 +5775,10 @@ getObjectIdentityParts(const ObjectAddress *object,
appendStringInfoString(&buffer,
" on schemas");
break;
+ case DEFACLOBJ_LARGEOBJECT:
+ appendStringInfoString(&buffer,
+ " on large objects");
+ break;
}
if (objname)
diff --git a/src/backend/catalog/partition.c b/src/backend/catalog/partition.c
index 018aad445d174..93d72157a46ae 100644
--- a/src/backend/catalog/partition.c
+++ b/src/backend/catalog/partition.c
@@ -3,7 +3,7 @@
* partition.c
* Partitioning related data structures and functions.
*
- * Portions Copyright (c) 1996-2024, PostgreSQL Global Development Group
+ * Portions Copyright (c) 1996-2025, PostgreSQL Global Development Group
* Portions Copyright (c) 1994, Regents of the University of California
*
*
diff --git a/src/backend/catalog/pg_aggregate.c b/src/backend/catalog/pg_aggregate.c
index 90fc7db949f5c..c62e8acd41375 100644
--- a/src/backend/catalog/pg_aggregate.c
+++ b/src/backend/catalog/pg_aggregate.c
@@ -3,7 +3,7 @@
* pg_aggregate.c
* routines to support manipulation of the pg_aggregate relation
*
- * Portions Copyright (c) 1996-2024, PostgreSQL Global Development Group
+ * Portions Copyright (c) 1996-2025, PostgreSQL Global Development Group
* Portions Copyright (c) 1994, Regents of the University of California
*
*
@@ -637,6 +637,7 @@ AggregateCreate(const char *aggName,
parameterNames, /* parameterNames */
parameterDefaults, /* parameterDefaults */
PointerGetDatum(NULL), /* trftypes */
+ NIL, /* trfoids */
PointerGetDatum(NULL), /* proconfig */
InvalidOid, /* no prosupport */
1, /* procost */
@@ -653,7 +654,7 @@ AggregateCreate(const char *aggName,
for (i = 0; i < Natts_pg_aggregate; i++)
{
nulls[i] = false;
- values[i] = (Datum) NULL;
+ values[i] = (Datum) 0;
replaces[i] = true;
}
values[Anum_pg_aggregate_aggfnoid - 1] = ObjectIdGetDatum(procOid);
diff --git a/src/backend/catalog/pg_attrdef.c b/src/backend/catalog/pg_attrdef.c
index 003ae70b4d255..1b6270b121324 100644
--- a/src/backend/catalog/pg_attrdef.c
+++ b/src/backend/catalog/pg_attrdef.c
@@ -3,7 +3,7 @@
* pg_attrdef.c
* routines to support manipulation of the pg_attrdef relation
*
- * Portions Copyright (c) 1996-2024, PostgreSQL Global Development Group
+ * Portions Copyright (c) 1996-2025, PostgreSQL Global Development Group
* Portions Copyright (c) 1994, Regents of the University of California
*
*
@@ -14,17 +14,12 @@
*/
#include "postgres.h"
-#include "access/genam.h"
#include "access/relation.h"
#include "access/table.h"
-#include "catalog/catalog.h"
#include "catalog/dependency.h"
#include "catalog/indexing.h"
#include "catalog/objectaccess.h"
#include "catalog/pg_attrdef.h"
-#include "executor/executor.h"
-#include "optimizer/optimizer.h"
-#include "utils/array.h"
#include "utils/builtins.h"
#include "utils/fmgroids.h"
#include "utils/rel.h"
@@ -35,25 +30,22 @@
* Store a default expression for column attnum of relation rel.
*
* Returns the OID of the new pg_attrdef tuple.
- *
- * add_column_mode must be true if we are storing the default for a new
- * attribute, and false if it's for an already existing attribute. The reason
- * for this is that the missing value must never be updated after it is set,
- * which can only be when a column is added to the table. Otherwise we would
- * in effect be changing existing tuples.
*/
Oid
StoreAttrDefault(Relation rel, AttrNumber attnum,
- Node *expr, bool is_internal, bool add_column_mode)
+ Node *expr, bool is_internal)
{
char *adbin;
Relation adrel;
HeapTuple tuple;
- Datum values[4];
- static bool nulls[4] = {false, false, false, false};
+ Datum values[Natts_pg_attrdef];
+ static bool nulls[Natts_pg_attrdef] = {false, false, false, false};
Relation attrrel;
HeapTuple atttup;
Form_pg_attribute attStruct;
+ Datum valuesAtt[Natts_pg_attribute] = {0};
+ bool nullsAtt[Natts_pg_attribute] = {0};
+ bool replacesAtt[Natts_pg_attribute] = {0};
char attgenerated;
Oid attrdefOid;
ObjectAddress colobject,
@@ -72,8 +64,8 @@ StoreAttrDefault(Relation rel, AttrNumber attnum,
attrdefOid = GetNewOidWithIndex(adrel, AttrDefaultOidIndexId,
Anum_pg_attrdef_oid);
values[Anum_pg_attrdef_oid - 1] = ObjectIdGetDatum(attrdefOid);
- values[Anum_pg_attrdef_adrelid - 1] = RelationGetRelid(rel);
- values[Anum_pg_attrdef_adnum - 1] = attnum;
+ values[Anum_pg_attrdef_adrelid - 1] = ObjectIdGetDatum(RelationGetRelid(rel));
+ values[Anum_pg_attrdef_adnum - 1] = Int16GetDatum(attnum);
values[Anum_pg_attrdef_adbin - 1] = CStringGetTextDatum(adbin);
tuple = heap_form_tuple(adrel->rd_att, values, nulls);
@@ -103,68 +95,15 @@ StoreAttrDefault(Relation rel, AttrNumber attnum,
attnum, RelationGetRelid(rel));
attStruct = (Form_pg_attribute) GETSTRUCT(atttup);
attgenerated = attStruct->attgenerated;
- if (!attStruct->atthasdef)
- {
- Form_pg_attribute defAttStruct;
-
- ExprState *exprState;
- Expr *expr2 = (Expr *) expr;
- EState *estate = NULL;
- ExprContext *econtext;
- Datum valuesAtt[Natts_pg_attribute] = {0};
- bool nullsAtt[Natts_pg_attribute] = {0};
- bool replacesAtt[Natts_pg_attribute] = {0};
- Datum missingval = (Datum) 0;
- bool missingIsNull = true;
-
- valuesAtt[Anum_pg_attribute_atthasdef - 1] = true;
- replacesAtt[Anum_pg_attribute_atthasdef - 1] = true;
-
- if (rel->rd_rel->relkind == RELKIND_RELATION && add_column_mode &&
- !attgenerated)
- {
- expr2 = expression_planner(expr2);
- estate = CreateExecutorState();
- exprState = ExecPrepareExpr(expr2, estate);
- econtext = GetPerTupleExprContext(estate);
-
- missingval = ExecEvalExpr(exprState, econtext,
- &missingIsNull);
-
- FreeExecutorState(estate);
-
- defAttStruct = TupleDescAttr(rel->rd_att, attnum - 1);
-
- if (missingIsNull)
- {
- /* if the default evaluates to NULL, just store a NULL array */
- missingval = (Datum) 0;
- }
- else
- {
- /* otherwise make a one-element array of the value */
- missingval = PointerGetDatum(construct_array(&missingval,
- 1,
- defAttStruct->atttypid,
- defAttStruct->attlen,
- defAttStruct->attbyval,
- defAttStruct->attalign));
- }
-
- valuesAtt[Anum_pg_attribute_atthasmissing - 1] = !missingIsNull;
- replacesAtt[Anum_pg_attribute_atthasmissing - 1] = true;
- valuesAtt[Anum_pg_attribute_attmissingval - 1] = missingval;
- replacesAtt[Anum_pg_attribute_attmissingval - 1] = true;
- nullsAtt[Anum_pg_attribute_attmissingval - 1] = missingIsNull;
- }
- atttup = heap_modify_tuple(atttup, RelationGetDescr(attrrel),
- valuesAtt, nullsAtt, replacesAtt);
-
- CatalogTupleUpdate(attrrel, &atttup->t_self, atttup);
-
- if (!missingIsNull)
- pfree(DatumGetPointer(missingval));
- }
+
+ valuesAtt[Anum_pg_attribute_atthasdef - 1] = BoolGetDatum(true);
+ replacesAtt[Anum_pg_attribute_atthasdef - 1] = true;
+
+ atttup = heap_modify_tuple(atttup, RelationGetDescr(attrrel),
+ valuesAtt, nullsAtt, replacesAtt);
+
+ CatalogTupleUpdate(attrrel, &atttup->t_self, atttup);
+
table_close(attrrel, RowExclusiveLock);
heap_freetuple(atttup);
diff --git a/src/backend/catalog/pg_cast.c b/src/backend/catalog/pg_cast.c
index 5a5b855d51415..1773c9c549160 100644
--- a/src/backend/catalog/pg_cast.c
+++ b/src/backend/catalog/pg_cast.c
@@ -3,7 +3,7 @@
* pg_cast.c
* routines to support manipulation of the pg_cast relation
*
- * Portions Copyright (c) 1996-2024, PostgreSQL Global Development Group
+ * Portions Copyright (c) 1996-2025, PostgreSQL Global Development Group
* Portions Copyright (c) 1994, Regents of the University of California
*
*
diff --git a/src/backend/catalog/pg_class.c b/src/backend/catalog/pg_class.c
index e05b0bbb2e025..18eecbdfc0648 100644
--- a/src/backend/catalog/pg_class.c
+++ b/src/backend/catalog/pg_class.c
@@ -3,7 +3,7 @@
* pg_class.c
* routines to support manipulation of the pg_class relation
*
- * Portions Copyright (c) 1996-2024, PostgreSQL Global Development Group
+ * Portions Copyright (c) 1996-2025, PostgreSQL Global Development Group
* Portions Copyright (c) 1994, Regents of the University of California
*
*
diff --git a/src/backend/catalog/pg_collation.c b/src/backend/catalog/pg_collation.c
index 7f2f7012299df..469635b35808d 100644
--- a/src/backend/catalog/pg_collation.c
+++ b/src/backend/catalog/pg_collation.c
@@ -3,7 +3,7 @@
* pg_collation.c
* routines to support manipulation of the pg_collation relation
*
- * Portions Copyright (c) 1996-2024, PostgreSQL Global Development Group
+ * Portions Copyright (c) 1996-2025, PostgreSQL Global Development Group
* Portions Copyright (c) 1994, Regents of the University of California
*
*
diff --git a/src/backend/catalog/pg_constraint.c b/src/backend/catalog/pg_constraint.c
index 3baf9231ed0c8..6002fd0002fc9 100644
--- a/src/backend/catalog/pg_constraint.c
+++ b/src/backend/catalog/pg_constraint.c
@@ -3,7 +3,7 @@
* pg_constraint.c
* routines to support manipulation of the pg_constraint relation
*
- * Portions Copyright (c) 1996-2024, PostgreSQL Global Development Group
+ * Portions Copyright (c) 1996-2025, PostgreSQL Global Development Group
* Portions Copyright (c) 1994, Regents of the University of California
*
*
@@ -15,17 +15,20 @@
#include "postgres.h"
#include "access/genam.h"
+#include "access/gist.h"
#include "access/htup_details.h"
#include "access/sysattr.h"
#include "access/table.h"
#include "catalog/catalog.h"
#include "catalog/dependency.h"
+#include "catalog/heap.h"
#include "catalog/indexing.h"
#include "catalog/objectaccess.h"
#include "catalog/pg_constraint.h"
#include "catalog/pg_operator.h"
#include "catalog/pg_type.h"
#include "commands/defrem.h"
+#include "common/int.h"
#include "utils/array.h"
#include "utils/builtins.h"
#include "utils/fmgroids.h"
@@ -50,6 +53,7 @@ CreateConstraintEntry(const char *constraintName,
char constraintType,
bool isDeferrable,
bool isDeferred,
+ bool isEnforced,
bool isValidated,
Oid parentConstrId,
Oid relId,
@@ -73,8 +77,9 @@ CreateConstraintEntry(const char *constraintName,
Node *conExpr,
const char *conBin,
bool conIsLocal,
- int conInhCount,
+ int16 conInhCount,
bool conNoInherit,
+ bool conPeriod,
bool is_internal)
{
Relation conDesc;
@@ -95,6 +100,12 @@ CreateConstraintEntry(const char *constraintName,
ObjectAddresses *addrs_auto;
ObjectAddresses *addrs_normal;
+ /* Only CHECK or FOREIGN KEY constraint can be not enforced */
+ Assert(isEnforced || constraintType == CONSTRAINT_CHECK ||
+ constraintType == CONSTRAINT_FOREIGN);
+ /* NOT ENFORCED constraint must be NOT VALID */
+ Assert(isEnforced || !isValidated);
+
conDesc = table_open(ConstraintRelationId, RowExclusiveLock);
Assert(constraintName);
@@ -118,8 +129,9 @@ CreateConstraintEntry(const char *constraintName,
if (foreignNKeys > 0)
{
Datum *fkdatums;
+ int nkeys = Max(foreignNKeys, numFkDeleteSetCols);
- fkdatums = (Datum *) palloc(foreignNKeys * sizeof(Datum));
+ fkdatums = (Datum *) palloc(nkeys * sizeof(Datum));
for (i = 0; i < foreignNKeys; i++)
fkdatums[i] = Int16GetDatum(foreignKey[i]);
confkeyArray = construct_array_builtin(fkdatums, foreignNKeys, INT2OID);
@@ -167,7 +179,7 @@ CreateConstraintEntry(const char *constraintName,
for (i = 0; i < Natts_pg_constraint; i++)
{
nulls[i] = false;
- values[i] = (Datum) NULL;
+ values[i] = (Datum) 0;
}
conOid = GetNewOidWithIndex(conDesc, ConstraintOidIndexId,
@@ -178,6 +190,7 @@ CreateConstraintEntry(const char *constraintName,
values[Anum_pg_constraint_contype - 1] = CharGetDatum(constraintType);
values[Anum_pg_constraint_condeferrable - 1] = BoolGetDatum(isDeferrable);
values[Anum_pg_constraint_condeferred - 1] = BoolGetDatum(isDeferred);
+ values[Anum_pg_constraint_conenforced - 1] = BoolGetDatum(isEnforced);
values[Anum_pg_constraint_convalidated - 1] = BoolGetDatum(isValidated);
values[Anum_pg_constraint_conrelid - 1] = ObjectIdGetDatum(relId);
values[Anum_pg_constraint_contypid - 1] = ObjectIdGetDatum(domainId);
@@ -190,6 +203,7 @@ CreateConstraintEntry(const char *constraintName,
values[Anum_pg_constraint_conislocal - 1] = BoolGetDatum(conIsLocal);
values[Anum_pg_constraint_coninhcount - 1] = Int16GetDatum(conInhCount);
values[Anum_pg_constraint_connoinherit - 1] = BoolGetDatum(conNoInherit);
+ values[Anum_pg_constraint_conperiod - 1] = BoolGetDatum(conPeriod);
if (conkeyArray)
values[Anum_pg_constraint_conkey - 1] = PointerGetDatum(conkeyArray);
@@ -481,6 +495,8 @@ ConstraintNameExists(const char *conname, Oid namespaceid)
* name1, name2, and label are used the same way as for makeObjectName(),
* except that the label can't be NULL; digits will be appended to the label
* if needed to create a name that is unique within the specified namespace.
+ * If the given label is empty, we only consider names that include at least
+ * one added digit.
*
* 'others' can be a list of string names already chosen within the current
* command (but not yet reflected into the catalogs); we will not choose
@@ -509,8 +525,11 @@ ChooseConstraintName(const char *name1, const char *name2,
conDesc = table_open(ConstraintRelationId, AccessShareLock);
- /* try the unmodified label first */
- strlcpy(modlabel, label, sizeof(modlabel));
+ /* try the unmodified label first, unless it's empty */
+ if (label[0] != '\0')
+ strlcpy(modlabel, label, sizeof(modlabel));
+ else
+ snprintf(modlabel, sizeof(modlabel), "%s%d", label, ++pass);
for (;;)
{
@@ -560,6 +579,77 @@ ChooseConstraintName(const char *name1, const char *name2,
return conname;
}
+/*
+ * Find and return a copy of the pg_constraint tuple that implements a
+ * (possibly not valid) not-null constraint for the given column of the
+ * given relation. If no such constraint exists, return NULL.
+ *
+ * XXX This would be easier if we had pg_attribute.notnullconstr with the OID
+ * of the constraint that implements the not-null constraint for that column.
+ * I'm not sure it's worth the catalog bloat and de-normalization, however.
+ */
+HeapTuple
+findNotNullConstraintAttnum(Oid relid, AttrNumber attnum)
+{
+ Relation pg_constraint;
+ HeapTuple conTup,
+ retval = NULL;
+ SysScanDesc scan;
+ ScanKeyData key;
+
+ pg_constraint = table_open(ConstraintRelationId, AccessShareLock);
+ ScanKeyInit(&key,
+ Anum_pg_constraint_conrelid,
+ BTEqualStrategyNumber, F_OIDEQ,
+ ObjectIdGetDatum(relid));
+ scan = systable_beginscan(pg_constraint, ConstraintRelidTypidNameIndexId,
+ true, NULL, 1, &key);
+
+ while (HeapTupleIsValid(conTup = systable_getnext(scan)))
+ {
+ Form_pg_constraint con = (Form_pg_constraint) GETSTRUCT(conTup);
+ AttrNumber conkey;
+
+ /*
+ * We're looking for a NOTNULL constraint with the column we're
+ * looking for as the sole element in conkey.
+ */
+ if (con->contype != CONSTRAINT_NOTNULL)
+ continue;
+
+ conkey = extractNotNullColumn(conTup);
+ if (conkey != attnum)
+ continue;
+
+ /* Found it */
+ retval = heap_copytuple(conTup);
+ break;
+ }
+
+ systable_endscan(scan);
+ table_close(pg_constraint, AccessShareLock);
+
+ return retval;
+}
+
+/*
+ * Find and return a copy of the pg_constraint tuple that implements a
+ * (possibly not valid) not-null constraint for the given column of the
+ * given relation.
+ * If no such column or no such constraint exists, return NULL.
+ */
+HeapTuple
+findNotNullConstraint(Oid relid, const char *colname)
+{
+ AttrNumber attnum;
+
+ attnum = get_attnum(relid, colname);
+ if (attnum <= InvalidAttrNumber)
+ return NULL;
+
+ return findNotNullConstraintAttnum(relid, attnum);
+}
+
/*
* Find and return the pg_constraint tuple that implements a validated
* not-null constraint for the given domain.
@@ -604,6 +694,200 @@ findDomainNotNullConstraint(Oid typid)
return retval;
}
+/*
+ * Given a pg_constraint tuple for a not-null constraint, return the column
+ * number it is for.
+ */
+AttrNumber
+extractNotNullColumn(HeapTuple constrTup)
+{
+ Datum adatum;
+ ArrayType *arr;
+
+ /* only tuples for not-null constraints should be given */
+ Assert(((Form_pg_constraint) GETSTRUCT(constrTup))->contype == CONSTRAINT_NOTNULL);
+
+ adatum = SysCacheGetAttrNotNull(CONSTROID, constrTup,
+ Anum_pg_constraint_conkey);
+ arr = DatumGetArrayTypeP(adatum); /* ensure not toasted */
+ if (ARR_NDIM(arr) != 1 ||
+ ARR_HASNULL(arr) ||
+ ARR_ELEMTYPE(arr) != INT2OID ||
+ ARR_DIMS(arr)[0] != 1)
+ elog(ERROR, "conkey is not a 1-D smallint array");
+
+ /* We leak the detoasted datum, but we don't care */
+
+ return ((AttrNumber *) ARR_DATA_PTR(arr))[0];
+}
+
+/*
+ * AdjustNotNullInheritance
+ * Adjust inheritance status for a single not-null constraint
+ *
+ * If no not-null constraint is found for the column, return false.
+ * Caller can create one.
+ *
+ * If a constraint exists but the connoinherit flag is not what the caller
+ * wants, throw an error about the incompatibility. If the desired
+ * constraint is valid but the existing constraint is not valid, also
+ * throw an error about that (the opposite case is acceptable).
+ *
+ * If everything checks out, we adjust conislocal/coninhcount and return
+ * true. If is_local is true we flip conislocal true, or do nothing if
+ * it's already true; otherwise we increment coninhcount by 1.
+ */
+bool
+AdjustNotNullInheritance(Oid relid, AttrNumber attnum,
+ bool is_local, bool is_no_inherit, bool is_notvalid)
+{
+ HeapTuple tup;
+
+ tup = findNotNullConstraintAttnum(relid, attnum);
+ if (HeapTupleIsValid(tup))
+ {
+ Relation pg_constraint;
+ Form_pg_constraint conform;
+ bool changed = false;
+
+ pg_constraint = table_open(ConstraintRelationId, RowExclusiveLock);
+ conform = (Form_pg_constraint) GETSTRUCT(tup);
+
+ /*
+ * If the NO INHERIT flag we're asked for doesn't match what the
+ * existing constraint has, throw an error.
+ */
+ if (is_no_inherit != conform->connoinherit)
+ ereport(ERROR,
+ errcode(ERRCODE_OBJECT_NOT_IN_PREREQUISITE_STATE),
+ errmsg("cannot change NO INHERIT status of NOT NULL constraint \"%s\" on relation \"%s\"",
+ NameStr(conform->conname), get_rel_name(relid)),
+ errhint("You might need to make the existing constraint inheritable using %s.",
+ "ALTER TABLE ... ALTER CONSTRAINT ... INHERIT"));
+
+ /*
+ * Throw an error if the existing constraint is NOT VALID and caller
+ * wants a valid one.
+ */
+ if (!is_notvalid && !conform->convalidated)
+ ereport(ERROR,
+ errcode(ERRCODE_OBJECT_NOT_IN_PREREQUISITE_STATE),
+ errmsg("incompatible NOT VALID constraint \"%s\" on relation \"%s\"",
+ NameStr(conform->conname), get_rel_name(relid)),
+ errhint("You might need to validate it using %s.",
+ "ALTER TABLE ... VALIDATE CONSTRAINT"));
+
+ if (!is_local)
+ {
+ if (pg_add_s16_overflow(conform->coninhcount, 1,
+ &conform->coninhcount))
+ ereport(ERROR,
+ errcode(ERRCODE_PROGRAM_LIMIT_EXCEEDED),
+ errmsg("too many inheritance parents"));
+ changed = true;
+ }
+ else if (!conform->conislocal)
+ {
+ conform->conislocal = true;
+ changed = true;
+ }
+
+ if (changed)
+ CatalogTupleUpdate(pg_constraint, &tup->t_self, tup);
+
+ table_close(pg_constraint, RowExclusiveLock);
+
+ return true;
+ }
+
+ return false;
+}
+
+/*
+ * RelationGetNotNullConstraints
+ * Return the list of not-null constraints for the given rel
+ *
+ * Caller can request cooked constraints, or raw.
+ *
+ * This is seldom needed, so we just scan pg_constraint each time.
+ *
+ * 'include_noinh' determines whether to include NO INHERIT constraints or not.
+ */
+List *
+RelationGetNotNullConstraints(Oid relid, bool cooked, bool include_noinh)
+{
+ List *notnulls = NIL;
+ Relation constrRel;
+ HeapTuple htup;
+ SysScanDesc conscan;
+ ScanKeyData skey;
+
+ constrRel = table_open(ConstraintRelationId, AccessShareLock);
+ ScanKeyInit(&skey,
+ Anum_pg_constraint_conrelid,
+ BTEqualStrategyNumber, F_OIDEQ,
+ ObjectIdGetDatum(relid));
+ conscan = systable_beginscan(constrRel, ConstraintRelidTypidNameIndexId, true,
+ NULL, 1, &skey);
+
+ while (HeapTupleIsValid(htup = systable_getnext(conscan)))
+ {
+ Form_pg_constraint conForm = (Form_pg_constraint) GETSTRUCT(htup);
+ AttrNumber colnum;
+
+ if (conForm->contype != CONSTRAINT_NOTNULL)
+ continue;
+ if (conForm->connoinherit && !include_noinh)
+ continue;
+
+ colnum = extractNotNullColumn(htup);
+
+ if (cooked)
+ {
+ CookedConstraint *cooked;
+
+ cooked = (CookedConstraint *) palloc(sizeof(CookedConstraint));
+
+ cooked->contype = CONSTR_NOTNULL;
+ cooked->conoid = conForm->oid;
+ cooked->name = pstrdup(NameStr(conForm->conname));
+ cooked->attnum = colnum;
+ cooked->expr = NULL;
+ cooked->is_enforced = true;
+ cooked->skip_validation = !conForm->convalidated;
+ cooked->is_local = true;
+ cooked->inhcount = 0;
+ cooked->is_no_inherit = conForm->connoinherit;
+
+ notnulls = lappend(notnulls, cooked);
+ }
+ else
+ {
+ Constraint *constr;
+
+ constr = makeNode(Constraint);
+ constr->contype = CONSTR_NOTNULL;
+ constr->conname = pstrdup(NameStr(conForm->conname));
+ constr->deferrable = false;
+ constr->initdeferred = false;
+ constr->location = -1;
+ constr->keys = list_make1(makeString(get_attname(relid, colnum,
+ false)));
+ constr->is_enforced = true;
+ constr->skip_validation = !conForm->convalidated;
+ constr->initially_valid = true;
+ constr->is_no_inherit = conForm->connoinherit;
+ notnulls = lappend(notnulls, constr);
+ }
+ }
+
+ systable_endscan(conscan);
+ table_close(constrRel, AccessShareLock);
+
+ return notnulls;
+}
+
+
/*
* Delete a single constraint record.
*/
@@ -846,11 +1130,12 @@ ConstraintSetParentConstraint(Oid childConstrId,
childConstrId);
constrForm->conislocal = false;
- constrForm->coninhcount++;
- if (constrForm->coninhcount < 0)
+ if (pg_add_s16_overflow(constrForm->coninhcount, 1,
+ &constrForm->coninhcount))
ereport(ERROR,
errcode(ERRCODE_PROGRAM_LIMIT_EXCEEDED),
errmsg("too many inheritance parents"));
+
constrForm->conparentid = parentConstrId;
CatalogTupleUpdate(constrRel, &tuple->t_self, newtup);
@@ -1347,6 +1632,78 @@ DeconstructFkConstraintRow(HeapTuple tuple, int *numfks,
*numfks = numkeys;
}
+/*
+ * FindFKPeriodOpers -
+ *
+ * Looks up the operator oids used for the PERIOD part of a temporal foreign key.
+ * The opclass should be the opclass of that PERIOD element.
+ * Everything else is an output: containedbyoperoid is the ContainedBy operator for
+ * types matching the PERIOD element.
+ * aggedcontainedbyoperoid is also a ContainedBy operator,
+ * but one whose rhs is a multirange.
+ * That way foreign keys can compare fkattr <@ range_agg(pkattr).
+ * intersectoperoid is used by NO ACTION constraints to trim the range being considered
+ * to just what was updated/deleted.
+ */
+void
+FindFKPeriodOpers(Oid opclass,
+ Oid *containedbyoperoid,
+ Oid *aggedcontainedbyoperoid,
+ Oid *intersectoperoid)
+{
+ Oid opfamily = InvalidOid;
+ Oid opcintype = InvalidOid;
+ StrategyNumber strat;
+
+ /* Make sure we have a range or multirange. */
+ if (get_opclass_opfamily_and_input_type(opclass, &opfamily, &opcintype))
+ {
+ if (opcintype != ANYRANGEOID && opcintype != ANYMULTIRANGEOID)
+ ereport(ERROR,
+ errcode(ERRCODE_FEATURE_NOT_SUPPORTED),
+ errmsg("invalid type for PERIOD part of foreign key"),
+ errdetail("Only range and multirange are supported."));
+
+ }
+ else
+ elog(ERROR, "cache lookup failed for opclass %u", opclass);
+
+ /*
+ * Look up the ContainedBy operator whose lhs and rhs are the opclass's
+ * type. We use this to optimize RI checks: if the new value includes all
+ * of the old value, then we can treat the attribute as if it didn't
+ * change, and skip the RI check.
+ */
+ GetOperatorFromCompareType(opclass,
+ InvalidOid,
+ COMPARE_CONTAINED_BY,
+ containedbyoperoid,
+ &strat);
+
+ /*
+ * Now look up the ContainedBy operator. Its left arg must be the type of
+ * the column (or rather of the opclass). Its right arg must match the
+ * return type of the support proc.
+ */
+ GetOperatorFromCompareType(opclass,
+ ANYMULTIRANGEOID,
+ COMPARE_CONTAINED_BY,
+ aggedcontainedbyoperoid,
+ &strat);
+
+ switch (opcintype)
+ {
+ case ANYRANGEOID:
+ *intersectoperoid = OID_RANGE_INTERSECT_RANGE_OP;
+ break;
+ case ANYMULTIRANGEOID:
+ *intersectoperoid = OID_MULTIRANGE_INTERSECT_MULTIRANGE_OP;
+ break;
+ default:
+ elog(ERROR, "unexpected opcintype: %u", opcintype);
+ }
+}
+
/*
* Determine whether a relation can be proven functionally dependent on
* a set of grouping columns. If so, return true and add the pg_constraint
diff --git a/src/backend/catalog/pg_conversion.c b/src/backend/catalog/pg_conversion.c
index 0770878eac582..090f680d1908f 100644
--- a/src/backend/catalog/pg_conversion.c
+++ b/src/backend/catalog/pg_conversion.c
@@ -3,7 +3,7 @@
* pg_conversion.c
* routines to support manipulation of the pg_conversion relation
*
- * Portions Copyright (c) 1996-2024, PostgreSQL Global Development Group
+ * Portions Copyright (c) 1996-2025, PostgreSQL Global Development Group
* Portions Copyright (c) 1994, Regents of the University of California
*
*
@@ -87,7 +87,7 @@ ConversionCreate(const char *conname, Oid connamespace,
for (i = 0; i < Natts_pg_conversion; i++)
{
nulls[i] = false;
- values[i] = (Datum) NULL;
+ values[i] = (Datum) 0;
}
/* form a tuple */
diff --git a/src/backend/catalog/pg_db_role_setting.c b/src/backend/catalog/pg_db_role_setting.c
index 8c20f519fc05e..090fc07c28acb 100644
--- a/src/backend/catalog/pg_db_role_setting.c
+++ b/src/backend/catalog/pg_db_role_setting.c
@@ -2,7 +2,7 @@
* pg_db_role_setting.c
* Routines to support manipulation of the pg_db_role_setting relation
*
- * Portions Copyright (c) 1996-2024, PostgreSQL Global Development Group
+ * Portions Copyright (c) 1996-2025, PostgreSQL Global Development Group
* Portions Copyright (c) 1994, Regents of the University of California
*
* IDENTIFICATION
diff --git a/src/backend/catalog/pg_depend.c b/src/backend/catalog/pg_depend.c
index 5366f7820c12e..c8b11f887e274 100644
--- a/src/backend/catalog/pg_depend.c
+++ b/src/backend/catalog/pg_depend.c
@@ -3,7 +3,7 @@
* pg_depend.c
* routines to support manipulation of the pg_depend relation
*
- * Portions Copyright (c) 1996-2024, PostgreSQL Global Development Group
+ * Portions Copyright (c) 1996-2025, PostgreSQL Global Development Group
* Portions Copyright (c) 1994, Regents of the University of California
*
*
@@ -28,7 +28,6 @@
#include "miscadmin.h"
#include "utils/fmgroids.h"
#include "utils/lsyscache.h"
-#include "utils/syscache.h"
#include "utils/rel.h"
@@ -36,7 +35,7 @@ static bool isObjectPinned(const ObjectAddress *object);
/*
- * Record a dependency between 2 objects via their respective objectAddress.
+ * Record a dependency between 2 objects via their respective ObjectAddress.
* The first argument is the dependent object, the second the one it
* references.
*
@@ -945,7 +944,7 @@ getOwnedSequences(Oid relid)
Oid
getIdentitySequence(Relation rel, AttrNumber attnum, bool missing_ok)
{
- Oid relid;
+ Oid relid = RelationGetRelid(rel);
List *seqlist;
/*
@@ -954,22 +953,16 @@ getIdentitySequence(Relation rel, AttrNumber attnum, bool missing_ok)
*/
if (RelationGetForm(rel)->relispartition)
{
- List *ancestors =
- get_partition_ancestors(RelationGetRelid(rel));
- HeapTuple ctup = SearchSysCacheAttNum(RelationGetRelid(rel), attnum);
- const char *attname = NameStr(((Form_pg_attribute) GETSTRUCT(ctup))->attname);
- HeapTuple ptup;
+ List *ancestors = get_partition_ancestors(relid);
+ const char *attname = get_attname(relid, attnum, false);
relid = llast_oid(ancestors);
- ptup = SearchSysCacheAttName(relid, attname);
- attnum = ((Form_pg_attribute) GETSTRUCT(ptup))->attnum;
-
- ReleaseSysCache(ctup);
- ReleaseSysCache(ptup);
+ attnum = get_attnum(relid, attname);
+ if (attnum == InvalidAttrNumber)
+ elog(ERROR, "cache lookup failed for attribute \"%s\" of relation %u",
+ attname, relid);
list_free(ancestors);
}
- else
- relid = RelationGetRelid(rel);
seqlist = getOwnedSequences_internal(relid, attnum, DEPENDENCY_INTERNAL);
if (list_length(seqlist) > 1)
diff --git a/src/backend/catalog/pg_enum.c b/src/backend/catalog/pg_enum.c
index 54cededac1bf3..da9c2a46cfaa1 100644
--- a/src/backend/catalog/pg_enum.c
+++ b/src/backend/catalog/pg_enum.c
@@ -3,7 +3,7 @@
* pg_enum.c
* routines to support manipulation of the pg_enum relation
*
- * Copyright (c) 2006-2024, PostgreSQL Global Development Group
+ * Copyright (c) 2006-2025, PostgreSQL Global Development Group
*
*
* IDENTIFICATION
@@ -110,12 +110,6 @@ EnumValuesCreate(Oid enumTypeOid, List *vals)
num_elems = list_length(vals);
- /*
- * We do not bother to check the list of values for duplicates --- if you
- * have any, you'll get a less-than-friendly unique-index violation. It is
- * probably not worth trying harder.
- */
-
pg_enum = table_open(EnumRelationId, RowExclusiveLock);
/*
@@ -164,6 +158,7 @@ EnumValuesCreate(Oid enumTypeOid, List *vals)
{
char *lab = strVal(lfirst(lc));
Name enumlabel = palloc0(NAMEDATALEN);
+ ListCell *lc2;
/*
* labels are stored in a name field, for easier syscache lookup, so
@@ -176,6 +171,24 @@ EnumValuesCreate(Oid enumTypeOid, List *vals)
errdetail("Labels must be %d bytes or less.",
NAMEDATALEN - 1)));
+ /*
+ * Check for duplicate labels. The unique index on pg_enum would catch
+ * that anyway, but we prefer a friendlier error message.
+ */
+ foreach(lc2, vals)
+ {
+ /* Only need to compare lc to earlier entries */
+ if (lc2 == lc)
+ break;
+
+ if (strcmp(lab, strVal(lfirst(lc2))) == 0)
+ ereport(ERROR,
+ (errcode(ERRCODE_DUPLICATE_OBJECT),
+ errmsg("enum label \"%s\" used more than once",
+ lab)));
+ }
+
+ /* OK, construct a tuple for this label */
ExecClearTuple(slot[slotCount]);
memset(slot[slotCount]->tts_isnull, false,
diff --git a/src/backend/catalog/pg_inherits.c b/src/backend/catalog/pg_inherits.c
index 836b4bfd894b8..929bb53b620fe 100644
--- a/src/backend/catalog/pg_inherits.c
+++ b/src/backend/catalog/pg_inherits.c
@@ -8,7 +8,7 @@
* Perhaps someday that code should be moved here, but it'd have to be
* disentangled from other stuff such as pg_depend updates.
*
- * Portions Copyright (c) 1996-2024, PostgreSQL Global Development Group
+ * Portions Copyright (c) 1996-2025, PostgreSQL Global Development Group
* Portions Copyright (c) 1994, Regents of the University of California
*
*
diff --git a/src/backend/catalog/pg_largeobject.c b/src/backend/catalog/pg_largeobject.c
index e235f7c5e680e..89fc810215099 100644
--- a/src/backend/catalog/pg_largeobject.c
+++ b/src/backend/catalog/pg_largeobject.c
@@ -3,7 +3,7 @@
* pg_largeobject.c
* routines to support manipulation of the pg_largeobject relation
*
- * Portions Copyright (c) 1996-2024, PostgreSQL Global Development Group
+ * Portions Copyright (c) 1996-2025, PostgreSQL Global Development Group
* Portions Copyright (c) 1994, Regents of the University of California
*
*
@@ -14,14 +14,13 @@
*/
#include "postgres.h"
-#include "access/genam.h"
-#include "access/htup_details.h"
#include "access/table.h"
#include "catalog/catalog.h"
#include "catalog/indexing.h"
#include "catalog/pg_largeobject.h"
#include "catalog/pg_largeobject_metadata.h"
#include "miscadmin.h"
+#include "utils/acl.h"
#include "utils/fmgroids.h"
#include "utils/rel.h"
@@ -41,6 +40,8 @@ LargeObjectCreate(Oid loid)
Oid loid_new;
Datum values[Natts_pg_largeobject_metadata];
bool nulls[Natts_pg_largeobject_metadata];
+ Oid ownerId;
+ Acl *lomacl;
pg_lo_meta = table_open(LargeObjectMetadataRelationId,
RowExclusiveLock);
@@ -57,11 +58,18 @@ LargeObjectCreate(Oid loid)
loid_new = GetNewOidWithIndex(pg_lo_meta,
LargeObjectMetadataOidIndexId,
Anum_pg_largeobject_metadata_oid);
+ ownerId = GetUserId();
+ lomacl = get_user_default_acl(OBJECT_LARGEOBJECT, ownerId, InvalidOid);
values[Anum_pg_largeobject_metadata_oid - 1] = ObjectIdGetDatum(loid_new);
values[Anum_pg_largeobject_metadata_lomowner - 1]
- = ObjectIdGetDatum(GetUserId());
- nulls[Anum_pg_largeobject_metadata_lomacl - 1] = true;
+ = ObjectIdGetDatum(ownerId);
+
+ if (lomacl != NULL)
+ values[Anum_pg_largeobject_metadata_lomacl - 1]
+ = PointerGetDatum(lomacl);
+ else
+ nulls[Anum_pg_largeobject_metadata_lomacl - 1] = true;
ntup = heap_form_tuple(RelationGetDescr(pg_lo_meta),
values, nulls);
@@ -72,6 +80,10 @@ LargeObjectCreate(Oid loid)
table_close(pg_lo_meta, RowExclusiveLock);
+ /* dependencies on roles mentioned in default ACL */
+ recordDependencyOnNewAcl(LargeObjectRelationId, loid_new, 0,
+ ownerId, lomacl);
+
return loid_new;
}
@@ -153,6 +165,15 @@ LargeObjectDrop(Oid loid)
*/
bool
LargeObjectExists(Oid loid)
+{
+ return LargeObjectExistsWithSnapshot(loid, NULL);
+}
+
+/*
+ * Same as LargeObjectExists(), except snapshot to read with can be specified.
+ */
+bool
+LargeObjectExistsWithSnapshot(Oid loid, Snapshot snapshot)
{
Relation pg_lo_meta;
ScanKeyData skey[1];
@@ -170,7 +191,7 @@ LargeObjectExists(Oid loid)
sd = systable_beginscan(pg_lo_meta,
LargeObjectMetadataOidIndexId, true,
- NULL, 1, skey);
+ snapshot, 1, skey);
tuple = systable_getnext(sd);
if (HeapTupleIsValid(tuple))
diff --git a/src/backend/catalog/pg_namespace.c b/src/backend/catalog/pg_namespace.c
index 3ce6e3800919e..616bcc7852113 100644
--- a/src/backend/catalog/pg_namespace.c
+++ b/src/backend/catalog/pg_namespace.c
@@ -3,7 +3,7 @@
* pg_namespace.c
* routines to support manipulation of the pg_namespace relation
*
- * Portions Copyright (c) 1996-2024, PostgreSQL Global Development Group
+ * Portions Copyright (c) 1996-2025, PostgreSQL Global Development Group
* Portions Copyright (c) 1994, Regents of the University of California
*
*
@@ -76,7 +76,7 @@ NamespaceCreate(const char *nspName, Oid ownerId, bool isTemp)
for (i = 0; i < Natts_pg_namespace; i++)
{
nulls[i] = false;
- values[i] = (Datum) NULL;
+ values[i] = (Datum) 0;
}
nspoid = GetNewOidWithIndex(nspdesc, NamespaceOidIndexId,
diff --git a/src/backend/catalog/pg_operator.c b/src/backend/catalog/pg_operator.c
index 65b45a424a276..44d2ccb6788e9 100644
--- a/src/backend/catalog/pg_operator.c
+++ b/src/backend/catalog/pg_operator.c
@@ -3,7 +3,7 @@
* pg_operator.c
* routines to support manipulation of the pg_operator relation
*
- * Portions Copyright (c) 1996-2024, PostgreSQL Global Development Group
+ * Portions Copyright (c) 1996-2025, PostgreSQL Global Development Group
* Portions Copyright (c) 1994, Regents of the University of California
*
*
@@ -225,7 +225,7 @@ OperatorShellMake(const char *operatorName,
for (i = 0; i < Natts_pg_operator; ++i)
{
nulls[i] = false;
- values[i] = (Datum) NULL; /* redundant, but safe */
+ values[i] = (Datum) 0; /* redundant, but safe */
}
/*
@@ -453,7 +453,7 @@ OperatorCreate(const char *operatorName,
for (i = 0; i < Natts_pg_operator; ++i)
{
- values[i] = (Datum) NULL;
+ values[i] = (Datum) 0;
replaces[i] = true;
nulls[i] = false;
}
diff --git a/src/backend/catalog/pg_parameter_acl.c b/src/backend/catalog/pg_parameter_acl.c
index e50f2666643e4..62a05783eb333 100644
--- a/src/backend/catalog/pg_parameter_acl.c
+++ b/src/backend/catalog/pg_parameter_acl.c
@@ -3,7 +3,7 @@
* pg_parameter_acl.c
* routines to support manipulation of the pg_parameter_acl relation
*
- * Portions Copyright (c) 1996-2024, PostgreSQL Global Development Group
+ * Portions Copyright (c) 1996-2025, PostgreSQL Global Development Group
* Portions Copyright (c) 1994, Regents of the University of California
*
*
diff --git a/src/backend/catalog/pg_proc.c b/src/backend/catalog/pg_proc.c
index 528c17cd7f676..75b17fed15e5b 100644
--- a/src/backend/catalog/pg_proc.c
+++ b/src/backend/catalog/pg_proc.c
@@ -3,7 +3,7 @@
* pg_proc.c
* routines to support manipulation of the pg_proc relation
*
- * Portions Copyright (c) 1996-2024, PostgreSQL Global Development Group
+ * Portions Copyright (c) 1996-2025, PostgreSQL Global Development Group
* Portions Copyright (c) 1994, Regents of the University of California
*
*
@@ -26,7 +26,6 @@
#include "catalog/pg_proc.h"
#include "catalog/pg_transform.h"
#include "catalog/pg_type.h"
-#include "commands/defrem.h"
#include "executor/functions.h"
#include "funcapi.h"
#include "mb/pg_wchar.h"
@@ -61,6 +60,35 @@ static bool match_prosrc_to_literal(const char *prosrc, const char *literal,
/* ----------------------------------------------------------------
* ProcedureCreate
*
+ * procedureName: string name of routine (proname)
+ * procNamespace: OID of namespace (pronamespace)
+ * replace: true to allow replacement of an existing pg_proc entry
+ * returnsSet: returns set? (proretset)
+ * returnType: OID of result type (prorettype)
+ * proowner: OID of owner role (proowner)
+ * languageObjectId: OID of function language (prolang)
+ * languageValidator: OID of validator function to apply, if any
+ * prosrc: string form of function definition (prosrc)
+ * probin: string form of binary reference, or NULL (probin)
+ * prosqlbody: Node tree of pre-parsed SQL body, or NULL (prosqlbody)
+ * prokind: function/aggregate/procedure/etc code (prokind)
+ * security_definer: security definer? (prosecdef)
+ * isLeakProof: leak proof? (proleakproof)
+ * isStrict: strict? (proisstrict)
+ * volatility: volatility code (provolatile)
+ * parallel: parallel safety code (proparallel)
+ * parameterTypes: input parameter types, as an oidvector (proargtypes)
+ * allParameterTypes: all parameter types, as an OID array (proallargtypes)
+ * parameterModes: parameter modes, as a "char" array (proargmodes)
+ * parameterNames: parameter names, as a text array (proargnames)
+ * parameterDefaults: defaults, as a List of Node trees (proargdefaults)
+ * trftypes: transformable type OIDs, as an OID array (protrftypes)
+ * trfoids: List of transform OIDs that routine should depend on
+ * proconfig: GUC set clauses, as a text array (proconfig)
+ * prosupport: OID of support function, if any (prosupport)
+ * procost: cost factor (procost)
+ * prorows: estimated output rows for a SRF (prorows)
+ *
* Note: allParameterTypes, parameterModes, parameterNames, trftypes, and proconfig
* are either arrays of the proper types or NULL. We declare them Datum,
* not "ArrayType *", to avoid importing array.h into pg_proc.h.
@@ -90,6 +118,7 @@ ProcedureCreate(const char *procedureName,
Datum parameterNames,
List *parameterDefaults,
Datum trftypes,
+ List *trfoids,
Datum proconfig,
Oid prosupport,
float4 procost,
@@ -115,7 +144,6 @@ ProcedureCreate(const char *procedureName,
referenced;
char *detailmsg;
int i;
- Oid trfid;
ObjectAddresses *addrs;
/*
@@ -609,25 +637,18 @@ ProcedureCreate(const char *procedureName,
ObjectAddressSet(referenced, TypeRelationId, returnType);
add_exact_object_address(&referenced, addrs);
- /* dependency on transform used by return type, if any */
- if ((trfid = get_transform_oid(returnType, languageObjectId, true)))
- {
- ObjectAddressSet(referenced, TransformRelationId, trfid);
- add_exact_object_address(&referenced, addrs);
- }
-
/* dependency on parameter types */
for (i = 0; i < allParamCount; i++)
{
ObjectAddressSet(referenced, TypeRelationId, allParams[i]);
add_exact_object_address(&referenced, addrs);
+ }
- /* dependency on transform used by parameter type, if any */
- if ((trfid = get_transform_oid(allParams[i], languageObjectId, true)))
- {
- ObjectAddressSet(referenced, TransformRelationId, trfid);
- add_exact_object_address(&referenced, addrs);
- }
+ /* dependency on transforms, if any */
+ foreach_oid(transformid, trfoids)
+ {
+ ObjectAddressSet(referenced, TransformRelationId, transformid);
+ add_exact_object_address(&referenced, addrs);
}
/* dependency on support function, if any */
@@ -873,7 +894,7 @@ fmgr_sql_validator(PG_FUNCTION_ARGS)
callback_arg.prosrc = prosrc;
sqlerrcontext.callback = sql_function_parse_error_callback;
- sqlerrcontext.arg = (void *) &callback_arg;
+ sqlerrcontext.arg = &callback_arg;
sqlerrcontext.previous = error_context_stack;
error_context_stack = &sqlerrcontext;
@@ -960,7 +981,7 @@ fmgr_sql_validator(PG_FUNCTION_ARGS)
(void) check_sql_fn_retval(querytree_list,
rettype, rettupdesc,
proc->prokind,
- false, NULL);
+ false);
}
error_context_stack = sqlerrcontext.previous;
@@ -1191,6 +1212,6 @@ oid_array_to_list(Datum datum)
deconstruct_array_builtin(array, OIDOID, &values, NULL, &nelems);
for (i = 0; i < nelems; i++)
- result = lappend_oid(result, values[i]);
+ result = lappend_oid(result, DatumGetObjectId(values[i]));
return result;
}
diff --git a/src/backend/catalog/pg_publication.c b/src/backend/catalog/pg_publication.c
index 0602398a54546..b911efcf9cb6a 100644
--- a/src/backend/catalog/pg_publication.c
+++ b/src/backend/catalog/pg_publication.c
@@ -3,7 +3,7 @@
* pg_publication.c
* publication C API manipulation
*
- * Portions Copyright (c) 1996-2024, PostgreSQL Global Development Group
+ * Portions Copyright (c) 1996-2025, PostgreSQL Global Development Group
* Portions Copyright (c) 1994, Regents of the University of California
*
* IDENTIFICATION
@@ -48,9 +48,6 @@ typedef struct
* table. */
} published_rel;
-static void publication_translate_columns(Relation targetrel, List *columns,
- int *natts, AttrNumber **attrs);
-
/*
* Check if relation can be in given publication and throws appropriate
* error if not.
@@ -259,6 +256,52 @@ is_schema_publication(Oid pubid)
return result;
}
+/*
+ * Returns true if the relation has column list associated with the
+ * publication, false otherwise.
+ *
+ * If a column list is found, the corresponding bitmap is returned through the
+ * cols parameter, if provided. The bitmap is constructed within the given
+ * memory context (mcxt).
+ */
+bool
+check_and_fetch_column_list(Publication *pub, Oid relid, MemoryContext mcxt,
+ Bitmapset **cols)
+{
+ HeapTuple cftuple;
+ bool found = false;
+
+ if (pub->alltables)
+ return false;
+
+ cftuple = SearchSysCache2(PUBLICATIONRELMAP,
+ ObjectIdGetDatum(relid),
+ ObjectIdGetDatum(pub->oid));
+ if (HeapTupleIsValid(cftuple))
+ {
+ Datum cfdatum;
+ bool isnull;
+
+ /* Lookup the column list attribute. */
+ cfdatum = SysCacheGetAttr(PUBLICATIONRELMAP, cftuple,
+ Anum_pg_publication_rel_prattrs, &isnull);
+
+ /* Was a column list found? */
+ if (!isnull)
+ {
+ /* Build the column list bitmap in the given memory context. */
+ if (cols)
+ *cols = pub_collist_to_bitmapset(*cols, cfdatum, mcxt);
+
+ found = true;
+ }
+
+ ReleaseSysCache(cftuple);
+ }
+
+ return found;
+}
+
/*
* Gets the relations based on the publication partition option for a specified
* relation.
@@ -351,6 +394,33 @@ GetTopMostAncestorInPublication(Oid puboid, List *ancestors, int *ancestor_level
return topmost_relid;
}
+/*
+ * attnumstoint2vector
+ * Convert a Bitmapset of AttrNumbers into an int2vector.
+ *
+ * AttrNumber numbers are 0-based, i.e., not offset by
+ * FirstLowInvalidHeapAttributeNumber.
+ */
+static int2vector *
+attnumstoint2vector(Bitmapset *attrs)
+{
+ int2vector *result;
+ int n = bms_num_members(attrs);
+ int i = -1;
+ int j = 0;
+
+ result = buildint2vector(NULL, n);
+
+ while ((i = bms_next_member(attrs, i)) >= 0)
+ {
+ Assert(i <= PG_INT16_MAX);
+
+ result->values[j++] = (int16) i;
+ }
+
+ return result;
+}
+
/*
* Insert new publication / relation mapping.
*/
@@ -365,12 +435,12 @@ publication_add_relation(Oid pubid, PublicationRelInfo *pri,
Relation targetrel = pri->relation;
Oid relid = RelationGetRelid(targetrel);
Oid pubreloid;
+ Bitmapset *attnums;
Publication *pub = GetPublication(pubid);
- AttrNumber *attarray = NULL;
- int natts = 0;
ObjectAddress myself,
referenced;
List *relids = NIL;
+ int i;
rel = table_open(PublicationRelRelationId, RowExclusiveLock);
@@ -395,13 +465,8 @@ publication_add_relation(Oid pubid, PublicationRelInfo *pri,
check_publication_add_relation(targetrel);
- /*
- * Translate column names to attnums and make sure the column list
- * contains only allowed elements (no system or generated columns etc.).
- * Also build an array of attnums, for storing in the catalog.
- */
- publication_translate_columns(pri->relation, pri->columns,
- &natts, &attarray);
+ /* Validate and translate column names into a Bitmapset of attnums. */
+ attnums = pub_collist_validate(pri->relation, pri->columns);
/* Form a tuple. */
memset(values, 0, sizeof(values));
@@ -423,7 +488,7 @@ publication_add_relation(Oid pubid, PublicationRelInfo *pri,
/* Add column list, if available */
if (pri->columns)
- values[Anum_pg_publication_rel_prattrs - 1] = PointerGetDatum(buildint2vector(attarray, natts));
+ values[Anum_pg_publication_rel_prattrs - 1] = PointerGetDatum(attnumstoint2vector(attnums));
else
nulls[Anum_pg_publication_rel_prattrs - 1] = true;
@@ -451,9 +516,10 @@ publication_add_relation(Oid pubid, PublicationRelInfo *pri,
false);
/* Add dependency on the columns, if any are listed */
- for (int i = 0; i < natts; i++)
+ i = -1;
+ while ((i = bms_next_member(attnums, i)) >= 0)
{
- ObjectAddressSubSet(referenced, RelationRelationId, relid, attarray[i]);
+ ObjectAddressSubSet(referenced, RelationRelationId, relid, i);
recordDependencyOn(&myself, &referenced, DEPENDENCY_NORMAL);
}
@@ -476,47 +542,23 @@ publication_add_relation(Oid pubid, PublicationRelInfo *pri,
return myself;
}
-/* qsort comparator for attnums */
-static int
-compare_int16(const void *a, const void *b)
-{
- int av = *(const int16 *) a;
- int bv = *(const int16 *) b;
-
- /* this can't overflow if int is wider than int16 */
- return (av - bv);
-}
-
/*
- * Translate a list of column names to an array of attribute numbers
- * and a Bitmapset with them; verify that each attribute is appropriate
- * to have in a publication column list (no system or generated attributes,
- * no duplicates). Additional checks with replica identity are done later;
- * see pub_collist_contains_invalid_column.
+ * pub_collist_validate
+ * Process and validate the 'columns' list and ensure the columns are all
+ * valid to use for a publication. Checks for and raises an ERROR for
+ * any unknown columns, system columns, duplicate columns, or virtual
+ * generated columns.
*
- * Note that the attribute numbers are *not* offset by
- * FirstLowInvalidHeapAttributeNumber; system columns are forbidden so this
- * is okay.
+ * Looks up each column's attnum and returns a 0-based Bitmapset of the
+ * corresponding attnums.
*/
-static void
-publication_translate_columns(Relation targetrel, List *columns,
- int *natts, AttrNumber **attrs)
+Bitmapset *
+pub_collist_validate(Relation targetrel, List *columns)
{
- AttrNumber *attarray = NULL;
Bitmapset *set = NULL;
ListCell *lc;
- int n = 0;
TupleDesc tupdesc = RelationGetDescr(targetrel);
- /* Bail out when no column list defined. */
- if (!columns)
- return;
-
- /*
- * Translate list of columns to attnums. We prohibit system attributes and
- * make sure there are no duplicate columns.
- */
- attarray = palloc(sizeof(AttrNumber) * list_length(columns));
foreach(lc, columns)
{
char *colname = strVal(lfirst(lc));
@@ -534,10 +576,10 @@ publication_translate_columns(Relation targetrel, List *columns,
errmsg("cannot use system column \"%s\" in publication column list",
colname));
- if (TupleDescAttr(tupdesc, attnum - 1)->attgenerated)
+ if (TupleDescAttr(tupdesc, attnum - 1)->attgenerated == ATTRIBUTE_GENERATED_VIRTUAL)
ereport(ERROR,
errcode(ERRCODE_INVALID_COLUMN_REFERENCE),
- errmsg("cannot use generated column \"%s\" in publication column list",
+ errmsg("cannot use virtual generated column \"%s\" in publication column list",
colname));
if (bms_is_member(attnum, set))
@@ -547,16 +589,9 @@ publication_translate_columns(Relation targetrel, List *columns,
colname));
set = bms_add_member(set, attnum);
- attarray[n++] = attnum;
}
- /* Be tidy, so that the catalog representation is always sorted */
- qsort(attarray, n, sizeof(AttrNumber), compare_int16);
-
- *natts = n;
- *attrs = attarray;
-
- bms_free(set);
+ return set;
}
/*
@@ -569,19 +604,12 @@ publication_translate_columns(Relation targetrel, List *columns,
Bitmapset *
pub_collist_to_bitmapset(Bitmapset *columns, Datum pubcols, MemoryContext mcxt)
{
- Bitmapset *result = NULL;
+ Bitmapset *result = columns;
ArrayType *arr;
int nelems;
int16 *elems;
MemoryContext oldcxt = NULL;
- /*
- * If an existing bitmap was provided, use it. Otherwise just use NULL and
- * build a new bitmap.
- */
- if (columns)
- result = columns;
-
arr = DatumGetArrayTypeP(pubcols);
nelems = ARR_DIMS(arr)[0];
elems = (int16 *) ARR_DATA_PTR(arr);
@@ -599,6 +627,42 @@ pub_collist_to_bitmapset(Bitmapset *columns, Datum pubcols, MemoryContext mcxt)
return result;
}
+/*
+ * Returns a bitmap representing the columns of the specified table.
+ *
+ * Generated columns are included if include_gencols_type is
+ * PUBLISH_GENCOLS_STORED.
+ */
+Bitmapset *
+pub_form_cols_map(Relation relation, PublishGencolsType include_gencols_type)
+{
+ Bitmapset *result = NULL;
+ TupleDesc desc = RelationGetDescr(relation);
+
+ for (int i = 0; i < desc->natts; i++)
+ {
+ Form_pg_attribute att = TupleDescAttr(desc, i);
+
+ if (att->attisdropped)
+ continue;
+
+ if (att->attgenerated)
+ {
+ /* We only support replication of STORED generated cols. */
+ if (att->attgenerated != ATTRIBUTE_GENERATED_STORED)
+ continue;
+
+ /* User hasn't requested to replicate STORED generated cols. */
+ if (include_gencols_type != PUBLISH_GENCOLS_STORED)
+ continue;
+ }
+
+ result = bms_add_member(result, att->attnum);
+ }
+
+ return result;
+}
+
/*
* Insert new publication / schema mapping.
*/
@@ -937,7 +1001,7 @@ GetSchemaPublicationRelations(Oid schemaid, PublicationPartOpt pub_partopt)
ScanKeyInit(&key[0],
Anum_pg_class_relnamespace,
BTEqualStrategyNumber, F_OIDEQ,
- schemaid);
+ ObjectIdGetDatum(schemaid));
/* get all the relations present in the specified schema */
scan = table_beginscan_catalog(classRel, 1, key);
@@ -1024,6 +1088,7 @@ GetPublication(Oid pubid)
pub->pubactions.pubdelete = pubform->pubdelete;
pub->pubactions.pubtruncate = pubform->pubtruncate;
pub->pubviaroot = pubform->pubviaroot;
+ pub->pubgencols_type = pubform->pubgencols;
ReleaseSysCache(tup);
@@ -1077,8 +1142,7 @@ pg_get_publication_tables(PG_FUNCTION_ARGS)
* publication name.
*/
arr = PG_GETARG_ARRAYTYPE_P(0);
- deconstruct_array(arr, TEXTOID, -1, false, TYPALIGN_INT,
- &elems, NULL, &nelems);
+ deconstruct_array_builtin(arr, TEXTOID, &elems, NULL, &nelems);
/* Get Oids of tables from each publication. */
for (i = 0; i < nelems; i++)
@@ -1158,7 +1222,7 @@ pg_get_publication_tables(PG_FUNCTION_ARGS)
PG_NODE_TREEOID, -1, 0);
funcctx->tuple_desc = BlessTupleDesc(tupdesc);
- funcctx->user_fctx = (void *) table_infos;
+ funcctx->user_fctx = table_infos;
MemoryContextSwitchTo(oldcontext);
}
@@ -1232,9 +1296,23 @@ pg_get_publication_tables(PG_FUNCTION_ARGS)
{
Form_pg_attribute att = TupleDescAttr(desc, i);
- if (att->attisdropped || att->attgenerated)
+ if (att->attisdropped)
continue;
+ if (att->attgenerated)
+ {
+ /* We only support replication of STORED generated cols. */
+ if (att->attgenerated != ATTRIBUTE_GENERATED_STORED)
+ continue;
+
+ /*
+ * User hasn't requested to replicate STORED generated
+ * cols.
+ */
+ if (pub->pubgencols_type != PUBLISH_GENCOLS_STORED)
+ continue;
+ }
+
attnums[nattnums++] = att->attnum;
}
diff --git a/src/backend/catalog/pg_range.c b/src/backend/catalog/pg_range.c
index 501a6ba41060b..8df73e7ab71b4 100644
--- a/src/backend/catalog/pg_range.c
+++ b/src/backend/catalog/pg_range.c
@@ -3,7 +3,7 @@
* pg_range.c
* routines to support manipulation of the pg_range relation
*
- * Portions Copyright (c) 1996-2024, PostgreSQL Global Development Group
+ * Portions Copyright (c) 1996-2025, PostgreSQL Global Development Group
* Portions Copyright (c) 1994, Regents of the University of California
*
*
diff --git a/src/backend/catalog/pg_shdepend.c b/src/backend/catalog/pg_shdepend.c
index 20bcfd779b969..16e3e5c7457db 100644
--- a/src/backend/catalog/pg_shdepend.c
+++ b/src/backend/catalog/pg_shdepend.c
@@ -3,7 +3,7 @@
* pg_shdepend.c
* routines to support manipulation of the pg_shdepend relation
*
- * Portions Copyright (c) 1996-2024, PostgreSQL Global Development Group
+ * Portions Copyright (c) 1996-2025, PostgreSQL Global Development Group
* Portions Copyright (c) 1994, Regents of the University of California
*
*
@@ -47,7 +47,6 @@
#include "catalog/pg_type.h"
#include "catalog/pg_user_mapping.h"
#include "commands/alter.h"
-#include "commands/dbcommands.h"
#include "commands/defrem.h"
#include "commands/event_trigger.h"
#include "commands/policy.h"
@@ -61,6 +60,7 @@
#include "storage/lmgr.h"
#include "utils/acl.h"
#include "utils/fmgroids.h"
+#include "utils/lsyscache.h"
#include "utils/memutils.h"
#include "utils/syscache.h"
@@ -103,6 +103,9 @@ static void storeObjectDescription(StringInfo descs,
ObjectAddress *object,
SharedDependencyType deptype,
int count);
+static void shdepReassignOwned_Owner(Form_pg_shdepend sdepForm, Oid newrole);
+static void shdepReassignOwned_InitAcl(Form_pg_shdepend sdepForm,
+ Oid oldrole, Oid newrole);
/*
@@ -345,10 +348,11 @@ changeDependencyOnOwner(Oid classId, Oid objectId, Oid newOwnerId)
AuthIdRelationId, newOwnerId,
SHARED_DEPENDENCY_ACL);
- /* The same applies to SHARED_DEPENDENCY_INITACL */
- shdepDropDependency(sdepRel, classId, objectId, 0, true,
- AuthIdRelationId, newOwnerId,
- SHARED_DEPENDENCY_INITACL);
+ /*
+ * However, nothing need be done about SHARED_DEPENDENCY_INITACL entries,
+ * since those exist whether or not the role is the object's owner, and
+ * ALTER OWNER does not modify the underlying pg_init_privs entry.
+ */
table_close(sdepRel, RowExclusiveLock);
}
@@ -500,16 +504,18 @@ updateAclDependencies(Oid classId, Oid objectId, int32 objsubId,
* Update the pg_shdepend info for a pg_init_privs entry.
*
* Exactly like updateAclDependencies, except we are considering a
- * pg_init_privs ACL for the specified object.
+ * pg_init_privs ACL for the specified object. Since recording of
+ * pg_init_privs role dependencies is the same for owners and non-owners,
+ * we do not need an ownerId argument.
*/
void
updateInitAclDependencies(Oid classId, Oid objectId, int32 objsubId,
- Oid ownerId,
int noldmembers, Oid *oldmembers,
int nnewmembers, Oid *newmembers)
{
updateAclDependenciesWorker(classId, objectId, objsubId,
- ownerId, SHARED_DEPENDENCY_INITACL,
+ InvalidOid, /* ownerId will not be consulted */
+ SHARED_DEPENDENCY_INITACL,
noldmembers, oldmembers,
nnewmembers, newmembers);
}
@@ -542,11 +548,13 @@ updateAclDependenciesWorker(Oid classId, Oid objectId, int32 objsubId,
Oid roleid = newmembers[i];
/*
- * Skip the owner: he has an OWNER shdep entry instead. (This is
- * not just a space optimization; it makes ALTER OWNER easier. See
- * notes in changeDependencyOnOwner.)
+ * For SHARED_DEPENDENCY_ACL entries, skip the owner: she has an
+ * OWNER shdep entry instead. (This is not just a space
+ * optimization; it makes ALTER OWNER easier. See notes in
+ * changeDependencyOnOwner.) But for INITACL entries, we record
+ * the owner too.
*/
- if (roleid == ownerId)
+ if (deptype == SHARED_DEPENDENCY_ACL && roleid == ownerId)
continue;
/* Skip pinned roles; they don't need dependency entries */
@@ -563,8 +571,8 @@ updateAclDependenciesWorker(Oid classId, Oid objectId, int32 objsubId,
{
Oid roleid = oldmembers[i];
- /* Skip the owner, same as above */
- if (roleid == ownerId)
+ /* Skip the owner for ACL entries, same as above */
+ if (deptype == SHARED_DEPENDENCY_ACL && roleid == ownerId)
continue;
/* Skip pinned roles */
@@ -948,12 +956,12 @@ copyTemplateDependencies(Oid templateDbId, Oid newDbId)
shdep = (Form_pg_shdepend) GETSTRUCT(tup);
slot[slot_stored_count]->tts_values[Anum_pg_shdepend_dbid - 1] = ObjectIdGetDatum(newDbId);
- slot[slot_stored_count]->tts_values[Anum_pg_shdepend_classid - 1] = shdep->classid;
- slot[slot_stored_count]->tts_values[Anum_pg_shdepend_objid - 1] = shdep->objid;
- slot[slot_stored_count]->tts_values[Anum_pg_shdepend_objsubid - 1] = shdep->objsubid;
- slot[slot_stored_count]->tts_values[Anum_pg_shdepend_refclassid - 1] = shdep->refclassid;
- slot[slot_stored_count]->tts_values[Anum_pg_shdepend_refobjid - 1] = shdep->refobjid;
- slot[slot_stored_count]->tts_values[Anum_pg_shdepend_deptype - 1] = shdep->deptype;
+ slot[slot_stored_count]->tts_values[Anum_pg_shdepend_classid - 1] = ObjectIdGetDatum(shdep->classid);
+ slot[slot_stored_count]->tts_values[Anum_pg_shdepend_objid - 1] = ObjectIdGetDatum(shdep->objid);
+ slot[slot_stored_count]->tts_values[Anum_pg_shdepend_objsubid - 1] = Int32GetDatum(shdep->objsubid);
+ slot[slot_stored_count]->tts_values[Anum_pg_shdepend_refclassid - 1] = ObjectIdGetDatum(shdep->refclassid);
+ slot[slot_stored_count]->tts_values[Anum_pg_shdepend_refobjid - 1] = ObjectIdGetDatum(shdep->refobjid);
+ slot[slot_stored_count]->tts_values[Anum_pg_shdepend_deptype - 1] = CharGetDatum(shdep->deptype);
ExecStoreVirtualTuple(slot[slot_stored_count]);
slot_stored_count++;
@@ -1476,6 +1484,13 @@ shdepDropOwned(List *roleids, DropBehavior behavior)
}
break;
case SHARED_DEPENDENCY_INITACL:
+
+ /*
+ * Any mentions of the role that remain in pg_init_privs
+ * entries are just dropped. This is the same policy as
+ * we apply to regular ACLs.
+ */
+
/* Shouldn't see a role grant here */
Assert(sdepForm->classid != AuthMemRelationId);
RemoveRoleFromInitPriv(roleid,
@@ -1577,12 +1592,8 @@ shdepReassignOwned(List *roleids, Oid newrole)
sdepForm->dbid != InvalidOid)
continue;
- /* We leave non-owner dependencies alone */
- if (sdepForm->deptype != SHARED_DEPENDENCY_OWNER)
- continue;
-
/*
- * The various ALTER OWNER routines tend to leak memory in
+ * The various DDL routines called here tend to leak memory in
* CurrentMemoryContext. That's not a problem when they're only
* called once per command; but in this usage where we might be
* touching many objects, it can amount to a serious memory leak.
@@ -1593,81 +1604,23 @@ shdepReassignOwned(List *roleids, Oid newrole)
ALLOCSET_DEFAULT_SIZES);
oldcxt = MemoryContextSwitchTo(cxt);
- /* Issue the appropriate ALTER OWNER call */
- switch (sdepForm->classid)
+ /* Perform the appropriate processing */
+ switch (sdepForm->deptype)
{
- case TypeRelationId:
- AlterTypeOwner_oid(sdepForm->objid, newrole, true);
- break;
-
- case NamespaceRelationId:
- AlterSchemaOwner_oid(sdepForm->objid, newrole);
- break;
-
- case RelationRelationId:
-
- /*
- * Pass recursing = true so that we don't fail on indexes,
- * owned sequences, etc when we happen to visit them
- * before their parent table.
- */
- ATExecChangeOwner(sdepForm->objid, newrole, true, AccessExclusiveLock);
- break;
-
- case DefaultAclRelationId:
-
- /*
- * Ignore default ACLs; they should be handled by DROP
- * OWNED, not REASSIGN OWNED.
- */
- break;
-
- case UserMappingRelationId:
- /* ditto */
- break;
-
- case ForeignServerRelationId:
- AlterForeignServerOwner_oid(sdepForm->objid, newrole);
- break;
-
- case ForeignDataWrapperRelationId:
- AlterForeignDataWrapperOwner_oid(sdepForm->objid, newrole);
- break;
-
- case EventTriggerRelationId:
- AlterEventTriggerOwner_oid(sdepForm->objid, newrole);
- break;
-
- case PublicationRelationId:
- AlterPublicationOwner_oid(sdepForm->objid, newrole);
+ case SHARED_DEPENDENCY_OWNER:
+ shdepReassignOwned_Owner(sdepForm, newrole);
break;
-
- case SubscriptionRelationId:
- AlterSubscriptionOwner_oid(sdepForm->objid, newrole);
+ case SHARED_DEPENDENCY_INITACL:
+ shdepReassignOwned_InitAcl(sdepForm, roleid, newrole);
break;
-
- /* Generic alter owner cases */
- case CollationRelationId:
- case ConversionRelationId:
- case OperatorRelationId:
- case ProcedureRelationId:
- case LanguageRelationId:
- case LargeObjectRelationId:
- case OperatorFamilyRelationId:
- case OperatorClassRelationId:
- case ExtensionRelationId:
- case StatisticExtRelationId:
- case TableSpaceRelationId:
- case DatabaseRelationId:
- case TSConfigRelationId:
- case TSDictionaryRelationId:
- AlterObjectOwner_internal(sdepForm->classid,
- sdepForm->objid,
- newrole);
+ case SHARED_DEPENDENCY_ACL:
+ case SHARED_DEPENDENCY_POLICY:
+ case SHARED_DEPENDENCY_TABLESPACE:
+ /* Nothing to do for these entry types */
break;
-
default:
- elog(ERROR, "unexpected classid %u", sdepForm->classid);
+ elog(ERROR, "unrecognized dependency type: %d",
+ (int) sdepForm->deptype);
break;
}
@@ -1684,3 +1637,123 @@ shdepReassignOwned(List *roleids, Oid newrole)
table_close(sdepRel, RowExclusiveLock);
}
+
+/*
+ * shdepReassignOwned_Owner
+ *
+ * shdepReassignOwned's processing of SHARED_DEPENDENCY_OWNER entries
+ */
+static void
+shdepReassignOwned_Owner(Form_pg_shdepend sdepForm, Oid newrole)
+{
+ /* Issue the appropriate ALTER OWNER call */
+ switch (sdepForm->classid)
+ {
+ case TypeRelationId:
+ AlterTypeOwner_oid(sdepForm->objid, newrole, true);
+ break;
+
+ case NamespaceRelationId:
+ AlterSchemaOwner_oid(sdepForm->objid, newrole);
+ break;
+
+ case RelationRelationId:
+
+ /*
+ * Pass recursing = true so that we don't fail on indexes, owned
+ * sequences, etc when we happen to visit them before their parent
+ * table.
+ */
+ ATExecChangeOwner(sdepForm->objid, newrole, true, AccessExclusiveLock);
+ break;
+
+ case DefaultAclRelationId:
+
+ /*
+ * Ignore default ACLs; they should be handled by DROP OWNED, not
+ * REASSIGN OWNED.
+ */
+ break;
+
+ case UserMappingRelationId:
+ /* ditto */
+ break;
+
+ case ForeignServerRelationId:
+ AlterForeignServerOwner_oid(sdepForm->objid, newrole);
+ break;
+
+ case ForeignDataWrapperRelationId:
+ AlterForeignDataWrapperOwner_oid(sdepForm->objid, newrole);
+ break;
+
+ case EventTriggerRelationId:
+ AlterEventTriggerOwner_oid(sdepForm->objid, newrole);
+ break;
+
+ case PublicationRelationId:
+ AlterPublicationOwner_oid(sdepForm->objid, newrole);
+ break;
+
+ case SubscriptionRelationId:
+ AlterSubscriptionOwner_oid(sdepForm->objid, newrole);
+ break;
+
+ /* Generic alter owner cases */
+ case CollationRelationId:
+ case ConversionRelationId:
+ case OperatorRelationId:
+ case ProcedureRelationId:
+ case LanguageRelationId:
+ case LargeObjectRelationId:
+ case OperatorFamilyRelationId:
+ case OperatorClassRelationId:
+ case ExtensionRelationId:
+ case StatisticExtRelationId:
+ case TableSpaceRelationId:
+ case DatabaseRelationId:
+ case TSConfigRelationId:
+ case TSDictionaryRelationId:
+ AlterObjectOwner_internal(sdepForm->classid,
+ sdepForm->objid,
+ newrole);
+ break;
+
+ default:
+ elog(ERROR, "unexpected classid %u", sdepForm->classid);
+ break;
+ }
+}
+
+/*
+ * shdepReassignOwned_InitAcl
+ *
+ * shdepReassignOwned's processing of SHARED_DEPENDENCY_INITACL entries
+ */
+static void
+shdepReassignOwned_InitAcl(Form_pg_shdepend sdepForm, Oid oldrole, Oid newrole)
+{
+ /*
+ * Currently, REASSIGN OWNED replaces mentions of oldrole with newrole in
+ * pg_init_privs entries, just as it does in the object's regular ACL.
+ * This is less than ideal, since pg_init_privs ought to retain a
+ * historical record of the situation at the end of CREATE EXTENSION.
+ * However, there are two big stumbling blocks to doing something
+ * different:
+ *
+ * 1. If we don't replace the references, what is to happen if the old
+ * role gets dropped? (DROP OWNED's current answer is to just delete the
+ * pg_init_privs entry, which is surely ahistorical.)
+ *
+ * 2. It's unlikely that pg_dump will cope nicely with pg_init_privs
+ * entries that are based on a different owner than the object now has ---
+ * the more so given that pg_init_privs doesn't record the original owner
+ * explicitly. (This problem actually exists anyway given that a bare
+ * ALTER OWNER won't update pg_init_privs, but we don't need REASSIGN
+ * OWNED making it worse.)
+ */
+ ReplaceRoleInInitPriv(oldrole, newrole,
+ sdepForm->classid,
+ sdepForm->objid,
+ sdepForm->objsubid);
+}
diff --git a/src/backend/catalog/pg_subscription.c b/src/backend/catalog/pg_subscription.c
index 9efc9159f2c22..b885890de3738 100644
--- a/src/backend/catalog/pg_subscription.c
+++ b/src/backend/catalog/pg_subscription.c
@@ -3,7 +3,7 @@
* pg_subscription.c
* replication subscriptions
*
- * Portions Copyright (c) 1996-2024, PostgreSQL Global Development Group
+ * Portions Copyright (c) 1996-2025, PostgreSQL Global Development Group
* Portions Copyright (c) 1994, Regents of the University of California
*
* IDENTIFICATION
@@ -34,6 +34,37 @@
static List *textarray_to_stringlist(ArrayType *textarray);
+/*
+ * Add a comma-separated list of publication names to the 'dest' string.
+ */
+void
+GetPublicationsStr(List *publications, StringInfo dest, bool quote_literal)
+{
+ ListCell *lc;
+ bool first = true;
+
+ Assert(publications != NIL);
+
+ foreach(lc, publications)
+ {
+ char *pubname = strVal(lfirst(lc));
+
+ if (first)
+ first = false;
+ else
+ appendStringInfoString(dest, ", ");
+
+ if (quote_literal)
+ appendStringInfoString(dest, quote_literal_cstr(pubname));
+ else
+ {
+ appendStringInfoChar(dest, '"');
+ appendStringInfoString(dest, pubname);
+ appendStringInfoChar(dest, '"');
+ }
+ }
+}
+
/*
* Fetch the subscription from the syscache.
*/
@@ -72,6 +103,9 @@ GetSubscription(Oid subid, bool missing_ok)
sub->passwordrequired = subform->subpasswordrequired;
sub->runasowner = subform->subrunasowner;
sub->failover = subform->subfailover;
+ sub->retaindeadtuples = subform->subretaindeadtuples;
+ sub->maxretention = subform->submaxretention;
+ sub->retentionactive = subform->subretentionactive;
/* Get conninfo */
datum = SysCacheGetAttrNotNull(SUBSCRIPTIONOID,
@@ -288,7 +322,7 @@ AddSubscriptionRelState(Oid subid, Oid relid, char state,
*/
void
UpdateSubscriptionRelState(Oid subid, Oid relid, char state,
- XLogRecPtr sublsn)
+ XLogRecPtr sublsn, bool already_locked)
{
Relation rel;
HeapTuple tup;
@@ -296,9 +330,24 @@ UpdateSubscriptionRelState(Oid subid, Oid relid, char state,
Datum values[Natts_pg_subscription_rel];
bool replaces[Natts_pg_subscription_rel];
- LockSharedObject(SubscriptionRelationId, subid, 0, AccessShareLock);
+ if (already_locked)
+ {
+#ifdef USE_ASSERT_CHECKING
+ LOCKTAG tag;
- rel = table_open(SubscriptionRelRelationId, RowExclusiveLock);
+ Assert(CheckRelationOidLockedByMe(SubscriptionRelRelationId,
+ RowExclusiveLock, true));
+ SET_LOCKTAG_OBJECT(tag, InvalidOid, SubscriptionRelationId, subid, 0);
+ Assert(LockHeldByMe(&tag, AccessShareLock, true));
+#endif
+
+ rel = table_open(SubscriptionRelRelationId, NoLock);
+ }
+ else
+ {
+ LockSharedObject(SubscriptionRelationId, subid, 0, AccessShareLock);
+ rel = table_open(SubscriptionRelRelationId, RowExclusiveLock);
+ }
/* Try finding existing mapping. */
tup = SearchSysCacheCopy2(SUBSCRIPTIONRELMAP,
@@ -551,3 +600,42 @@ GetSubscriptionRelations(Oid subid, bool not_ready)
return res;
}
+
+/*
+ * Update the dead tuple retention status for the given subscription.
+ */
+void
+UpdateDeadTupleRetentionStatus(Oid subid, bool active)
+{
+ Relation rel;
+ bool nulls[Natts_pg_subscription];
+ bool replaces[Natts_pg_subscription];
+ Datum values[Natts_pg_subscription];
+ HeapTuple tup;
+
+ /* Look up the subscription in the catalog */
+ rel = table_open(SubscriptionRelationId, RowExclusiveLock);
+ tup = SearchSysCacheCopy1(SUBSCRIPTIONOID, ObjectIdGetDatum(subid));
+
+ if (!HeapTupleIsValid(tup))
+ elog(ERROR, "cache lookup failed for subscription %u", subid);
+
+ LockSharedObject(SubscriptionRelationId, subid, 0, AccessShareLock);
+
+ /* Form a new tuple. */
+ memset(values, 0, sizeof(values));
+ memset(nulls, false, sizeof(nulls));
+ memset(replaces, false, sizeof(replaces));
+
+ /* Set the subscription to disabled. */
+ values[Anum_pg_subscription_subretentionactive - 1] = active;
+ replaces[Anum_pg_subscription_subretentionactive - 1] = true;
+
+ /* Update the catalog */
+ tup = heap_modify_tuple(tup, RelationGetDescr(rel), values, nulls,
+ replaces);
+ CatalogTupleUpdate(rel, &tup->t_self, tup);
+ heap_freetuple(tup);
+
+ table_close(rel, NoLock);
+}
diff --git a/src/backend/catalog/pg_type.c b/src/backend/catalog/pg_type.c
index 395dec8ed88e8..3cd9b69edc575 100644
--- a/src/backend/catalog/pg_type.c
+++ b/src/backend/catalog/pg_type.c
@@ -3,7 +3,7 @@
* pg_type.c
* routines to support manipulation of the pg_type relation
*
- * Portions Copyright (c) 1996-2024, PostgreSQL Global Development Group
+ * Portions Copyright (c) 1996-2025, PostgreSQL Global Development Group
* Portions Copyright (c) 1994, Regents of the University of California
*
*
@@ -80,7 +80,7 @@ TypeShellMake(const char *typeName, Oid typeNamespace, Oid ownerId)
for (i = 0; i < Natts_pg_type; ++i)
{
nulls[i] = false;
- values[i] = (Datum) NULL; /* redundant, but safe */
+ values[i] = (Datum) 0; /* redundant, but safe */
}
/*
@@ -285,8 +285,7 @@ TypeCreate(Oid newTypeOid,
errmsg("alignment \"%c\" is invalid for passed-by-value type of size %d",
alignment, internalSize)));
}
-#if SIZEOF_DATUM == 8
- else if (internalSize == (int16) sizeof(Datum))
+ else if (internalSize == (int16) sizeof(int64))
{
if (alignment != TYPALIGN_DOUBLE)
ereport(ERROR,
@@ -294,7 +293,6 @@ TypeCreate(Oid newTypeOid,
errmsg("alignment \"%c\" is invalid for passed-by-value type of size %d",
alignment, internalSize)));
}
-#endif
else
ereport(ERROR,
(errcode(ERRCODE_INVALID_OBJECT_DEFINITION),
diff --git a/src/backend/catalog/sql_features.txt b/src/backend/catalog/sql_features.txt
index c002f37202f58..ebe85337c2877 100644
--- a/src/backend/catalog/sql_features.txt
+++ b/src/backend/catalog/sql_features.txt
@@ -281,7 +281,7 @@ F461 Named character sets NO
F471 Scalar subquery values YES
F481 Expanded NULL predicate YES
F491 Constraint management YES
-F492 Optional table constraint enforcement NO
+F492 Optional table constraint enforcement YES except not-null constraints
F501 Features and conformance views YES
F501 Features and conformance views 01 SQL_FEATURES view YES
F501 Features and conformance views 02 SQL_SIZING view YES
diff --git a/src/backend/catalog/storage.c b/src/backend/catalog/storage.c
index f56b3cc0f231b..c58e9418ac313 100644
--- a/src/backend/catalog/storage.c
+++ b/src/backend/catalog/storage.c
@@ -3,7 +3,7 @@
* storage.c
* code to create and destroy physical storage for relations
*
- * Portions Copyright (c) 1996-2024, PostgreSQL Global Development Group
+ * Portions Copyright (c) 1996-2025, PostgreSQL Global Development Group
* Portions Copyright (c) 1994, Regents of the University of California
*
*
@@ -27,6 +27,7 @@
#include "catalog/storage.h"
#include "catalog/storage_xlog.h"
#include "miscadmin.h"
+#include "pgstat.h"
#include "storage/bulk_write.h"
#include "storage/freespace.h"
#include "storage/proc.h"
@@ -194,7 +195,7 @@ log_smgrcreate(const RelFileLocator *rlocator, ForkNumber forkNum)
xlrec.forkNum = forkNum;
XLogBeginInsert();
- XLogRegisterData((char *) &xlrec, sizeof(xlrec));
+ XLogRegisterData(&xlrec, sizeof(xlrec));
XLogInsert(RM_SMGR_ID, XLOG_SMGR_CREATE | XLR_SPECIAL_REL_UPDATE);
}
@@ -291,6 +292,7 @@ RelationTruncate(Relation rel, BlockNumber nblocks)
bool vm;
bool need_fsm_vacuum = false;
ForkNumber forks[MAX_FORKNUM];
+ BlockNumber old_blocks[MAX_FORKNUM];
BlockNumber blocks[MAX_FORKNUM];
int nforks = 0;
SMgrRelation reln;
@@ -306,6 +308,7 @@ RelationTruncate(Relation rel, BlockNumber nblocks)
/* Prepare for truncation of MAIN fork of the relation */
forks[nforks] = MAIN_FORKNUM;
+ old_blocks[nforks] = smgrnblocks(reln, MAIN_FORKNUM);
blocks[nforks] = nblocks;
nforks++;
@@ -317,6 +320,7 @@ RelationTruncate(Relation rel, BlockNumber nblocks)
if (BlockNumberIsValid(blocks[nforks]))
{
forks[nforks] = FSM_FORKNUM;
+ old_blocks[nforks] = smgrnblocks(reln, FSM_FORKNUM);
nforks++;
need_fsm_vacuum = true;
}
@@ -330,6 +334,7 @@ RelationTruncate(Relation rel, BlockNumber nblocks)
if (BlockNumberIsValid(blocks[nforks]))
{
forks[nforks] = VISIBILITYMAP_FORKNUM;
+ old_blocks[nforks] = smgrnblocks(reln, VISIBILITYMAP_FORKNUM);
nforks++;
}
}
@@ -337,30 +342,49 @@ RelationTruncate(Relation rel, BlockNumber nblocks)
RelationPreTruncate(rel);
/*
- * Make sure that a concurrent checkpoint can't complete while truncation
- * is in progress.
+ * The code which follows can interact with concurrent checkpoints in two
+ * separate ways.
*
- * The truncation operation might drop buffers that the checkpoint
+ * First, the truncation operation might drop buffers that the checkpoint
* otherwise would have flushed. If it does, then it's essential that the
* files actually get truncated on disk before the checkpoint record is
* written. Otherwise, if reply begins from that checkpoint, the
* to-be-truncated blocks might still exist on disk but have older
* contents than expected, which can cause replay to fail. It's OK for the
* blocks to not exist on disk at all, but not for them to have the wrong
- * contents.
+ * contents. For this reason, we need to set DELAY_CHKPT_COMPLETE while
+ * this code executes.
+ *
+ * Second, the call to smgrtruncate() below will in turn call
+ * RegisterSyncRequest(). We need the sync request created by that call to
+ * be processed before the checkpoint completes. CheckPointGuts() will
+ * call ProcessSyncRequests(), but if we register our sync request after
+ * that happens, then the WAL record for the truncation could end up
+ * preceding the checkpoint record, while the actual sync doesn't happen
+ * until the next checkpoint. To prevent that, we need to set
+ * DELAY_CHKPT_START here. That way, if the XLOG_SMGR_TRUNCATE precedes
+ * the redo pointer of a concurrent checkpoint, we're guaranteed that the
+ * corresponding sync request will be processed before the checkpoint
+ * completes.
*/
- Assert((MyProc->delayChkptFlags & DELAY_CHKPT_COMPLETE) == 0);
- MyProc->delayChkptFlags |= DELAY_CHKPT_COMPLETE;
+ Assert((MyProc->delayChkptFlags & (DELAY_CHKPT_START | DELAY_CHKPT_COMPLETE)) == 0);
+ MyProc->delayChkptFlags |= DELAY_CHKPT_START | DELAY_CHKPT_COMPLETE;
/*
- * We WAL-log the truncation before actually truncating, which means
- * trouble if the truncation fails. If we then crash, the WAL replay
- * likely isn't going to succeed in the truncation either, and cause a
- * PANIC. It's tempting to put a critical section here, but that cure
- * would be worse than the disease. It would turn a usually harmless
- * failure to truncate, that might spell trouble at WAL replay, into a
- * certain PANIC.
+ * We WAL-log the truncation first and then truncate in a critical
+ * section. Truncation drops buffers, even if dirty, and then truncates
+ * disk files. All of that work needs to complete before the lock is
+ * released, or else old versions of pages on disk that are missing recent
+ * changes would become accessible again. We'll try the whole operation
+ * again in crash recovery if we panic, but even then we can't give up
+ * because we don't want standbys' relation sizes to diverge and break
+ * replay or visibility invariants downstream. The critical section also
+ * suppresses interrupts.
+ *
+ * (See also visibilitymap.c if changing this code.)
*/
+ START_CRIT_SECTION();
+
if (RelationNeedsWAL(rel))
{
/*
@@ -374,7 +398,7 @@ RelationTruncate(Relation rel, BlockNumber nblocks)
xlrec.flags = SMGR_TRUNCATE_ALL;
XLogBeginInsert();
- XLogRegisterData((char *) &xlrec, sizeof(xlrec));
+ XLogRegisterData(&xlrec, sizeof(xlrec));
lsn = XLogInsert(RM_SMGR_ID,
XLOG_SMGR_TRUNCATE | XLR_SPECIAL_REL_UPDATE);
@@ -384,10 +408,10 @@ RelationTruncate(Relation rel, BlockNumber nblocks)
* hit the disk before the WAL record, and the truncation of the FSM
* or visibility map. If we crashed during that window, we'd be left
* with a truncated heap, but the FSM or visibility map would still
- * contain entries for the non-existent heap pages.
+ * contain entries for the non-existent heap pages, and standbys would
+ * also never replay the truncation.
*/
- if (fsm || vm)
- XLogFlush(lsn);
+ XLogFlush(lsn);
}
/*
@@ -395,10 +419,12 @@ RelationTruncate(Relation rel, BlockNumber nblocks)
* longer exist after truncation is complete, and then truncate the
* corresponding files on disk.
*/
- smgrtruncate(RelationGetSmgr(rel), forks, nforks, blocks);
+ smgrtruncate(RelationGetSmgr(rel), forks, nforks, old_blocks, blocks);
+
+ END_CRIT_SECTION();
/* We've done all the critical work, so checkpoints are OK now. */
- MyProc->delayChkptFlags &= ~DELAY_CHKPT_COMPLETE;
+ MyProc->delayChkptFlags &= ~(DELAY_CHKPT_START | DELAY_CHKPT_COMPLETE);
/*
* Update upper-level FSM pages to account for the truncation. This is
@@ -482,6 +508,9 @@ RelationCopyStorage(SMgrRelation src, SMgrRelation dst,
for (blkno = 0; blkno < nblocks; blkno++)
{
BulkWriteBuffer buf;
+ int piv_flags;
+ bool checksum_failure;
+ bool verified;
/* If we got a cancel signal during the copy of the data, quit */
CHECK_FOR_INTERRUPTS();
@@ -489,8 +518,20 @@ RelationCopyStorage(SMgrRelation src, SMgrRelation dst,
buf = smgr_bulk_get_buf(bulkstate);
smgrread(src, forkNum, blkno, (Page) buf);
- if (!PageIsVerifiedExtended((Page) buf, blkno,
- PIV_LOG_WARNING | PIV_REPORT_STAT))
+ piv_flags = PIV_LOG_WARNING;
+ if (ignore_checksum_failure)
+ piv_flags |= PIV_IGNORE_CHECKSUM_FAILURE;
+ verified = PageIsVerified((Page) buf, blkno, piv_flags,
+ &checksum_failure);
+ if (checksum_failure)
+ {
+ RelFileLocatorBackend rloc = src->smgr_rlocator;
+
+ pgstat_prepare_report_checksum_failure(rloc.locator.dbOid);
+ pgstat_report_checksum_failures_in_db(rloc.locator.dbOid, 1);
+ }
+
+ if (!verified)
{
/*
* For paranoia's sake, capture the file path before invoking the
@@ -499,14 +540,14 @@ RelationCopyStorage(SMgrRelation src, SMgrRelation dst,
* (errcontext callbacks shouldn't be risking any such thing, but
* people have been known to forget that rule.)
*/
- char *relpath = relpathbackend(src->smgr_rlocator.locator,
+ RelPathStr relpath = relpathbackend(src->smgr_rlocator.locator,
src->smgr_rlocator.backend,
forkNum);
ereport(ERROR,
(errcode(ERRCODE_DATA_CORRUPTED),
- errmsg("invalid page in block %u of relation %s",
- blkno, relpath)));
+ errmsg("invalid page in block %u of relation \"%s\"",
+ blkno, relpath.str)));
}
/*
@@ -545,7 +586,7 @@ RelFileLocatorSkippingWAL(RelFileLocator rlocator)
Size
EstimatePendingSyncsSpace(void)
{
- long entries;
+ int64 entries;
entries = pendingSyncHash ? hash_get_num_entries(pendingSyncHash) : 0;
return mul_size(1 + entries, sizeof(RelFileLocator));
@@ -738,7 +779,7 @@ smgrDoPendingSyncs(bool isCommit, bool isParallelWorker)
{
ForkNumber fork;
BlockNumber nblocks[MAX_FORKNUM + 1];
- BlockNumber total_blocks = 0;
+ uint64 total_blocks = 0;
SMgrRelation srel;
srel = smgropen(pendingsync->rlocator, INVALID_PROC_NUMBER);
@@ -782,7 +823,7 @@ smgrDoPendingSyncs(bool isCommit, bool isParallelWorker)
* main fork is longer than ever but FSM fork gets shorter.
*/
if (pendingsync->is_truncated ||
- total_blocks * BLCKSZ / 1024 >= wal_skip_threshold)
+ total_blocks >= wal_skip_threshold * (uint64) 1024 / BLCKSZ)
{
/* allocate the initial array, or extend it, if needed */
if (maxrels == 0)
@@ -960,6 +1001,7 @@ smgr_redo(XLogReaderState *record)
Relation rel;
ForkNumber forks[MAX_FORKNUM];
BlockNumber blocks[MAX_FORKNUM];
+ BlockNumber old_blocks[MAX_FORKNUM];
int nforks = 0;
bool need_fsm_vacuum = false;
@@ -994,6 +1036,7 @@ smgr_redo(XLogReaderState *record)
if ((xlrec->flags & SMGR_TRUNCATE_HEAP) != 0)
{
forks[nforks] = MAIN_FORKNUM;
+ old_blocks[nforks] = smgrnblocks(reln, MAIN_FORKNUM);
blocks[nforks] = xlrec->blkno;
nforks++;
@@ -1011,6 +1054,7 @@ smgr_redo(XLogReaderState *record)
if (BlockNumberIsValid(blocks[nforks]))
{
forks[nforks] = FSM_FORKNUM;
+ old_blocks[nforks] = smgrnblocks(reln, FSM_FORKNUM);
nforks++;
need_fsm_vacuum = true;
}
@@ -1022,13 +1066,18 @@ smgr_redo(XLogReaderState *record)
if (BlockNumberIsValid(blocks[nforks]))
{
forks[nforks] = VISIBILITYMAP_FORKNUM;
+ old_blocks[nforks] = smgrnblocks(reln, VISIBILITYMAP_FORKNUM);
nforks++;
}
}
/* Do the real work to truncate relation forks */
if (nforks > 0)
- smgrtruncate(reln, forks, nforks, blocks);
+ {
+ START_CRIT_SECTION();
+ smgrtruncate(reln, forks, nforks, old_blocks, blocks);
+ END_CRIT_SECTION();
+ }
/*
* Update upper-level FSM pages to account for the truncation. This is
diff --git a/src/backend/catalog/system_functions.sql b/src/backend/catalog/system_functions.sql
index ae099e328c245..566f308e4439d 100644
--- a/src/backend/catalog/system_functions.sql
+++ b/src/backend/catalog/system_functions.sql
@@ -1,7 +1,7 @@
/*
* PostgreSQL System Functions
*
- * Copyright (c) 1996-2024, PostgreSQL Global Development Group
+ * Copyright (c) 1996-2025, PostgreSQL Global Development Group
*
* src/backend/catalog/system_functions.sql
*
@@ -607,6 +607,20 @@ LANGUAGE INTERNAL
STRICT STABLE PARALLEL SAFE
AS 'jsonb_path_query_first_tz';
+CREATE OR REPLACE FUNCTION
+ jsonb_strip_nulls(target jsonb, strip_in_arrays boolean DEFAULT false)
+RETURNS jsonb
+LANGUAGE INTERNAL
+STRICT STABLE PARALLEL SAFE
+AS 'jsonb_strip_nulls';
+
+CREATE OR REPLACE FUNCTION
+ json_strip_nulls(target json, strip_in_arrays boolean DEFAULT false)
+RETURNS json
+LANGUAGE INTERNAL
+STRICT STABLE PARALLEL SAFE
+AS 'json_strip_nulls';
+
-- default normalization form is NFC, per SQL standard
CREATE OR REPLACE FUNCTION
"normalize"(text, text DEFAULT 'NFC')
@@ -679,9 +693,11 @@ REVOKE EXECUTE ON FUNCTION pg_stat_reset_single_table_counters(oid) FROM public;
REVOKE EXECUTE ON FUNCTION pg_stat_reset_single_function_counters(oid) FROM public;
+REVOKE EXECUTE ON FUNCTION pg_stat_reset_backend_stats(integer) FROM public;
+
REVOKE EXECUTE ON FUNCTION pg_stat_reset_replication_slot(text) FROM public;
-REVOKE EXECUTE ON FUNCTION pg_stat_have_stats(text, oid, oid) FROM public;
+REVOKE EXECUTE ON FUNCTION pg_stat_have_stats(text, oid, int8) FROM public;
REVOKE EXECUTE ON FUNCTION pg_stat_reset_subscription_stats(oid) FROM public;
@@ -697,6 +713,8 @@ REVOKE EXECUTE ON FUNCTION pg_ls_waldir() FROM public;
REVOKE EXECUTE ON FUNCTION pg_ls_archive_statusdir() FROM public;
+REVOKE EXECUTE ON FUNCTION pg_ls_summariesdir() FROM public;
+
REVOKE EXECUTE ON FUNCTION pg_ls_tmpdir() FROM public;
REVOKE EXECUTE ON FUNCTION pg_ls_tmpdir(oid) FROM public;
@@ -767,6 +785,8 @@ GRANT EXECUTE ON FUNCTION pg_ls_waldir() TO pg_monitor;
GRANT EXECUTE ON FUNCTION pg_ls_archive_statusdir() TO pg_monitor;
+GRANT EXECUTE ON FUNCTION pg_ls_summariesdir() TO pg_monitor;
+
GRANT EXECUTE ON FUNCTION pg_ls_tmpdir() TO pg_monitor;
GRANT EXECUTE ON FUNCTION pg_ls_tmpdir(oid) TO pg_monitor;
diff --git a/src/backend/catalog/system_views.sql b/src/backend/catalog/system_views.sql
index 53047cab5fce1..c77fa0234bb7d 100644
--- a/src/backend/catalog/system_views.sql
+++ b/src/backend/catalog/system_views.sql
@@ -1,7 +1,7 @@
/*
* PostgreSQL System Views
*
- * Copyright (c) 1996-2024, PostgreSQL Global Development Group
+ * Copyright (c) 1996-2025, PostgreSQL Global Development Group
*
* src/backend/catalog/system_views.sql
*
@@ -176,11 +176,7 @@ CREATE VIEW pg_sequences AS
S.seqincrement AS increment_by,
S.seqcycle AS cycle,
S.seqcache AS cache_size,
- CASE
- WHEN has_sequence_privilege(C.oid, 'SELECT,USAGE'::text)
- THEN pg_sequence_last_value(C.oid)
- ELSE NULL
- END AS last_value
+ pg_sequence_last_value(C.oid) AS last_value
FROM pg_sequence S JOIN pg_class C ON (C.oid = S.seqrelid)
LEFT JOIN pg_namespace N ON (N.oid = C.relnamespace)
WHERE NOT pg_is_other_temp_schema(N.oid)
@@ -638,7 +634,12 @@ REVOKE ALL ON pg_ident_file_mappings FROM PUBLIC;
REVOKE EXECUTE ON FUNCTION pg_ident_file_mappings() FROM PUBLIC;
CREATE VIEW pg_timezone_abbrevs AS
- SELECT * FROM pg_timezone_abbrevs();
+ SELECT * FROM pg_timezone_abbrevs_zone() z
+ UNION ALL
+ (SELECT * FROM pg_timezone_abbrevs_abbrevs() a
+ WHERE NOT EXISTS (SELECT 1 FROM pg_timezone_abbrevs_zone() z2
+ WHERE z2.abbrev = a.abbrev))
+ ORDER BY abbrev;
CREATE VIEW pg_timezone_names AS
SELECT * FROM pg_timezone_names();
@@ -657,6 +658,22 @@ GRANT SELECT ON pg_shmem_allocations TO pg_read_all_stats;
REVOKE EXECUTE ON FUNCTION pg_get_shmem_allocations() FROM PUBLIC;
GRANT EXECUTE ON FUNCTION pg_get_shmem_allocations() TO pg_read_all_stats;
+CREATE VIEW pg_shmem_allocations_numa AS
+ SELECT * FROM pg_get_shmem_allocations_numa();
+
+REVOKE ALL ON pg_shmem_allocations_numa FROM PUBLIC;
+GRANT SELECT ON pg_shmem_allocations_numa TO pg_read_all_stats;
+REVOKE EXECUTE ON FUNCTION pg_get_shmem_allocations_numa() FROM PUBLIC;
+GRANT EXECUTE ON FUNCTION pg_get_shmem_allocations_numa() TO pg_read_all_stats;
+
+CREATE VIEW pg_dsm_registry_allocations AS
+ SELECT * FROM pg_get_dsm_registry_allocations();
+
+REVOKE ALL ON pg_dsm_registry_allocations FROM PUBLIC;
+GRANT SELECT ON pg_dsm_registry_allocations TO pg_read_all_stats;
+REVOKE EXECUTE ON FUNCTION pg_get_dsm_registry_allocations() FROM PUBLIC;
+GRANT EXECUTE ON FUNCTION pg_get_dsm_registry_allocations() TO pg_read_all_stats;
+
CREATE VIEW pg_backend_memory_contexts AS
SELECT * FROM pg_get_backend_memory_contexts();
@@ -695,7 +712,11 @@ CREATE VIEW pg_stat_all_tables AS
pg_stat_get_vacuum_count(C.oid) AS vacuum_count,
pg_stat_get_autovacuum_count(C.oid) AS autovacuum_count,
pg_stat_get_analyze_count(C.oid) AS analyze_count,
- pg_stat_get_autoanalyze_count(C.oid) AS autoanalyze_count
+ pg_stat_get_autoanalyze_count(C.oid) AS autoanalyze_count,
+ pg_stat_get_total_vacuum_time(C.oid) AS total_vacuum_time,
+ pg_stat_get_total_autovacuum_time(C.oid) AS total_autovacuum_time,
+ pg_stat_get_total_analyze_time(C.oid) AS total_analyze_time,
+ pg_stat_get_total_autoanalyze_time(C.oid) AS total_autoanalyze_time
FROM pg_class C LEFT JOIN
pg_index I ON C.oid = I.indrelid
LEFT JOIN pg_namespace N ON (N.oid = C.relnamespace)
@@ -882,7 +903,7 @@ CREATE VIEW pg_stat_activity AS
S.wait_event,
S.state,
S.backend_xid,
- s.backend_xmin,
+ S.backend_xmin,
S.query_id,
S.query,
S.backend_type
@@ -1020,6 +1041,7 @@ CREATE VIEW pg_replication_slots AS
L.wal_status,
L.safe_wal_size,
L.two_phase,
+ L.two_phase_at,
L.inactive_since,
L.conflicting,
L.invalidation_reason,
@@ -1077,6 +1099,8 @@ CREATE VIEW pg_stat_database AS
pg_stat_get_db_sessions_abandoned(D.oid) AS sessions_abandoned,
pg_stat_get_db_sessions_fatal(D.oid) AS sessions_fatal,
pg_stat_get_db_sessions_killed(D.oid) AS sessions_killed,
+ pg_stat_get_db_parallel_workers_to_launch(D.oid) as parallel_workers_to_launch,
+ pg_stat_get_db_parallel_workers_launched(D.oid) as parallel_workers_launched,
pg_stat_get_db_stat_reset_time(D.oid) AS stats_reset
FROM (
SELECT 0 AS oid, NULL::name AS datname
@@ -1142,12 +1166,14 @@ CREATE VIEW pg_stat_checkpointer AS
SELECT
pg_stat_get_checkpointer_num_timed() AS num_timed,
pg_stat_get_checkpointer_num_requested() AS num_requested,
+ pg_stat_get_checkpointer_num_performed() AS num_done,
pg_stat_get_checkpointer_restartpoints_timed() AS restartpoints_timed,
pg_stat_get_checkpointer_restartpoints_requested() AS restartpoints_req,
pg_stat_get_checkpointer_restartpoints_performed() AS restartpoints_done,
pg_stat_get_checkpointer_write_time() AS write_time,
pg_stat_get_checkpointer_sync_time() AS sync_time,
pg_stat_get_checkpointer_buffers_written() AS buffers_written,
+ pg_stat_get_checkpointer_slru_written() AS slru_written,
pg_stat_get_checkpointer_stat_reset_time() AS stats_reset;
CREATE VIEW pg_stat_io AS
@@ -1156,14 +1182,16 @@ SELECT
b.object,
b.context,
b.reads,
+ b.read_bytes,
b.read_time,
b.writes,
+ b.write_bytes,
b.write_time,
b.writebacks,
b.writeback_time,
b.extends,
+ b.extend_bytes,
b.extend_time,
- b.op_bytes,
b.hits,
b.evictions,
b.reuses,
@@ -1178,10 +1206,6 @@ CREATE VIEW pg_stat_wal AS
w.wal_fpi,
w.wal_bytes,
w.wal_buffers_full,
- w.wal_write,
- w.wal_sync,
- w.wal_write_time,
- w.wal_sync_time,
w.stats_reset
FROM pg_stat_get_wal() w;
@@ -1202,7 +1226,8 @@ CREATE VIEW pg_stat_progress_analyze AS
S.param5 AS ext_stats_computed,
S.param6 AS child_tables_total,
S.param7 AS child_tables_done,
- CAST(S.param8 AS oid) AS current_child_table_relid
+ CAST(S.param8 AS oid) AS current_child_table_relid,
+ S.param9 / 1000000::double precision AS delay_time
FROM pg_stat_get_progress_info('ANALYZE') AS S
LEFT JOIN pg_database D ON S.datid = D.oid;
@@ -1221,7 +1246,9 @@ CREATE VIEW pg_stat_progress_vacuum AS
S.param2 AS heap_blks_total, S.param3 AS heap_blks_scanned,
S.param4 AS heap_blks_vacuumed, S.param5 AS index_vacuum_count,
S.param6 AS max_dead_tuple_bytes, S.param7 AS dead_tuple_bytes,
- S.param8 AS indexes_total, S.param9 AS indexes_processed
+ S.param8 AS num_dead_item_ids, S.param9 AS indexes_total,
+ S.param10 AS indexes_processed,
+ S.param11 / 1000000::double precision AS delay_time
FROM pg_stat_get_progress_info('VACUUM') AS S
LEFT JOIN pg_database D ON S.datid = D.oid;
@@ -1300,7 +1327,10 @@ CREATE VIEW pg_stat_progress_basebackup AS
CASE S.param2 WHEN -1 THEN NULL ELSE S.param2 END AS backup_total,
S.param3 AS backup_streamed,
S.param4 AS tablespaces_total,
- S.param5 AS tablespaces_streamed
+ S.param5 AS tablespaces_streamed,
+ CASE S.param6 WHEN 1 THEN 'full'
+ WHEN 2 THEN 'incremental'
+ END AS backup_type
FROM pg_stat_get_progress_info('BASEBACKUP') AS S;
@@ -1359,6 +1389,7 @@ REVOKE ALL ON pg_subscription FROM public;
GRANT SELECT (oid, subdbid, subskiplsn, subname, subowner, subenabled,
subbinary, substream, subtwophasestate, subdisableonerr,
subpasswordrequired, subrunasowner, subfailover,
+ subretaindeadtuples, submaxretention, subretentionactive,
subslotname, subsynccommit, subpublications, suborigin)
ON pg_subscription TO public;
@@ -1368,9 +1399,24 @@ CREATE VIEW pg_stat_subscription_stats AS
s.subname,
ss.apply_error_count,
ss.sync_error_count,
+ ss.confl_insert_exists,
+ ss.confl_update_origin_differs,
+ ss.confl_update_exists,
+ ss.confl_update_deleted,
+ ss.confl_update_missing,
+ ss.confl_delete_origin_differs,
+ ss.confl_delete_missing,
+ ss.confl_multiple_unique_conflicts,
ss.stats_reset
FROM pg_subscription as s,
pg_stat_get_subscription_stats(s.oid) as ss;
CREATE VIEW pg_wait_events AS
SELECT * FROM pg_get_wait_events();
+
+CREATE VIEW pg_aios AS
+ SELECT * FROM pg_get_aios();
+REVOKE ALL ON pg_aios FROM PUBLIC;
+GRANT SELECT ON pg_aios TO pg_read_all_stats;
+REVOKE EXECUTE ON FUNCTION pg_get_aios() FROM PUBLIC;
+GRANT EXECUTE ON FUNCTION pg_get_aios() TO pg_read_all_stats;
diff --git a/src/backend/catalog/toasting.c b/src/backend/catalog/toasting.c
index 738bc46ae8293..874a8fc89adb3 100644
--- a/src/backend/catalog/toasting.c
+++ b/src/backend/catalog/toasting.c
@@ -4,7 +4,7 @@
* This file contains routines to support creation of toast tables
*
*
- * Portions Copyright (c) 1996-2024, PostgreSQL Global Development Group
+ * Portions Copyright (c) 1996-2025, PostgreSQL Global Development Group
* Portions Copyright (c) 1994, Regents of the University of California
*
* IDENTIFICATION
@@ -29,6 +29,7 @@
#include "catalog/toasting.h"
#include "miscadmin.h"
#include "nodes/makefuncs.h"
+#include "utils/fmgroids.h"
#include "utils/rel.h"
#include "utils/syscache.h"
@@ -333,21 +334,36 @@ create_toast_table(Relation rel, Oid toastOid, Oid toastIndexOid,
*/
class_rel = table_open(RelationRelationId, RowExclusiveLock);
- reltup = SearchSysCacheCopy1(RELOID, ObjectIdGetDatum(relOid));
- if (!HeapTupleIsValid(reltup))
- elog(ERROR, "cache lookup failed for relation %u", relOid);
-
- ((Form_pg_class) GETSTRUCT(reltup))->reltoastrelid = toast_relid;
-
if (!IsBootstrapProcessingMode())
{
/* normal case, use a transactional update */
+ reltup = SearchSysCacheCopy1(RELOID, ObjectIdGetDatum(relOid));
+ if (!HeapTupleIsValid(reltup))
+ elog(ERROR, "cache lookup failed for relation %u", relOid);
+
+ ((Form_pg_class) GETSTRUCT(reltup))->reltoastrelid = toast_relid;
+
CatalogTupleUpdate(class_rel, &reltup->t_self, reltup);
}
else
{
/* While bootstrapping, we cannot UPDATE, so overwrite in-place */
- heap_inplace_update(class_rel, reltup);
+
+ ScanKeyData key[1];
+ void *state;
+
+ ScanKeyInit(&key[0],
+ Anum_pg_class_oid,
+ BTEqualStrategyNumber, F_OIDEQ,
+ ObjectIdGetDatum(relOid));
+ systable_inplace_update_begin(class_rel, ClassOidIndexId, true,
+ NULL, 1, key, &reltup, &state);
+ if (!HeapTupleIsValid(reltup))
+ elog(ERROR, "cache lookup failed for relation %u", relOid);
+
+ ((Form_pg_class) GETSTRUCT(reltup))->reltoastrelid = toast_relid;
+
+ systable_inplace_update_finish(state, reltup);
}
heap_freetuple(reltup);
diff --git a/src/backend/commands/Makefile b/src/backend/commands/Makefile
index 48f7348f91c72..cb2fbdc7c6018 100644
--- a/src/backend/commands/Makefile
+++ b/src/backend/commands/Makefile
@@ -34,6 +34,9 @@ OBJS = \
dropcmds.o \
event_trigger.o \
explain.o \
+ explain_dr.o \
+ explain_format.o \
+ explain_state.o \
extension.o \
foreigncmds.o \
functioncmds.o \
diff --git a/src/backend/commands/aggregatecmds.c b/src/backend/commands/aggregatecmds.c
index fde5a2a0e0496..4268adfe78729 100644
--- a/src/backend/commands/aggregatecmds.c
+++ b/src/backend/commands/aggregatecmds.c
@@ -4,7 +4,7 @@
*
* Routines for aggregate-manipulation commands
*
- * Portions Copyright (c) 1996-2024, PostgreSQL Global Development Group
+ * Portions Copyright (c) 1996-2025, PostgreSQL Global Development Group
* Portions Copyright (c) 1994, Regents of the University of California
*
*
@@ -12,11 +12,11 @@
* src/backend/commands/aggregatecmds.c
*
* DESCRIPTION
- * The "DefineFoo" routines take the parse tree and pick out the
+ * The "DefineAggregate" routine takes the parse tree and picks out the
* appropriate arguments/flags, passing the results to the
- * corresponding "FooDefine" routines (in src/catalog) that do
- * the actual catalog-munging. These routines also verify permission
- * of the user to execute the command.
+ * "AggregateCreate" routine (in src/backend/catalog), which does the
+ * actual catalog-munging. DefineAggregate also verifies the permission of
+ * the user to execute the command.
*
*-------------------------------------------------------------------------
*/
diff --git a/src/backend/commands/alter.c b/src/backend/commands/alter.c
index 4f99ebb4470a6..cb75e11fced62 100644
--- a/src/backend/commands/alter.c
+++ b/src/backend/commands/alter.c
@@ -3,7 +3,7 @@
* alter.c
* Drivers for generic alter commands
*
- * Portions Copyright (c) 1996-2024, PostgreSQL Global Development Group
+ * Portions Copyright (c) 1996-2025, PostgreSQL Global Development Group
* Portions Copyright (c) 1994, Regents of the University of California
*
*
@@ -59,6 +59,7 @@
#include "miscadmin.h"
#include "replication/logicalworker.h"
#include "rewrite/rewriteDefine.h"
+#include "storage/lmgr.h"
#include "utils/acl.h"
#include "utils/builtins.h"
#include "utils/lsyscache.h"
@@ -219,7 +220,7 @@ AlterObjectRename_internal(Relation rel, Oid objectId, const char *new_name)
Assert(!isnull);
ownerId = DatumGetObjectId(datum);
- if (!has_privs_of_role(GetUserId(), DatumGetObjectId(ownerId)))
+ if (!has_privs_of_role(GetUserId(), ownerId))
aclcheck_error(ACLCHECK_NOT_OWNER, get_object_type(classId, objectId),
old_name);
@@ -337,6 +338,22 @@ AlterObjectRename_internal(Relation rel, Oid objectId, const char *new_name)
InvokeObjectPostAlterHook(classId, objectId, 0);
+ /* Do post catalog-update tasks */
+ if (classId == PublicationRelationId)
+ {
+ Form_pg_publication pub = (Form_pg_publication) GETSTRUCT(oldtup);
+
+ /*
+ * Invalidate relsynccache entries.
+ *
+ * Unlike ALTER PUBLICATION ADD/SET/DROP commands, renaming a
+ * publication does not impact the publication status of tables. So,
+ * we don't need to invalidate relcache to rebuild the rd_pubdesc.
+ * Instead, we invalidate only the relsyncache.
+ */
+ InvalidatePubRelSyncCache(pub->oid, pub->puballtables);
+ }
+
/* Release memory */
pfree(values);
pfree(nulls);
@@ -421,13 +438,11 @@ ExecRenameStmt(RenameStmt *stmt)
{
ObjectAddress address;
Relation catalog;
- Relation relation;
address = get_object_address(stmt->renameType,
stmt->object,
- &relation,
+ NULL,
AccessExclusiveLock, false);
- Assert(relation == NULL);
catalog = table_open(address.classId, RowExclusiveLock);
AlterObjectRename_internal(catalog,
@@ -482,8 +497,7 @@ ExecAlterObjectDependsStmt(AlterObjectDependsStmt *stmt, ObjectAddress *refAddre
table_close(rel, NoLock);
refAddr = get_object_address(OBJECT_EXTENSION, (Node *) stmt->extname,
- &rel, AccessExclusiveLock, false);
- Assert(rel == NULL);
+ NULL, AccessExclusiveLock, false);
if (refAddress)
*refAddress = refAddr;
@@ -563,16 +577,14 @@ ExecAlterObjectSchemaStmt(AlterObjectSchemaStmt *stmt,
case OBJECT_TSTEMPLATE:
{
Relation catalog;
- Relation relation;
Oid classId;
Oid nspOid;
address = get_object_address(stmt->objectType,
stmt->object,
- &relation,
+ NULL,
AccessExclusiveLock,
false);
- Assert(relation == NULL);
classId = address.classId;
catalog = table_open(classId, RowExclusiveLock);
nspOid = LookupCreationNamespace(stmt->newschema);
@@ -876,15 +888,13 @@ ExecAlterOwnerStmt(AlterOwnerStmt *stmt)
case OBJECT_TSDICTIONARY:
case OBJECT_TSCONFIGURATION:
{
- Relation relation;
ObjectAddress address;
address = get_object_address(stmt->objectType,
stmt->object,
- &relation,
+ NULL,
AccessExclusiveLock,
false);
- Assert(relation == NULL);
AlterObjectOwner_internal(address.classId, address.objectId,
newowner);
@@ -931,7 +941,9 @@ AlterObjectOwner_internal(Oid classId, Oid objectId, Oid new_ownerId)
rel = table_open(catalogId, RowExclusiveLock);
- oldtup = get_catalog_object_by_oid(rel, Anum_oid, objectId);
+ /* Search tuple and lock it. */
+ oldtup =
+ get_catalog_object_by_oid_extended(rel, Anum_oid, objectId, true);
if (oldtup == NULL)
elog(ERROR, "cache lookup failed for object %u of catalog \"%s\"",
objectId, RelationGetRelationName(rel));
@@ -1031,6 +1043,8 @@ AlterObjectOwner_internal(Oid classId, Oid objectId, Oid new_ownerId)
/* Perform actual update */
CatalogTupleUpdate(rel, &newtup->t_self, newtup);
+ UnlockTuple(rel, &oldtup->t_self, InplaceUpdateTupleLock);
+
/* Update owner dependency reference */
changeDependencyOnOwner(classId, objectId, new_ownerId);
@@ -1039,6 +1053,8 @@ AlterObjectOwner_internal(Oid classId, Oid objectId, Oid new_ownerId)
pfree(nulls);
pfree(replaces);
}
+ else
+ UnlockTuple(rel, &oldtup->t_self, InplaceUpdateTupleLock);
/* Note the post-alter hook gets classId not catalogId */
InvokeObjectPostAlterHook(classId, objectId, 0);
diff --git a/src/backend/commands/amcmds.c b/src/backend/commands/amcmds.c
index aaa0f9a1dc8c9..58ed9d216cc01 100644
--- a/src/backend/commands/amcmds.c
+++ b/src/backend/commands/amcmds.c
@@ -3,7 +3,7 @@
* amcmds.c
* Routines for SQL commands that manipulate access methods.
*
- * Portions Copyright (c) 1996-2024, PostgreSQL Global Development Group
+ * Portions Copyright (c) 1996-2025, PostgreSQL Global Development Group
* Portions Copyright (c) 1994, Regents of the University of California
*
*
diff --git a/src/backend/commands/analyze.c b/src/backend/commands/analyze.c
index 7d2cd24997292..8ea2913d90632 100644
--- a/src/backend/commands/analyze.c
+++ b/src/backend/commands/analyze.c
@@ -3,7 +3,7 @@
* analyze.c
* the Postgres statistics generator
*
- * Portions Copyright (c) 1996-2024, PostgreSQL Global Development Group
+ * Portions Copyright (c) 1996-2025, PostgreSQL Global Development Group
* Portions Copyright (c) 1994, Regents of the University of California
*
*
@@ -29,7 +29,6 @@
#include "catalog/index.h"
#include "catalog/indexing.h"
#include "catalog/pg_inherits.h"
-#include "commands/dbcommands.h"
#include "commands/progress.h"
#include "commands/tablecmds.h"
#include "commands/vacuum.h"
@@ -41,7 +40,6 @@
#include "parser/parse_oper.h"
#include "parser/parse_relation.h"
#include "pgstat.h"
-#include "postmaster/autovacuum.h"
#include "statistics/extended_stats_internal.h"
#include "statistics/statistics.h"
#include "storage/bufmgr.h"
@@ -54,7 +52,6 @@
#include "utils/pg_rusage.h"
#include "utils/sampling.h"
#include "utils/sortsupport.h"
-#include "utils/spccache.h"
#include "utils/syscache.h"
#include "utils/timestamp.h"
@@ -78,7 +75,7 @@ static BufferAccessStrategy vac_strategy;
static void do_analyze_rel(Relation onerel,
- VacuumParams *params, List *va_cols,
+ const VacuumParams params, List *va_cols,
AcquireSampleRowsFunc acquirefunc, BlockNumber relpages,
bool inh, bool in_outer_xact, int elevel);
static void compute_index_stats(Relation onerel, double totalrows,
@@ -109,7 +106,7 @@ static Datum ind_fetch_func(VacAttrStatsP stats, int rownum, bool *isNull);
*/
void
analyze_rel(Oid relid, RangeVar *relation,
- VacuumParams *params, List *va_cols, bool in_outer_xact,
+ const VacuumParams params, List *va_cols, bool in_outer_xact,
BufferAccessStrategy bstrategy)
{
Relation onerel;
@@ -118,7 +115,7 @@ analyze_rel(Oid relid, RangeVar *relation,
BlockNumber relpages = 0;
/* Select logging level */
- if (params->options & VACOPT_VERBOSE)
+ if (params.options & VACOPT_VERBOSE)
elevel = INFO;
else
elevel = DEBUG2;
@@ -140,8 +137,8 @@ analyze_rel(Oid relid, RangeVar *relation,
*
* Make sure to generate only logs for ANALYZE in this case.
*/
- onerel = vacuum_open_relation(relid, relation, params->options & ~(VACOPT_VACUUM),
- params->log_min_duration >= 0,
+ onerel = vacuum_open_relation(relid, relation, params.options & ~(VACOPT_VACUUM),
+ params.log_min_duration >= 0,
ShareUpdateExclusiveLock);
/* leave if relation could not be opened or locked */
@@ -157,7 +154,7 @@ analyze_rel(Oid relid, RangeVar *relation,
*/
if (!vacuum_is_permitted_for_relation(RelationGetRelid(onerel),
onerel->rd_rel,
- params->options & ~VACOPT_VACUUM))
+ params.options & ~VACOPT_VACUUM))
{
relation_close(onerel, ShareUpdateExclusiveLock);
return;
@@ -229,7 +226,7 @@ analyze_rel(Oid relid, RangeVar *relation,
else
{
/* No need for a WARNING if we already complained during VACUUM */
- if (!(params->options & VACOPT_VACUUM))
+ if (!(params.options & VACOPT_VACUUM))
ereport(WARNING,
(errmsg("skipping \"%s\" --- cannot analyze non-tables or special system tables",
RelationGetRelationName(onerel))));
@@ -277,7 +274,7 @@ analyze_rel(Oid relid, RangeVar *relation,
* appropriate acquirefunc for each child table.
*/
static void
-do_analyze_rel(Relation onerel, VacuumParams *params,
+do_analyze_rel(Relation onerel, const VacuumParams params,
List *va_cols, AcquireSampleRowsFunc acquirefunc,
BlockNumber relpages, bool inh, bool in_outer_xact,
int elevel)
@@ -288,7 +285,9 @@ do_analyze_rel(Relation onerel, VacuumParams *params,
ind;
Relation *Irel;
int nindexes;
- bool hasindex;
+ bool verbose,
+ instrument,
+ hasindex;
VacAttrStats **vacattrstats;
AnlIndexData *indexdata;
int targrows,
@@ -303,12 +302,15 @@ do_analyze_rel(Relation onerel, VacuumParams *params,
Oid save_userid;
int save_sec_context;
int save_nestlevel;
- int64 AnalyzePageHit = VacuumPageHit;
- int64 AnalyzePageMiss = VacuumPageMiss;
- int64 AnalyzePageDirty = VacuumPageDirty;
+ WalUsage startwalusage = pgWalUsage;
+ BufferUsage startbufferusage = pgBufferUsage;
+ BufferUsage bufferusage;
PgStat_Counter startreadtime = 0;
PgStat_Counter startwritetime = 0;
+ verbose = (params.options & VACOPT_VERBOSE) != 0;
+ instrument = (verbose || (AmAutoVacuumWorkerProcess() &&
+ params.log_min_duration >= 0));
if (inh)
ereport(elevel,
(errmsg("analyzing \"%s.%s\" inheritance tree",
@@ -340,8 +342,11 @@ do_analyze_rel(Relation onerel, VacuumParams *params,
save_nestlevel = NewGUCNestLevel();
RestrictSearchPath();
- /* measure elapsed time iff autovacuum logging requires it */
- if (AmAutoVacuumWorkerProcess() && params->log_min_duration >= 0)
+ /*
+ * When verbose or autovacuum logging is used, initialize a resource usage
+ * snapshot and optionally track I/O timing.
+ */
+ if (instrument)
{
if (track_io_timing)
{
@@ -350,9 +355,11 @@ do_analyze_rel(Relation onerel, VacuumParams *params,
}
pg_rusage_init(&ru0);
- starttime = GetCurrentTimestamp();
}
+ /* Used for instrumentation and stats report */
+ starttime = GetCurrentTimestamp();
+
/*
* Determine which columns to analyze
*
@@ -622,18 +629,22 @@ do_analyze_rel(Relation onerel, VacuumParams *params,
*/
if (!inh)
{
- BlockNumber relallvisible;
+ BlockNumber relallvisible = 0;
+ BlockNumber relallfrozen = 0;
if (RELKIND_HAS_STORAGE(onerel->rd_rel->relkind))
- visibilitymap_count(onerel, &relallvisible, NULL);
- else
- relallvisible = 0;
+ visibilitymap_count(onerel, &relallvisible, &relallfrozen);
- /* Update pg_class for table relation */
+ /*
+ * Update pg_class for table relation. CCI first, in case acquirefunc
+ * updated pg_class.
+ */
+ CommandCounterIncrement();
vac_update_relstats(onerel,
relpages,
totalrows,
relallvisible,
+ relallfrozen,
hasindex,
InvalidTransactionId,
InvalidMultiXactId,
@@ -650,7 +661,7 @@ do_analyze_rel(Relation onerel, VacuumParams *params,
vac_update_relstats(Irel[ind],
RelationGetNumberOfBlocks(Irel[ind]),
totalindexrows,
- 0,
+ 0, 0,
false,
InvalidTransactionId,
InvalidMultiXactId,
@@ -664,8 +675,9 @@ do_analyze_rel(Relation onerel, VacuumParams *params,
* Partitioned tables don't have storage, so we don't set any fields
* in their pg_class entries except for reltuples and relhasindex.
*/
+ CommandCounterIncrement();
vac_update_relstats(onerel, -1, totalrows,
- 0, hasindex, InvalidTransactionId,
+ 0, 0, hasindex, InvalidTransactionId,
InvalidMultiXactId,
NULL, NULL,
in_outer_xact);
@@ -677,14 +689,14 @@ do_analyze_rel(Relation onerel, VacuumParams *params,
* only do it for inherited stats. (We're never called for not-inherited
* stats on partitioned tables anyway.)
*
- * Reset the changes_since_analyze counter only if we analyzed all
- * columns; otherwise, there is still work for auto-analyze to do.
+ * Reset the mod_since_analyze counter only if we analyzed all columns;
+ * otherwise, there is still work for auto-analyze to do.
*/
if (!inh)
pgstat_report_analyze(onerel, totalrows, totaldeadrows,
- (va_cols == NIL));
+ (va_cols == NIL), starttime);
else if (onerel->rd_rel->relkind == RELKIND_PARTITIONED_TABLE)
- pgstat_report_analyze(onerel, 0, 0, (va_cols == NIL));
+ pgstat_report_analyze(onerel, 0, 0, (va_cols == NIL), starttime);
/*
* If this isn't part of VACUUM ANALYZE, let index AMs do cleanup.
@@ -693,7 +705,7 @@ do_analyze_rel(Relation onerel, VacuumParams *params,
* amvacuumcleanup() when called in ANALYZE-only mode. The only exception
* among core index AMs is GIN/ginvacuumcleanup().
*/
- if (!(params->options & VACOPT_VACUUM))
+ if (!(params.options & VACOPT_VACUUM))
{
for (ind = 0; ind < nindexes; ind++)
{
@@ -719,27 +731,35 @@ do_analyze_rel(Relation onerel, VacuumParams *params,
vac_close_indexes(nindexes, Irel, NoLock);
/* Log the action if appropriate */
- if (AmAutoVacuumWorkerProcess() && params->log_min_duration >= 0)
+ if (instrument)
{
TimestampTz endtime = GetCurrentTimestamp();
- if (params->log_min_duration == 0 ||
+ if (verbose || params.log_min_duration == 0 ||
TimestampDifferenceExceeds(starttime, endtime,
- params->log_min_duration))
+ params.log_min_duration))
{
long delay_in_ms;
+ WalUsage walusage;
double read_rate = 0;
double write_rate = 0;
+ char *msgfmt;
StringInfoData buf;
-
- /*
- * Calculate the difference in the Page Hit/Miss/Dirty that
- * happened as part of the analyze by subtracting out the
- * pre-analyze values which we saved above.
- */
- AnalyzePageHit = VacuumPageHit - AnalyzePageHit;
- AnalyzePageMiss = VacuumPageMiss - AnalyzePageMiss;
- AnalyzePageDirty = VacuumPageDirty - AnalyzePageDirty;
+ int64 total_blks_hit;
+ int64 total_blks_read;
+ int64 total_blks_dirtied;
+
+ memset(&bufferusage, 0, sizeof(BufferUsage));
+ BufferUsageAccumDiff(&bufferusage, &pgBufferUsage, &startbufferusage);
+ memset(&walusage, 0, sizeof(WalUsage));
+ WalUsageAccumDiff(&walusage, &pgWalUsage, &startwalusage);
+
+ total_blks_hit = bufferusage.shared_blks_hit +
+ bufferusage.local_blks_hit;
+ total_blks_read = bufferusage.shared_blks_read +
+ bufferusage.local_blks_read;
+ total_blks_dirtied = bufferusage.shared_blks_dirtied +
+ bufferusage.local_blks_dirtied;
/*
* We do not expect an analyze to take > 25 days and it simplifies
@@ -765,10 +785,10 @@ do_analyze_rel(Relation onerel, VacuumParams *params,
if (delay_in_ms > 0)
{
- read_rate = (double) BLCKSZ * AnalyzePageMiss / (1024 * 1024) /
- (delay_in_ms / 1000.0);
- write_rate = (double) BLCKSZ * AnalyzePageDirty / (1024 * 1024) /
- (delay_in_ms / 1000.0);
+ read_rate = (double) BLCKSZ * total_blks_read /
+ (1024 * 1024) / (delay_in_ms / 1000.0);
+ write_rate = (double) BLCKSZ * total_blks_dirtied /
+ (1024 * 1024) / (delay_in_ms / 1000.0);
}
/*
@@ -777,10 +797,25 @@ do_analyze_rel(Relation onerel, VacuumParams *params,
*/
initStringInfo(&buf);
- appendStringInfo(&buf, _("automatic analyze of table \"%s.%s.%s\"\n"),
+
+ if (AmAutoVacuumWorkerProcess())
+ msgfmt = _("automatic analyze of table \"%s.%s.%s\"\n");
+ else
+ msgfmt = _("finished analyzing table \"%s.%s.%s\"\n");
+
+ appendStringInfo(&buf, msgfmt,
get_database_name(MyDatabaseId),
get_namespace_name(RelationGetNamespace(onerel)),
RelationGetRelationName(onerel));
+ if (track_cost_delay_timing)
+ {
+ /*
+ * We bypass the changecount mechanism because this value is
+ * only updated by the calling process.
+ */
+ appendStringInfo(&buf, _("delay time: %.3f ms\n"),
+ (double) MyBEEntry->st_progress_param[PROGRESS_ANALYZE_DELAY_TIME] / 1000000.0);
+ }
if (track_io_timing)
{
double read_ms = (double) (pgStatBlockReadTime - startreadtime) / 1000;
@@ -791,13 +826,19 @@ do_analyze_rel(Relation onerel, VacuumParams *params,
}
appendStringInfo(&buf, _("avg read rate: %.3f MB/s, avg write rate: %.3f MB/s\n"),
read_rate, write_rate);
- appendStringInfo(&buf, _("buffer usage: %lld hits, %lld misses, %lld dirtied\n"),
- (long long) AnalyzePageHit,
- (long long) AnalyzePageMiss,
- (long long) AnalyzePageDirty);
+ appendStringInfo(&buf, _("buffer usage: %" PRId64 " hits, %" PRId64 " reads, %" PRId64 " dirtied\n"),
+ total_blks_hit,
+ total_blks_read,
+ total_blks_dirtied);
+ appendStringInfo(&buf,
+ _("WAL usage: %" PRId64 " records, %" PRId64 " full page images, %" PRIu64 " bytes, %" PRId64 " buffers full\n"),
+ walusage.wal_records,
+ walusage.wal_fpi,
+ walusage.wal_bytes,
+ walusage.wal_buffers_full);
appendStringInfo(&buf, _("system usage: %s"), pg_rusage_show(&ru0));
- ereport(LOG,
+ ereport(verbose ? INFO : LOG,
(errmsg_internal("%s", buf.data)));
pfree(buf.data);
@@ -883,7 +924,7 @@ compute_index_stats(Relation onerel, double totalrows,
{
HeapTuple heapTuple = rows[rowno];
- vacuum_delay_point();
+ vacuum_delay_point(true);
/*
* Reset the per-tuple context each time, to reclaim any cruft
@@ -1007,6 +1048,10 @@ examine_attribute(Relation onerel, int attnum, Node *index_expr)
if (attr->attisdropped)
return NULL;
+ /* Don't analyze virtual generated columns */
+ if (attr->attgenerated == ATTRIBUTE_GENERATED_VIRTUAL)
+ return NULL;
+
/*
* Get attstattarget value. Set to -1 if null. (Analyze functions expect
* -1 to mean use default_statistics_target; see for example
@@ -1191,7 +1236,12 @@ acquire_sample_rows(Relation onerel, int elevel,
scan = table_beginscan_analyze(onerel);
slot = table_slot_create(onerel, NULL);
- stream = read_stream_begin_relation(READ_STREAM_MAINTENANCE,
+ /*
+ * It is safe to use batching, as block_sampling_read_stream_next never
+ * blocks.
+ */
+ stream = read_stream_begin_relation(READ_STREAM_MAINTENANCE |
+ READ_STREAM_USE_BATCHING,
vac_strategy,
scan->rs_rd,
MAIN_FORKNUM,
@@ -1202,7 +1252,7 @@ acquire_sample_rows(Relation onerel, int elevel,
/* Outer loop over blocks to sample */
while (table_scan_analyze_next_block(scan, stream))
{
- vacuum_delay_point();
+ vacuum_delay_point(true);
while (table_scan_analyze_next_tuple(scan, OldestXmin, &liverows, &deadrows, slot))
{
@@ -1934,7 +1984,7 @@ compute_trivial_stats(VacAttrStatsP stats,
Datum value;
bool isnull;
- vacuum_delay_point();
+ vacuum_delay_point(true);
value = fetchfunc(stats, i, &isnull);
@@ -2050,7 +2100,7 @@ compute_distinct_stats(VacAttrStatsP stats,
int firstcount1,
j;
- vacuum_delay_point();
+ vacuum_delay_point(true);
value = fetchfunc(stats, i, &isnull);
@@ -2397,7 +2447,7 @@ compute_scalar_stats(VacAttrStatsP stats,
Datum value;
bool isnull;
- vacuum_delay_point();
+ vacuum_delay_point(true);
value = fetchfunc(stats, i, &isnull);
diff --git a/src/backend/commands/async.c b/src/backend/commands/async.c
index ab4c72762d84b..4bd37d5beb559 100644
--- a/src/backend/commands/async.c
+++ b/src/backend/commands/async.c
@@ -3,7 +3,7 @@
* async.c
* Asynchronous notification: NOTIFY, LISTEN, UNLISTEN
*
- * Portions Copyright (c) 1996-2024, PostgreSQL Global Development Group
+ * Portions Copyright (c) 1996-2025, PostgreSQL Global Development Group
* Portions Copyright (c) 1994, Regents of the University of California
*
* IDENTIFICATION
@@ -283,7 +283,7 @@ typedef struct AsyncQueueControl
QueuePosition head; /* head points to the next free location */
QueuePosition tail; /* tail must be <= the queue position of every
* listening backend */
- int stopPage; /* oldest unrecycled page; must be <=
+ int64 stopPage; /* oldest unrecycled page; must be <=
* tail.page */
ProcNumber firstListener; /* id of first listener, or
* INVALID_PROC_NUMBER */
@@ -1271,9 +1271,9 @@ asyncQueueUnregister(void)
static bool
asyncQueueIsFull(void)
{
- int headPage = QUEUE_POS_PAGE(QUEUE_HEAD);
- int tailPage = QUEUE_POS_PAGE(QUEUE_TAIL);
- int occupied = headPage - tailPage;
+ int64 headPage = QUEUE_POS_PAGE(QUEUE_HEAD);
+ int64 tailPage = QUEUE_POS_PAGE(QUEUE_TAIL);
+ int64 occupied = headPage - tailPage;
return occupied >= max_notify_queue_pages;
}
@@ -1505,9 +1505,9 @@ pg_notification_queue_usage(PG_FUNCTION_ARGS)
static double
asyncQueueUsage(void)
{
- int headPage = QUEUE_POS_PAGE(QUEUE_HEAD);
- int tailPage = QUEUE_POS_PAGE(QUEUE_TAIL);
- int occupied = headPage - tailPage;
+ int64 headPage = QUEUE_POS_PAGE(QUEUE_HEAD);
+ int64 tailPage = QUEUE_POS_PAGE(QUEUE_TAIL);
+ int64 occupied = headPage - tailPage;
if (occupied == 0)
return (double) 0; /* fast exit for common case */
@@ -1932,7 +1932,7 @@ asyncQueueReadAllNotifications(void)
do
{
- int curpage = QUEUE_POS_PAGE(pos);
+ int64 curpage = QUEUE_POS_PAGE(pos);
int curoffset = QUEUE_POS_OFFSET(pos);
int slotno;
int copysize;
@@ -2108,9 +2108,9 @@ static void
asyncQueueAdvanceTail(void)
{
QueuePosition min;
- int oldtailpage;
- int newtailpage;
- int boundary;
+ int64 oldtailpage;
+ int64 newtailpage;
+ int64 boundary;
/* Restrict task to one backend per cluster; see SimpleLruTruncate(). */
LWLockAcquire(NotifyQueueTailLock, LW_EXCLUSIVE);
diff --git a/src/backend/commands/cluster.c b/src/backend/commands/cluster.c
index 78f96789b0e84..b55221d44cd00 100644
--- a/src/backend/commands/cluster.c
+++ b/src/backend/commands/cluster.c
@@ -6,7 +6,7 @@
* There is hardly anything left of Paul Brown's original implementation...
*
*
- * Portions Copyright (c) 1996-2024, PostgreSQL Global Development Group
+ * Portions Copyright (c) 1996-2025, PostgreSQL Global Development Group
* Portions Copyright (c) 1994-5, Regents of the University of California
*
*
@@ -32,7 +32,6 @@
#include "catalog/namespace.h"
#include "catalog/objectaccess.h"
#include "catalog/pg_am.h"
-#include "catalog/pg_database.h"
#include "catalog/pg_inherits.h"
#include "catalog/toasting.h"
#include "commands/cluster.h"
@@ -70,8 +69,8 @@ typedef struct
static void cluster_multiple_rels(List *rtcs, ClusterParams *params);
-static void rebuild_relation(Relation OldHeap, Oid indexOid, bool verbose);
-static void copy_table_data(Oid OIDNewHeap, Oid OIDOldHeap, Oid OIDOldIndex,
+static void rebuild_relation(Relation OldHeap, Relation index, bool verbose);
+static void copy_table_data(Relation NewHeap, Relation OldHeap, Relation OldIndex,
bool verbose, bool *pSwapToastByContent,
TransactionId *pFreezeXid, MultiXactId *pCutoffMulti);
static List *get_tables_to_cluster(MemoryContext cluster_context);
@@ -192,13 +191,11 @@ cluster(ParseState *pstate, ClusterStmt *stmt, bool isTopLevel)
stmt->indexname, stmt->relation->relname)));
}
+ /* For non-partitioned tables, do what we came here to do. */
if (rel->rd_rel->relkind != RELKIND_PARTITIONED_TABLE)
{
- /* close relation, keep lock till commit */
- table_close(rel, NoLock);
-
- /* Do the job. */
- cluster_rel(tableOid, indexOid, ¶ms);
+ cluster_rel(rel, indexOid, ¶ms);
+ /* cluster_rel closes the relation, but keeps lock */
return;
}
@@ -275,6 +272,7 @@ cluster_multiple_rels(List *rtcs, ClusterParams *params)
foreach(lc, rtcs)
{
RelToCluster *rtc = (RelToCluster *) lfirst(lc);
+ Relation rel;
/* Start a new transaction for each relation. */
StartTransactionCommand();
@@ -282,8 +280,11 @@ cluster_multiple_rels(List *rtcs, ClusterParams *params)
/* functions in indexes may want a snapshot set */
PushActiveSnapshot(GetTransactionSnapshot());
- /* Do the job. */
- cluster_rel(rtc->tableOid, rtc->indexOid, params);
+ rel = table_open(rtc->tableOid, AccessExclusiveLock);
+
+ /* Process this table */
+ cluster_rel(rel, rtc->indexOid, params);
+ /* cluster_rel closes the relation, but keeps lock */
PopActiveSnapshot();
CommitTransactionCommand();
@@ -296,8 +297,7 @@ cluster_multiple_rels(List *rtcs, ClusterParams *params)
* This clusters the table by creating a new, clustered table and
* swapping the relfilenumbers of the new table and the old table, so
* the OID of the original table is preserved. Thus we do not lose
- * GRANT, inheritance nor references to this table (this was a bug
- * in releases through 7.3).
+ * GRANT, inheritance nor references to this table.
*
* Indexes are rebuilt too, via REINDEX. Since we are effectively bulk-loading
* the new table, it's better to create the indexes afterwards than to fill
@@ -308,14 +308,17 @@ cluster_multiple_rels(List *rtcs, ClusterParams *params)
* and error messages should refer to the operation as VACUUM not CLUSTER.
*/
void
-cluster_rel(Oid tableOid, Oid indexOid, ClusterParams *params)
+cluster_rel(Relation OldHeap, Oid indexOid, ClusterParams *params)
{
- Relation OldHeap;
+ Oid tableOid = RelationGetRelid(OldHeap);
Oid save_userid;
int save_sec_context;
int save_nestlevel;
bool verbose = ((params->options & CLUOPT_VERBOSE) != 0);
bool recheck = ((params->options & CLUOPT_RECHECK) != 0);
+ Relation index;
+
+ Assert(CheckRelationLockedByMe(OldHeap, AccessExclusiveLock, false));
/* Check for user-requested abort. */
CHECK_FOR_INTERRUPTS();
@@ -328,21 +331,6 @@ cluster_rel(Oid tableOid, Oid indexOid, ClusterParams *params)
pgstat_progress_update_param(PROGRESS_CLUSTER_COMMAND,
PROGRESS_CLUSTER_COMMAND_VACUUM_FULL);
- /*
- * We grab exclusive access to the target rel and index for the duration
- * of the transaction. (This is redundant for the single-transaction
- * case, since cluster() already did it.) The index lock is taken inside
- * check_index_is_clusterable.
- */
- OldHeap = try_relation_open(tableOid, AccessExclusiveLock);
-
- /* If the table has gone away, we can skip processing it */
- if (!OldHeap)
- {
- pgstat_progress_end_command();
- return;
- }
-
/*
* Switch to the table owner's userid, so that any index functions are run
* as that user. Also lock down security-restricted operations and
@@ -445,7 +433,14 @@ cluster_rel(Oid tableOid, Oid indexOid, ClusterParams *params)
/* Check heap and index are valid to cluster on */
if (OidIsValid(indexOid))
+ {
+ /* verify the index is good and lock it */
check_index_is_clusterable(OldHeap, indexOid, AccessExclusiveLock);
+ /* also open it */
+ index = index_open(indexOid, NoLock);
+ }
+ else
+ index = NULL;
/*
* Quietly ignore the request if this is a materialized view which has not
@@ -474,9 +469,8 @@ cluster_rel(Oid tableOid, Oid indexOid, ClusterParams *params)
TransferPredicateLocksToHeapRelation(OldHeap);
/* rebuild_relation does all the dirty work */
- rebuild_relation(OldHeap, indexOid, verbose);
-
- /* NB: rebuild_relation does table_close() on OldHeap */
+ rebuild_relation(OldHeap, index, verbose);
+ /* rebuild_relation closes OldHeap, and index if valid */
out:
/* Roll back any GUC changes executed by index functions */
@@ -624,45 +618,68 @@ mark_index_clustered(Relation rel, Oid indexOid, bool is_internal)
/*
* rebuild_relation: rebuild an existing relation in index or physical order
*
- * OldHeap: table to rebuild --- must be opened and exclusive-locked!
- * indexOid: index to cluster by, or InvalidOid to rewrite in physical order.
+ * OldHeap: table to rebuild.
+ * index: index to cluster by, or NULL to rewrite in physical order.
*
- * NB: this routine closes OldHeap at the right time; caller should not.
+ * On entry, heap and index (if one is given) must be open, and
+ * AccessExclusiveLock held on them.
+ * On exit, they are closed, but locks on them are not released.
*/
static void
-rebuild_relation(Relation OldHeap, Oid indexOid, bool verbose)
+rebuild_relation(Relation OldHeap, Relation index, bool verbose)
{
Oid tableOid = RelationGetRelid(OldHeap);
Oid accessMethod = OldHeap->rd_rel->relam;
Oid tableSpace = OldHeap->rd_rel->reltablespace;
Oid OIDNewHeap;
+ Relation NewHeap;
char relpersistence;
bool is_system_catalog;
bool swap_toast_by_content;
TransactionId frozenXid;
MultiXactId cutoffMulti;
- if (OidIsValid(indexOid))
+ Assert(CheckRelationLockedByMe(OldHeap, AccessExclusiveLock, false) &&
+ (index == NULL || CheckRelationLockedByMe(index, AccessExclusiveLock, false)));
+
+ if (index)
/* Mark the correct index as clustered */
- mark_index_clustered(OldHeap, indexOid, true);
+ mark_index_clustered(OldHeap, RelationGetRelid(index), true);
/* Remember info about rel before closing OldHeap */
relpersistence = OldHeap->rd_rel->relpersistence;
is_system_catalog = IsSystemRelation(OldHeap);
- /* Close relcache entry, but keep lock until transaction commit */
- table_close(OldHeap, NoLock);
-
- /* Create the transient table that will receive the re-ordered data */
+ /*
+ * Create the transient table that will receive the re-ordered data.
+ *
+ * OldHeap is already locked, so no need to lock it again. make_new_heap
+ * obtains AccessExclusiveLock on the new heap and its toast table.
+ */
OIDNewHeap = make_new_heap(tableOid, tableSpace,
accessMethod,
relpersistence,
- AccessExclusiveLock);
+ NoLock);
+ Assert(CheckRelationOidLockedByMe(OIDNewHeap, AccessExclusiveLock, false));
+ NewHeap = table_open(OIDNewHeap, NoLock);
/* Copy the heap data into the new table in the desired order */
- copy_table_data(OIDNewHeap, tableOid, indexOid, verbose,
+ copy_table_data(NewHeap, OldHeap, index, verbose,
&swap_toast_by_content, &frozenXid, &cutoffMulti);
+
+ /* Close relcache entries, but keep lock until transaction commit */
+ table_close(OldHeap, NoLock);
+ if (index)
+ index_close(index, NoLock);
+
+ /*
+ * Close the new relation so it can be dropped as soon as the storage is
+ * swapped. The relation is not visible to others, so no need to unlock it
+ * explicitly.
+ */
+ table_close(NewHeap, NoLock);
+
/*
* Swap the physical files of the target and transient tables, then
* rebuild the target's indexes and throw away the transient table.
@@ -811,13 +828,10 @@ make_new_heap(Oid OIDOldHeap, Oid NewTableSpace, Oid NewAccessMethod,
* *pCutoffMulti receives the MultiXactId used as a cutoff point.
*/
static void
-copy_table_data(Oid OIDNewHeap, Oid OIDOldHeap, Oid OIDOldIndex, bool verbose,
+copy_table_data(Relation NewHeap, Relation OldHeap, Relation OldIndex, bool verbose,
bool *pSwapToastByContent, TransactionId *pFreezeXid,
MultiXactId *pCutoffMulti)
{
- Relation NewHeap,
- OldHeap,
- OldIndex;
Relation relRelation;
HeapTuple reltup;
Form_pg_class relform;
@@ -836,16 +850,6 @@ copy_table_data(Oid OIDNewHeap, Oid OIDOldHeap, Oid OIDOldIndex, bool verbose,
pg_rusage_init(&ru0);
- /*
- * Open the relations we need.
- */
- NewHeap = table_open(OIDNewHeap, AccessExclusiveLock);
- OldHeap = table_open(OIDOldHeap, AccessExclusiveLock);
- if (OidIsValid(OIDOldIndex))
- OldIndex = index_open(OIDOldIndex, AccessExclusiveLock);
- else
- OldIndex = NULL;
-
/* Store a copy of the namespace name for logging purposes */
nspname = get_namespace_name(RelationGetNamespace(OldHeap));
@@ -913,7 +917,7 @@ copy_table_data(Oid OIDNewHeap, Oid OIDOldHeap, Oid OIDOldIndex, bool verbose,
* not to be aggressive about this.
*/
memset(¶ms, 0, sizeof(VacuumParams));
- vacuum_get_cutoffs(OldHeap, ¶ms, &cutoffs);
+ vacuum_get_cutoffs(OldHeap, params, &cutoffs);
/*
* FreezeXid will become the table's new relfrozenxid, and that mustn't go
@@ -946,7 +950,8 @@ copy_table_data(Oid OIDNewHeap, Oid OIDOldHeap, Oid OIDOldIndex, bool verbose,
* provided, else plain seqscan.
*/
if (OldIndex != NULL && OldIndex->rd_rel->relam == BTREE_AM_OID)
- use_sort = plan_cluster_use_sort(OIDOldHeap, OIDOldIndex);
+ use_sort = plan_cluster_use_sort(RelationGetRelid(OldHeap),
+ RelationGetRelid(OldIndex));
else
use_sort = false;
@@ -1001,24 +1006,21 @@ copy_table_data(Oid OIDNewHeap, Oid OIDOldHeap, Oid OIDOldIndex, bool verbose,
tups_recently_dead,
pg_rusage_show(&ru0))));
- if (OldIndex != NULL)
- index_close(OldIndex, NoLock);
- table_close(OldHeap, NoLock);
- table_close(NewHeap, NoLock);
-
/* Update pg_class to reflect the correct values of pages and tuples. */
relRelation = table_open(RelationRelationId, RowExclusiveLock);
- reltup = SearchSysCacheCopy1(RELOID, ObjectIdGetDatum(OIDNewHeap));
+ reltup = SearchSysCacheCopy1(RELOID,
+ ObjectIdGetDatum(RelationGetRelid(NewHeap)));
if (!HeapTupleIsValid(reltup))
- elog(ERROR, "cache lookup failed for relation %u", OIDNewHeap);
+ elog(ERROR, "cache lookup failed for relation %u",
+ RelationGetRelid(NewHeap));
relform = (Form_pg_class) GETSTRUCT(reltup);
relform->relpages = num_pages;
relform->reltuples = num_tuples;
/* Don't update the stats for pg_class. See swap_relation_files. */
- if (OIDOldHeap != RelationRelationId)
+ if (RelationGetRelid(OldHeap) != RelationRelationId)
CatalogTupleUpdate(relRelation, &reltup->t_self, reltup);
else
CacheInvalidateRelcacheByTuple(reltup);
@@ -1224,6 +1226,7 @@ swap_relation_files(Oid r1, Oid r2, bool target_is_pg_class,
int32 swap_pages;
float4 swap_tuples;
int32 swap_allvisible;
+ int32 swap_allfrozen;
swap_pages = relform1->relpages;
relform1->relpages = relform2->relpages;
@@ -1236,6 +1239,10 @@ swap_relation_files(Oid r1, Oid r2, bool target_is_pg_class,
swap_allvisible = relform1->relallvisible;
relform1->relallvisible = relform2->relallvisible;
relform2->relallvisible = swap_allvisible;
+
+ swap_allfrozen = relform1->relallfrozen;
+ relform1->relallfrozen = relform2->relallfrozen;
+ relform2->relallfrozen = swap_allfrozen;
}
/*
diff --git a/src/backend/commands/collationcmds.c b/src/backend/commands/collationcmds.c
index 63ef9a08411b0..8acbfbbeda041 100644
--- a/src/backend/commands/collationcmds.c
+++ b/src/backend/commands/collationcmds.c
@@ -3,7 +3,7 @@
* collationcmds.c
* collation-related commands support code
*
- * Portions Copyright (c) 1996-2024, PostgreSQL Global Development Group
+ * Portions Copyright (c) 1996-2025, PostgreSQL Global Development Group
* Portions Copyright (c) 1994, Regents of the University of California
*
*
@@ -377,13 +377,9 @@ DefineCollation(ParseState *pstate, List *names, List *parameters, bool if_not_e
if (!OidIsValid(newoid))
return InvalidObjectAddress;
- /*
- * Check that the locales can be loaded. NB: pg_newlocale_from_collation
- * is only supposed to be called on non-C-equivalent locales.
- */
+ /* Check that the locales can be loaded. */
CommandCounterIncrement();
- if (!lc_collate_is_c(newoid) || !lc_ctype_is_c(newoid))
- (void) pg_newlocale_from_collation(newoid);
+ (void) pg_newlocale_from_collation(newoid);
ObjectAddressSet(address, CollationRelationId, newoid);
diff --git a/src/backend/commands/comment.c b/src/backend/commands/comment.c
index e9d50fc7d876f..5c783cc61f1d7 100644
--- a/src/backend/commands/comment.c
+++ b/src/backend/commands/comment.c
@@ -4,7 +4,7 @@
*
* PostgreSQL object comments utility code.
*
- * Copyright (c) 1996-2024, PostgreSQL Global Development Group
+ * Copyright (c) 1996-2025, PostgreSQL Global Development Group
*
* IDENTIFICATION
* src/backend/commands/comment.c
@@ -20,10 +20,10 @@
#include "access/table.h"
#include "catalog/indexing.h"
#include "catalog/objectaddress.h"
+#include "catalog/pg_database.h"
#include "catalog/pg_description.h"
#include "catalog/pg_shdescription.h"
#include "commands/comment.h"
-#include "commands/dbcommands.h"
#include "miscadmin.h"
#include "utils/builtins.h"
#include "utils/fmgroids.h"
diff --git a/src/backend/commands/constraint.c b/src/backend/commands/constraint.c
index f7dc42f7452c7..3497a8221f29a 100644
--- a/src/backend/commands/constraint.c
+++ b/src/backend/commands/constraint.c
@@ -3,7 +3,7 @@
* constraint.c
* PostgreSQL CONSTRAINT support code.
*
- * Portions Copyright (c) 1996-2024, PostgreSQL Global Development Group
+ * Portions Copyright (c) 1996-2025, PostgreSQL Global Development Group
* Portions Copyright (c) 1994, Regents of the University of California
*
* IDENTIFICATION
diff --git a/src/backend/commands/conversioncmds.c b/src/backend/commands/conversioncmds.c
index ddd5d1d1c54a2..d3ecc76d97b14 100644
--- a/src/backend/commands/conversioncmds.c
+++ b/src/backend/commands/conversioncmds.c
@@ -3,7 +3,7 @@
* conversioncmds.c
* conversion creation command support code
*
- * Portions Copyright (c) 1996-2024, PostgreSQL Global Development Group
+ * Portions Copyright (c) 1996-2025, PostgreSQL Global Development Group
* Portions Copyright (c) 1994, Regents of the University of California
*
*
diff --git a/src/backend/commands/copy.c b/src/backend/commands/copy.c
index df7a4a21c9458..fae9c41db6565 100644
--- a/src/backend/commands/copy.c
+++ b/src/backend/commands/copy.c
@@ -3,7 +3,7 @@
* copy.c
* Implements the COPY utility command
*
- * Portions Copyright (c) 1996-2024, PostgreSQL Global Development Group
+ * Portions Copyright (c) 1996-2025, PostgreSQL Global Development Group
* Portions Copyright (c) 1994, Regents of the University of California
*
*
@@ -322,11 +322,13 @@ DoCopy(ParseState *pstate, const CopyStmt *stmt,
}
/*
- * Extract a CopyHeaderChoice value from a DefElem. This is like
- * defGetBoolean() but also accepts the special value "match".
+ * Extract the CopyFormatOptions.header_line value from a DefElem.
+ *
+ * Parses the HEADER option for COPY, which can be a boolean, a non-negative
+ * integer (number of lines to skip), or the special value "match".
*/
-static CopyHeaderChoice
-defGetCopyHeaderChoice(DefElem *def, bool is_from)
+static int
+defGetCopyHeaderOption(DefElem *def, bool is_from)
{
/*
* If no parameter value given, assume "true" is meant.
@@ -335,20 +337,27 @@ defGetCopyHeaderChoice(DefElem *def, bool is_from)
return COPY_HEADER_TRUE;
/*
- * Allow 0, 1, "true", "false", "on", "off", or "match".
+ * Allow 0, 1, "true", "false", "on", "off", a non-negative integer, or
+ * "match".
*/
switch (nodeTag(def->arg))
{
case T_Integer:
- switch (intVal(def->arg))
{
- case 0:
- return COPY_HEADER_FALSE;
- case 1:
- return COPY_HEADER_TRUE;
- default:
- /* otherwise, error out below */
- break;
+ int ival = intVal(def->arg);
+
+ if (ival < 0)
+ ereport(ERROR,
+ (errcode(ERRCODE_INVALID_PARAMETER_VALUE),
+ errmsg("a negative integer value cannot be "
+ "specified for %s", def->defname)));
+
+ if (!is_from && ival > 1)
+ ereport(ERROR,
+ (errcode(ERRCODE_FEATURE_NOT_SUPPORTED),
+ errmsg("cannot use multi-line header in COPY TO")));
+
+ return ival;
}
break;
default:
@@ -381,7 +390,8 @@ defGetCopyHeaderChoice(DefElem *def, bool is_from)
}
ereport(ERROR,
(errcode(ERRCODE_SYNTAX_ERROR),
- errmsg("%s requires a Boolean value or \"match\"",
+ errmsg("%s requires a Boolean value, a non-negative integer, "
+ "or the string \"match\"",
def->defname)));
return COPY_HEADER_FALSE; /* keep compiler quiet */
}
@@ -397,7 +407,9 @@ defGetCopyOnErrorChoice(DefElem *def, ParseState *pstate, bool is_from)
if (!is_from)
ereport(ERROR,
(errcode(ERRCODE_INVALID_PARAMETER_VALUE),
- errmsg("COPY ON_ERROR cannot be used with COPY TO"),
+ /*- translator: first %s is the name of a COPY option, e.g. ON_ERROR,
+ second %s is a COPY with direction, e.g. COPY TO */
+ errmsg("COPY %s cannot be used with %s", "ON_ERROR", "COPY TO"),
parser_errposition(pstate, def->location)));
/*
@@ -410,11 +422,43 @@ defGetCopyOnErrorChoice(DefElem *def, ParseState *pstate, bool is_from)
ereport(ERROR,
(errcode(ERRCODE_INVALID_PARAMETER_VALUE),
- errmsg("COPY ON_ERROR \"%s\" not recognized", sval),
+ /*- translator: first %s is the name of a COPY option, e.g. ON_ERROR */
+ errmsg("COPY %s \"%s\" not recognized", "ON_ERROR", sval),
parser_errposition(pstate, def->location)));
return COPY_ON_ERROR_STOP; /* keep compiler quiet */
}
+/*
+ * Extract REJECT_LIMIT value from a DefElem.
+ *
+ * REJECT_LIMIT can be specified in two ways: as an int64 for the COPY command
+ * option or as a single-quoted string for the foreign table option using
+ * file_fdw. Therefore this function needs to handle both formats.
+ */
+static int64
+defGetCopyRejectLimitOption(DefElem *def)
+{
+ int64 reject_limit;
+
+ if (def->arg == NULL)
+ ereport(ERROR,
+ (errcode(ERRCODE_SYNTAX_ERROR),
+ errmsg("%s requires a numeric value",
+ def->defname)));
+ else if (nodeTag(def->arg) == T_String)
+ reject_limit = pg_strtoint64(strVal(def->arg));
+ else
+ reject_limit = defGetInt64(def);
+
+ if (reject_limit <= 0)
+ ereport(ERROR,
+ (errcode(ERRCODE_INVALID_PARAMETER_VALUE),
+ errmsg("REJECT_LIMIT (%" PRId64 ") must be greater than zero",
+ reject_limit)));
+
+ return reject_limit;
+}
+
/*
* Extract a CopyLogVerbosityChoice value from a DefElem.
*/
@@ -424,9 +468,11 @@ defGetCopyLogVerbosityChoice(DefElem *def, ParseState *pstate)
char *sval;
/*
- * Allow "default", or "verbose" values.
+ * Allow "silent", "default", or "verbose" values.
*/
sval = defGetString(def);
+ if (pg_strcasecmp(sval, "silent") == 0)
+ return COPY_LOG_VERBOSITY_SILENT;
if (pg_strcasecmp(sval, "default") == 0)
return COPY_LOG_VERBOSITY_DEFAULT;
if (pg_strcasecmp(sval, "verbose") == 0)
@@ -434,7 +480,8 @@ defGetCopyLogVerbosityChoice(DefElem *def, ParseState *pstate)
ereport(ERROR,
(errcode(ERRCODE_INVALID_PARAMETER_VALUE),
- errmsg("COPY LOG_VERBOSITY \"%s\" not recognized", sval),
+ /*- translator: first %s is the name of a COPY option, e.g. ON_ERROR */
+ errmsg("COPY %s \"%s\" not recognized", "LOG_VERBOSITY", sval),
parser_errposition(pstate, def->location)));
return COPY_LOG_VERBOSITY_DEFAULT; /* keep compiler quiet */
}
@@ -466,6 +513,7 @@ ProcessCopyOptions(ParseState *pstate,
bool header_specified = false;
bool on_error_specified = false;
bool log_verbosity_specified = false;
+ bool reject_limit_specified = false;
ListCell *option;
/* Support external use for option sanity checking */
@@ -528,7 +576,7 @@ ProcessCopyOptions(ParseState *pstate,
if (header_specified)
errorConflictingDefElem(defel, pstate);
header_specified = true;
- opts_out->header_line = defGetCopyHeaderChoice(defel, is_from);
+ opts_out->header_line = defGetCopyHeaderOption(defel, is_from);
}
else if (strcmp(defel->defname, "quote") == 0)
{
@@ -632,6 +680,13 @@ ProcessCopyOptions(ParseState *pstate,
log_verbosity_specified = true;
opts_out->log_verbosity = defGetCopyLogVerbosityChoice(defel, pstate);
}
+ else if (strcmp(defel->defname, "reject_limit") == 0)
+ {
+ if (reject_limit_specified)
+ errorConflictingDefElem(defel, pstate);
+ reject_limit_specified = true;
+ opts_out->reject_limit = defGetCopyRejectLimitOption(defel);
+ }
else
ereport(ERROR,
(errcode(ERRCODE_SYNTAX_ERROR),
@@ -641,28 +696,24 @@ ProcessCopyOptions(ParseState *pstate,
}
/*
- * Check for incompatible options (must do these two before inserting
+ * Check for incompatible options (must do these three before inserting
* defaults)
*/
if (opts_out->binary && opts_out->delim)
ereport(ERROR,
(errcode(ERRCODE_SYNTAX_ERROR),
- errmsg("cannot specify DELIMITER in BINARY mode")));
+ /*- translator: %s is the name of a COPY option, e.g. ON_ERROR */
+ errmsg("cannot specify %s in BINARY mode", "DELIMITER")));
if (opts_out->binary && opts_out->null_print)
ereport(ERROR,
(errcode(ERRCODE_SYNTAX_ERROR),
- errmsg("cannot specify NULL in BINARY mode")));
+ errmsg("cannot specify %s in BINARY mode", "NULL")));
if (opts_out->binary && opts_out->default_print)
ereport(ERROR,
(errcode(ERRCODE_SYNTAX_ERROR),
- errmsg("cannot specify DEFAULT in BINARY mode")));
-
- if (opts_out->binary && opts_out->on_error != COPY_ON_ERROR_STOP)
- ereport(ERROR,
- (errcode(ERRCODE_SYNTAX_ERROR),
- errmsg("only ON_ERROR STOP is allowed in BINARY mode")));
+ errmsg("cannot specify %s in BINARY mode", "DEFAULT")));
/* Set defaults for omitted options */
if (!opts_out->delim)
@@ -728,16 +779,18 @@ ProcessCopyOptions(ParseState *pstate,
errmsg("COPY delimiter cannot be \"%s\"", opts_out->delim)));
/* Check header */
- if (opts_out->binary && opts_out->header_line)
+ if (opts_out->binary && opts_out->header_line != COPY_HEADER_FALSE)
ereport(ERROR,
(errcode(ERRCODE_FEATURE_NOT_SUPPORTED),
- errmsg("cannot specify HEADER in BINARY mode")));
+ /*- translator: %s is the name of a COPY option, e.g. ON_ERROR */
+ errmsg("cannot specify %s in BINARY mode", "HEADER")));
/* Check quote */
if (!opts_out->csv_mode && opts_out->quote != NULL)
ereport(ERROR,
(errcode(ERRCODE_FEATURE_NOT_SUPPORTED),
- errmsg("COPY QUOTE requires CSV mode")));
+ /*- translator: %s is the name of a COPY option, e.g. ON_ERROR */
+ errmsg("COPY %s requires CSV mode", "QUOTE")));
if (opts_out->csv_mode && strlen(opts_out->quote) != 1)
ereport(ERROR,
@@ -753,7 +806,8 @@ ProcessCopyOptions(ParseState *pstate,
if (!opts_out->csv_mode && opts_out->escape != NULL)
ereport(ERROR,
(errcode(ERRCODE_FEATURE_NOT_SUPPORTED),
- errmsg("COPY ESCAPE requires CSV mode")));
+ /*- translator: %s is the name of a COPY option, e.g. ON_ERROR */
+ errmsg("COPY %s requires CSV mode", "ESCAPE")));
if (opts_out->csv_mode && strlen(opts_out->escape) != 1)
ereport(ERROR,
@@ -764,71 +818,101 @@ ProcessCopyOptions(ParseState *pstate,
if (!opts_out->csv_mode && (opts_out->force_quote || opts_out->force_quote_all))
ereport(ERROR,
(errcode(ERRCODE_FEATURE_NOT_SUPPORTED),
- errmsg("COPY FORCE_QUOTE requires CSV mode")));
+ /*- translator: %s is the name of a COPY option, e.g. ON_ERROR */
+ errmsg("COPY %s requires CSV mode", "FORCE_QUOTE")));
if ((opts_out->force_quote || opts_out->force_quote_all) && is_from)
ereport(ERROR,
(errcode(ERRCODE_FEATURE_NOT_SUPPORTED),
- errmsg("COPY FORCE_QUOTE cannot be used with COPY FROM")));
+ /*- translator: first %s is the name of a COPY option, e.g. ON_ERROR,
+ second %s is a COPY with direction, e.g. COPY TO */
+ errmsg("COPY %s cannot be used with %s", "FORCE_QUOTE",
+ "COPY FROM")));
/* Check force_notnull */
- if (!opts_out->csv_mode && opts_out->force_notnull != NIL)
+ if (!opts_out->csv_mode && (opts_out->force_notnull != NIL ||
+ opts_out->force_notnull_all))
ereport(ERROR,
(errcode(ERRCODE_FEATURE_NOT_SUPPORTED),
- errmsg("COPY FORCE_NOT_NULL requires CSV mode")));
- if (opts_out->force_notnull != NIL && !is_from)
+ /*- translator: %s is the name of a COPY option, e.g. ON_ERROR */
+ errmsg("COPY %s requires CSV mode", "FORCE_NOT_NULL")));
+ if ((opts_out->force_notnull != NIL || opts_out->force_notnull_all) &&
+ !is_from)
ereport(ERROR,
(errcode(ERRCODE_INVALID_PARAMETER_VALUE),
- errmsg("COPY FORCE_NOT_NULL cannot be used with COPY TO")));
+ /*- translator: first %s is the name of a COPY option, e.g. ON_ERROR,
+ second %s is a COPY with direction, e.g. COPY TO */
+ errmsg("COPY %s cannot be used with %s", "FORCE_NOT_NULL",
+ "COPY TO")));
/* Check force_null */
- if (!opts_out->csv_mode && opts_out->force_null != NIL)
+ if (!opts_out->csv_mode && (opts_out->force_null != NIL ||
+ opts_out->force_null_all))
ereport(ERROR,
(errcode(ERRCODE_FEATURE_NOT_SUPPORTED),
- errmsg("COPY FORCE_NULL requires CSV mode")));
+ /*- translator: %s is the name of a COPY option, e.g. ON_ERROR */
+ errmsg("COPY %s requires CSV mode", "FORCE_NULL")));
- if (opts_out->force_null != NIL && !is_from)
+ if ((opts_out->force_null != NIL || opts_out->force_null_all) &&
+ !is_from)
ereport(ERROR,
(errcode(ERRCODE_INVALID_PARAMETER_VALUE),
- errmsg("COPY FORCE_NULL cannot be used with COPY TO")));
+ /*- translator: first %s is the name of a COPY option, e.g. ON_ERROR,
+ second %s is a COPY with direction, e.g. COPY TO */
+ errmsg("COPY %s cannot be used with %s", "FORCE_NULL",
+ "COPY TO")));
/* Don't allow the delimiter to appear in the null string. */
if (strchr(opts_out->null_print, opts_out->delim[0]) != NULL)
ereport(ERROR,
(errcode(ERRCODE_INVALID_PARAMETER_VALUE),
- errmsg("COPY delimiter character must not appear in the NULL specification")));
+ /*- translator: %s is the name of a COPY option, e.g. NULL */
+ errmsg("COPY delimiter character must not appear in the %s specification",
+ "NULL")));
/* Don't allow the CSV quote char to appear in the null string. */
if (opts_out->csv_mode &&
strchr(opts_out->null_print, opts_out->quote[0]) != NULL)
ereport(ERROR,
(errcode(ERRCODE_INVALID_PARAMETER_VALUE),
- errmsg("CSV quote character must not appear in the NULL specification")));
+ /*- translator: %s is the name of a COPY option, e.g. NULL */
+ errmsg("CSV quote character must not appear in the %s specification",
+ "NULL")));
/* Check freeze */
if (opts_out->freeze && !is_from)
ereport(ERROR,
(errcode(ERRCODE_INVALID_PARAMETER_VALUE),
- errmsg("COPY FREEZE cannot be used with COPY TO")));
+ /*- translator: first %s is the name of a COPY option, e.g. ON_ERROR,
+ second %s is a COPY with direction, e.g. COPY TO */
+ errmsg("COPY %s cannot be used with %s", "FREEZE",
+ "COPY TO")));
if (opts_out->default_print)
{
if (!is_from)
ereport(ERROR,
(errcode(ERRCODE_FEATURE_NOT_SUPPORTED),
- errmsg("COPY DEFAULT only available using COPY FROM")));
+ /*- translator: first %s is the name of a COPY option, e.g. ON_ERROR,
+ second %s is a COPY with direction, e.g. COPY TO */
+ errmsg("COPY %s cannot be used with %s", "DEFAULT",
+ "COPY TO")));
/* Don't allow the delimiter to appear in the default string. */
if (strchr(opts_out->default_print, opts_out->delim[0]) != NULL)
ereport(ERROR,
(errcode(ERRCODE_FEATURE_NOT_SUPPORTED),
- errmsg("COPY delimiter must not appear in the DEFAULT specification")));
+ /*- translator: %s is the name of a COPY option, e.g. NULL */
+ errmsg("COPY delimiter character must not appear in the %s specification",
+ "DEFAULT")));
/* Don't allow the CSV quote char to appear in the default string. */
if (opts_out->csv_mode &&
strchr(opts_out->default_print, opts_out->quote[0]) != NULL)
ereport(ERROR,
(errcode(ERRCODE_FEATURE_NOT_SUPPORTED),
- errmsg("CSV quote character must not appear in the DEFAULT specification")));
+ /*- translator: %s is the name of a COPY option, e.g. NULL */
+ errmsg("CSV quote character must not appear in the %s specification",
+ "DEFAULT")));
/* Don't allow the NULL and DEFAULT string to be the same */
if (opts_out->null_print_len == opts_out->default_print_len &&
@@ -838,6 +922,19 @@ ProcessCopyOptions(ParseState *pstate,
(errcode(ERRCODE_FEATURE_NOT_SUPPORTED),
errmsg("NULL specification and DEFAULT specification cannot be the same")));
}
+ /* Check on_error */
+ if (opts_out->binary && opts_out->on_error != COPY_ON_ERROR_STOP)
+ ereport(ERROR,
+ (errcode(ERRCODE_SYNTAX_ERROR),
+ errmsg("only ON_ERROR STOP is allowed in BINARY mode")));
+
+ if (opts_out->reject_limit && !opts_out->on_error)
+ ereport(ERROR,
+ (errcode(ERRCODE_INVALID_PARAMETER_VALUE),
+ /*- translator: first and second %s are the names of COPY option, e.g.
+ * ON_ERROR, third is the value of the COPY option, e.g. IGNORE */
+ errmsg("COPY %s requires %s to be set to %s",
+ "REJECT_LIMIT", "ON_ERROR", "IGNORE")));
}
/*
@@ -867,9 +964,9 @@ CopyGetAttnums(TupleDesc tupDesc, Relation rel, List *attnamelist)
for (i = 0; i < attr_count; i++)
{
- if (TupleDescAttr(tupDesc, i)->attisdropped)
- continue;
- if (TupleDescAttr(tupDesc, i)->attgenerated)
+ CompactAttribute *attr = TupleDescCompactAttr(tupDesc, i);
+
+ if (attr->attisdropped || attr->attgenerated)
continue;
attnums = lappend_int(attnums, i + 1);
}
diff --git a/src/backend/commands/copyfrom.c b/src/backend/commands/copyfrom.c
index ce4d62e707c95..12781963b4f95 100644
--- a/src/backend/commands/copyfrom.c
+++ b/src/backend/commands/copyfrom.c
@@ -9,7 +9,7 @@
* Reading data from the input file or client and parsing it into Datums
* is handled in copyfromparse.c.
*
- * Portions Copyright (c) 1996-2024, PostgreSQL Global Development Group
+ * Portions Copyright (c) 1996-2025, PostgreSQL Global Development Group
* Portions Copyright (c) 1994, Regents of the University of California
*
*
@@ -28,7 +28,7 @@
#include "access/tableam.h"
#include "access/xact.h"
#include "catalog/namespace.h"
-#include "commands/copy.h"
+#include "commands/copyapi.h"
#include "commands/copyfrom_internal.h"
#include "commands/progress.h"
#include "commands/trigger.h"
@@ -68,7 +68,10 @@
*/
#define MAX_BUFFERED_BYTES 65535
-/* Trim the list of buffers back down to this number after flushing */
+/*
+ * Trim the list of buffers back down to this number after flushing. This
+ * must be >= 2.
+ */
#define MAX_PARTITION_BUFFERS 32
/* Stores multi-insert data related to a single relation in CopyFrom. */
@@ -103,6 +106,145 @@ typedef struct CopyMultiInsertInfo
/* non-export function prototypes */
static void ClosePipeFromProgram(CopyFromState cstate);
+/*
+ * Built-in format-specific routines. One-row callbacks are defined in
+ * copyfromparse.c.
+ */
+static void CopyFromTextLikeInFunc(CopyFromState cstate, Oid atttypid, FmgrInfo *finfo,
+ Oid *typioparam);
+static void CopyFromTextLikeStart(CopyFromState cstate, TupleDesc tupDesc);
+static void CopyFromTextLikeEnd(CopyFromState cstate);
+static void CopyFromBinaryInFunc(CopyFromState cstate, Oid atttypid,
+ FmgrInfo *finfo, Oid *typioparam);
+static void CopyFromBinaryStart(CopyFromState cstate, TupleDesc tupDesc);
+static void CopyFromBinaryEnd(CopyFromState cstate);
+
+
+/*
+ * COPY FROM routines for built-in formats.
+ *
+ * CSV and text formats share the same TextLike routines except for the
+ * one-row callback.
+ */
+
+/* text format */
+static const CopyFromRoutine CopyFromRoutineText = {
+ .CopyFromInFunc = CopyFromTextLikeInFunc,
+ .CopyFromStart = CopyFromTextLikeStart,
+ .CopyFromOneRow = CopyFromTextOneRow,
+ .CopyFromEnd = CopyFromTextLikeEnd,
+};
+
+/* CSV format */
+static const CopyFromRoutine CopyFromRoutineCSV = {
+ .CopyFromInFunc = CopyFromTextLikeInFunc,
+ .CopyFromStart = CopyFromTextLikeStart,
+ .CopyFromOneRow = CopyFromCSVOneRow,
+ .CopyFromEnd = CopyFromTextLikeEnd,
+};
+
+/* binary format */
+static const CopyFromRoutine CopyFromRoutineBinary = {
+ .CopyFromInFunc = CopyFromBinaryInFunc,
+ .CopyFromStart = CopyFromBinaryStart,
+ .CopyFromOneRow = CopyFromBinaryOneRow,
+ .CopyFromEnd = CopyFromBinaryEnd,
+};
+
+/* Return a COPY FROM routine for the given options */
+static const CopyFromRoutine *
+CopyFromGetRoutine(const CopyFormatOptions *opts)
+{
+ if (opts->csv_mode)
+ return &CopyFromRoutineCSV;
+ else if (opts->binary)
+ return &CopyFromRoutineBinary;
+
+ /* default is text */
+ return &CopyFromRoutineText;
+}
+
+/* Implementation of the start callback for text and CSV formats */
+static void
+CopyFromTextLikeStart(CopyFromState cstate, TupleDesc tupDesc)
+{
+ AttrNumber attr_count;
+
+ /*
+ * If encoding conversion is needed, we need another buffer to hold the
+ * converted input data. Otherwise, we can just point input_buf to the
+ * same buffer as raw_buf.
+ */
+ if (cstate->need_transcoding)
+ {
+ cstate->input_buf = (char *) palloc(INPUT_BUF_SIZE + 1);
+ cstate->input_buf_index = cstate->input_buf_len = 0;
+ }
+ else
+ cstate->input_buf = cstate->raw_buf;
+ cstate->input_reached_eof = false;
+
+ initStringInfo(&cstate->line_buf);
+
+ /*
+ * Create workspace for CopyReadAttributes results; used by CSV and text
+ * format.
+ */
+ attr_count = list_length(cstate->attnumlist);
+ cstate->max_fields = attr_count;
+ cstate->raw_fields = (char **) palloc(attr_count * sizeof(char *));
+}
+
+/*
+ * Implementation of the infunc callback for text and CSV formats. Assign
+ * the input function data to the given *finfo.
+ */
+static void
+CopyFromTextLikeInFunc(CopyFromState cstate, Oid atttypid, FmgrInfo *finfo,
+ Oid *typioparam)
+{
+ Oid func_oid;
+
+ getTypeInputInfo(atttypid, &func_oid, typioparam);
+ fmgr_info(func_oid, finfo);
+}
+
+/* Implementation of the end callback for text and CSV formats */
+static void
+CopyFromTextLikeEnd(CopyFromState cstate)
+{
+ /* nothing to do */
+}
+
+/* Implementation of the start callback for binary format */
+static void
+CopyFromBinaryStart(CopyFromState cstate, TupleDesc tupDesc)
+{
+ /* Read and verify binary header */
+ ReceiveCopyBinaryHeader(cstate);
+}
+
+/*
+ * Implementation of the infunc callback for binary format. Assign
+ * the binary input function to the given *finfo.
+ */
+static void
+CopyFromBinaryInFunc(CopyFromState cstate, Oid atttypid,
+ FmgrInfo *finfo, Oid *typioparam)
+{
+ Oid func_oid;
+
+ getTypeBinaryInputInfo(atttypid, &func_oid, typioparam);
+ fmgr_info(func_oid, finfo);
+}
+
+/* Implementation of the end callback for binary format */
+static void
+CopyFromBinaryEnd(CopyFromState cstate)
+{
+ /* nothing to do */
+}
+
/*
* error context callback for COPY FROM
*
@@ -123,14 +265,14 @@ CopyFromErrorCallback(void *arg)
{
/* can't usefully display the data */
if (cstate->cur_attname)
- errcontext("COPY %s, line %llu, column %s",
+ errcontext("COPY %s, line %" PRIu64 ", column %s",
cstate->cur_relname,
- (unsigned long long) cstate->cur_lineno,
+ cstate->cur_lineno,
cstate->cur_attname);
else
- errcontext("COPY %s, line %llu",
+ errcontext("COPY %s, line %" PRIu64,
cstate->cur_relname,
- (unsigned long long) cstate->cur_lineno);
+ cstate->cur_lineno);
}
else
{
@@ -140,9 +282,9 @@ CopyFromErrorCallback(void *arg)
char *attval;
attval = CopyLimitPrintoutLength(cstate->cur_attval);
- errcontext("COPY %s, line %llu, column %s: \"%s\"",
+ errcontext("COPY %s, line %" PRIu64 ", column %s: \"%s\"",
cstate->cur_relname,
- (unsigned long long) cstate->cur_lineno,
+ cstate->cur_lineno,
cstate->cur_attname,
attval);
pfree(attval);
@@ -150,9 +292,9 @@ CopyFromErrorCallback(void *arg)
else if (cstate->cur_attname)
{
/* error is relevant to a particular column, value is NULL */
- errcontext("COPY %s, line %llu, column %s: null input",
+ errcontext("COPY %s, line %" PRIu64 ", column %s: null input",
cstate->cur_relname,
- (unsigned long long) cstate->cur_lineno,
+ cstate->cur_lineno,
cstate->cur_attname);
}
else
@@ -167,16 +309,16 @@ CopyFromErrorCallback(void *arg)
char *lineval;
lineval = CopyLimitPrintoutLength(cstate->line_buf.data);
- errcontext("COPY %s, line %llu: \"%s\"",
+ errcontext("COPY %s, line %" PRIu64 ": \"%s\"",
cstate->cur_relname,
- (unsigned long long) cstate->cur_lineno, lineval);
+ cstate->cur_lineno, lineval);
pfree(lineval);
}
else
{
- errcontext("COPY %s, line %llu",
+ errcontext("COPY %s, line %" PRIu64,
cstate->cur_relname,
- (unsigned long long) cstate->cur_lineno);
+ cstate->cur_lineno);
}
}
}
@@ -550,6 +692,13 @@ CopyMultiInsertInfoFlush(CopyMultiInsertInfo *miinfo, ResultRelInfo *curr_rri,
*/
if (buffer->resultRelInfo == curr_rri)
{
+ /*
+ * The code below would misbehave if we were trying to reduce the
+ * list to less than two items.
+ */
+ StaticAssertDecl(MAX_PARTITION_BUFFERS >= 2,
+ "MAX_PARTITION_BUFFERS must be >= 2");
+
miinfo->multiInsertBuffers = list_delete_first(miinfo->multiInsertBuffers);
miinfo->multiInsertBuffers = lappend(miinfo->multiInsertBuffers, buffer);
buffer = (CopyMultiInsertBuffer *) linitial(miinfo->multiInsertBuffers);
@@ -587,10 +736,12 @@ CopyMultiInsertInfoNextFreeSlot(CopyMultiInsertInfo *miinfo,
ResultRelInfo *rri)
{
CopyMultiInsertBuffer *buffer = rri->ri_CopyMultiInsertBuffer;
- int nused = buffer->nused;
+ int nused;
Assert(buffer != NULL);
- Assert(nused < MAX_BUFFERED_TUPLES);
+ Assert(buffer->nused < MAX_BUFFERED_TUPLES);
+
+ nused = buffer->nused;
if (buffer->slots[nused] == NULL)
buffer->slots[nused] = table_slot_create(rri->ri_RelationDesc, NULL);
@@ -645,7 +796,6 @@ CopyFrom(CopyFromState cstate)
CopyMultiInsertInfo multiInsertInfo = {0}; /* pacify compiler */
int64 processed = 0;
int64 excluded = 0;
- int64 skipped = 0;
bool has_before_insert_row_trig;
bool has_instead_insert_row_trig;
bool leafpart_use_multi_insert = false;
@@ -729,6 +879,12 @@ CopyFrom(CopyFromState cstate)
errmsg("cannot perform COPY FREEZE on a partitioned table")));
}
+ /* There's currently no support for COPY FREEZE on foreign tables. */
+ if (cstate->rel->rd_rel->relkind == RELKIND_FOREIGN_TABLE)
+ ereport(ERROR,
+ (errcode(ERRCODE_FEATURE_NOT_SUPPORTED),
+ errmsg("cannot perform COPY FREEZE on a foreign table")));
+
/*
* Tolerate one registration for the benefit of FirstXactSnapshot.
* Scan-bearing queries generally create at least two registrations,
@@ -757,12 +913,13 @@ CopyFrom(CopyFromState cstate)
* index-entry-making machinery. (There used to be a huge amount of code
* here that basically duplicated execUtils.c ...)
*/
- ExecInitRangeTable(estate, cstate->range_table, cstate->rteperminfos);
+ ExecInitRangeTable(estate, cstate->range_table, cstate->rteperminfos,
+ bms_make_singleton(1));
resultRelInfo = target_resultRelInfo = makeNode(ResultRelInfo);
ExecInitResultRelation(estate, resultRelInfo, 1);
/* Verify the named relation is a valid target for INSERT */
- CheckValidResultRel(resultRelInfo, CMD_INSERT, NIL);
+ CheckValidResultRel(resultRelInfo, CMD_INSERT, ONCONFLICT_NONE, NIL);
ExecOpenIndices(resultRelInfo, false);
@@ -948,7 +1105,7 @@ CopyFrom(CopyFromState cstate)
/* Set up callback to identify error line number */
errcallback.callback = CopyFromErrorCallback;
- errcallback.arg = (void *) cstate;
+ errcallback.arg = cstate;
errcallback.previous = error_context_stack;
error_context_stack = &errcallback;
@@ -992,26 +1149,29 @@ CopyFrom(CopyFromState cstate)
if (!NextCopyFrom(cstate, econtext, myslot->tts_values, myslot->tts_isnull))
break;
- if (cstate->opts.on_error != COPY_ON_ERROR_STOP &&
+ if (cstate->opts.on_error == COPY_ON_ERROR_IGNORE &&
cstate->escontext->error_occurred)
{
/*
- * Soft error occurred, skip this tuple and deal with error
- * information according to ON_ERROR.
+ * Soft error occurred, skip this tuple and just make
+ * ErrorSaveContext ready for the next NextCopyFrom. Since we
+ * don't set details_wanted and error_data is not to be filled,
+ * just resetting error_occurred is enough.
*/
- if (cstate->opts.on_error == COPY_ON_ERROR_IGNORE)
-
- /*
- * Just make ErrorSaveContext ready for the next NextCopyFrom.
- * Since we don't set details_wanted and error_data is not to
- * be filled, just resetting error_occurred is enough.
- */
- cstate->escontext->error_occurred = false;
+ cstate->escontext->error_occurred = false;
/* Report that this tuple was skipped by the ON_ERROR clause */
pgstat_progress_update_param(PROGRESS_COPY_TUPLES_SKIPPED,
- ++skipped);
+ cstate->num_errors);
+ if (cstate->opts.reject_limit > 0 &&
+ cstate->num_errors > cstate->opts.reject_limit)
+ ereport(ERROR,
+ (errcode(ERRCODE_INVALID_TEXT_REPRESENTATION),
+ errmsg("skipped more than REJECT_LIMIT (%" PRId64 ") rows due to data type incompatibility",
+ cstate->opts.reject_limit)));
+
+ /* Repeat NextCopyFrom() until no soft error occurs */
continue;
}
@@ -1308,12 +1468,13 @@ CopyFrom(CopyFromState cstate)
error_context_stack = errcallback.previous;
if (cstate->opts.on_error != COPY_ON_ERROR_STOP &&
- cstate->num_errors > 0)
+ cstate->num_errors > 0 &&
+ cstate->opts.log_verbosity >= COPY_LOG_VERBOSITY_DEFAULT)
ereport(NOTICE,
- errmsg_plural("%llu row was skipped due to data type incompatibility",
- "%llu rows were skipped due to data type incompatibility",
- (unsigned long long) cstate->num_errors,
- (unsigned long long) cstate->num_errors));
+ errmsg_plural("%" PRIu64 " row was skipped due to data type incompatibility",
+ "%" PRIu64 " rows were skipped due to data type incompatibility",
+ cstate->num_errors,
+ cstate->num_errors));
if (bistate != NULL)
FreeBulkInsertState(bistate);
@@ -1381,7 +1542,6 @@ BeginCopyFrom(ParseState *pstate,
num_defaults;
FmgrInfo *in_functions;
Oid *typioparams;
- Oid in_func_oid;
int *defmap;
ExprState **defexprs;
MemoryContext oldcontext;
@@ -1413,6 +1573,9 @@ BeginCopyFrom(ParseState *pstate,
/* Extract options from the statement node tree */
ProcessCopyOptions(pstate, &cstate->opts, true /* is_from */ , options);
+ /* Set the format routine */
+ cstate->routine = CopyFromGetRoutine(&cstate->opts);
+
/* Process the target relation */
cstate->rel = rel;
@@ -1444,8 +1607,9 @@ BeginCopyFrom(ParseState *pstate,
if (!list_member_int(cstate->attnumlist, attnum))
ereport(ERROR,
(errcode(ERRCODE_INVALID_COLUMN_REFERENCE),
- errmsg("FORCE_NOT_NULL column \"%s\" not referenced by COPY",
- NameStr(attr->attname))));
+ /*- translator: first %s is the name of a COPY option, e.g. FORCE_NOT_NULL */
+ errmsg("%s column \"%s\" not referenced by COPY",
+ "FORCE_NOT_NULL", NameStr(attr->attname))));
cstate->opts.force_notnull_flags[attnum - 1] = true;
}
}
@@ -1486,8 +1650,9 @@ BeginCopyFrom(ParseState *pstate,
if (!list_member_int(cstate->attnumlist, attnum))
ereport(ERROR,
(errcode(ERRCODE_INVALID_COLUMN_REFERENCE),
- errmsg("FORCE_NULL column \"%s\" not referenced by COPY",
- NameStr(attr->attname))));
+ /*- translator: first %s is the name of a COPY option, e.g. FORCE_NOT_NULL */
+ errmsg("%s column \"%s\" not referenced by COPY",
+ "FORCE_NULL", NameStr(attr->attname))));
cstate->opts.force_null_flags[attnum - 1] = true;
}
}
@@ -1566,25 +1731,6 @@ BeginCopyFrom(ParseState *pstate,
cstate->raw_buf_index = cstate->raw_buf_len = 0;
cstate->raw_reached_eof = false;
- if (!cstate->opts.binary)
- {
- /*
- * If encoding conversion is needed, we need another buffer to hold
- * the converted input data. Otherwise, we can just point input_buf
- * to the same buffer as raw_buf.
- */
- if (cstate->need_transcoding)
- {
- cstate->input_buf = (char *) palloc(INPUT_BUF_SIZE + 1);
- cstate->input_buf_index = cstate->input_buf_len = 0;
- }
- else
- cstate->input_buf = cstate->raw_buf;
- cstate->input_reached_eof = false;
-
- initStringInfo(&cstate->line_buf);
- }
-
initStringInfo(&cstate->attribute_buf);
/* Assign range table and rteperminfos, we'll need them in CopyFrom. */
@@ -1617,13 +1763,9 @@ BeginCopyFrom(ParseState *pstate,
continue;
/* Fetch the input function and typioparam info */
- if (cstate->opts.binary)
- getTypeBinaryInputInfo(att->atttypid,
- &in_func_oid, &typioparams[attnum - 1]);
- else
- getTypeInputInfo(att->atttypid,
- &in_func_oid, &typioparams[attnum - 1]);
- fmgr_info(in_func_oid, &in_functions[attnum - 1]);
+ cstate->routine->CopyFromInFunc(cstate, att->atttypid,
+ &in_functions[attnum - 1],
+ &typioparams[attnum - 1]);
/* Get default info if available */
defexprs[attnum - 1] = NULL;
@@ -1758,20 +1900,7 @@ BeginCopyFrom(ParseState *pstate,
pgstat_progress_update_multi_param(3, progress_cols, progress_vals);
- if (cstate->opts.binary)
- {
- /* Read and verify binary header */
- ReceiveCopyBinaryHeader(cstate);
- }
-
- /* create workspace for CopyReadAttributes results */
- if (!cstate->opts.binary)
- {
- AttrNumber attr_count = list_length(cstate->attnumlist);
-
- cstate->max_fields = attr_count;
- cstate->raw_fields = (char **) palloc(attr_count * sizeof(char *));
- }
+ cstate->routine->CopyFromStart(cstate, tupDesc);
MemoryContextSwitchTo(oldcontext);
@@ -1784,6 +1913,9 @@ BeginCopyFrom(ParseState *pstate,
void
EndCopyFrom(CopyFromState cstate)
{
+ /* Invoke the end callback */
+ cstate->routine->CopyFromEnd(cstate);
+
/* No COPY FROM related resources except memory. */
if (cstate->is_program)
{
diff --git a/src/backend/commands/copyfromparse.c b/src/backend/commands/copyfromparse.c
index 7efcb891598f0..b1ae97b833dff 100644
--- a/src/backend/commands/copyfromparse.c
+++ b/src/backend/commands/copyfromparse.c
@@ -47,7 +47,7 @@
* and 'attribute_buf' are expanded on demand, to hold the longest line
* encountered so far.
*
- * Portions Copyright (c) 1996-2024, PostgreSQL Global Development Group
+ * Portions Copyright (c) 1996-2025, PostgreSQL Global Development Group
* Portions Copyright (c) 1994, Regents of the University of California
*
*
@@ -62,7 +62,7 @@
#include
#include
-#include "commands/copy.h"
+#include "commands/copyapi.h"
#include "commands/copyfrom_internal.h"
#include "commands/progress.h"
#include "executor/executor.h"
@@ -70,7 +70,6 @@
#include "libpq/pqformat.h"
#include "mb/pg_wchar.h"
#include "miscadmin.h"
-#include "nodes/miscnodes.h"
#include "pgstat.h"
#include "port/pg_bswap.h"
#include "utils/builtins.h"
@@ -136,26 +135,27 @@ if (1) \
} \
} else ((void) 0)
-/* Undo any read-ahead and jump out of the block. */
-#define NO_END_OF_COPY_GOTO \
-if (1) \
-{ \
- input_buf_ptr = prev_raw_ptr + 1; \
- goto not_end_of_copy; \
-} else ((void) 0)
-
/* NOTE: there's a copy of this in copyto.c */
static const char BinarySignature[11] = "PGCOPY\n\377\r\n\0";
/* non-export function prototypes */
-static bool CopyReadLine(CopyFromState cstate);
-static bool CopyReadLineText(CopyFromState cstate);
+static bool CopyReadLine(CopyFromState cstate, bool is_csv);
+static bool CopyReadLineText(CopyFromState cstate, bool is_csv);
static int CopyReadAttributesText(CopyFromState cstate);
static int CopyReadAttributesCSV(CopyFromState cstate);
static Datum CopyReadBinaryAttribute(CopyFromState cstate, FmgrInfo *flinfo,
Oid typioparam, int32 typmod,
bool *isnull);
+static pg_attribute_always_inline bool CopyFromTextLikeOneRow(CopyFromState cstate,
+ ExprContext *econtext,
+ Datum *values,
+ bool *nulls,
+ bool is_csv);
+static pg_attribute_always_inline bool NextCopyFromRawFieldsInternal(CopyFromState cstate,
+ char ***fields,
+ int *nfields,
+ bool is_csv);
/* Low-level communications functions */
@@ -740,8 +740,21 @@ CopyReadBinaryData(CopyFromState cstate, char *dest, int nbytes)
}
/*
- * Read raw fields in the next line for COPY FROM in text or csv mode.
- * Return false if no more lines.
+ * This function is exposed for use by extensions that read raw fields in the
+ * next line. See NextCopyFromRawFieldsInternal() for details.
+ */
+bool
+NextCopyFromRawFields(CopyFromState cstate, char ***fields, int *nfields)
+{
+ return NextCopyFromRawFieldsInternal(cstate, fields, nfields,
+ cstate->opts.csv_mode);
+}
+
+/*
+ * Workhorse for NextCopyFromRawFields().
+ *
+ * Read raw fields in the next line for COPY FROM in text or csv mode. Return
+ * false if no more lines.
*
* An internal temporary buffer is returned via 'fields'. It is valid until
* the next call of the function. Since the function returns all raw fields
@@ -749,32 +762,45 @@ CopyReadBinaryData(CopyFromState cstate, char *dest, int nbytes)
* in the relation.
*
* NOTE: force_not_null option are not applied to the returned fields.
+ *
+ * We use pg_attribute_always_inline to reduce function call overhead
+ * and to help compilers to optimize away the 'is_csv' condition when called
+ * by internal functions such as CopyFromTextLikeOneRow().
*/
-bool
-NextCopyFromRawFields(CopyFromState cstate, char ***fields, int *nfields)
+static pg_attribute_always_inline bool
+NextCopyFromRawFieldsInternal(CopyFromState cstate, char ***fields, int *nfields, bool is_csv)
{
int fldct;
- bool done;
+ bool done = false;
/* only available for text or csv input */
Assert(!cstate->opts.binary);
/* on input check that the header line is correct if needed */
- if (cstate->cur_lineno == 0 && cstate->opts.header_line)
+ if (cstate->cur_lineno == 0 && cstate->opts.header_line != COPY_HEADER_FALSE)
{
ListCell *cur;
TupleDesc tupDesc;
+ int lines_to_skip = cstate->opts.header_line;
+
+ /* If set to "match", one header line is skipped */
+ if (cstate->opts.header_line == COPY_HEADER_MATCH)
+ lines_to_skip = 1;
tupDesc = RelationGetDescr(cstate->rel);
- cstate->cur_lineno++;
- done = CopyReadLine(cstate);
+ for (int i = 0; i < lines_to_skip; i++)
+ {
+ cstate->cur_lineno++;
+ if ((done = CopyReadLine(cstate, is_csv)))
+ break;
+ }
if (cstate->opts.header_line == COPY_HEADER_MATCH)
{
int fldnum;
- if (cstate->opts.csv_mode)
+ if (is_csv)
fldct = CopyReadAttributesCSV(cstate);
else
fldct = CopyReadAttributesText(cstate);
@@ -818,7 +844,7 @@ NextCopyFromRawFields(CopyFromState cstate, char ***fields, int *nfields)
cstate->cur_lineno++;
/* Actually read the line into memory here */
- done = CopyReadLine(cstate);
+ done = CopyReadLine(cstate, is_csv);
/*
* EOF at start of line means we're done. If we see EOF after some
@@ -829,7 +855,7 @@ NextCopyFromRawFields(CopyFromState cstate, char ***fields, int *nfields)
return false;
/* Parse the line into de-escaped field values */
- if (cstate->opts.csv_mode)
+ if (is_csv)
fldct = CopyReadAttributesCSV(cstate);
else
fldct = CopyReadAttributesText(cstate);
@@ -856,233 +882,275 @@ NextCopyFrom(CopyFromState cstate, ExprContext *econtext,
{
TupleDesc tupDesc;
AttrNumber num_phys_attrs,
- attr_count,
num_defaults = cstate->num_defaults;
- FmgrInfo *in_functions = cstate->in_functions;
- Oid *typioparams = cstate->typioparams;
int i;
int *defmap = cstate->defmap;
ExprState **defexprs = cstate->defexprs;
tupDesc = RelationGetDescr(cstate->rel);
num_phys_attrs = tupDesc->natts;
- attr_count = list_length(cstate->attnumlist);
/* Initialize all values for row to NULL */
MemSet(values, 0, num_phys_attrs * sizeof(Datum));
MemSet(nulls, true, num_phys_attrs * sizeof(bool));
MemSet(cstate->defaults, false, num_phys_attrs * sizeof(bool));
- if (!cstate->opts.binary)
+ /* Get one row from source */
+ if (!cstate->routine->CopyFromOneRow(cstate, econtext, values, nulls))
+ return false;
+
+ /*
+ * Now compute and insert any defaults available for the columns not
+ * provided by the input data. Anything not processed here or above will
+ * remain NULL.
+ */
+ for (i = 0; i < num_defaults; i++)
{
- char **field_strings;
- ListCell *cur;
- int fldct;
- int fieldno;
- char *string;
+ /*
+ * The caller must supply econtext and have switched into the
+ * per-tuple memory context in it.
+ */
+ Assert(econtext != NULL);
+ Assert(CurrentMemoryContext == econtext->ecxt_per_tuple_memory);
- /* read raw fields in the next line */
- if (!NextCopyFromRawFields(cstate, &field_strings, &fldct))
- return false;
+ values[defmap[i]] = ExecEvalExpr(defexprs[defmap[i]], econtext,
+ &nulls[defmap[i]]);
+ }
+
+ return true;
+}
+
+/* Implementation of the per-row callback for text format */
+bool
+CopyFromTextOneRow(CopyFromState cstate, ExprContext *econtext, Datum *values,
+ bool *nulls)
+{
+ return CopyFromTextLikeOneRow(cstate, econtext, values, nulls, false);
+}
+
+/* Implementation of the per-row callback for CSV format */
+bool
+CopyFromCSVOneRow(CopyFromState cstate, ExprContext *econtext, Datum *values,
+ bool *nulls)
+{
+ return CopyFromTextLikeOneRow(cstate, econtext, values, nulls, true);
+}
+
+/*
+ * Workhorse for CopyFromTextOneRow() and CopyFromCSVOneRow().
+ *
+ * We use pg_attribute_always_inline to reduce function call overhead
+ * and to help compilers to optimize away the 'is_csv' condition.
+ */
+static pg_attribute_always_inline bool
+CopyFromTextLikeOneRow(CopyFromState cstate, ExprContext *econtext,
+ Datum *values, bool *nulls, bool is_csv)
+{
+ TupleDesc tupDesc;
+ AttrNumber attr_count;
+ FmgrInfo *in_functions = cstate->in_functions;
+ Oid *typioparams = cstate->typioparams;
+ ExprState **defexprs = cstate->defexprs;
+ char **field_strings;
+ ListCell *cur;
+ int fldct;
+ int fieldno;
+ char *string;
- /* check for overflowing fields */
- if (attr_count > 0 && fldct > attr_count)
+ tupDesc = RelationGetDescr(cstate->rel);
+ attr_count = list_length(cstate->attnumlist);
+
+ /* read raw fields in the next line */
+ if (!NextCopyFromRawFieldsInternal(cstate, &field_strings, &fldct, is_csv))
+ return false;
+
+ /* check for overflowing fields */
+ if (attr_count > 0 && fldct > attr_count)
+ ereport(ERROR,
+ (errcode(ERRCODE_BAD_COPY_FILE_FORMAT),
+ errmsg("extra data after last expected column")));
+
+ fieldno = 0;
+
+ /* Loop to read the user attributes on the line. */
+ foreach(cur, cstate->attnumlist)
+ {
+ int attnum = lfirst_int(cur);
+ int m = attnum - 1;
+ Form_pg_attribute att = TupleDescAttr(tupDesc, m);
+
+ if (fieldno >= fldct)
ereport(ERROR,
(errcode(ERRCODE_BAD_COPY_FILE_FORMAT),
- errmsg("extra data after last expected column")));
+ errmsg("missing data for column \"%s\"",
+ NameStr(att->attname))));
+ string = field_strings[fieldno++];
- fieldno = 0;
-
- /* Loop to read the user attributes on the line. */
- foreach(cur, cstate->attnumlist)
+ if (cstate->convert_select_flags &&
+ !cstate->convert_select_flags[m])
{
- int attnum = lfirst_int(cur);
- int m = attnum - 1;
- Form_pg_attribute att = TupleDescAttr(tupDesc, m);
-
- if (fieldno >= fldct)
- ereport(ERROR,
- (errcode(ERRCODE_BAD_COPY_FILE_FORMAT),
- errmsg("missing data for column \"%s\"",
- NameStr(att->attname))));
- string = field_strings[fieldno++];
+ /* ignore input field, leaving column as NULL */
+ continue;
+ }
- if (cstate->convert_select_flags &&
- !cstate->convert_select_flags[m])
+ if (is_csv)
+ {
+ if (string == NULL &&
+ cstate->opts.force_notnull_flags[m])
{
- /* ignore input field, leaving column as NULL */
- continue;
+ /*
+ * FORCE_NOT_NULL option is set and column is NULL - convert
+ * it to the NULL string.
+ */
+ string = cstate->opts.null_print;
}
-
- if (cstate->opts.csv_mode)
+ else if (string != NULL && cstate->opts.force_null_flags[m]
+ && strcmp(string, cstate->opts.null_print) == 0)
{
- if (string == NULL &&
- cstate->opts.force_notnull_flags[m])
- {
- /*
- * FORCE_NOT_NULL option is set and column is NULL -
- * convert it to the NULL string.
- */
- string = cstate->opts.null_print;
- }
- else if (string != NULL && cstate->opts.force_null_flags[m]
- && strcmp(string, cstate->opts.null_print) == 0)
- {
- /*
- * FORCE_NULL option is set and column matches the NULL
- * string. It must have been quoted, or otherwise the
- * string would already have been set to NULL. Convert it
- * to NULL as specified.
- */
- string = NULL;
- }
+ /*
+ * FORCE_NULL option is set and column matches the NULL
+ * string. It must have been quoted, or otherwise the string
+ * would already have been set to NULL. Convert it to NULL as
+ * specified.
+ */
+ string = NULL;
}
+ }
- cstate->cur_attname = NameStr(att->attname);
- cstate->cur_attval = string;
+ cstate->cur_attname = NameStr(att->attname);
+ cstate->cur_attval = string;
- if (string != NULL)
- nulls[m] = false;
+ if (string != NULL)
+ nulls[m] = false;
- if (cstate->defaults[m])
- {
- /*
- * The caller must supply econtext and have switched into the
- * per-tuple memory context in it.
- */
- Assert(econtext != NULL);
- Assert(CurrentMemoryContext == econtext->ecxt_per_tuple_memory);
+ if (cstate->defaults[m])
+ {
+ /* We must have switched into the per-tuple memory context */
+ Assert(econtext != NULL);
+ Assert(CurrentMemoryContext == econtext->ecxt_per_tuple_memory);
- values[m] = ExecEvalExpr(defexprs[m], econtext, &nulls[m]);
- }
+ values[m] = ExecEvalExpr(defexprs[m], econtext, &nulls[m]);
+ }
- /*
- * If ON_ERROR is specified with IGNORE, skip rows with soft
- * errors
- */
- else if (!InputFunctionCallSafe(&in_functions[m],
- string,
- typioparams[m],
- att->atttypmod,
- (Node *) cstate->escontext,
- &values[m]))
- {
- Assert(cstate->opts.on_error != COPY_ON_ERROR_STOP);
+ /*
+ * If ON_ERROR is specified with IGNORE, skip rows with soft errors
+ */
+ else if (!InputFunctionCallSafe(&in_functions[m],
+ string,
+ typioparams[m],
+ att->atttypmod,
+ (Node *) cstate->escontext,
+ &values[m]))
+ {
+ Assert(cstate->opts.on_error != COPY_ON_ERROR_STOP);
- cstate->num_errors++;
+ cstate->num_errors++;
- if (cstate->opts.log_verbosity == COPY_LOG_VERBOSITY_VERBOSE)
- {
- /*
- * Since we emit line number and column info in the below
- * notice message, we suppress error context information
- * other than the relation name.
- */
- Assert(!cstate->relname_only);
- cstate->relname_only = true;
+ if (cstate->opts.log_verbosity == COPY_LOG_VERBOSITY_VERBOSE)
+ {
+ /*
+ * Since we emit line number and column info in the below
+ * notice message, we suppress error context information other
+ * than the relation name.
+ */
+ Assert(!cstate->relname_only);
+ cstate->relname_only = true;
- if (cstate->cur_attval)
- {
- char *attval;
-
- attval = CopyLimitPrintoutLength(cstate->cur_attval);
- ereport(NOTICE,
- errmsg("skipping row due to data type incompatibility at line %llu for column %s: \"%s\"",
- (unsigned long long) cstate->cur_lineno,
- cstate->cur_attname,
- attval));
- pfree(attval);
- }
- else
- ereport(NOTICE,
- errmsg("skipping row due to data type incompatibility at line %llu for column %s: null input",
- (unsigned long long) cstate->cur_lineno,
- cstate->cur_attname));
-
- /* reset relname_only */
- cstate->relname_only = false;
+ if (cstate->cur_attval)
+ {
+ char *attval;
+
+ attval = CopyLimitPrintoutLength(cstate->cur_attval);
+ ereport(NOTICE,
+ errmsg("skipping row due to data type incompatibility at line %" PRIu64 " for column \"%s\": \"%s\"",
+ cstate->cur_lineno,
+ cstate->cur_attname,
+ attval));
+ pfree(attval);
}
+ else
+ ereport(NOTICE,
+ errmsg("skipping row due to data type incompatibility at line %" PRIu64 " for column \"%s\": null input",
+ cstate->cur_lineno,
+ cstate->cur_attname));
- return true;
+ /* reset relname_only */
+ cstate->relname_only = false;
}
- cstate->cur_attname = NULL;
- cstate->cur_attval = NULL;
+ return true;
}
- Assert(fieldno == attr_count);
+ cstate->cur_attname = NULL;
+ cstate->cur_attval = NULL;
}
- else
- {
- /* binary */
- int16 fld_count;
- ListCell *cur;
- cstate->cur_lineno++;
+ Assert(fieldno == attr_count);
- if (!CopyGetInt16(cstate, &fld_count))
- {
- /* EOF detected (end of file, or protocol-level EOF) */
- return false;
- }
+ return true;
+}
- if (fld_count == -1)
- {
- /*
- * Received EOF marker. Wait for the protocol-level EOF, and
- * complain if it doesn't come immediately. In COPY FROM STDIN,
- * this ensures that we correctly handle CopyFail, if client
- * chooses to send that now. When copying from file, we could
- * ignore the rest of the file like in text mode, but we choose to
- * be consistent with the COPY FROM STDIN case.
- */
- char dummy;
+/* Implementation of the per-row callback for binary format */
+bool
+CopyFromBinaryOneRow(CopyFromState cstate, ExprContext *econtext, Datum *values,
+ bool *nulls)
+{
+ TupleDesc tupDesc;
+ AttrNumber attr_count;
+ FmgrInfo *in_functions = cstate->in_functions;
+ Oid *typioparams = cstate->typioparams;
+ int16 fld_count;
+ ListCell *cur;
- if (CopyReadBinaryData(cstate, &dummy, 1) > 0)
- ereport(ERROR,
- (errcode(ERRCODE_BAD_COPY_FILE_FORMAT),
- errmsg("received copy data after EOF marker")));
- return false;
- }
+ tupDesc = RelationGetDescr(cstate->rel);
+ attr_count = list_length(cstate->attnumlist);
- if (fld_count != attr_count)
- ereport(ERROR,
- (errcode(ERRCODE_BAD_COPY_FILE_FORMAT),
- errmsg("row field count is %d, expected %d",
- (int) fld_count, attr_count)));
+ cstate->cur_lineno++;
- foreach(cur, cstate->attnumlist)
- {
- int attnum = lfirst_int(cur);
- int m = attnum - 1;
- Form_pg_attribute att = TupleDescAttr(tupDesc, m);
-
- cstate->cur_attname = NameStr(att->attname);
- values[m] = CopyReadBinaryAttribute(cstate,
- &in_functions[m],
- typioparams[m],
- att->atttypmod,
- &nulls[m]);
- cstate->cur_attname = NULL;
- }
+ if (!CopyGetInt16(cstate, &fld_count))
+ {
+ /* EOF detected (end of file, or protocol-level EOF) */
+ return false;
}
- /*
- * Now compute and insert any defaults available for the columns not
- * provided by the input data. Anything not processed here or above will
- * remain NULL.
- */
- for (i = 0; i < num_defaults; i++)
+ if (fld_count == -1)
{
/*
- * The caller must supply econtext and have switched into the
- * per-tuple memory context in it.
+ * Received EOF marker. Wait for the protocol-level EOF, and complain
+ * if it doesn't come immediately. In COPY FROM STDIN, this ensures
+ * that we correctly handle CopyFail, if client chooses to send that
+ * now. When copying from file, we could ignore the rest of the file
+ * like in text mode, but we choose to be consistent with the COPY
+ * FROM STDIN case.
*/
- Assert(econtext != NULL);
- Assert(CurrentMemoryContext == econtext->ecxt_per_tuple_memory);
+ char dummy;
- values[defmap[i]] = ExecEvalExpr(defexprs[defmap[i]], econtext,
- &nulls[defmap[i]]);
+ if (CopyReadBinaryData(cstate, &dummy, 1) > 0)
+ ereport(ERROR,
+ (errcode(ERRCODE_BAD_COPY_FILE_FORMAT),
+ errmsg("received copy data after EOF marker")));
+ return false;
+ }
+
+ if (fld_count != attr_count)
+ ereport(ERROR,
+ (errcode(ERRCODE_BAD_COPY_FILE_FORMAT),
+ errmsg("row field count is %d, expected %d",
+ (int) fld_count, attr_count)));
+
+ foreach(cur, cstate->attnumlist)
+ {
+ int attnum = lfirst_int(cur);
+ int m = attnum - 1;
+ Form_pg_attribute att = TupleDescAttr(tupDesc, m);
+
+ cstate->cur_attname = NameStr(att->attname);
+ values[m] = CopyReadBinaryAttribute(cstate,
+ &in_functions[m],
+ typioparams[m],
+ att->atttypmod,
+ &nulls[m]);
+ cstate->cur_attname = NULL;
}
return true;
@@ -1096,7 +1164,7 @@ NextCopyFrom(CopyFromState cstate, ExprContext *econtext,
* in the final value of line_buf.
*/
static bool
-CopyReadLine(CopyFromState cstate)
+CopyReadLine(CopyFromState cstate, bool is_csv)
{
bool result;
@@ -1104,7 +1172,7 @@ CopyReadLine(CopyFromState cstate)
cstate->line_buf_valid = false;
/* Parse data and transfer into line_buf */
- result = CopyReadLineText(cstate);
+ result = CopyReadLineText(cstate, is_csv);
if (result)
{
@@ -1172,7 +1240,7 @@ CopyReadLine(CopyFromState cstate)
* CopyReadLineText - inner loop of CopyReadLine for text mode
*/
static bool
-CopyReadLineText(CopyFromState cstate)
+CopyReadLineText(CopyFromState cstate, bool is_csv)
{
char *copy_input_buf;
int input_buf_ptr;
@@ -1182,13 +1250,12 @@ CopyReadLineText(CopyFromState cstate)
bool result = false;
/* CSV variables */
- bool first_char_in_line = true;
bool in_quote = false,
last_was_esc = false;
char quotec = '\0';
char escapec = '\0';
- if (cstate->opts.csv_mode)
+ if (is_csv)
{
quotec = cstate->opts.quote[0];
escapec = cstate->opts.escape[0];
@@ -1265,15 +1332,15 @@ CopyReadLineText(CopyFromState cstate)
prev_raw_ptr = input_buf_ptr;
c = copy_input_buf[input_buf_ptr++];
- if (cstate->opts.csv_mode)
+ if (is_csv)
{
/*
- * If character is '\\' or '\r', we may need to look ahead below.
- * Force fetch of the next character if we don't already have it.
- * We need to do this before changing CSV state, in case one of
- * these characters is also the quote or escape character.
+ * If character is '\r', we may need to look ahead below. Force
+ * fetch of the next character if we don't already have it. We
+ * need to do this before changing CSV state, in case '\r' is also
+ * the quote or escape character.
*/
- if (c == '\\' || c == '\r')
+ if (c == '\r')
{
IF_NEED_REFILL_AND_NOT_EOF_CONTINUE(0);
}
@@ -1304,7 +1371,7 @@ CopyReadLineText(CopyFromState cstate)
}
/* Process \r */
- if (c == '\r' && (!cstate->opts.csv_mode || !in_quote))
+ if (c == '\r' && (!is_csv || !in_quote))
{
/* Check for \r\n on first line, _and_ handle \r\n. */
if (cstate->eol_type == EOL_UNKNOWN ||
@@ -1332,10 +1399,10 @@ CopyReadLineText(CopyFromState cstate)
if (cstate->eol_type == EOL_CRNL)
ereport(ERROR,
(errcode(ERRCODE_BAD_COPY_FILE_FORMAT),
- !cstate->opts.csv_mode ?
+ !is_csv ?
errmsg("literal carriage return found in data") :
errmsg("unquoted carriage return found in data"),
- !cstate->opts.csv_mode ?
+ !is_csv ?
errhint("Use \"\\r\" to represent carriage return.") :
errhint("Use quoted CSV field to represent carriage return.")));
@@ -1349,10 +1416,10 @@ CopyReadLineText(CopyFromState cstate)
else if (cstate->eol_type == EOL_NL)
ereport(ERROR,
(errcode(ERRCODE_BAD_COPY_FILE_FORMAT),
- !cstate->opts.csv_mode ?
+ !is_csv ?
errmsg("literal carriage return found in data") :
errmsg("unquoted carriage return found in data"),
- !cstate->opts.csv_mode ?
+ !is_csv ?
errhint("Use \"\\r\" to represent carriage return.") :
errhint("Use quoted CSV field to represent carriage return.")));
/* If reach here, we have found the line terminator */
@@ -1360,15 +1427,15 @@ CopyReadLineText(CopyFromState cstate)
}
/* Process \n */
- if (c == '\n' && (!cstate->opts.csv_mode || !in_quote))
+ if (c == '\n' && (!is_csv || !in_quote))
{
if (cstate->eol_type == EOL_CR || cstate->eol_type == EOL_CRNL)
ereport(ERROR,
(errcode(ERRCODE_BAD_COPY_FILE_FORMAT),
- !cstate->opts.csv_mode ?
+ !is_csv ?
errmsg("literal newline found in data") :
errmsg("unquoted newline found in data"),
- !cstate->opts.csv_mode ?
+ !is_csv ?
errhint("Use \"\\n\" to represent newline.") :
errhint("Use quoted CSV field to represent newline.")));
cstate->eol_type = EOL_NL; /* in case not set yet */
@@ -1377,10 +1444,10 @@ CopyReadLineText(CopyFromState cstate)
}
/*
- * In CSV mode, we only recognize \. alone on a line. This is because
- * \. is a valid CSV data value.
+ * Process backslash, except in CSV mode where backslash is a normal
+ * character.
*/
- if (c == '\\' && (!cstate->opts.csv_mode || first_char_in_line))
+ if (c == '\\' && !is_csv)
{
char c2;
@@ -1398,12 +1465,6 @@ CopyReadLineText(CopyFromState cstate)
if (c2 == '.')
{
input_buf_ptr++; /* consume the '.' */
-
- /*
- * Note: if we loop back for more data here, it does not
- * matter that the CSV state change checks are re-executed; we
- * will come back here with no important state changed.
- */
if (cstate->eol_type == EOL_CRNL)
{
/* Get the next character */
@@ -1412,23 +1473,13 @@ CopyReadLineText(CopyFromState cstate)
c2 = copy_input_buf[input_buf_ptr++];
if (c2 == '\n')
- {
- if (!cstate->opts.csv_mode)
- ereport(ERROR,
- (errcode(ERRCODE_BAD_COPY_FILE_FORMAT),
- errmsg("end-of-copy marker does not match previous newline style")));
- else
- NO_END_OF_COPY_GOTO;
- }
+ ereport(ERROR,
+ (errcode(ERRCODE_BAD_COPY_FILE_FORMAT),
+ errmsg("end-of-copy marker does not match previous newline style")));
else if (c2 != '\r')
- {
- if (!cstate->opts.csv_mode)
- ereport(ERROR,
- (errcode(ERRCODE_BAD_COPY_FILE_FORMAT),
- errmsg("end-of-copy marker corrupt")));
- else
- NO_END_OF_COPY_GOTO;
- }
+ ereport(ERROR,
+ (errcode(ERRCODE_BAD_COPY_FILE_FORMAT),
+ errmsg("end-of-copy marker is not alone on its line")));
}
/* Get the next character */
@@ -1437,37 +1488,34 @@ CopyReadLineText(CopyFromState cstate)
c2 = copy_input_buf[input_buf_ptr++];
if (c2 != '\r' && c2 != '\n')
- {
- if (!cstate->opts.csv_mode)
- ereport(ERROR,
- (errcode(ERRCODE_BAD_COPY_FILE_FORMAT),
- errmsg("end-of-copy marker corrupt")));
- else
- NO_END_OF_COPY_GOTO;
- }
+ ereport(ERROR,
+ (errcode(ERRCODE_BAD_COPY_FILE_FORMAT),
+ errmsg("end-of-copy marker is not alone on its line")));
if ((cstate->eol_type == EOL_NL && c2 != '\n') ||
(cstate->eol_type == EOL_CRNL && c2 != '\n') ||
(cstate->eol_type == EOL_CR && c2 != '\r'))
- {
ereport(ERROR,
(errcode(ERRCODE_BAD_COPY_FILE_FORMAT),
errmsg("end-of-copy marker does not match previous newline style")));
- }
/*
- * Transfer only the data before the \. into line_buf, then
- * discard the data and the \. sequence.
+ * If there is any data on this line before the \., complain.
+ */
+ if (cstate->line_buf.len > 0 ||
+ prev_raw_ptr > cstate->input_buf_index)
+ ereport(ERROR,
+ (errcode(ERRCODE_BAD_COPY_FILE_FORMAT),
+ errmsg("end-of-copy marker is not alone on its line")));
+
+ /*
+ * Discard the \. and newline, then report EOF.
*/
- if (prev_raw_ptr > cstate->input_buf_index)
- appendBinaryStringInfo(&cstate->line_buf,
- cstate->input_buf + cstate->input_buf_index,
- prev_raw_ptr - cstate->input_buf_index);
cstate->input_buf_index = input_buf_ptr;
result = true; /* report EOF */
break;
}
- else if (!cstate->opts.csv_mode)
+ else
{
/*
* If we are here, it means we found a backslash followed by
@@ -1475,23 +1523,11 @@ CopyReadLineText(CopyFromState cstate)
* after a backslash is special, so we skip over that second
* character too. If we didn't do that \\. would be
* considered an eof-of copy, while in non-CSV mode it is a
- * literal backslash followed by a period. In CSV mode,
- * backslashes are not special, so we want to process the
- * character after the backslash just like a normal character,
- * so we don't increment in those cases.
+ * literal backslash followed by a period.
*/
input_buf_ptr++;
}
}
-
- /*
- * This label is for CSV cases where \. appears at the start of a
- * line, but there is more text after it, meaning it was a data value.
- * We are more strict for \. in CSV mode because \. could be a data
- * value, while in non-CSV mode, \. cannot be a data value.
- */
-not_end_of_copy:
- first_char_in_line = false;
} /* end of outer loop */
/*
@@ -1511,7 +1547,7 @@ GetDecimalFromHex(char hex)
if (isdigit((unsigned char) hex))
return hex - '0';
else
- return tolower((unsigned char) hex) - 'a' + 10;
+ return pg_ascii_tolower((unsigned char) hex) - 'a' + 10;
}
/*
diff --git a/src/backend/commands/copyto.c b/src/backend/commands/copyto.c
index ae8b2e36d72db..67b94b91cae44 100644
--- a/src/backend/commands/copyto.c
+++ b/src/backend/commands/copyto.c
@@ -3,7 +3,7 @@
* copyto.c
* COPY