| 1 |
<!-- doc/src/sgml/uuid-ossp.sgml --> |
| 2 |
|
| 3 |
<sect1 id="uuid-ossp" xreflabel="uuid-ossp"> |
| 4 |
<title>uuid-ossp — a UUID generator</title> |
| 5 |
|
| 6 |
<indexterm zone="uuid-ossp"> |
| 7 |
<primary>uuid-ossp</primary> |
| 8 |
</indexterm> |
| 9 |
|
| 10 |
<para> |
| 11 |
The <filename>uuid-ossp</filename> module provides functions to generate universally |
| 12 |
unique identifiers (UUIDs) using one of several standard algorithms. There |
| 13 |
are also functions to produce certain special UUID constants. |
| 14 |
This module is only necessary for special requirements beyond what is |
| 15 |
available in core <productname>PostgreSQL</productname>. See <xref |
| 16 |
linkend="functions-uuid"/> for built-in ways to generate UUIDs. |
| 17 |
</para> |
| 18 |
|
| 19 |
<para> |
| 20 |
This module is considered <quote>trusted</quote>, that is, it can be |
| 21 |
installed by non-superusers who have <literal>CREATE</literal> privilege |
| 22 |
on the current database. |
| 23 |
</para> |
| 24 |
|
| 25 |
<sect2 id="uuid-ossp-functions-sect"> |
| 26 |
<title><literal>uuid-ossp</literal> Functions</title> |
| 27 |
|
| 28 |
<para> |
| 29 |
<xref linkend="uuid-ossp-functions"/> shows the functions available to |
| 30 |
generate UUIDs. |
| 31 |
The relevant standards ITU-T Rec. X.667, ISO/IEC 9834-8:2005, and |
| 32 |
<ulink url="https://datatracker.ietf.org/doc/html/rfc4122">RFC 4122</ulink> |
| 33 |
specify four algorithms for generating UUIDs, identified by the |
| 34 |
version numbers 1, 3, 4, and 5. (There is no version 2 algorithm.) |
| 35 |
Each of these algorithms could be suitable for a different set of |
| 36 |
applications. |
| 37 |
</para> |
| 38 |
|
| 39 |
<table id="uuid-ossp-functions"> |
| 40 |
<title>Functions for UUID Generation</title> |
| 41 |
<tgroup cols="1"> |
| 42 |
<thead> |
| 43 |
<row> |
| 44 |
<entry role="func_table_entry"><para role="func_signature"> |
| 45 |
Function |
| 46 |
</para> |
| 47 |
<para> |
| 48 |
Description |
| 49 |
</para></entry> |
| 50 |
</row> |
| 51 |
</thead> |
| 52 |
|
| 53 |
<tbody> |
| 54 |
<row> |
| 55 |
<entry role="func_table_entry"><para role="func_signature"> |
| 56 |
<indexterm><primary>uuid_generate_v1</primary></indexterm> |
| 57 |
<function>uuid_generate_v1</function> () |
| 58 |
<returnvalue>uuid</returnvalue> |
| 59 |
</para> |
| 60 |
<para> |
| 61 |
Generates a version 1 UUID. This involves the MAC |
| 62 |
address of the computer and a time stamp. Note that UUIDs of this |
| 63 |
kind reveal the identity of the computer that created the identifier |
| 64 |
and the time at which it did so, which might make it unsuitable for |
| 65 |
certain security-sensitive applications. |
| 66 |
</para></entry> |
| 67 |
</row> |
| 68 |
|
| 69 |
<row> |
| 70 |
<entry role="func_table_entry"><para role="func_signature"> |
| 71 |
<indexterm><primary>uuid_generate_v1mc</primary></indexterm> |
| 72 |
<function>uuid_generate_v1mc</function> () |
| 73 |
<returnvalue>uuid</returnvalue> |
| 74 |
</para> |
| 75 |
<para> |
| 76 |
Generates a version 1 UUID, but uses a random multicast |
| 77 |
MAC address instead of the real MAC address of the computer. |
| 78 |
</para></entry> |
| 79 |
</row> |
| 80 |
|
| 81 |
<row> |
| 82 |
<entry role="func_table_entry"><para role="func_signature"> |
| 83 |
<indexterm><primary>uuid_generate_v3</primary></indexterm> |
| 84 |
<function>uuid_generate_v3</function> ( <parameter>namespace</parameter> <type>uuid</type>, <parameter>name</parameter> <type>text</type> ) |
| 85 |
<returnvalue>uuid</returnvalue> |
| 86 |
</para> |
| 87 |
<para> |
| 88 |
Generates a version 3 UUID in the given namespace using |
| 89 |
the specified input name. The namespace should be one of the special |
| 90 |
constants produced by the <function>uuid_ns_*()</function> functions |
| 91 |
shown in <xref linkend="uuid-ossp-constants"/>. (It could be any UUID |
| 92 |
in theory.) The name is an identifier in the selected namespace. |
| 93 |
</para> |
| 94 |
<para> |
| 95 |
For example: |
| 96 |
|
| 97 |
<programlisting> |
| 98 |
SELECT uuid_generate_v3(uuid_ns_url(), 'http://www.postgresql.org'); |
| 99 |
</programlisting> |
| 100 |
|
| 101 |
The name parameter will be MD5-hashed, so the cleartext cannot be |
| 102 |
derived from the generated UUID. |
| 103 |
The generation of UUIDs by this method has no random or |
| 104 |
environment-dependent element and is therefore reproducible. |
| 105 |
</para></entry> |
| 106 |
</row> |
| 107 |
|
| 108 |
<row> |
| 109 |
<entry role="func_table_entry"><para role="func_signature"> |
| 110 |
<function>uuid_generate_v4</function> () |
| 111 |
<returnvalue>uuid</returnvalue> |
| 112 |
</para> |
| 113 |
<para> |
| 114 |
Generates a version 4 UUID, which is derived entirely |
| 115 |
from random numbers. |
| 116 |
</para></entry> |
| 117 |
</row> |
| 118 |
|
| 119 |
<row> |
| 120 |
<entry role="func_table_entry"><para role="func_signature"> |
| 121 |
<function>uuid_generate_v5</function> ( <parameter>namespace</parameter> <type>uuid</type>, <parameter>name</parameter> <type>text</type> ) |
| 122 |
<returnvalue>uuid</returnvalue> |
| 123 |
</para> |
| 124 |
<para> |
| 125 |
Generates a version 5 UUID, which works like a version 3 |
| 126 |
UUID except that SHA-1 is used as a hashing method. Version 5 should |
| 127 |
be preferred over version 3 because SHA-1 is thought to be more secure |
| 128 |
than MD5. |
| 129 |
</para></entry> |
| 130 |
</row> |
| 131 |
</tbody> |
| 132 |
</tgroup> |
| 133 |
</table> |
| 134 |
|
| 135 |
<table id="uuid-ossp-constants"> |
| 136 |
<title>Functions Returning UUID Constants</title> |
| 137 |
<tgroup cols="1"> |
| 138 |
<thead> |
| 139 |
<row> |
| 140 |
<entry role="func_table_entry"><para role="func_signature"> |
| 141 |
Function |
| 142 |
</para> |
| 143 |
<para> |
| 144 |
Description |
| 145 |
</para></entry> |
| 146 |
</row> |
| 147 |
</thead> |
| 148 |
|
| 149 |
<tbody> |
| 150 |
<row> |
| 151 |
<entry role="func_table_entry"><para role="func_signature"> |
| 152 |
<function>uuid_nil</function> () |
| 153 |
<returnvalue>uuid</returnvalue> |
| 154 |
</para> |
| 155 |
<para> |
| 156 |
Returns a <quote>nil</quote> UUID constant, which does not occur as a |
| 157 |
real UUID. |
| 158 |
</para></entry> |
| 159 |
</row> |
| 160 |
|
| 161 |
<row> |
| 162 |
<entry role="func_table_entry"><para role="func_signature"> |
| 163 |
<function>uuid_ns_dns</function> () |
| 164 |
<returnvalue>uuid</returnvalue> |
| 165 |
</para> |
| 166 |
<para> |
| 167 |
Returns a constant designating the DNS namespace for UUIDs. |
| 168 |
</para></entry> |
| 169 |
</row> |
| 170 |
|
| 171 |
<row> |
| 172 |
<entry role="func_table_entry"><para role="func_signature"> |
| 173 |
<function>uuid_ns_url</function> () |
| 174 |
<returnvalue>uuid</returnvalue> |
| 175 |
</para> |
| 176 |
<para> |
| 177 |
Returns a constant designating the URL namespace for UUIDs. |
| 178 |
</para></entry> |
| 179 |
</row> |
| 180 |
|
| 181 |
<row> |
| 182 |
<entry role="func_table_entry"><para role="func_signature"> |
| 183 |
<function>uuid_ns_oid</function> () |
| 184 |
<returnvalue>uuid</returnvalue> |
| 185 |
</para> |
| 186 |
<para> |
| 187 |
Returns a constant designating the ISO object identifier (OID) namespace for |
| 188 |
UUIDs. (This pertains to ASN.1 OIDs, which are unrelated to the OIDs |
| 189 |
used in <productname>PostgreSQL</productname>.) |
| 190 |
</para></entry> |
| 191 |
</row> |
| 192 |
|
| 193 |
<row> |
| 194 |
<entry role="func_table_entry"><para role="func_signature"> |
| 195 |
<function>uuid_ns_x500</function> () |
| 196 |
<returnvalue>uuid</returnvalue> |
| 197 |
</para> |
| 198 |
<para> |
| 199 |
Returns a constant designating the X.500 distinguished name (DN) |
| 200 |
namespace for UUIDs. |
| 201 |
</para></entry> |
| 202 |
</row> |
| 203 |
</tbody> |
| 204 |
</tgroup> |
| 205 |
</table> |
| 206 |
</sect2> |
| 207 |
|
| 208 |
<sect2 id="uuid-ossp-building"> |
| 209 |
<title>Building <filename>uuid-ossp</filename></title> |
| 210 |
|
| 211 |
<para> |
| 212 |
Historically this module depended on the OSSP UUID library, which accounts |
| 213 |
for the module's name. While the OSSP UUID library can still be found |
| 214 |
at <ulink url="http://www.ossp.org/pkg/lib/uuid/"></ulink>, it is not well |
| 215 |
maintained, and is becoming increasingly difficult to port to newer |
| 216 |
platforms. <filename>uuid-ossp</filename> can now be built without the OSSP |
| 217 |
library on some platforms. On FreeBSD and some other BSD-derived |
| 218 |
platforms, suitable UUID creation functions are included in the |
| 219 |
core <filename>libc</filename> library. On Linux, macOS, and some other |
| 220 |
platforms, suitable functions are provided in the <filename>libuuid</filename> |
| 221 |
library, which originally came from the <literal>e2fsprogs</literal> project |
| 222 |
(though on modern Linux it is considered part |
| 223 |
of <literal>util-linux-ng</literal>). When invoking <filename>configure</filename>, |
| 224 |
specify <option>--with-uuid=bsd</option> to use the BSD functions, |
| 225 |
or <option>--with-uuid=e2fs</option> to |
| 226 |
use <literal>e2fsprogs</literal>' <filename>libuuid</filename>, or |
| 227 |
<option>--with-uuid=ossp</option> to use the OSSP UUID library. |
| 228 |
More than one of these libraries might be available on a particular |
| 229 |
machine, so <filename>configure</filename> does not automatically choose one. |
| 230 |
</para> |
| 231 |
</sect2> |
| 232 |
|
| 233 |
<sect2 id="uuid-ossp-author"> |
| 234 |
<title>Author</title> |
| 235 |
|
| 236 |
<para> |
| 237 |
Peter Eisentraut <email>[email protected]</email> |
| 238 |
</para> |
| 239 |
|
| 240 |
</sect2> |
| 241 |
|
| 242 |
</sect1> |