This software package is an addon module for postgres.  It supplies
support functions for the built-in uuid data type.  It was originally built and
tested against postgres version 8.4.0.    This file and all supplied files
are written by Nathan Wagner and placed in the public domain.  Bug
reports to nw@hydaspes.if.org.

Credit: the hash functions are stripped down implementations from
libtomcrypt by Tom St Denis, also in the public domain.

Functions supplied are uuid generation functions, conforming (with
one exception) to RFC 4122 (see below for details).

Features:

UUID generation functions for version 1, 3, 4, and 5 uuids.

RFC 4122 compliance, with the exception of the multicast bit
for randomly generated mac addresses.  This module sets the correct
bit (the most significant bit), rather than the one specified in the RFC
(the least significant one).

No external library dependency (other than the standard C library).
The uuid generation has been written from scratch and is included
with the source.

The entire package is in the public domain, so there are no licensing
issues.

Compiles with the usual postgres addon infrastructure.
make
make install

The 'make install' step will need sufficient privileges to write
to the Postgres extension directory, so 'sudo make install'
might be needed.

Installation can be done via the usual Postgres extension mechanism.
create extension pduuid;

The extension is re-locatable, so you can specify a schema if you
like.

Installation can be done manually with:

psql -f uuid.sql
psql -f uninstall-uuid.sql

A pure postgres implementation is also supplied of just the generation
functions in purepguuid.sql, though this is very inefficient, feature
incomplete, and untested.  It's there if you need it though.

Generation Functions:

uuid_v1()
returns a version 1 uuid.  if the mac address can't be determined,
uses a random one.

uuid_v1mc()
returns a version 1 uuid using a random mac address

uuid_v3(uuid, text)
returns a version 3 uuid using the supplied namespace uuid and the
given input string.  This is an md5 based uuid.

uuid_v4()
returns a version 4 uuid.  This is a random uuid.  The odds of collision
are vanishingly low and it is safe to use for regular production uuid
generation.

uuid_v5(uuid, text)
returns a version 5 uuid using the supplied namespace uuid and the
given input string.  This is an sha1 based uuid.

uuid_url(text)
Returns a version 5 uuid using the URL namespace.

uuid_dns(text)
Returns a version 5 uuid using the DNS namespace.

uuid_oid(text)
Returns a version 5 uuid using the DNS namespace.

uuid_x500(text)
Returns a version 5 uuid using the DNS namespace.

UUID Lookup Functions:

uuid_recent()
returns the most recent uuid generated by this backend.  Returns
the nil uuid if no uuids have been generated yet.

uuid_nil()
Returns the nil uuid (all bits zero).

uuid_ns_dns()
Returns the DNS namespace uuid.
6ba7b810-9dad-11d1-80b4-00c04fd430c8

uuid_ns_url()
Returns the URL namespace uuid.
6ba7b811-9dad-11d1-80b4-00c04fd430c8

uuid_ns_oid()
Returns the OID namespace uuid.
6ba7b812-9dad-11d1-80b4-00c04fd430c8

uuid_ns_x500()
Returns the X500 namespace uuid.
6ba7b813-9dad-11d1-80b4-00c04fd430c8

Casting Support:

Cast functions and casts are created for uuids to and from data types
where this is reasonable:

Bytea: treats the UUID as an array of bytes.  This is always in
network byte order for the subfields of a uuid, where applicable.

Numeric: treats the UUID as a 128 bit number and converts it to a numeric.

Bit(128) and bit varying: treats the uuid as a 128 bit vector.
Casts to bit(n) where n is shorter than 128 will truncate
the uuid.  Where n is longer than 128, the bit vector
will be zero extended.

Field extraction functions:

uuid_version(uuid)
Returns an integer corresponding to the 4 bit version number.

uuid_macaddr(uuid)
Returns a macaddr type corresponding to the mac address part of the
uuid.  This function can be called on any uuid, not just version 1 uuids.

uuid_timestamp(uuid)
Returns a timestamp corresponding to the timestamp field in the uuid.  You
probably want to use uuid_timestamptz().

uuid_timestamptz(uuid)
Returns a timestamp with time zonecorresponding to the timestamp field in the
uuid.