From 26e742558b96c684c6f1db708dd45057e6687b1b Mon Sep 17 00:00:00 2001 From: Masahiko Sawada Date: Fri, 28 Feb 2025 10:42:21 -0800 Subject: [PATCH] doc: Convert UUID functions list to table format. Convert the list of UUID functions into a table for better readability. This commit also adds references to the UUID type section and include descriptions of different UUID generation algorithm versions. Author: Andy Alsup Reviewed-by: Laurenz Albe Discussion: https://postgr.es/m/CADOZ7s7OHag+r6w+BzKw2xgb3fVtAD-pU=_N9-9pSe5W1TB+xQ@mail.gmail.com --- doc/src/sgml/datatype.sgml | 9 ++ doc/src/sgml/func.sgml | 182 +++++++++++++++++++++++++++++-------- 2 files changed, 155 insertions(+), 36 deletions(-) diff --git a/doc/src/sgml/datatype.sgml b/doc/src/sgml/datatype.sgml index 87679dc4a11d..09309ba0390b 100644 --- a/doc/src/sgml/datatype.sgml +++ b/doc/src/sgml/datatype.sgml @@ -4407,6 +4407,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 diff --git a/doc/src/sgml/func.sgml b/doc/src/sgml/func.sgml index 0e6c53496525..e0f5a346587b 100644 --- a/doc/src/sgml/func.sgml +++ b/doc/src/sgml/func.sgml @@ -14328,54 +14328,164 @@ CREATE TYPE rainbow AS ENUM ('red', 'orange', 'yellow', 'green', 'blue', 'purple - PostgreSQL includes several functions to generate a UUID. - -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. + shows the PostgreSQL + functions that can be used to generate UUIDs. - - The module provides additional functions that - implement other standard algorithms for generating UUIDs. - + + <acronym>UUID</acronym> Generation Functions + + + + + + Function + + + Description + + + Example(s) + + + + - - 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 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. - + + + + + 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 + ( shift interval ) + 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. + + - -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 - generated by gen_random_uuid, this function will - return 4. + 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-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-885799a4af1d'::UUID) + 4 + + + uuid_extract_version('019535d9-3df7-79fb-b466-fa907fa17f9e'::UUID) + 7 + + + + + +
+ PostgreSQL also provides the usual comparison operators shown in for UUIDs. + + See for details on the data type + uuid in PostgreSQL. +