begriffs open source - ai-pg/blob - full-docs/txt/uuid-ossp.txt

   1
   2 F.49. uuid-ossp — a UUID generator #
   3
   4    F.49.1. uuid-ossp Functions
   5    F.49.2. Building uuid-ossp
   6    F.49.3. Author
   7
   8    The uuid-ossp module provides functions to generate universally unique
   9    identifiers (UUIDs) using one of several standard algorithms. There are
  10    also functions to produce certain special UUID constants. This module
  11    is only necessary for special requirements beyond what is available in
  12    core PostgreSQL. See Section 9.14 for built-in ways to generate UUIDs.
  13
  14    This module is considered “trusted”, that is, it can be installed by
  15    non-superusers who have CREATE privilege on the current database.
  16
  17 F.49.1. uuid-ossp Functions #
  18
  19    Table F.35 shows the functions available to generate UUIDs. The
  20    relevant standards ITU-T Rec. X.667, ISO/IEC 9834-8:2005, and RFC 4122
  21    specify four algorithms for generating UUIDs, identified by the version
  22    numbers 1, 3, 4, and 5. (There is no version 2 algorithm.) Each of
  23    these algorithms could be suitable for a different set of applications.
  24
  25    Table F.35. Functions for UUID Generation
  26
  27    Function
  28
  29    Description
  30
  31    uuid_generate_v1 () → uuid
  32
  33    Generates a version 1 UUID. This involves the MAC address of the
  34    computer and a time stamp. Note that UUIDs of this kind reveal the
  35    identity of the computer that created the identifier and the time at
  36    which it did so, which might make it unsuitable for certain
  37    security-sensitive applications.
  38
  39    uuid_generate_v1mc () → uuid
  40
  41    Generates a version 1 UUID, but uses a random multicast MAC address
  42    instead of the real MAC address of the computer.
  43
  44    uuid_generate_v3 ( namespace uuid, name text ) → uuid
  45
  46    Generates a version 3 UUID in the given namespace using the specified
  47    input name. The namespace should be one of the special constants
  48    produced by the uuid_ns_*() functions shown in Table F.36. (It could be
  49    any UUID in theory.) The name is an identifier in the selected
  50    namespace.
  51
  52    For example:
  53 SELECT uuid_generate_v3(uuid_ns_url(), 'http://www.postgresql.org');
  54
  55    The name parameter will be MD5-hashed, so the cleartext cannot be
  56    derived from the generated UUID. The generation of UUIDs by this method
  57    has no random or environment-dependent element and is therefore
  58    reproducible.
  59
  60    uuid_generate_v4 () → uuid
  61
  62    Generates a version 4 UUID, which is derived entirely from random
  63    numbers.
  64
  65    uuid_generate_v5 ( namespace uuid, name text ) → uuid
  66
  67    Generates a version 5 UUID, which works like a version 3 UUID except
  68    that SHA-1 is used as a hashing method. Version 5 should be preferred
  69    over version 3 because SHA-1 is thought to be more secure than MD5.
  70
  71    Table F.36. Functions Returning UUID Constants
  72
  73    Function
  74
  75    Description
  76
  77    uuid_nil () → uuid
  78
  79    Returns a “nil” UUID constant, which does not occur as a real UUID.
  80
  81    uuid_ns_dns () → uuid
  82
  83    Returns a constant designating the DNS namespace for UUIDs.
  84
  85    uuid_ns_url () → uuid
  86
  87    Returns a constant designating the URL namespace for UUIDs.
  88
  89    uuid_ns_oid () → uuid
  90
  91    Returns a constant designating the ISO object identifier (OID)
  92    namespace for UUIDs. (This pertains to ASN.1 OIDs, which are unrelated
  93    to the OIDs used in PostgreSQL.)
  94
  95    uuid_ns_x500 () → uuid
  96
  97    Returns a constant designating the X.500 distinguished name (DN)
  98    namespace for UUIDs.
  99
 100 F.49.2. Building uuid-ossp #
 101
 102    Historically this module depended on the OSSP UUID library, which
 103    accounts for the module's name. While the OSSP UUID library can still
 104    be found at http://www.ossp.org/pkg/lib/uuid/, it is not well
 105    maintained, and is becoming increasingly difficult to port to newer
 106    platforms. uuid-ossp can now be built without the OSSP library on some
 107    platforms. On FreeBSD and some other BSD-derived platforms, suitable
 108    UUID creation functions are included in the core libc library. On
 109    Linux, macOS, and some other platforms, suitable functions are provided
 110    in the libuuid library, which originally came from the e2fsprogs
 111    project (though on modern Linux it is considered part of
 112    util-linux-ng). When invoking configure, specify --with-uuid=bsd to use
 113    the BSD functions, or --with-uuid=e2fs to use e2fsprogs' libuuid, or
 114    --with-uuid=ossp to use the OSSP UUID library. More than one of these
 115    libraries might be available on a particular machine, so configure does
 116    not automatically choose one.
 117
 118 F.49.3. Author #
 119
 120    Peter Eisentraut <peter_e@gmx.net>