citadel/docs/citadel-with-berkeley-db.txt

   1
   2                Using Citadel/UX with Sleepycat (Berkeley) DB
   3
   4 Abstract
   5
   6    [1]Citadel/UX can now use the robust and scalable [2]Berkeley DB from
   7    Sleepycat Software as its data store, for increased scalability,
   8    reliability, and recoverability.
   9
  10 History and introduction
  11
  12    From its inception in 1987 until versions 5.1x in 1988,
  13    Citadel/UX utilized a built-in data store loosely modelled after Jeff
  14    Prothero's original Citadel-CP/M design.  But as Citadel systems
  15    scaled upwards, supporting Internet-connected systems with heavy
  16    concurrent use, and aspirations of becoming a world-class
  17    messaging/groupware platform someday, the developers made the decision
  18    to switch to an embedded database.  The Free Software Foundation's
  19    [3]GDBM product was chosen for its simple API and its free license
  20    (the LGPL).
  21
  22    Somewhat less than trouble-free operation from 1988 through 2000,
  23    however, proved that GDBM was not the best choice.  Heavily utilized
  24    systems experienced occasional database corruption, often resulting in
  25    repeated crashes of the Citadel server.  As a result, we made the
  26    decision to switch to [4]Berkeley DB.
  27
  28    Berkeley DB offers [5]numerous features which help Citadel/UX to meet
  29    its goals as a high-end messaging platform:
  30      * Database sizes can scale to hundreds of terabytes
  31      * A transaction-based logging system
  32      * Recovery utilities
  33
  34    It is clear that Berkeley DB is a better choice than GDBM for a
  35    high-utilization database that requires crash recovery.  Beginning on
  36    December 7, 2000, Citadel/UX supports the use of either GDBM or DB as
  37    the data store.  At some point in the future, DB will become the
  38    default.  If you are setting up a potentially busy system, we
  39    recommend that you use DB.
  40
  41
  42 Building Citadel/UX with DB support
  43
  44    Here are the steps required to get Citadel/UX running with Berkeley
  45    DB as its back end data store.
  46
  47     1. First, you must download and build Berkeley DB itself.  Citadel
  48        has been developed and tested with DB 3.1.17, which can be
  49        downloaded from [6]www.sleepycat.com.  Follow the "[7]Building for
  50        UNIX" instructions.  Make sure that you run the test suite, and
  51        perhaps test with some of the sample applications, before moving
  52        on.
  53     2. Start with a clean source tree.  Either unpack a fresh copy of the
  54        source or do a "make distclean" before continuing.
  55     3. Run the configure script:  ./configure
  56        --with-db=/usr/local/BerkeleyDB.3.1   (Specify whatever directory
  57        you've actually installed DB into, of course.  Also specify any
  58        other configure options you need at this time.)
  59     4. Run "make" and "make install-exec."  Continue installing Citadel
  60        as per the instructions supplied with the system.
  61
  62 Migrating an existing GDBM-based Citadel to a DB-based Citadel
  63
  64    If you have an existing system, you must export your databases,
  65    rebuild Citadel with DB support, and then re-import your databases
  66    into the new system.  Please refer to the document "[8]How to use the
  67    importer/exporter" for detailed instructions on this.
  68
  69    After you export your database, but before you re-import it, you must
  70    perform the following steps:
  71     1. Re-build Citadel with DB support, as described above
  72     2. Remove all of the *.gdbm files from your data directory.
  73
  74 Care and feeding of your DB-powered Citadel
  75
  76    Citadel uses the transaction-based logging facility of Berkeley DB.
  77    Therefore you will notice log files accumulating in your data
  78    directory.  These are required for automatic recovery in the event of
  79    a catastrophic system failure.  Log files have filenames that look
  80    like "log.0000000001" whereas the normal database files have names
  81    like "cdb.05".
  82
  83    So do you have to keep these log files around forever?  No, but there
  84    are some rules you should follow:
  85      * Don't remove a log file if it's the only log file there.
  86      * Don't remove any log file that has a recent timestamp.  Generally
  87        speaking, if it's more than a week old, and you've been running
  88        tape backups every day (you are doing daily backups, right?), you
  89        can safely remove the log file.
  90
  91    You may think that it's going to keep writing to that one log file
  92    forever, but don't panic; when the log file gets sufficiently large it
  93    will switch over to another one.  As a general rule of thumb, your
  94    archival procedure should be to back up to tape every day, and only
  95    delete log files that are older than your oldest backup.  Berkeley DB
  96    supports "hot" backups; in other words, you are permitted to back up
  97    your Citadel data without having to first shut down the Citadel
  98    server.
  99
 100 References
 101
 102    1. http://uncensored.citadel.org/citadel
 103    2. http://www.sleepycat.com/
 104    3. http://www.gnu.org/software/gdbm/gdbm.html
 105    4. http://www.sleepycat.com/
 106    5. http://www.sleepycat.com/xactfeatures.html
 107    6. http://www.sleepycat.com/
 108    7. http://www.sleepycat.com/docs/ref/build_unix/intro.html
 109    8. http://pixel.citadel.org/citadel/docs/export.html