Merge pull request #468 from percona/ps-9684

PS-9684 [DOCS]- provide description for UUID_VX component 8.0

Author: patrickbirch

docs/uuid-versions.md

@@ -1,40 +1,71 @@
 # UUID_VX component
 
-A Universally Unique Identifier (UUID) is a 128-bit number used to identify information uniquely in computer systems. It is often represented as a 32-character hexadecimal string divided into five groups separated by hyphens.
+The `UUID_VX` component in Percona Server for MySQL provides functions to work with different versions of Universally Unique Identifiers (UUIDs). It allows for:
 
-| Benefit                | Description |
-|------------------------|-------------|
-| Global Uniqueness      | UUIDs ensure that each identifier is unique across different databases and systems without needing a central authority to manage the IDs. This prevents ID conflicts when merging data from multiple sources. |
-| Decentralized Generation | Since UUIDs can be generated independently by different systems, there is no need for coordination. This is particularly useful in distributed environments where systems might not have constant communication with each other. |
-| Scalability            | UUIDs support scalability in distributed databases. New records can be added without worrying about generating duplicate IDs, even when data is inserted concurrently across multiple nodes. |
-| Improved Data Merging  | When data from various sources is combined, UUIDs prevent conflicts, making the merging process simpler and more reliable. |
-| Security               | UUIDs, especially those generated randomly (like UUIDv4), are hard to predict, adding a layer of security when used as identifiers. |
+* Managing any UUID version: You can handle various UUID versions, including UUIDv1, UUIDv4, and others.  
 
-The following table describes the UUID versions:
+* Generating UUIDs for specific versions: This includes creating time-based UUIDs (versions 1, 6, and 7) and random UUIDs (version 4).  
 
-| UUID Version | Description |
-|--------------|-------------|
-| Version 1 (Time-based) | - Generated using the current time and a node identifier (usually the MAC address). <br> - Ensures uniqueness over time and across nodes. |
-| Version 2 (DCE Security) | - Similar to version 1 but includes additional information such as POSIX UID/GID. <br> - Often used in environments requiring enhanced security. |
-| Version 3 (Name-based, MD5 hash) | - Generated from a namespace identifier and a name (string). <br> - Uses the MD5 hashing algorithm to ensure the UUID is derived from the namespace and name. |
-| Version 4 (Random) | - Generated using random numbers. <br> - Offers high uniqueness and is easy to generate without requiring specific inputs. |
-| Version 5 (Name-based, SHA-1 hash) | - Similar to version 3 but uses the SHA-1 hashing algorithm. <br> - Provides a stronger hash function than MD5. |
-| Version 6 (Time-ordered) | - A reordered version of UUIDv1 for better indexing and storage efficiency. <br> - Combines timestamp and random or unique data. |
-| Version 7 (Unix Epoch Time) | - Combines a high-precision timestamp with random data. <br> - Provides unique, time-ordered UUIDs that are ideal for database indexing. |
-| Version 8 (Custom) | - Reserved for user-defined purposes and experimental uses. <br> - Allows custom formats and structures according to specific requirements. |
+* Enhancing support for UUID-based operations: This adds flexibility in how UUIDs are generated and used within the database.  
 
-UUID version 4 (UUIDv4) generates a unique identifier using random numbers. This randomness ensures a high level of uniqueness without needing a central authority to manage IDs. However, using UUIDv4 as a primary key in a distributed database is not recommended. The random nature of UUIDv4 leads to several issues:
+By utilizing `UUID_VX`, you can tailor UUID generation to suit your application's needs. For instance, time-based UUIDs ensure chronological ordering, which can improve indexing and query performance in distributed systems. Random UUIDs, on the other hand, provide a higher level of uniqueness and are useful for security-sensitive applications.  
 
-| Issue            | Description                                                                                                  |
-|------------------|--------------------------------------------------------------------------------------------------------------|
-| Inefficient Indexing | UUIDv4 does not follow any order, causing inefficient indexing. Databases struggle to keep records organized, leading to slower query performance. |
-| Fragmentation    | The random distribution of UUIDv4 can cause data fragmentation, making database storage less efficient.     |
-| Storage Space    | UUIDs are larger (128 bits) than traditional integer keys, consuming more storage space and memory.         |
+This component empowers developers to optimize their database operations by choosing the most appropriate UUID version for their specific scenarios.
 
+## Universally unique identifier (UUID) overview  
 
