pseudorandomfuncs.c

Go to the documentation of this file.

/*-------------------------------------------------------------------------
 *
 * pseudorandomfuncs.c
 *    Functions giving SQL access to a pseudorandom number generator.
 *
 * Portions Copyright (c) 1996-2025, PostgreSQL Global Development Group
 * Portions Copyright (c) 1994, Regents of the University of California
 *
 * IDENTIFICATION
 *    src/backend/utils/adt/pseudorandomfuncs.c
 *
 *-------------------------------------------------------------------------
 */
#include "postgres.h"
 
#include <math.h>
 
#include "common/pg_prng.h"
#include "miscadmin.h"
#include "utils/date.h"
#include "utils/fmgrprotos.h"
#include "utils/numeric.h"
#include "utils/timestamp.h"
 
/* Shared PRNG state used by all the random functions */
static pg_prng_state prng_state;
static bool prng_seed_set = false;
 
/*
 * Macro for checking the range bounds of random(min, max) functions. Throws
 * an error if they're the wrong way round.
 */
#define CHECK_RANGE_BOUNDS(rmin, rmax) \
    do { \
        if ((rmin) > (rmax)) \
            ereport(ERROR, \
                    errcode(ERRCODE_INVALID_PARAMETER_VALUE), \
                    errmsg("lower bound must be less than or equal to upper bound")); \
    } while (0)
 
/*
 * initialize_prng() -
 *
 *  Initialize (seed) the PRNG, if not done yet in this process.
 */
static void
initialize_prng(void)
{
    if (unlikely(!prng_seed_set))
    {
        /*
         * If possible, seed the PRNG using high-quality random bits. Should
         * that fail for some reason, we fall back on a lower-quality seed
         * based on current time and PID.
         */
        if (unlikely(!pg_prng_strong_seed(&prng_state)))
        {
            TimestampTz now = GetCurrentTimestamp();
            uint64      iseed;
 
            /* Mix the PID with the most predictable bits of the timestamp */
            iseed = (uint64) now ^ ((uint64) MyProcPid << 32);
            pg_prng_seed(&prng_state, iseed);
        }
        prng_seed_set = true;
    }
}
 
/*
 * setseed() -
 *
 *  Seed the PRNG from a specified value in the range [-1.0, 1.0].
 */
Datum
setseed(PG_FUNCTION_ARGS)
{
    float8      seed = PG_GETARG_FLOAT8(0);
 
    if (seed < -1 || seed > 1 || isnan(seed))
        ereport(ERROR,
                errcode(ERRCODE_INVALID_PARAMETER_VALUE),
                errmsg("setseed parameter %g is out of allowed range [-1,1]",
                       seed));
 
    pg_prng_fseed(&prng_state, seed);
    prng_seed_set = true;
 
    PG_RETURN_VOID();
}
 
/*
 * drandom() -
 *
 *  Returns a random number chosen uniformly in the range [0.0, 1.0).
 */
Datum
drandom(PG_FUNCTION_ARGS)
{
    float8      result;
 
    initialize_prng();
 
    /* pg_prng_double produces desired result range [0.0, 1.0) */
    result = pg_prng_double(&prng_state);
 
    PG_RETURN_FLOAT8(result);
}
 
/*
 * drandom_normal() -
 *
 *  Returns a random number from a normal distribution.
 */
Datum
drandom_normal(PG_FUNCTION_ARGS)
{
    float8      mean = PG_GETARG_FLOAT8(0);
    float8      stddev = PG_GETARG_FLOAT8(1);
    float8      result,
                z;
 
    initialize_prng();
 
    /* Get random value from standard normal(mean = 0.0, stddev = 1.0) */
    z = pg_prng_double_normal(&prng_state);
    /* Transform the normal standard variable (z) */
    /* using the target normal distribution parameters */
    result = (stddev * z) + mean;
 
    PG_RETURN_FLOAT8(result);
}
 
/*
 * int4random() -
 *
 *  Returns a random 32-bit integer chosen uniformly in the specified range.
 */
