pd.if.org Git - uuid/blob - postgres/README

   1 This software package is an addon module for postgres.  It supplies
   2 support functions for the built-in uuid data type.  It was built and
   3 tested against postgres version 8.4.0.  This file and all supplied files
   4 are written by Nathan Wagner and placed in the public domain.  Bug
   5 reports to nw@hydaspes.if.org.
   6
   7 Credit: the hash functions are stripped down implementations from
   8 libtomcrypt by Tom St Denis, also in the public domain.
   9
  10 Functions supplied are uuid generation functions, conforming (with
  11 one exception) to RFC 4122.  The exception lies in the multicast
  12 bit
  13
  14 Features:
  15
  16 UUID generation functions for version 1, 3, 4, and 5 UUIDS.
  17
  18 RFC 4122 compliance, with the exception of the multicast bit
  19 for randomly generated mac addresses.  This module sets the correct
  20 bit (the most significant bit), rather than the one specified in the RFC
  21 (the least significant one).
  22
  23 No external library dependency (other than the standard C library).
  24 The uuid generation has been written from scratch and is included
  25 with the source.
  26
  27 The entire package is in the public domain, so there are no licensing
  28 issues.
  29
  30 Compiles with the usual postgres addon infrastructure.
  31 make
  32 make install
  33 psql -f uuid.sql
  34 psql -f uninstall-uuid.sql
  35
  36 A pure postgres implementation is also supplied of just the generation
  37 functions in purepguuid.sql.
  38
  39 Generation Functions:
  40
  41 uuid_v1()
  42 returns a version 1 uuid.  if the mac address can't be determined,
  43 uses a random one.
  44
  45 uuid_v1mc()
  46 returns a version 1 uuid using a random mac address
  47
  48 uuid_v3(uuid, text)
  49 returns a version 3 uuid using the supplied namespace uuid and the
  50 given input string.  This is an md5 based uuid.
  51
  52 uuid_v4()
  53 returns a version 4 uuid.  This is a random uuid.  The odds of collision
  54 are vanishingly low and it is safe to use for regular production uuid
  55 generation.
  56
  57 uuid_v3(uuid, text)
  58 returns a version 5 uuid using the supplied namespace uuid and the
  59 given input string.  This is an sha1 based uuid.
  60
  61 uuid_url(text)
  62 Returns a version 5 uuid using the URL namespace.
  63
  64 uuid_dns(text)
  65 Returns a version 5 uuid using the DNS namespace.
  66
  67 uuid_oid(text)
  68 Returns a version 5 uuid using the DNS namespace.
  69
  70 uuid_x500(text)
  71 Returns a version 5 uuid using the DNS namespace.
  72
  73 UUID Lookup Functions:
  74
  75 uuid_recent()
  76 returns the most recent uuid generated by this backend.  Returns
  77 the nil uuid if no uuids have been generated yet.
  78
  79 uuid_nil()
  80 Returns the nil uuid (all bits zero).
  81
  82 uuid_ns_dns()
  83 Returns the DNS namespace uuid.
  84 6ba7b810-9dad-11d1-80b4-00c04fd430c8
  85
  86 uuid_ns_url()
  87 Returns the URL namespace uuid.
  88 6ba7b811-9dad-11d1-80b4-00c04fd430c8
  89
  90 uuid_ns_oid()
  91 Returns the OID namespace uuid.
  92 6ba7b812-9dad-11d1-80b4-00c04fd430c8
  93
  94 uuid_ns_x500()
  95 Returns the X500 namespace uuid.
  96 6ba7b813-9dad-11d1-80b4-00c04fd430c8
  97
  98 Casting Support:
  99
 100 Cast functions and casts are created for uuids to and from data types
 101 where this is reasonable:
 102
 103 Bytea: treats the UUID as an array of bytes.  This is always in
 104 network byte order for the subfields of a uuid, where applicable.
 105
 106 Numeric: treats the UUID as a 128 bit number and converts it to a numeric.
 107
 108 Bit(128) and bit varying: treats the uuid as a 128 bit vector.
 109
 110 Field extraction functions:
 111
 112 uuid_version(uuid)
 113 Returns an integer corresponding to the 4 bit version number.
 114
 115 uuid_macaddr(uuid)
 116 Returns a macaddr type corresponding to the mac address part of the
 117 uuid.  This function can be called on any uuid, not just version 1 uuids.
 118
 119 uuid_timestamp(uuid)
 120 Returns a timestamp corresponding to the timestamp field in the uuid.  You
 121 probably want to use uuid_timestamptz().
 122
 123 uuid_timestamptz(uuid)
 124 Returns a timestamp with time zonecorresponding to the timestamp field in the
 125 uuid.