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.a...@cybertec.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. >
v2-0001-docs-for-UUID-funcs-formatted-in-table.patch
Description: Binary data