-For better performance and efficiency in a distributed database, consider using  UUIDv7, which incorporates timestamps for some order levels.
+A universally unique identifier (UUID) is a 128-bit number used to uniquely identify information in computer systems. It is commonly represented as a 32-character hexadecimal string divided into five groups separated by hyphens.  
 
-UUID version 7 (UUIDv7) creates time-ordered identifiers by encoding a Unix timestamp with millisecond precision in the first 48 bits. It uses 6 bits to specify the UUID version and variant, while the remaining 74 bits are random. This time-ordering results in nearly sequential values, which helps improve index performance and locality in distributed systems.
+## Benefits of using UUIDs  
+
+UUIDs offer several advantages in distributed systems:  
+
+* Global uniqueness: UUIDs ensure that each identifier is unique across different databases and systems without needing a central authority. This prevents ID conflicts when merging data from multiple sources.  
+
+* Decentralized generation: UUIDs can be generated independently by different systems, removing the need for coordination. This is particularly useful in distributed environments.  
+
+* Scalability: UUIDs support distributed databases by allowing new records to be added without generating duplicate IDs, even with concurrent insertions.  
+
+* Improved data merging: UUIDs prevent conflicts when combining data from different sources, simplifying the merging process.  
+
+* Security: Randomly generated UUIDs (like UUIDv4) are hard to predict, adding an extra security layer when used as identifiers.  
+
+## UUID versions  
+
+The table below describes the different UUID versions and their characteristics:  
+
+| UUID version | Description |
+|-------------|-------------|
+| Version 1 (time-based) | - Generated using the current time and a node identifier (usually a MAC address). <br> - Ensures uniqueness over time and across nodes. |
+| Version 2 (DCE security) | - Similar to version 1 but includes POSIX UID/GID for enhanced security. |
+| Version 3 (name-based, MD5 hash) | - Generated from a namespace identifier and a name (string). <br> - Uses the MD5 hashing algorithm to derive the UUID. |
+| Version 4 (random) | - Completely random UUIDs. <br> - Offers uniqueness without requiring specific inputs. |
+| Version 5 (name-based, SHA-1 hash) | - Similar to version 3 but uses SHA-1 instead of MD5 for a stronger hash function. |
+| Version 6 (time-ordered) | - A reordered version of UUIDv1 for better indexing and storage efficiency. |
+| Version 7 (Unix epoch time) | - Encodes a high-precision Unix timestamp with random data. <br> - Provides unique, time-ordered UUIDs ideal for database indexing. |
+| Version 8 (custom) | - Reserved for user-defined and experimental purposes. <br> - Allows custom formats and structures. |
+
+## Challenges with UUIDv4 in databases  
+
+While UUIDv4 provides strong uniqueness through randomness, using it as a primary key in distributed databases is generally discouraged due to the following issues:  
+
+| Issue | Description |
+|-------|-------------|
+| Inefficient indexing | UUIDv4 lacks order, making it inefficient for indexing. Databases struggle to keep records organized, leading to slower query performance. |
+| Fragmentation | The random distribution of UUIDv4 causes data fragmentation, reducing storage efficiency. |
+| Storage overhead | UUIDs (128 bits) consume more storage space than traditional integer keys, increasing memory usage. |
+
+To improve performance in distributed databases, consider using UUIDv7. UUIDv7 encodes a Unix timestamp (millisecond precision) in the first 48 bits, followed by six bits for the UUID version and variant, with the remaining 74 bits as random data. This structure makes UUIDv7 nearly sequential, improving indexing and query efficiency.
+
+### Advantages of UUIDv7 
+
+The following advantages make UUIDv7 a better choice for distributed databases:
+
+* Time-ordered values improve indexing performance and data locality. 
+
+* Better scalability for high-insert workloads in distributed databases.
+
+* Maintains uniqueness while allowing efficient range queries.  
 
 ## Install the UUID_VX component
 
@@ -64,15 +95,15 @@ The following functions are compatible with all UUID versions:
 
 | Function name        | Argument | Description |
 |----------------------|----------|---|
