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 includes 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

diff --git a/doc/src/sgml/datatype.sgml b/doc/src/sgml/datatype.sgml
index 87679dc4a11dd8375dfd45fed1709b8f7cdbb29b..09309ba0390b72cd20e3a47f315212bda364d428 100644 (file)
--- 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 0e6c534965254e86561a821c7a3933ddbf6e2fc2..bf31b1f3eeed7d6dfe883cf64d8f81bdface15d8 100644 (file)
--- 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.
+