Doc/lib/libbsddb.tex

   1 \section{\module{bsddb} ---
   2          Interface to Berkeley DB library}
   3
   4 \declaremodule{extension}{bsddb}
   5   \platform{Unix, Windows}
   6 \modulesynopsis{Interface to Berkeley DB database library}
   7 \sectionauthor{Skip Montanaro}{skip@mojam.com}
   8
   9
  10 The \module{bsddb} module provides an interface to the Berkeley DB library.
  11 Users can create hash, btree or record based library files using the
  12 appropriate open call. Bsddb objects behave generally like dictionaries.
  13 Keys and values must be strings, however, so to use other objects as keys or
  14 to store other kinds of objects the user must serialize them somehow,
  15 typically using marshal.dumps or pickle.dumps.
  16
  17 The \module{bsddb} module is only available on \UNIX{} systems, so it is not
  18 built by default in the standard Python distribution.  Also, there are two
  19 incompatible versions of the underlying library.  Version 1.85 is widely
  20 available, but has some known bugs.  Version 2 is not quite as widely used,
  21 but does offer some improvements.  The \module{bsddb} module uses the 1.85
  22 interface.  Users wishing to use version 2 of the Berkeley DB library will
  23 have to modify the source for the module to include db_185.h instead of
  24 db.h.
  25
  26 The \module{bsddb} module defines the following functions that create
  27 objects that access the appropriate type of Berkeley DB file.  The first two
  28 arguments of each function are the same.  For ease of portability, only the
  29 first two arguments should be used in most instances.
  30
  31 \begin{funcdesc}{hashopen}{filename\optional{, flag\optional{,
  32 mode\optional{, bsize\optional{, ffactor\optional{, nelem\optional{,
  33 cachesize\optional{, hash\optional{, lorder}}}}}}}}}
  34 Open the hash format file named \var{filename}.  The optional \var{flag}
  35 identifies the mode used to open the file.  It may be ``r'' (read only),
  36 ``w'' (read-write), ``c'' (read-write - create if necessary) or ``n''
  37 (read-write - truncate to zero length).  The other arguments are rarely used
  38 and are just passed to the low-level dbopen function.  Consult the
  39 Berkeley DB documentation for their use and interpretation.
  40 \end{funcdesc}
  41
  42
  43 \begin{funcdesc}{btopen}{filename\optional{, flag\optional{,
  44 mode\optional{, btflags\optional{, cachesize\optional{, maxkeypage\optional{,
  45 minkeypage\optional{, psize\optional{, lorder}}}}}}}}}
  46 Open the btree format file named \var{filename}.  The optional \var{flag}
  47 identifies the mode used to open the file.  It may be ``r'' (read only),
  48 ``w'' (read-write), ``c'' (read-write - create if necessary) or ``n''
  49 (read-write - truncate to zero length).  The other arguments are rarely used
  50 and are just passed to the low-level dbopen function.  Consult the
  51 Berkeley DB documentation for their use and interpretation.
  52 \end{funcdesc}
  53
  54 \begin{funcdesc}{rnopen}{filename\optional{, flag\optional{, mode\optional{,
  55 rnflags\optional{, cachesize\optional{, psize\optional{, lorder\optional{,
  56 reclen\optional{, bval\optional{, bfname}}}}}}}}}}
  57 Open a DB record format file named \var{filename}.  The optional \var{flag}
  58 identifies the mode used to open the file.  It may be ``r'' (read only),
  59 ``w'' (read-write), ``c'' (read-write - create if necessary) or ``n''
  60 (read-write - truncate to zero length).  The other arguments are rarely used
  61 and are just passed to the low-level dbopen function.  Consult the
  62 Berkeley DB documentation for their use and interpretation.
  63 \end{funcdesc}
  64
  65
  66 \begin{seealso}
  67   \seemodule{dbhash}{DBM-style interface to the \module{bsddb}}
  68 \end{seealso}
  69
  70
  71 \subsection{Hash, BTree and Record Objects \label{bsddb-objects}}
  72
  73 Once instantiated, hash, btree and record objects support the following
  74 methods:
  75
  76 \begin{methoddesc}{close}{}
  77 Close the underlying file.  The object can no longer be accessed.  Since
  78 there is no open \method{open} method for these objects, to open the file
  79 again a new \module{bsddb} module open function must be called.
  80 \end{methoddesc}
  81
  82 \begin{methoddesc}{keys}{}
  83 Return the list of keys contained in the DB file.  The order of the list is
  84 unspecified and should not be relied on.  In particular, the order of the
  85 list returned is different for different file formats.
  86 \end{methoddesc}
  87
  88 \begin{methoddesc}{has_key}{key}
  89 Return 1 if the DB file contains the argument as a key.
  90 \end{methoddesc}
  91
  92 \begin{methoddesc}{set_location}{key}
  93 Set the cursor to the item indicated by the key and return it.
  94 \end{methoddesc}
  95
  96 \begin{methoddesc}{first}{}
  97 Set the cursor to the first item in the DB file and return it.  The order of
  98 keys in the file is unspecified, except in the case of B-Tree databases.
  99 \end{methoddesc}
 100
 101 \begin{methoddesc}{next}{}
 102 Set the cursor to the next item in the DB file and return it.  The order of
 103 keys in the file is unspecified, except in the case of B-Tree databases.
 104 \end{methoddesc}
 105
 106 \begin{methoddesc}{previous}{}
 107 Set the cursor to the first item in the DB file and return it.  The
 108 order of keys in the file is unspecified, except in the case of B-Tree
 109 databases.  This is not supported on hashtable databases (those opened
 110 with \function{hashopen()}).
 111 \end{methoddesc}
 112
 113 \begin{methoddesc}{last}{}
 114 Set the cursor to the last item in the DB file and return it.  The
 115 order of keys in the file is unspecified.  This is not supported on
 116 hashtable databases (those opened with \function{hashopen()}).
 117 \end{methoddesc}
 118
 119 \begin{methoddesc}{sync}{}
 120 Synchronize the database on disk.
 121 \end{methoddesc}
 122
 123 Example:
 124
 125 \begin{verbatim}
 126 >>> import bsddb
 127 >>> db = bsddb.btopen('/tmp/spam.db', 'c')
 128 >>> for i in range(10): db['%d'%i] = '%d'% (i*i)
 129 ...
 130 >>> db['3']
 131 '9'
 132 >>> db.keys()
 133 ['0', '1', '2', '3', '4', '5', '6', '7', '8', '9']
 134 >>> db.first()
 135 ('0', '0')
 136 >>> db.next()
 137 ('1', '1')
 138 >>> db.last()
 139 ('9', '81')
 140 >>> db.set_location('2')
 141 ('2', '4')
 142 >>> db.previous()
 143 ('1', '1')
 144 >>> db.sync()
 145 0
 146 \end{verbatim}