243 lines
8.4 KiB
Plaintext
243 lines
8.4 KiB
Plaintext
<!-- doc/src/sgml/uuid-ossp.sgml -->
|
|
|
|
<sect1 id="uuid-ossp" xreflabel="uuid-ossp">
|
|
<title>uuid-ossp — a UUID generator</title>
|
|
|
|
<indexterm zone="uuid-ossp">
|
|
<primary>uuid-ossp</primary>
|
|
</indexterm>
|
|
|
|
<para>
|
|
The <filename>uuid-ossp</filename> module provides functions to generate universally
|
|
unique identifiers (UUIDs) using one of several standard algorithms. There
|
|
are also functions to produce certain special UUID constants.
|
|
This module is only necessary for special requirements beyond what is
|
|
available in core <productname>PostgreSQL</productname>. See <xref
|
|
linkend="functions-uuid"/> for built-in ways to generate UUIDs.
|
|
</para>
|
|
|
|
<para>
|
|
This module is considered <quote>trusted</quote>, that is, it can be
|
|
installed by non-superusers who have <literal>CREATE</literal> privilege
|
|
on the current database.
|
|
</para>
|
|
|
|
<sect2 id="uuid-ossp-functions-sect">
|
|
<title><literal>uuid-ossp</literal> Functions</title>
|
|
|
|
<para>
|
|
<xref linkend="uuid-ossp-functions"/> shows the functions available to
|
|
generate UUIDs.
|
|
The relevant standards ITU-T Rec. X.667, ISO/IEC 9834-8:2005, and
|
|
<ulink url="https://datatracker.ietf.org/doc/html/rfc4122">RFC 4122</ulink>
|
|
specify four algorithms for generating UUIDs, identified by the
|
|
version numbers 1, 3, 4, and 5. (There is no version 2 algorithm.)
|
|
Each of these algorithms could be suitable for a different set of
|
|
applications.
|
|
</para>
|
|
|
|
<table id="uuid-ossp-functions">
|
|
<title>Functions for UUID Generation</title>
|
|
<tgroup cols="1">
|
|
<thead>
|
|
<row>
|
|
<entry role="func_table_entry"><para role="func_signature">
|
|
Function
|
|
</para>
|
|
<para>
|
|
Description
|
|
</para></entry>
|
|
</row>
|
|
</thead>
|
|
|
|
<tbody>
|
|
<row>
|
|
<entry role="func_table_entry"><para role="func_signature">
|
|
<indexterm><primary>uuid_generate_v1</primary></indexterm>
|
|
<function>uuid_generate_v1</function> ()
|
|
<returnvalue>uuid</returnvalue>
|
|
</para>
|
|
<para>
|
|
Generates a version 1 UUID. This involves the MAC
|
|
address of the computer and a time stamp. Note that UUIDs of this
|
|
kind reveal the identity of the computer that created the identifier
|
|
and the time at which it did so, which might make it unsuitable for
|
|
certain security-sensitive applications.
|
|
</para></entry>
|
|
</row>
|
|
|
|
<row>
|
|
<entry role="func_table_entry"><para role="func_signature">
|
|
<indexterm><primary>uuid_generate_v1mc</primary></indexterm>
|
|
<function>uuid_generate_v1mc</function> ()
|
|
<returnvalue>uuid</returnvalue>
|
|
</para>
|
|
<para>
|
|
Generates a version 1 UUID, but uses a random multicast
|
|
MAC address instead of the real MAC address of the computer.
|
|
</para></entry>
|
|
</row>
|
|
|
|
<row>
|
|
<entry role="func_table_entry"><para role="func_signature">
|
|
<indexterm><primary>uuid_generate_v3</primary></indexterm>
|
|
<function>uuid_generate_v3</function> ( <parameter>namespace</parameter> <type>uuid</type>, <parameter>name</parameter> <type>text</type> )
|
|
<returnvalue>uuid</returnvalue>
|
|
</para>
|
|
<para>
|
|
Generates a version 3 UUID in the given namespace using
|
|
the specified input name. The namespace should be one of the special
|
|
constants produced by the <function>uuid_ns_*()</function> functions
|
|
shown in <xref linkend="uuid-ossp-constants"/>. (It could be any UUID
|
|
in theory.) The name is an identifier in the selected namespace.
|
|
</para>
|
|
<para>
|
|
For example:
|
|
|
|
<programlisting>
|
|
SELECT uuid_generate_v3(uuid_ns_url(), 'http://www.postgresql.org');
|
|
</programlisting>
|
|
|
|
The name parameter will be MD5-hashed, so the cleartext cannot be
|
|
derived from the generated UUID.
|
|
The generation of UUIDs by this method has no random or
|
|
environment-dependent element and is therefore reproducible.
|
|
</para></entry>
|
|
</row>
|
|
|
|
<row>
|
|
<entry role="func_table_entry"><para role="func_signature">
|
|
<function>uuid_generate_v4</function> ()
|
|
<returnvalue>uuid</returnvalue>
|
|
</para>
|
|
<para>
|
|
Generates a version 4 UUID, which is derived entirely
|
|
from random numbers.
|
|
</para></entry>
|
|
</row>
|
|
|
|
<row>
|
|
<entry role="func_table_entry"><para role="func_signature">
|
|
<function>uuid_generate_v5</function> ( <parameter>namespace</parameter> <type>uuid</type>, <parameter>name</parameter> <type>text</type> )
|
|
<returnvalue>uuid</returnvalue>
|
|
</para>
|
|
<para>
|
|
Generates a version 5 UUID, which works like a version 3
|
|
UUID except that SHA-1 is used as a hashing method. Version 5 should
|
|
be preferred over version 3 because SHA-1 is thought to be more secure
|
|
than MD5.
|
|
</para></entry>
|
|
</row>
|
|
</tbody>
|
|
</tgroup>
|
|
</table>
|
|
|
|
<table id="uuid-ossp-constants">
|
|
<title>Functions Returning UUID Constants</title>
|
|
<tgroup cols="1">
|
|
<thead>
|
|
<row>
|
|
<entry role="func_table_entry"><para role="func_signature">
|
|
Function
|
|
</para>
|
|
<para>
|
|
Description
|
|
</para></entry>
|
|
</row>
|
|
</thead>
|
|
|
|
<tbody>
|
|
<row>
|
|
<entry role="func_table_entry"><para role="func_signature">
|
|
<function>uuid_nil</function> ()
|
|
<returnvalue>uuid</returnvalue>
|
|
</para>
|
|
<para>
|
|
Returns a <quote>nil</quote> UUID constant, which does not occur as a
|
|
real UUID.
|
|
</para></entry>
|
|
</row>
|
|
|
|
<row>
|
|
<entry role="func_table_entry"><para role="func_signature">
|
|
<function>uuid_ns_dns</function> ()
|
|
<returnvalue>uuid</returnvalue>
|
|
</para>
|
|
<para>
|
|
Returns a constant designating the DNS namespace for UUIDs.
|
|
</para></entry>
|
|
</row>
|
|
|
|
<row>
|
|
<entry role="func_table_entry"><para role="func_signature">
|
|
<function>uuid_ns_url</function> ()
|
|
<returnvalue>uuid</returnvalue>
|
|
</para>
|
|
<para>
|
|
Returns a constant designating the URL namespace for UUIDs.
|
|
</para></entry>
|
|
</row>
|
|
|
|
<row>
|
|
<entry role="func_table_entry"><para role="func_signature">
|
|
<function>uuid_ns_oid</function> ()
|
|
<returnvalue>uuid</returnvalue>
|
|
</para>
|
|
<para>
|
|
Returns a constant designating the ISO object identifier (OID) namespace for
|
|
UUIDs. (This pertains to ASN.1 OIDs, which are unrelated to the OIDs
|
|
used in <productname>PostgreSQL</productname>.)
|
|
</para></entry>
|
|
</row>
|
|
|
|
<row>
|
|
<entry role="func_table_entry"><para role="func_signature">
|
|
<function>uuid_ns_x500</function> ()
|
|
<returnvalue>uuid</returnvalue>
|
|
</para>
|
|
<para>
|
|
Returns a constant designating the X.500 distinguished name (DN)
|
|
namespace for UUIDs.
|
|
</para></entry>
|
|
</row>
|
|
</tbody>
|
|
</tgroup>
|
|
</table>
|
|
</sect2>
|
|
|
|
<sect2 id="uuid-ossp-building">
|
|
<title>Building <filename>uuid-ossp</filename></title>
|
|
|
|
<para>
|
|
Historically this module depended on the OSSP UUID library, which accounts
|
|
for the module's name. While the OSSP UUID library can still be found
|
|
at <ulink url="http://www.ossp.org/pkg/lib/uuid/"></ulink>, it is not well
|
|
maintained, and is becoming increasingly difficult to port to newer
|
|
platforms. <filename>uuid-ossp</filename> can now be built without the OSSP
|
|
library on some platforms. On FreeBSD and some other BSD-derived
|
|
platforms, suitable UUID creation functions are included in the
|
|
core <filename>libc</filename> library. On Linux, macOS, and some other
|
|
platforms, suitable functions are provided in the <filename>libuuid</filename>
|
|
library, which originally came from the <literal>e2fsprogs</literal> project
|
|
(though on modern Linux it is considered part
|
|
of <literal>util-linux-ng</literal>). When invoking <filename>configure</filename>,
|
|
specify <option>--with-uuid=bsd</option> to use the BSD functions,
|
|
or <option>--with-uuid=e2fs</option> to
|
|
use <literal>e2fsprogs</literal>' <filename>libuuid</filename>, or
|
|
<option>--with-uuid=ossp</option> to use the OSSP UUID library.
|
|
More than one of these libraries might be available on a particular
|
|
machine, so <filename>configure</filename> does not automatically choose one.
|
|
</para>
|
|
</sect2>
|
|
|
|
<sect2 id="uuid-ossp-author">
|
|
<title>Author</title>
|
|
|
|
<para>
|
|
Peter Eisentraut <email>peter_e@gmx.net</email>
|
|
</para>
|
|
|
|
</sect2>
|
|
|
|
</sect1>
|