Update docs for UUID data type
The attached patch file makes some modest changes to the docs for the UUID data type (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. Regards, Andy Alsup 0001-UUID-datatype-docs.patch Description: Binary data
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 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,GUID 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. > > + > > + > > + > > +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 > > +uuid datatype uniformly, regardless of the UUID > version or whether it > > +was generated internally or externally. > > "PostgreSQL" should wear a 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 uuid 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 > >shows the PostgreSQL functions > that can be used to generate UUIDs: > > Yours, > Laurenz Albe > > -- > > *E-Mail Disclaimer* > Der Inhalt dieser E-Mail ist ausschliesslich fuer den >
Re: Update docs for UUID data type
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. Regards, Andy Alsup On Fri, Feb 21, 2025 at 11:42 PM Andy Alsup wrote: > The attached patch file makes some modest changes to the docs for the UUID > data type (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. > > Regards, > Andy Alsup > 0001-docs-for-UUID-datatype-mention-UUID-versions.patch Description: Binary data 0002-docs-for-UUID-funcs-formatted-in-table.patch Description: Binary data
Re: Update docs for UUID data type
Masahiko, I like the change you've made. Thanks, Andy Alsup On Fri, Feb 28, 2025 at 2:05 PM Masahiko Sawada wrote: > On Thu, Feb 27, 2025 at 5:50 PM Andy Alsup wrote: > > > > Masahiko, > > > > I have combined the gen_random_uuid() and uuidv4() into a single row, as > you suggested. Please find the v5 patch, which has been squashed into a > single commit. > > Thank you for updating the patch! > > I like that the patch adds the reference to the uuid data type. But I > think we might want to adjust terminology: > > + > + See for how details on the UUID > datatype in > +PostgreSQL. > + > > On 9.14. UUID Functions section, we use the word 'UUID' for data that > are generated based on algorithms defined by RFC9562 whereas we use > uuid (i.e., uuid in func.sgml) to a PostgreSQL data type. > IIUC you want to refer 'UUID datatype' in the above change to the > latter, PostgreSQL's uuid data type. Is that correct? If so, how about > the following change? > >See for details on the data type >uuid in PostgreSQL. > > I've attached the updated patch that incorporates the above change, > and updated the commit message too. > > Regards, > > -- > Masahiko Sawada > Amazon Web Services: https://aws.amazon.com >
Re: Update docs for UUID data type
Masahiko, I have combined the gen_random_uuid() and uuidv4() into a single row, as you suggested. Please find the v5 patch, which has been squashed into a single commit. Best regards, Andy Alsup On Thu, Feb 27, 2025 at 5:02 PM Masahiko Sawada wrote: > On Thu, Feb 27, 2025 at 1:26 PM Andy Alsup wrote: > > > > I've submitted it for the up-coming commitfest. The link is: > https://commitfest.postgresql.org/patch/5604/ > > Thanks for all your help in reviewing these changes. > > Thank you for the patch! > > Regarding the 0001 patch, I think we can put uuidv4() and > get_random_uuid() in the same row since they are effectively identical > functions. For example, we have precedent such as char_length() and > character_length(). > > The 0002 patch looks good to me. > > Regards, > > -- > Masahiko Sawada > Amazon Web Services: https://aws.amazon.com > v5-0001-Docs-for-UUID-funcs-formatted-in-table-and-UUID-d.patch Description: Binary data
Re: Update docs for UUID data type
I've submitted it for the up-coming commitfest. The link is: https://commitfest.postgresql.org/patch/5604/ Thanks for all your help in reviewing these changes. Best Regards, Andy Alsup On Thu, Feb 27, 2025 at 1:58 PM Laurenz Albe wrote: > On Wed, 2025-02-26 at 22:11 -0500, Andy Alsup wrote: > > Please find the latest patch files attached. > > This is good to go. If you add it to the commitfest, I'm happy to > mark it "ready for committer". > > Yours, > Laurenz Albe >
Re: Update docs for UUID data type
Thank you for the clarification, and the well-worded paragraph. Please find the latest patch files attached. Best regards, Andy Alsup On Tue, Feb 25, 2025 at 12:41 PM Laurenz Albe wrote: > On Mon, 2025-02-24 at 21:04 -0500, Andy Alsup wrote: > > 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. > > Your patch looks good to me. > > I didn't mean that adding more information about the "uuid" data type is > a bad thing. Perhaps that additional paragraph could be > > 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. > PostgreSQL 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 > uuid can be used > to store any UUID, regardless of the origin and the UUID version. > > I would be happy if you added something like that again. > > Yours, > Laurenz Albe > v3-0001-docs-for-UUID-funcs-formatted-in-table.patch Description: Binary data v3-0002-docs-for-UUID-datatype-mention-UUID-versions.patch Description: Binary data
