Subject: Re: random() function documentation

From: Tom Lane <[email-masked]>
Date: Mon, 11 Apr 2022 15:19:47 -0400

=?utf-8?Q?Dagfinn_Ilmari_Manns=C3=A5ker?= <[email-masked]> writes:
> Tom Lane <[email-masked]> writes:
>> How about we just say "uses a linear-feedback shift register algorithm"?

> That works for me.  Nice and simple, and not overly specific.  Should we
> perhaps also add a warning that the same seed is not guaranteed to
> produce the same sequence across different (major?) versions?

I wouldn't bother, on the grounds that then we'd need such disclaimers
in a whole lot of places.  Others might see it differently though.

			regards, tom lane

---

From: Dean Rasheed <[email-masked]>
Date: Tue, 12 Apr 2022 01:18:58 +0100

> >> How about we just say "uses a linear-feedback shift register algorithm"?

I think it'd be sufficient to just say that it's a deterministic
pseudorandom number generator. I don't see much value in documenting
the internal algorithm used.

> > Should we

Agreed, though I think when the release notes are written, they ought
to warn that the sequence will change with this release.

Regards,
Dean

---

From: Fabien COELHO <[email-masked]>
Date: Tue, 12 Apr 2022 10:19:07 +0200 (CEST)

> the internal algorithm used.

Hmmm… I'm not so sure. ISTM that people interested in using the random 
user-facing variants (only random?) could like a pointer on the algorithm 
to check for the expected quality of the produced pseudo-random stream?

See attached.

>>> Should we perhaps also add a warning that the same seed is not 
>>> guaranteed to produce the same sequence across different (major?) 
>>> versions?
>>
> Agreed,

Agreed.

> though I think when the release notes are written, they ought

Yes.

-- 
Fabien.

diff --git a/doc/src/sgml/func.sgml b/doc/src/sgml/func.sgml
index 0a5c402640..7492454592 100644
--- a/doc/src/sgml/func.sgml
+++ b/doc/src/sgml/func.sgml
@@ -1832,10 +1832,11 @@ repeat('Pg', 4) <returnvalue>PgPgPgPg</returnvalue>
    </table>
 
   <para>
-   The <function>random()</function> function uses a simple linear
-   congruential algorithm.  It is fast but not suitable for cryptographic
-   applications; see the <xref linkend="pgcrypto"/> module for a more
-   secure alternative.
+   The <function>random()</function> function uses
+   <ulink url="https://en.wikipedia.org/wiki/Xoroshiro128%2B">xoroshiro128**</ulink>, a
+   linear feedback shift register algorithm.
+   It is fast but not suitable for cryptographic applications;
+   see the <xref linkend="pgcrypto"/> module for a more secure alternative.
    If <function>setseed()</function> is called, the series of results of
    subsequent <function>random()</function> calls in the current session
    can be repeated by re-issuing <function>setseed()</function> with the same

---

From: Tom Lane <[email-masked]>
Date: Tue, 12 Apr 2022 11:03:41 -0400

> See attached.

I don't want to get that specific.  We were not specific before and
there has been no call for such detail in the docs.  (Unlike
closed-source software, anybody who really wants algorithmic details
can find all they want to know in the source code.)  It would just
amount to another thing to forget to update next time someone changes
the algorithm ... which is a consideration that leads me to favor
Dean's phrasing.

			regards, tom lane