diff options
Diffstat (limited to 'doc/src')
| -rw-r--r-- | doc/src/sgml/datatype.sgml | 9 | ||||
| -rw-r--r-- | 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 87679dc4a11..09309ba0390 100644 --- a/doc/src/sgml/datatype.sgml +++ b/doc/src/sgml/datatype.sgml @@ -4408,6 +4408,15 @@ SELECT to_tsvector( 'postgraduate' ), to_tsquery( 'postgres:*' ); </para> <para> + 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. + <productname>PostgreSQL</productname> 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 <type>uuid</type> can be used + to store any UUID, regardless of the origin and the UUID version. + </para> + + <para> A UUID is written as a sequence of lower-case hexadecimal digits, in several groups separated by hyphens, specifically a group of 8 digits followed by three groups of 4 digits followed by a group of diff --git a/doc/src/sgml/func.sgml b/doc/src/sgml/func.sgml index 0e6c5349652..bf31b1f3eee 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 </indexterm> <para> - <productname>PostgreSQL</productname> includes several functions to generate a UUID. -<synopsis> -<function>gen_random_uuid</function> () <returnvalue>uuid</returnvalue> -<function>uuidv4</function> () <returnvalue>uuid</returnvalue> -</synopsis> - These functions return a version 4 (random) UUID. -<synopsis> -<function>uuidv7</function> (<optional> <parameter>shift</parameter> <type>interval</type> </optional>) <returnvalue>uuid</returnvalue> -</synopsis> - This function returns a version 7 UUID (UNIX timestamp with millisecond - precision + sub-millisecond timestamp + random). This function can accept - optional <parameter>shift</parameter> parameter of type <type>interval</type> - which shift internal timestamp by the given interval. + <xref linkend="func_uuid_gen_table"/> shows the <productname>PostgreSQL</productname> + functions that can be used to generate UUIDs. </para> - <para> - The <xref linkend="uuid-ossp"/> module provides additional functions that - implement other standard algorithms for generating UUIDs. - </para> + <table id="func_uuid_gen_table"> + <title><acronym>UUID</acronym> Generation Functions</title> + <tgroup cols="1"> + <thead> + <row> + <entry role="func_table_entry"> + <para role="func_signature"> + Function + </para> + <para> + Description + </para> + <para> + Example(s) + </para> + </entry> + </row> + </thead> - <para> - There are also functions to extract data from UUIDs: -<synopsis> -<function>uuid_extract_timestamp</function> (uuid) <returnvalue>timestamp with time zone</returnvalue> -</synopsis> - This function extracts a <type>timestamp with time zone</type> 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. - </para> + <tbody> + <row> + <entry role="func_table_entry"> + <para role="func_signature"> + <type>gen_random_uuid</type> + <returnvalue>uuid</returnvalue> + </para> + <para role="func_signature"> + <type>uuidv4</type> + <returnvalue>uuid</returnvalue> + </para> + <para> + Generate a version 4 (random) UUID. + </para> + <para> + <literal>gen_random_uuid()</literal> + <returnvalue>5b30857f-0bfa-48b5-ac0b-5c64e28078d1</returnvalue> + </para> + <para> + <literal>uuidv4()</literal> + <returnvalue>b42410ee-132f-42ee-9e4f-09a6485c95b8</returnvalue> + </para> + </entry> + </row> + <row> + <entry role="func_table_entry"> + <para role="func_signature"> + <type>uuidv7</type> + ( <optional> <parameter>shift</parameter> <type>interval</type> </optional> ) + <returnvalue>uuid</returnvalue> + </para> + <para> + Generate a version 7 (time-ordered) UUID. The timestamp is computed using UNIX timestamp + with millisecond precision + sub-millisecond timestamp + random. The optional parameter + <parameter>shift</parameter> will shift the computed timestamp by the given <type>interval</type>. + </para> + <para> + <literal>uuidv7()</literal> + <returnvalue>019535d9-3df7-79fb-b466-fa907fa17f9e</returnvalue> + </para> + </entry> + </row> + </tbody> + </tgroup> + </table> + + <note> + <para> + The <xref linkend="uuid-ossp"/> module provides additional functions that + implement other standard algorithms for generating UUIDs. + </para> + </note> <para> -<synopsis> -<function>uuid_extract_version</function> (uuid) <returnvalue>smallint</returnvalue> -</synopsis> - This function extracts the version from a UUID of the variant described by - <ulink url="https://datatracker.ietf.org/doc/html/rfc9562">RFC 9562</ulink>. For - other variants, this function returns null. For example, for a UUID - generated by <function>gen_random_uuid</function>, this function will - return 4. + <xref linkend="func_uuid_extract_table"/> shows the <productname>PostgreSQL</productname> + functions that can be used to extract information from UUIDs. </para> + <table id="func_uuid_extract_table"> + <title><acronym>UUID</acronym> Extraction Functions</title> + <tgroup cols="1"> + <thead> + <row> + <entry role="func_table_entry"> + <para role="func_signature"> + Function + </para> + <para> + Description + </para> + <para> + Example(s) + </para> + </entry> + </row> + </thead> + + <tbody> + <row> + <entry role="func_table_entry"> + <para role="func_signature"> + <type>uuid_extract_timestamp</type> + ( <type>uuid</type> ) + <returnvalue>timestamp with time zone</returnvalue> + </para> + <para> + Extracts a <type>timestamp with time zone</type> 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. + </para> + <para> + <literal>uuid_extract_timestamp('019535d9-3df7-79fb-b466-fa907fa17f9e'::uuid)</literal> + <returnvalue>2025-02-23 21:46:24.503-05</returnvalue> + </para> + </entry> + </row> + <row> + <entry role="func_table_entry"> + <para role="func_signature"> + <type>uuid_extract_version</type> + ( <type>uuid</type> ) + <returnvalue>smallint</returnvalue> + </para> + <para> + Extracts the version from a UUID of the variant described by + <ulink url="https://datatracker.ietf.org/doc/html/rfc9562">RFC 9562</ulink>. For + other variants, this function returns null. For example, for a UUID + generated by <function>gen_random_uuid</function>, this function will + return 4. + </para> + <para> + <literal>uuid_extract_version('41db1265-8bc1-4ab3-992f-885799a4af1d'::uuid)</literal> + <returnvalue>4</returnvalue> + </para> + <para> + <literal>uuid_extract_version('019535d9-3df7-79fb-b466-fa907fa17f9e'::uuid)</literal> + <returnvalue>7</returnvalue> + </para> + </entry> + </row> + </tbody> + </tgroup> + </table> + <para> <productname>PostgreSQL</productname> also provides the usual comparison operators shown in <xref linkend="functions-comparison-op-table"/> for UUIDs. </para> + <para> + See <xref linkend="datatype-uuid"/> for details on the data type + <type>uuid</type> in <productname>PostgreSQL</productname>. + </para> </sect1> <sect1 id="functions-xml"> |