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 originally 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 (see below for details).
  12
  13 Features:
  14
  15 UUID generation functions for version 1, 3, 4, and 5 uuids.
  16
  17 RFC 4122 compliance, with the exception of the multicast bit
  18 for randomly generated mac addresses.  This module sets the correct
  19 bit (the most significant bit), rather than the one specified in the RFC
  20 (the least significant one).
  21
  22 No external library dependency (other than the standard C library).
  23 The uuid generation has been written from scratch and is included
  24 with the source.
  25
  26 The entire package is in the public domain, so there are no licensing
  27 issues.
  28
  29 Compiles with the usual postgres addon infrastructure.
  30 make
  31 make install
  32
  33 The 'make install' step will need sufficient privileges to write
  34 to the Postgres extension directory, so 'sudo make install'
  35 might be needed.
  36
  37 Installation can be done via the usual Postgres extension mechanism.
  38 create extension pduuid;
  39
  40 The extension is re-locatable, so you can specify a schema if you
  41 like.
  42
  43 Installation can be done manually with:
  44
  45 psql -f uuid.sql
  46 psql -f uninstall-uuid.sql
  47
  48 A pure postgres implementation is also supplied of just the generation
  49 functions in purepguuid.sql, though this is very inefficient, feature
  50 incomplete, and untested.  It's there if you need it though.
  51
  52 Generation Functions:
  53
  54 uuid_v1()
  55 returns a version 1 uuid.  if the mac address can't be determined,
  56 uses a random one.
  57
  58 uuid_v1mc()
  59 returns a version 1 uuid using a random mac address
  60
  61 uuid_v3(uuid, text)
  62 returns a version 3 uuid using the supplied namespace uuid and the
  63 given input string.  This is an md5 based uuid.
  64
  65 uuid_v4()
  66 returns a version 4 uuid.  This is a random uuid.  The odds of collision
  67 are vanishingly low and it is safe to use for regular production uuid
  68 generation.
  69
  70 uuid_v5(uuid, text)
  71 returns a version 5 uuid using the supplied namespace uuid and the
  72 given input string.  This is an sha1 based uuid.
  73
  74 uuid_url(text)
  75 Returns a version 5 uuid using the URL namespace.
  76
  77 uuid_dns(text)
  78 Returns a version 5 uuid using the DNS namespace.
  79
  80 uuid_oid(text)
  81 Returns a version 5 uuid using the DNS namespace.
  82
  83 uuid_x500(text)
  84 Returns a version 5 uuid using the DNS namespace.
  85
  86 UUID Lookup Functions:
  87
  88 uuid_recent()
  89 returns the most recent uuid generated by this backend.  Returns
  90 the nil uuid if no uuids have been generated yet.
  91
  92 uuid_nil()
  93 Returns the nil uuid (all bits zero).
  94
  95 uuid_ns_dns()
  96 Returns the DNS namespace uuid.
  97 6ba7b810-9dad-11d1-80b4-00c04fd430c8
  98
  99 uuid_ns_url()
 100 Returns the URL namespace uuid.
 101 6ba7b811-9dad-11d1-80b4-00c04fd430c8
 102
 103 uuid_ns_oid()
 104 Returns the OID namespace uuid.
 105 6ba7b812-9dad-11d1-80b4-00c04fd430c8
 106
 107 uuid_ns_x500()
 108 Returns the X500 namespace uuid.
 109 6ba7b813-9dad-11d1-80b4-00c04fd430c8
 110
 111 Casting Support:
 112
 113 Cast functions and casts are created for uuids to and from data types
 114 where this is reasonable:
 115
 116 Bytea: treats the UUID as an array of bytes.  This is always in
 117 network byte order for the subfields of a uuid, where applicable.
 118
 119 Numeric: treats the UUID as a 128 bit number and converts it to a numeric.
 120
 121 Bit(128) and bit varying: treats the uuid as a 128 bit vector.
 122 Casts to bit(n) where n is shorter than 128 will truncate
 123 the uuid.  Where n is longer than 128, the bit vector
 124 will be zero extended.
 125
 126 Field extraction functions:
 127
 128 uuid_version(uuid)
 129 Returns an integer corresponding to the 4 bit version number.
 130
 131 uuid_macaddr(uuid)
 132 Returns a macaddr type corresponding to the mac address part of the
 133 uuid.  This function can be called on any uuid, not just version 1 uuids.
 134
 135 uuid_timestamp(uuid)
 136 Returns a timestamp corresponding to the timestamp field in the uuid.  You
 137 probably want to use uuid_timestamptz().
 138
 139 uuid_timestamptz(uuid)
 140 Returns a timestamp with time zonecorresponding to the timestamp field in the
 141 uuid.