Datum
int4random(PG_FUNCTION_ARGS)
{
    int32       rmin = PG_GETARG_INT32(0);
    int32       rmax = PG_GETARG_INT32(1);
    int32       result;
 
    CHECK_RANGE_BOUNDS(rmin, rmax);
 
    initialize_prng();
 
    result = (int32) pg_prng_int64_range(&prng_state, rmin, rmax);
 
    PG_RETURN_INT32(result);
}
 
/*
 * int8random() -
 *
 *  Returns a random 64-bit integer chosen uniformly in the specified range.
 */
Datum
int8random(PG_FUNCTION_ARGS)
{
    int64       rmin = PG_GETARG_INT64(0);
    int64       rmax = PG_GETARG_INT64(1);
    int64       result;
 
    CHECK_RANGE_BOUNDS(rmin, rmax);
 
    initialize_prng();
 
    result = pg_prng_int64_range(&prng_state, rmin, rmax);
 
    PG_RETURN_INT64(result);
}
 
/*
 * numeric_random() -
 *
 *  Returns a random numeric value chosen uniformly in the specified range.
 */
Datum
numeric_random(PG_FUNCTION_ARGS)
{
    Numeric     rmin = PG_GETARG_NUMERIC(0);
    Numeric     rmax = PG_GETARG_NUMERIC(1);
    Numeric     result;
 
    /* Leave range bound checking to random_numeric() */
 
    initialize_prng();
 
    result = random_numeric(&prng_state, rmin, rmax);
 
    PG_RETURN_NUMERIC(result);
}
 
 
/*
 * date_random() -
 *
 *  Returns a random date chosen uniformly in the specified range.
 */
Datum
date_random(PG_FUNCTION_ARGS)
{
    int32       rmin = (int32) PG_GETARG_DATEADT(0);
    int32       rmax = (int32) PG_GETARG_DATEADT(1);
    DateADT     result;
 
    CHECK_RANGE_BOUNDS(rmin, rmax);
 
    if (DATE_IS_NOBEGIN(rmin) || DATE_IS_NOEND(rmax))
        ereport(ERROR,
                errcode(ERRCODE_INVALID_PARAMETER_VALUE),
                errmsg("lower and upper bounds must be finite"));
 
    initialize_prng();
 
    result = (DateADT) pg_prng_int64_range(&prng_state, rmin, rmax);
 
    PG_RETURN_DATEADT(result);
}
 
/*
 * timestamp_random() -
 *
 *  Returns a random timestamp chosen uniformly in the specified range.
 */
Datum
timestamp_random(PG_FUNCTION_ARGS)
{
    int64       rmin = (int64) PG_GETARG_TIMESTAMP(0);
    int64       rmax = (int64) PG_GETARG_TIMESTAMP(1);
    Timestamp   result;
 
    CHECK_RANGE_BOUNDS(rmin, rmax);
 
    if (TIMESTAMP_IS_NOBEGIN(rmin) || TIMESTAMP_IS_NOEND(rmax))
        ereport(ERROR,
                errcode(ERRCODE_INVALID_PARAMETER_VALUE),
                errmsg("lower and upper bounds must be finite"));
 
    initialize_prng();
 
    result = (Timestamp) pg_prng_int64_range(&prng_state, rmin, rmax);
 
    PG_RETURN_TIMESTAMP(result);
}
 
/*
 * timestamptz_random() -
 *
 *  Returns a random timestamptz chosen uniformly in the specified range.
 */
Datum
timestamptz_random(PG_FUNCTION_ARGS)
{
    int64       rmin = (int64) PG_GETARG_TIMESTAMPTZ(0);
    int64       rmax = (int64) PG_GETARG_TIMESTAMPTZ(1);
    TimestampTz result;
 
    CHECK_RANGE_BOUNDS(rmin, rmax);
 
    if (TIMESTAMP_IS_NOBEGIN(rmin) || TIMESTAMP_IS_NOEND(rmax))
        ereport(ERROR,
                errcode(ERRCODE_INVALID_PARAMETER_VALUE),
                errmsg("lower and upper bounds must be finite"));
 
    initialize_prng();
 
    result = (TimestampTz) pg_prng_int64_range(&prng_state, rmin, rmax);
 
    PG_RETURN_TIMESTAMPTZ(result);
}