diff --git a/doc/src/sgml/func.sgml b/doc/src/sgml/func.sgml index 7efc819..f7d3f6e 100644 --- a/doc/src/sgml/func.sgml +++ b/doc/src/sgml/func.sgml @@ -14323,31 +14323,95 @@ CREATE TYPE rainbow AS ENUM ('red', 'orange', 'yellow', 'green', 'blue', 'purple - PostgreSQL includes several functions to generate a UUID. + PostgreSQL provides functions for generating + Universally Unique Identifiers (UUIDs) as defined by + RFC 9562. + This section details the UUID functions included in the core distribution. + + + + The module provides additional functions that + implement other standard algorithms for generating UUIDs. + + + + PostgreSQL also provides the usual comparison + operators shown in for + UUIDs. + + + + Generating Version 7 UUIDs + + +uuidv7 ( offset +interval ) uuid + + + + The uuidv7() function is designed as the preferred + method for generating primary keys, offering an alternative to integer data + types backed by sequence generators. + + + + The function returns a version 7 UUID, which includes a UNIX timestamp with + millisecond precision, a 12-bit sub-millisecond timestamp, and a random + component. This function can accept optional offset + parameter of type interval which is added to the internal + timestamp. + + + + Monotonically increasing identifiers are generated even if the system clock + jumps backward, if access to the system clock is unavailable, or if UUIDs + are generated at a very high frequency, due to the internal timestamp + functioning as a counter to maintain order. + + + + If the offset parameter results in a timestamp + overflow or a negative timestamp, an adjusted timestamp value is + automatically used. The timestamp behaves like a ring buffer: when the + maximum value is exceeded, it wraps around to the minimum value. Similarly, + if the absolute value of the negative offset exceeds + the time elapsed since 00:00:00 UTC on 1 January, 1970, the timestamp wraps + around to the maximum value. + + + + + + Generating Version 4 UUIDs + gen_random_uuid () uuid uuidv4 () uuid + + These functions return a version 4 (random) UUID. - -uuidv7 ( shift interval ) uuid - - This function returns a version 7 UUID (UNIX timestamp with millisecond - precision + sub-millisecond timestamp + random). This function can accept - optional shift parameter of type interval - which shift internal timestamp by the given interval. - + + + + They are not recommended for generation of primary keys. + + + + + + Extracting Data from UUIDs - The module provides additional functions that - implement other standard algorithms for generating UUIDs. +There are also two functions to extract data from UUIDs: - - There are also functions to extract data from UUIDs: -uuid_extract_timestamp (uuid) timestamp with time zone +uuid_extract_timestamp (uuid) timestamp with +time zone + + This function 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 @@ -14355,22 +14419,195 @@ CREATE TYPE rainbow AS ENUM ('red', 'orange', 'yellow', 'green', 'blue', 'purple UUID. - -uuid_extract_version (uuid) smallint +uuid_extract_version (uuid) +smallint + + This function 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 + RFC 9562. + 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. - + + + + Deciding Whether and Which UUID to Use + + + UUIDs serve as unique identifiers. Alternatives include integer data types + backed by a sequence generator. When choosing between them for primary keys, + consider the following information. + + + + + + + No. + Disadvantages or limitations of identifier types + uuidv4() + uuidv7() + uuidv7(offset) + identity or bigserial + + + + + + + 1. + Data merging necessitates key replacement; furthermore, + maintaining key relationships requires disk space + NO + NO + NO + YES + + + + 2. + Exporting data to external information systems requires key + replacement + NO + NO + NO + YES + + + + 3. + Synchronization is necessary for distributed generation across + multiple processes (microservices) + NO + NO + NO + YES + + + + 4. + Lock contention arises from concurrent writes to the same table + by multiple processes (microservices) + NO + YES + NO (with several offsets) + YES + + + + 5. + Identifier locality absence reduces performance and increases + index size + YES + NO + NO + NO + + + + 6. + Identifier locality absence results in inefficient + partitioning + YES + NO + NO + NO + + + + 7. + The record creation order is unknown for logging systems, + time-series databases, debugging, and auditing + YES + NO + NO (with nondecreasing offsets) + NO + + + + 8. + The number of records within the table is disclosed + NO + NO + NO + YES + + + + 9. + The record creation date and time are disclosed + NO + YES + NO + NO + + + + 10. + A longer identifier is utilized + YES + YES + YES + NO + + + + 11. + Identifier-based full-text search is ambiguous + NO + NO + NO + YES + + + + 12. + Erroneous accidental key matches occur + NO + NO + NO + YES + + + + 13. + Valid keys can be generated maliciously + NO + NO + NO + YES + + + + + + + + When generating identifiers simultaneously in several client sessions, the + uuidv7() function does not guarantee monotonicity, + although monotonicity is usually preserved in such a situation. + + + + In real-world scenarios, the performance of keys generated by + uuidv7() function is nearly equivalent to that of + identity or bigserial type, significantly + outperforming uuidv4(). + + + + It is advisable to assess the performance of keys generated by different + methods using the benchmarking utility, along + with custom scenarios and script files tailored to your specific + requirements. + + + +