Re: Update docs for UUID data type

Please find the attached patch, which only addresses the UUID functions (in
table format). I appreciate the comments related to the UUID datatype. If
you feel like the additional content didn't add clarity, I certainly won't
argue.

Best regards,
Andy Alsup

On Mon, Feb 24, 2025 at 2:02 AM Laurenz Albe <laurenz(dot)albe(at)cybertec(dot)at>
wrote:

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