database/postgres
database/postgres
1
0
Fork 0
mirror of https://github.com/postgres/postgres.git synced 2025-05-31 03:21:24 +03:00
Code

doc: Convert UUID functions list to table format.

Browse Source 
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 <bluesbreaker@gmail.com>
Reviewed-by: Laurenz Albe <laurenz.albe@cybertec.at>
Discussion: https://postgr.es/m/CADOZ7s7OHag+r6w+BzKw2xgb3fVtAD-pU=_N9-9pSe5W1TB+xQ@mail.gmail.com
This commit is contained in:
Masahiko Sawada 2025-03-03 15:44:01 -08:00
parent 246dedc5d0
commit ba57dcfdcd
2 changed files with 155 additions and 36 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

9
doc/src/sgml/datatype.sgml
View File

@ -4407,6 +4407,15 @@ SELECT to_tsvector( 'postgraduate' ), to_tsquery( 'postgres:*' );
are only unique within a single database. are only unique within a single database.
</para> </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> <para>
A UUID is written as a sequence of lower-case hexadecimal digits, A UUID is written as a sequence of lower-case hexadecimal digits,
in several groups separated by hyphens, specifically a group of 8 in several groups separated by hyphens, specifically a group of 8

156
doc/src/sgml/func.sgml
View File

@ -14328,54 +14328,164 @@ CREATE TYPE rainbow AS ENUM ('red', 'orange', 'yellow', 'green', 'blue', 'purple
</indexterm> </indexterm>
<para> <para>
<productname>PostgreSQL</productname> includes several functions to generate a UUID. <xref linkend="func_uuid_gen_table"/> shows the <productname>PostgreSQL</productname>
<synopsis> functions that can be used to generate UUIDs.
<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.
</para> </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>
<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> <para>
The <xref linkend="uuid-ossp"/> module provides additional functions that The <xref linkend="uuid-ossp"/> module provides additional functions that
implement other standard algorithms for generating UUIDs. implement other standard algorithms for generating UUIDs.
</para> </para>
</note>
<para> <para>
There are also functions to extract data from UUIDs: <xref linkend="func_uuid_extract_table"/> shows the <productname>PostgreSQL</productname>
<synopsis> functions that can be used to extract information from UUIDs.
<function>uuid_extract_timestamp</function> (uuid) <returnvalue>timestamp with time zone</returnvalue> </para>
</synopsis>
This function extracts a <type>timestamp with time zone</type> from UUID <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 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 the extracted timestamp is not necessarily exactly equal to the time the
UUID was generated; this depends on the implementation that generated the UUID was generated; this depends on the implementation that generated the
UUID. UUID.
</para> </para>
<para> <para>
<synopsis> <literal>uuid_extract_timestamp('019535d9-3df7-79fb-b466-fa907fa17f9e'::uuid)</literal>
<function>uuid_extract_version</function> (uuid) <returnvalue>smallint</returnvalue> <returnvalue>2025-02-23 21:46:24.503-05</returnvalue>
</synopsis> </para>
This function extracts the version from a UUID of the variant described by </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 <ulink url="https://datatracker.ietf.org/doc/html/rfc9562">RFC 9562</ulink>. For
other variants, this function returns null. For example, for a UUID other variants, this function returns null. For example, for a UUID
generated by <function>gen_random_uuid</function>, this function will generated by <function>gen_random_uuid</function>, this function will
return 4. return 4.
</para> </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> <para>
<productname>PostgreSQL</productname> also provides the usual comparison <productname>PostgreSQL</productname> also provides the usual comparison
operators shown in <xref linkend="functions-comparison-op-table"/> for operators shown in <xref linkend="functions-comparison-op-table"/> for
UUIDs. UUIDs.
</para> </para>
<para>
See <xref linkend="datatype-uuid"/> for details on the data type
<type>uuid</type> in <productname>PostgreSQL</productname>.
</para>
</sect1> </sect1>
<sect1 id="functions-xml"> <sect1 id="functions-xml">