Re: Update docs for UUID data type - Mailing list pgsql-hackers

On Sun, 2025-02-23 at 22:23 -0500, Andy Alsup wrote:
> Please find the attached patch files that supersede the previous email. 
>
> Patch 0001 contains some modest modifications to the UUID data type docs
> (Section 8.12. UUID Type). The main goal is to inform the reader that there
> are multiple versions of UUID generation algorithms (presently 8); however,
> once generated, PostgreSQL treats all UUIDs uniformly.
>
> Patch 0002 contains modifications to the UUID functions docs (Section 9.14.
> UUID Functions). The main goal is to format the UUID functions in table form,
> similar to other function docs, such as Section 9.4. String Functions and
> Operators. This provides the user a more consistent format, in line with
> more established sections of the PostgreSQL documentation.
>
> Thank you for your time and consideration.

I had a look at the patches.

About the first patch:

> diff --git a/doc/src/sgml/datatype.sgml b/doc/src/sgml/datatype.sgml
> index 87679dc4a11..9841b125e06 100644
> --- a/doc/src/sgml/datatype.sgml
> +++ b/doc/src/sgml/datatype.sgml
> @@ -4399,12 +4399,21 @@ SELECT to_tsvector( 'postgraduate' ), to_tsquery( 'postgres:*' );
>      ISO/IEC 9834-8:2005, and related standards.
>      (Some systems refer to this data type as a globally unique identifier, or
>      GUID,<indexterm><primary>GUID</primary></indexterm> instead.)  This
> -    identifier is a 128-bit quantity that is generated by an algorithm chosen
> -    to make it very unlikely that the same identifier will be generated by
> -    anyone else in the known universe using the same algorithm.  Therefore,
> -    for distributed systems, these identifiers provide a better uniqueness
> -    guarantee than sequence generators, which
> -    are only unique within a single database.
> +    identifier is a 128-bit quantity generated by an algorithm chosen to make it
> +    extremely unlikely that the same identifier will be generated by any other system.
> +    Therefore, for distributed systems, these identifiers offer better uniqueness
> +    guarantees than sequence generators, which only guarantee uniqueness within a
> +    single database.
> +   </para>
> +
> +   <para>
> +    The UUID RFC defines 8 discrete 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
> +    PostgreSQL database using any algorithm. In any case, PostgreSQL supports the
> +    <type>uuid</type> datatype uniformly, regardless of the UUID version or whether it
> +    was generated internally or externally.

"PostgreSQL" should wear a <productname> tag.

Your change to the first paragraph is just the removal of "that is" and
rearranging the line breaks.  I don't think that the wording becomes any
clearer through that change, and it makes reading the patch more difficult.
It is a good idea to change as little as possible in the existing text
(particularly in the line breaks), so that reviewing becomes easier.

About the new paragraph: it should be "different", not "discrete".

I am not certain if the part after "alternatively" adds any relevant
information.  Also, I am not certain what you mean with "uniformly".
Perhaps that sentence could be

  The PostgreSQL data type <type>uuid</type> supports all kinds of UUIDs,
  regardless of their version.

We don't mention that "integer" can be used to store integers generated
inside and outside PostgreSQL, so I don't think we need to mention that
here.

About the second patch:

A table is a good thing.  We typically have an introductory paragraph
before such tables that contains a hyperlink to the table, something like

  <xref ...> shows the <productname>PostgreSQL</productname> functions
  that can be used to generate UUIDs:

Yours,
Laurenz Albe

--

*E-Mail Disclaimer*
Der Inhalt dieser E-Mail ist ausschliesslich fuer den
bezeichneten Adressaten bestimmt. Wenn Sie nicht der vorgesehene Adressat
dieser E-Mail oder dessen Vertreter sein sollten, so beachten Sie bitte,
dass jede Form der Kenntnisnahme, Veroeffentlichung, Vervielfaeltigung oder
Weitergabe des Inhalts dieser E-Mail unzulaessig ist. Wir bitten Sie, sich
in diesem Fall mit dem Absender der E-Mail in Verbindung zu setzen.

*CONFIDENTIALITY NOTICE & DISCLAIMER
*This message and any attachment are
confidential and may be privileged or otherwise protected from disclosure
and solely for the use of the person(s) or entity to whom it is intended.
If you have received this message in error and are not the intended
recipient, please notify the sender immediately and delete this message and
any attachment from your system. If you are not the intended recipient, be
advised that any use of this message is prohibited and may be unlawful, and
you must not copy this message or attachment or disclose the contents to
any other person.