begriffs open source - ai-pg/blob - full-docs/src/sgml/html/uuid-ossp.html

   1 <?xml version="1.0" encoding="UTF-8" standalone="no"?>
   2 <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>F.49. uuid-ossp — a UUID generator</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="unaccent.html" title="F.48. unaccent — a text search dictionary which removes diacritics" /><link rel="next" href="xml2.html" title="F.50. xml2 — XPath querying and XSLT functionality" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">F.49. uuid-ossp — a UUID generator</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="unaccent.html" title="F.48. unaccent — a text search dictionary which removes diacritics">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="contrib.html" title="Appendix F. Additional Supplied Modules and Extensions">Up</a></td><th width="60%" align="center">Appendix F. Additional Supplied Modules and Extensions</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 18.0 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="xml2.html" title="F.50. xml2 — XPath querying and XSLT functionality">Next</a></td></tr></table><hr /></div><div class="sect1" id="UUID-OSSP"><div class="titlepage"><div><div><h2 class="title" style="clear: both">F.49. uuid-ossp — a UUID generator <a href="#UUID-OSSP" class="id_link">#</a></h2></div></div></div><div class="toc"><dl class="toc"><dt><span class="sect2"><a href="uuid-ossp.html#UUID-OSSP-FUNCTIONS-SECT">F.49.1. <code class="literal">uuid-ossp</code> Functions</a></span></dt><dt><span class="sect2"><a href="uuid-ossp.html#UUID-OSSP-BUILDING">F.49.2. Building <code class="filename">uuid-ossp</code></a></span></dt><dt><span class="sect2"><a href="uuid-ossp.html#UUID-OSSP-AUTHOR">F.49.3. Author</a></span></dt></dl></div><a id="id-1.11.7.59.2" class="indexterm"></a><p>
   3   The <code class="filename">uuid-ossp</code> module provides functions to generate universally
   4   unique identifiers (UUIDs) using one of several standard algorithms.  There
   5   are also functions to produce certain special UUID constants.
   6   This module is only necessary for special requirements beyond what is
   7   available in core <span class="productname">PostgreSQL</span>.  See <a class="xref" href="functions-uuid.html" title="9.14. UUID Functions">Section 9.14</a> for built-in ways to generate UUIDs.
   8  </p><p>
   9   This module is considered <span class="quote">“<span class="quote">trusted</span>”</span>, that is, it can be
  10   installed by non-superusers who have <code class="literal">CREATE</code> privilege
  11   on the current database.
  12  </p><div class="sect2" id="UUID-OSSP-FUNCTIONS-SECT"><div class="titlepage"><div><div><h3 class="title">F.49.1. <code class="literal">uuid-ossp</code> Functions <a href="#UUID-OSSP-FUNCTIONS-SECT" class="id_link">#</a></h3></div></div></div><p>
  13    <a class="xref" href="uuid-ossp.html#UUID-OSSP-FUNCTIONS" title="Table F.35. Functions for UUID Generation">Table F.35</a> shows the functions available to
  14    generate UUIDs.
  15    The relevant standards ITU-T Rec. X.667, ISO/IEC 9834-8:2005, and
  16    <a class="ulink" href="https://datatracker.ietf.org/doc/html/rfc4122" target="_top">RFC 4122</a>
  17    specify four algorithms for generating UUIDs, identified by the
  18    version numbers 1, 3, 4, and 5.  (There is no version 2 algorithm.)
  19    Each of these algorithms could be suitable for a different set of
  20    applications.
  21   </p><div class="table" id="UUID-OSSP-FUNCTIONS"><p class="title"><strong>Table F.35. Functions for UUID Generation</strong></p><div class="table-contents"><table class="table" summary="Functions for UUID Generation" border="1"><colgroup><col /></colgroup><thead><tr><th class="func_table_entry"><p class="func_signature">
  22         Function
  23        </p>
  24        <p>
  25         Description
  26        </p></th></tr></thead><tbody><tr><td class="func_table_entry"><p class="func_signature">
  27         <a id="id-1.11.7.59.5.3.2.2.1.1.1.1" class="indexterm"></a>
  28         <code class="function">uuid_generate_v1</code> ()
  29         → <code class="returnvalue">uuid</code>
  30        </p>
  31        <p>
  32         Generates a version 1 UUID.  This involves the MAC
  33         address of the computer and a time stamp.  Note that UUIDs of this
  34         kind reveal the identity of the computer that created the identifier
  35         and the time at which it did so, which might make it unsuitable for
  36         certain security-sensitive applications.
  37        </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
  38         <a id="id-1.11.7.59.5.3.2.2.2.1.1.1" class="indexterm"></a>
  39         <code class="function">uuid_generate_v1mc</code> ()
  40         → <code class="returnvalue">uuid</code>
  41        </p>
  42        <p>
  43         Generates a version 1 UUID, but uses a random multicast
  44         MAC address instead of the real MAC address of the computer.
  45        </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
  46         <a id="id-1.11.7.59.5.3.2.2.3.1.1.1" class="indexterm"></a>
  47         <code class="function">uuid_generate_v3</code> ( <em class="parameter"><code>namespace</code></em> <code class="type">uuid</code>, <em class="parameter"><code>name</code></em> <code class="type">text</code> )
  48         → <code class="returnvalue">uuid</code>
  49        </p>
  50        <p>
  51         Generates a version 3 UUID in the given namespace using
  52         the specified input name.  The namespace should be one of the special
  53         constants produced by the <code class="function">uuid_ns_*()</code> functions
  54         shown in <a class="xref" href="uuid-ossp.html#UUID-OSSP-CONSTANTS" title="Table F.36. Functions Returning UUID Constants">Table F.36</a>.  (It could be any UUID
  55         in theory.)  The name is an identifier in the selected namespace.
  56        </p>
  57        <p>
  58         For example:
  59
  60 </p><pre class="programlisting">
  61 SELECT uuid_generate_v3(uuid_ns_url(), 'http://www.postgresql.org');
  62 </pre><p>
  63
  64         The name parameter will be MD5-hashed, so the cleartext cannot be
  65         derived from the generated UUID.
  66         The generation of UUIDs by this method has no random or
  67         environment-dependent element and is therefore reproducible.
  68        </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
  69         <code class="function">uuid_generate_v4</code> ()
  70         → <code class="returnvalue">uuid</code>
  71        </p>
  72        <p>
  73         Generates a version 4 UUID, which is derived entirely
  74         from random numbers.
  75        </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
  76         <code class="function">uuid_generate_v5</code> ( <em class="parameter"><code>namespace</code></em> <code class="type">uuid</code>, <em class="parameter"><code>name</code></em> <code class="type">text</code> )
  77         → <code class="returnvalue">uuid</code>
  78        </p>
  79        <p>
  80         Generates a version 5 UUID, which works like a version 3
  81         UUID except that SHA-1 is used as a hashing method.  Version 5 should
  82         be preferred over version 3 because SHA-1 is thought to be more secure
  83         than MD5.
  84        </p></td></tr></tbody></table></div></div><br class="table-break" /><div class="table" id="UUID-OSSP-CONSTANTS"><p class="title"><strong>Table F.36. Functions Returning UUID Constants</strong></p><div class="table-contents"><table class="table" summary="Functions Returning UUID Constants" border="1"><colgroup><col /></colgroup><thead><tr><th class="func_table_entry"><p class="func_signature">
  85         Function
  86        </p>
  87        <p>
  88         Description
  89        </p></th></tr></thead><tbody><tr><td class="func_table_entry"><p class="func_signature">
  90         <code class="function">uuid_nil</code> ()
  91         → <code class="returnvalue">uuid</code>
  92        </p>
  93        <p>
  94         Returns a <span class="quote">“<span class="quote">nil</span>”</span> UUID constant, which does not occur as a
  95         real UUID.
  96        </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
  97         <code class="function">uuid_ns_dns</code> ()
  98         → <code class="returnvalue">uuid</code>
  99        </p>
 100        <p>
 101         Returns a constant designating the DNS namespace for UUIDs.
 102        </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
 103         <code class="function">uuid_ns_url</code> ()
 104         → <code class="returnvalue">uuid</code>
 105        </p>
 106        <p>
 107         Returns a constant designating the URL namespace for UUIDs.
 108        </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
 109         <code class="function">uuid_ns_oid</code> ()
 110         → <code class="returnvalue">uuid</code>
 111        </p>
 112        <p>
 113         Returns a constant designating the ISO object identifier (OID) namespace for
 114         UUIDs.  (This pertains to ASN.1 OIDs, which are unrelated to the OIDs
 115         used in <span class="productname">PostgreSQL</span>.)
 116        </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
 117         <code class="function">uuid_ns_x500</code> ()
 118         → <code class="returnvalue">uuid</code>
 119        </p>
 120        <p>
 121         Returns a constant designating the X.500 distinguished name (DN)
 122         namespace for UUIDs.
 123        </p></td></tr></tbody></table></div></div><br class="table-break" /></div><div class="sect2" id="UUID-OSSP-BUILDING"><div class="titlepage"><div><div><h3 class="title">F.49.2. Building <code class="filename">uuid-ossp</code> <a href="#UUID-OSSP-BUILDING" class="id_link">#</a></h3></div></div></div><p>
 124    Historically this module depended on the OSSP UUID library, which accounts
 125    for the module's name.  While the OSSP UUID library can still be found
 126    at <a class="ulink" href="http://www.ossp.org/pkg/lib/uuid/" target="_top">http://www.ossp.org/pkg/lib/uuid/</a>, it is not well
 127    maintained, and is becoming increasingly difficult to port to newer
 128    platforms.  <code class="filename">uuid-ossp</code> can now be built without the OSSP
 129    library on some platforms.  On FreeBSD and some other BSD-derived
 130    platforms, suitable UUID creation functions are included in the
 131    core <code class="filename">libc</code> library.  On Linux, macOS, and some other
 132    platforms, suitable functions are provided in the <code class="filename">libuuid</code>
 133    library, which originally came from the <code class="literal">e2fsprogs</code> project
 134    (though on modern Linux it is considered part
 135    of <code class="literal">util-linux-ng</code>).  When invoking <code class="filename">configure</code>,
 136    specify <code class="option">--with-uuid=bsd</code> to use the BSD functions,
 137    or <code class="option">--with-uuid=e2fs</code> to
 138    use <code class="literal">e2fsprogs</code>' <code class="filename">libuuid</code>, or
 139    <code class="option">--with-uuid=ossp</code> to use the OSSP UUID library.
 140    More than one of these libraries might be available on a particular
 141    machine, so <code class="filename">configure</code> does not automatically choose one.
 142   </p></div><div class="sect2" id="UUID-OSSP-AUTHOR"><div class="titlepage"><div><div><h3 class="title">F.49.3. Author <a href="#UUID-OSSP-AUTHOR" class="id_link">#</a></h3></div></div></div><p>
 143    Peter Eisentraut <code class="email">&lt;<a class="email" href="mailto:peter_e@gmx.net">peter_e@gmx.net</a>&gt;</code>
 144   </p></div></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="unaccent.html" title="F.48. unaccent — a text search dictionary which removes diacritics">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="contrib.html" title="Appendix F. Additional Supplied Modules and Extensions">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="xml2.html" title="F.50. xml2 — XPath querying and XSLT functionality">Next</a></td></tr><tr><td width="40%" align="left" valign="top">F.48. unaccent — a text search dictionary which removes diacritics </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 18.0 Documentation">Home</a></td><td width="40%" align="right" valign="top"> F.50. xml2 — XPath querying and XSLT functionality</td></tr></table></div></body></html>