summaryrefslogtreecommitdiffstats
path: root/doc/src/sgml/uuid-ossp.sgml
diff options
context:
space:
mode:
Diffstat (limited to 'doc/src/sgml/uuid-ossp.sgml')
-rw-r--r--doc/src/sgml/uuid-ossp.sgml242
1 files changed, 242 insertions, 0 deletions
diff --git a/doc/src/sgml/uuid-ossp.sgml b/doc/src/sgml/uuid-ossp.sgml
new file mode 100644
index 0000000..6f851ac
--- /dev/null
+++ b/doc/src/sgml/uuid-ossp.sgml
@@ -0,0 +1,242 @@
+<!-- doc/src/sgml/uuid-ossp.sgml -->
+
+<sect1 id="uuid-ossp" xreflabel="uuid-ossp">
+ <title>uuid-ossp &mdash; 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://tools.ietf.org/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>