-| `BIN_TO_UUID_VX()` | One string argument that must be a hexadecimal of exactly 32 characters (16 bytes) | The function returns a UUID with binary data from the argument. It returns an error for all other inputs. |
-| `IS_MAX_UUID_VX()`   |  One string argument that represents a UUID in standard or hexadecimal form. | The function returns true if the argument is a valid UUID and is a MAX UUID. It returns false for all other inputs. If the argument is NULL, it returns NULL. If the argument cannot be parsed as a UUID, the function throws an error. |
+| `BIN_TO_UUID_VX()` | One string argument that must be hexadecimal of exactly 32 characters (16 bytes) | The function returns a UUID with binary data from the argument. It returns an error for all other inputs. |
+| `IS_MAX_UUID_VX()`   |  One string argument that represents a UUID in standard or hexadecimal form. | The function returns true if the argument is a valid UUID and is a MAX UUID. It returns false for all other inputs. If the argument is NULL, it returns NULL. The function throws an error if the argument cannot be parsed as a UUID. |
 | `IS_NIL_UUID_VX()`   | One string argument representing a UUID in standard or hexadecimal form. | The function returns true if the string is a NIL UUID. If the argument is NULL, it returns NULL. If the argument is not a valid UUID, it throws an error. |
-| `IS_UUID_VX()`       | One string argument that represents a UUID in either standard or hexadecimal form. | The function returns true if the argument is a valid UUID. If the argument is NULL, it returns NULL. For any other input, it returns false. |
+| `IS_UUID_VX()`       | One string argument representing a UUID in either standard or hexadecimal form. | The function returns true if the argument is a valid UUID. If the argument is NULL, it returns NULL. For any other input, it returns false. |
 | `MAX_UUID_VX()`      | No argument | This function generates a MAX UUID, which has all 128 bits set to one (FFFFFFFF-FFFF-FFFF-FFFF-FFFFFFFFFFFF). This function result is the opposite of the NIL UUID. |
 | `NIL_UUID_VX()`     | No argument. | This function generates a NIL UUID, which has all 128 bits set to zero (00000000-0000-0000-0000-000000000000). |
-| `UUID_VX_TO_BIN()`   | One string argument, formatted as a UUID or in hexadecimal form | The function converts the string arugment to its binary representation. |
-| `UUID_VX_VARIANT()`  | One string argument that represents a UUID in either standard or hexadecimal format. | The function returns the UUID version (1-8) or an error if the argument is not a valid UUID or returns NULL if the input is NULL. |
-| `UUID_VX_VERSION()`  | One string representing a UUID in standard or hexadecimal form. | The function returns version of UUID(1-8). The function throws an error if the argument is not a valid UUID in formatted or hexadecimal form or returns a NULL if the argument is NULL. If the argument is a valid UUID string but has an unknown value (outside of the 1-8 range) the function returns `-1`. |
+| `UUID_VX_TO_BIN()`   | One string argument, formatted as a UUID or in hexadecimal form | The function converts the string argument to its binary representation. |
+| `UUID_VX_VARIANT()`  | One string argument representing a UUID in either standard or hexadecimal format. | The function returns the UUID version (1-8) or an error if the argument is not a valid UUID or returns NULL if the input is NULL. |
+| `UUID_VX_VERSION()`  | One string representing a UUID in standard or hexadecimal form. | The function returns version of UUID(1-8). The function throws an error if the argument is not a valid UUID in formatted or hexadecimal form or returns a NULL if the argument is NULL. If the argument is a valid UUID string with an unknown value (outside of the 1-8 range), the function returns `-1`. |
 
 
 ### Examples of functions for all UUID versions
@@ -127,11 +158,11 @@ The following functions generate specific UUID versions:
 | UUID Version | Arguement | Description |
 |--------------|-----------|---|
 | `UUID_V1()` | No argument | Generates a version 1 UUID based on a timestamp. If possible, use UUID_V7() instead. |
-| `UUID_V3()` | One or two arguments: the first argument is a string that is hashed with MD5 and used in the UUID; the second argument is optional and specifies a namespace (integer values: DNS: 0, URL: 1, OID: 2, X.500: 3; default is 1 or URL). | Generates a version 3 UUID based on a name.  Note: MD5 is outdated and not secure. Use with caution and avoid exposing sensitive data. |
+| `UUID_V3()` | One or two arguments: the first argument is a string that is hashed with MD5 and used in the UUID; the second argument is optional and specifies a namespace (integer values: DNS: 0, URL: 1, OID: 2, X.500: 3; default is 1 or URL). | Generates a version 3 UUID based on a name. Note: MD5 is outdated and not secure. Use with caution and avoid exposing sensitive data. |
 | `UUID_V4()` |  No argument | The function generates a version 4 UUID using random numbers and is similar to the built-in UUID() function. |
