From 5925e5549890416bcf588334d9d0bc99f8ad6c7f Mon Sep 17 00:00:00 2001
From: Peter Eisentraut <peter@eisentraut.org>
Date: Sun, 14 Jul 2019 14:30:27 +0200
Subject: Add gen_random_uuid function

This adds a built-in function to generate UUIDs.

PostgreSQL hasn't had a built-in function to generate a UUID yet,
relying on external modules such as uuid-ossp and pgcrypto to provide
one.  Now that we have a strong random number generator built-in, we
can easily provide a version 4 (random) UUID generation function.

This patch takes the existing function gen_random_uuid() from pgcrypto
and makes it a built-in function.  The pgcrypto implementation now
internally redirects to the built-in one.

Reviewed-by: Fabien COELHO <coelho@cri.ensmp.fr>
Discussion: https://www.postgresql.org/message-id/6a65610c-46fc-2323-6b78-e8086340a325@2ndquadrant.com
---
 doc/src/sgml/datatype.sgml  | 12 ++----------
 doc/src/sgml/func.sgml      | 26 ++++++++++++++++++++++++++
 doc/src/sgml/pgcrypto.sgml  |  3 ++-
 doc/src/sgml/uuid-ossp.sgml | 11 +++--------
 4 files changed, 33 insertions(+), 19 deletions(-)

(limited to 'doc/src')

diff --git a/doc/src/sgml/datatype.sgml b/doc/src/sgml/datatype.sgml
index 35ecd48ed5d..9b6d6878eb0 100644
--- a/doc/src/sgml/datatype.sgml
+++ b/doc/src/sgml/datatype.sgml
@@ -4195,16 +4195,8 @@ a0ee-bc99-9c0b-4ef8-bb6d-6bb9-bd38-0a11
    </para>
 
    <para>
-    <productname>PostgreSQL</productname> provides storage and comparison
-    functions for UUIDs, but the core database does not include any
-    function for generating UUIDs, because no single algorithm is well
-    suited for every application.  The <xref
-    linkend="uuid-ossp"/> module
-    provides functions that implement several standard algorithms.
-    The <xref linkend="pgcrypto"/> module also provides a generation
-    function for random UUIDs.
-    Alternatively, UUIDs could be generated by client applications or
-    other libraries invoked through a server-side function.
+    See <xref linkend="functions-uuid"/> for how to generate a UUID in
+    <productname>PostgreSQL</productname>.
    </para>
   </sect1>
 
diff --git a/doc/src/sgml/func.sgml b/doc/src/sgml/func.sgml
index a25c122ac8f..c2f5a75ff67 100644
--- a/doc/src/sgml/func.sgml
+++ b/doc/src/sgml/func.sgml
@@ -10267,6 +10267,32 @@ CREATE TYPE rainbow AS ENUM ('red', 'orange', 'yellow', 'green', 'blue', 'purple
 
  </sect1>
 
+ <sect1 id="functions-uuid">
+  <title>UUID Functions</title>
+
+  <indexterm zone="datatype-uuid">
+   <primary>UUID</primary>
+   <secondary>generating</secondary>
+  </indexterm>
+
+  <indexterm>
+   <primary>gen_random_uuid</primary>
+  </indexterm>
+
+  <para>
+   <productname>PostgreSQL</productname> includes one function to generate a UUID:
+<synopsis>
+gen_random_uuid() returns uuid
+</synopsis>
+   This function returns a version 4 (random) UUID.  This is the most commonly
+   used type of UUID and is appropriate for most applications.
+  </para>
+
+  <para>
+   The <xref linkend="uuid-ossp"/> module provides additional functions that
+   implement other standard algorithms for generating UUIDs.
+  </para>
+ </sect1>
 
  <sect1 id="functions-xml">
 
diff --git a/doc/src/sgml/pgcrypto.sgml b/doc/src/sgml/pgcrypto.sgml
index 5c796666543..0acd11ed555 100644
--- a/doc/src/sgml/pgcrypto.sgml
+++ b/doc/src/sgml/pgcrypto.sgml
@@ -1132,7 +1132,8 @@ gen_random_bytes(count integer) returns bytea
 gen_random_uuid() returns uuid
 </synopsis>
   <para>
-   Returns a version 4 (random) UUID.
+   Returns a version 4 (random) UUID. (Obsolete, this function is now also
+   included in core <productname>PostgreSQL</productname>.)
   </para>
  </sect2>
 
diff --git a/doc/src/sgml/uuid-ossp.sgml b/doc/src/sgml/uuid-ossp.sgml
index b3b816c3725..0fbabbfda24 100644
--- a/doc/src/sgml/uuid-ossp.sgml
+++ b/doc/src/sgml/uuid-ossp.sgml
@@ -11,6 +11,9 @@
   The <filename>uuid-ossp</filename> module provides functions to generate universally
   unique identifiers (UUIDs) using one of several standard algorithms.  There
   are also functions to produce certain special UUID constants.
+  This module is only necessary for special requirements beyond what is
+  available in core <productname>PostgreSQL</productname>.  See <xref
+  linkend="functions-uuid"/> for built-in ways to generate UUIDs.
  </para>
 
  <sect2>
@@ -181,14 +184,6 @@ SELECT uuid_generate_v3(uuid_ns_url(), 'http://www.postgresql.org');
    More than one of these libraries might be available on a particular
    machine, so <filename>configure</filename> does not automatically choose one.
   </para>
-
-  <note>
-   <para>
-    If you only need randomly-generated (version 4) UUIDs,
-    consider using the <function>gen_random_uuid()</function> function
-    from the <xref linkend="pgcrypto"/> module instead.
-   </para>
-  </note>
  </sect2>
 
  <sect2>
-- 
cgit v1.2.3