-| `UUID_V5()` | One or two arguments: the first argument is a string that is hashed with SHA1 and used in the UUID; the second argument is optional and specifies a namespace (integer values: DNS: 0, URL: 1, OID: 2, X.500: 3; default is 1 or URL).| Generates a version 5 UUID based on a name.  Note: SHA1 is better than MD5 but still not secure. Use with caution and avoid exposing sensitive data. |
+| `UUID_V5()` | One or two arguments: the first argument is a string that is hashed with SHA1 and used in the UUID; the second argument is optional and specifies a namespace (integer values: DNS: 0, URL: 1, OID: 2, X.500: 3; default is 1 or URL).| Generates a version 5 UUID based on a name. Note: SHA1 is better than MD5 but still not secure. Use with caution and avoid exposing sensitive data. |
 | `UUID_V6()` |  No argument | Generates a version 6 UUID based on a timestamp. If possible, use UUID_V7() instead. |
-| `UUID_V7()` | Can have either no argument or a one integer argument: the argument is the number of milliseconds to adjust the timestamp forward or backward (negative values). | Generates a version 7 UUID based on a timestamp.  If there is no argument, no timestamp shift occurs. Timestamp shift can hide the actual creation time of the record. |
+| `UUID_V7()` | Can have either no argument or a one integer argument: the argument is the number of milliseconds to adjust the timestamp forward or backward (negative values). | Generates a version 7 UUID based on a timestamp. If there is no argument, no timestamp shift occurs. Timestamp shift can hide the actual creation time of the record. |
 
 The `UUID_v3()` function and `UUID_v5()` function do not validate the string argument, such as whether the URL is formatted correctly or the DNS name is correct. These functions generate a string hash and then add that hash to a UUID with the defined namespace. The user specifies the string.
 
@@ -289,9 +320,9 @@ The following functions are used only with time-based UUIDs, specifically versio
 
 | Function name     | Argument          | Description                                                                                                                                                    |
 |-----------------------------|---|----------------------------------------------------------------------------------------------------------------------------------------------------------------|
-| UUID_VX_TO_TIMESTAMP()      | One string argument | Returns a timestamp string like “2024-05-29 18:04:14.201”. If the argument is not parsable as UUID v.1,6,7, the function throws an error. The function always uses UTC time, regardless of system settings or time zone settings in MySQL. |
-| UUID_VX_TO_TIMESTAMP_TZ()   | One string argument | Returns a timestamp string with the time zone like “Wed May 29 18:05:07 2024 GMT”. If the argument is not parsable as UUID v.1,6,7, the function throws an error. The function always uses UTC time (GMT time zone), regardless of system settings or time zone settings in MySQL. |
-| UUID_VX_TO_UNIXTIME()       | One string argument | Returns a number of milliseconds since the Epoch. If the argument is not parsable as UUID v.1,6,7, the function throws an error. |
+| UUID_VX_TO_TIMESTAMP()      | One string argument | Returns a timestamp string like “2024-05-29 18:04:14.201”. The function throws an error if the argument is not parsable as UUID v.1,6,7. The function always uses UTC, regardless of MySQL's system settings or time zone settings. |
+| UUID_VX_TO_TIMESTAMP_TZ()   | One string argument | Returns a timestamp string with the time zone like “Wed May 29 18:05:07 2024 GMT”. The function throws an error if the argument is not parsable as UUID v.1,6,7. The function always uses UTC (GMT zone), regardless of MySQL's system settings or time zone settings. |
+| UUID_VX_TO_UNIXTIME()       | One string argument | Returns the number of milliseconds since the Epoch. The function throws an error if the argument is not parsable as UUID v.1,6,7. |
 
 ### Timestamp-based function examples
 
@@ -349,4 +380,4 @@ mysql> UNINSTALL COMPONENT 'file://component_uuid_vx_udf';
 
     ```{.text .no-copy}
     Query OK, 0 rows affected (0.03 sec)
-    ```
+    ```

mkdocs-base.yml

@@ -317,8 +317,7 @@ nav:
       - pam-plugin.md
       - ssl-improvement.md
       - secure-log-path-variable.md
-      - UUID_VX component:
-        - uuid-versions.md
+      - uuid-versions.md
       - Data-at-rest-encryption:
         - data-at-rest-encryption.md
         - Keyring plugin and components: