source: server/databases/db.xml@ 8d288fe8

<?xml version="1.0" encoding="ISO-8859-1"?>
<!DOCTYPE sect1 PUBLIC "-//OASIS//DTD DocBook XML V4.4//EN"
   "http://www.oasis-open.org/docbook/xml/4.4/docbookx.dtd" [
  <!ENTITY % general-entities SYSTEM "../../general.ent">
  %general-entities;

  <!ENTITY db-download-http " ">
  <!ENTITY db-download-ftp  "ftp://sleepycat1.inetu.net/releases/db-&db-version;.tar.gz">
  <!ENTITY db-md5sum        "e27759537db6054b31d8cb3e99ba6fbb">
  <!ENTITY db-size          "5.8 MB">
  <!ENTITY db-buildsize     "74 MB (additional 140 MB to run parallel standard testsuite)">
  <!ENTITY db-time          "1.0 SBU (additional 80 SBU to run parallel standard testsuite)">
]>

<sect1 id="db" xreflabel="Berkeley DB-&db-version;">
  <?dbhtml filename="db.html"?>

  <sect1info>
    <othername>$LastChangedBy$</othername>
    <date>$Date$</date>
  </sect1info>

  <title>Berkeley DB-&db-version;</title>

  <indexterm zone="db">
    <primary sortas="a-Berkeley-DB">Berkeley DB</primary>
  </indexterm>

  <sect2 role="package">
    <title>Introduction to Berkeley DB</title>

    <para>The <application>Berkeley DB</application> package contains programs
    and utilities used by many other applications for database related
    functions.</para>

    <bridgehead renderas="sect3">Package Information</bridgehead>
    <itemizedlist spacing="compact">
      <listitem>
        <para>Download (HTTP): <ulink url="&db-download-http;"/></para>
      </listitem>
      <listitem>
        <para>Download (FTP): <ulink url="&db-download-ftp;"/></para>
      </listitem>
      <listitem>
        <para>Download MD5 sum: &db-md5sum;</para>
      </listitem>
      <listitem>
        <para>Download size: &db-size;</para>
      </listitem>
      <listitem>
        <para>Estimated disk space required: &db-buildsize;</para>
      </listitem>
      <listitem>
        <para>Estimated build time: &db-time;</para>
      </listitem>
    </itemizedlist>

    <bridgehead renderas="sect3">Berkeley DB Dependencies</bridgehead>

    <bridgehead renderas="sect4">Optional</bridgehead>
    <para><xref linkend="tcl"/> and <xref linkend="jdk"/></para>

  </sect2>

  <sect2 role="testing">
    <title>Testing Berkeley DB</title>

    <para>It is recommended you skip ahead to Installation.  The test-suite
    takes more than 80 SBU and has a few bugs causing reports of 'Regression
    Tests Failed'. You must have <application>Tcl</application> to test 
    <application>Berkeley DB</application>.</para>

    <para>Build for the <application>Berkeley DB</application> test by running
    the following commands:</para>

<screen><userinput>cd build_unix &amp;&amp;
../dist/configure --prefix=/usr \
    --enable-test --enable-tcl --with-tcl=/usr/lib &amp;&amp;
make LIBSO_LIBS="-lpthread" LIBXSO_LIBS="-lpthread" &amp;&amp;
chmod 644 ../test/sijointest.tcl &amp;&amp; 
sed -i 's:puts "[s,S].*::' \
    ../test/sijointest.tcl</userinput></screen>

    <para>To test the results, start <command>tclsh</command>:</para>
    
<screen><userinput>tclsh</userinput></screen>

    <para>From the tclsh prompt (%), run:</para>

<screen><userinput>source ../test/test.tcl
run_parallel 4 run_std
exit</userinput></screen>

    <para>Clean up with the following command:</para>

<screen><userinput>make realclean &amp;&amp;
cd ..</userinput></screen>

  </sect2>

  <sect2 role="installation">
    <title>Installation of Berkeley DB</title>

    <para>Install <application>Berkeley DB</application> by running the
    following commands:</para>

<screen><userinput>cd build_unix &amp;&amp;
../dist/configure --prefix=/usr \
    --enable-compat185 \
    --enable-cxx &amp;&amp;
make LIBSO_LIBS="-lpthread" LIBXSO_LIBS="-lpthread"</userinput></screen>

    <para>Now, as the <systemitem class="username">root</systemitem> user:</para>

<screen role="root"><userinput>make docdir=/usr/share/doc/db-&db-version; install &amp;&amp;
chown root:root /usr/bin/db_* \
/usr/lib/libdb* /usr/include/db* &amp;&amp;
chown -R root:root /usr/share/doc/db-&db-version;</userinput></screen>

  </sect2>

  <sect2 role="commands">
    <title>Command Explanations</title>

    <para><command>cd build_unix &amp;&amp;
    ../dist/configure --prefix=/usr...</command>:
    This replaces the normal <command>./configure</command> command, as
    <application>Berkeley DB</application> comes with various
    build directories for different platforms.</para>

    <para><parameter>--enable-compat185</parameter>: This switch enables
    building DB 1.85 compatibility API.</para>

    <para><parameter>--enable-cxx</parameter>: This switch enables building
    C++ API libraries.</para>

    <para><parameter>--enable-test</parameter>: Enables building the test suite
    (requires the two Tcl switches below).</para>

    <para><parameter>--enable-tcl --with-tcl=/usr/lib</parameter>:
    Enables <application>Tcl</application> support in DB and creates the
    <filename class="libraryfile">libdb_tcl</filename> libraries.</para>

    <para><parameter>--enable-java</parameter>: Enables
    <application>Java</application> support in DB and creates the
    <filename class='libraryfile'>libdb_java</filename> libraries.</para>

    <para><parameter>--enable-rpc</parameter>: Enables building the
    <application>Berkeley DB</application> RPC server.</para>

    <para><command>make LIBSO_LIBS="-lpthread"
    LIBXSO_LIBS="-lpthread"</command>: <command>configure</command>
    does not correctly handle NPTL. These variables force it to
    properly link against NPTL.</para>

    <para><command>make docdir=/usr/share/doc/db-&db-version;
    install</command>: This installs the documentation in
    the correct place.</para>

    <para><command>sed -i 's:puts "[s,S].*::' ../test/sijointest.tcl</command>:
    This prevents logging two notes that are not recognized by
    <command>run_std</command>.</para>

  </sect2>

  <sect2 role="content">
    <title>Contents</title>

    <segmentedlist>
      <segtitle>Installed Programs</segtitle>
      <segtitle>Installed Libraries</segtitle>
      <segtitle>Installed Directory</segtitle>

      <seglistitem>
        <seg>db_archive, db_checkpoint, db_deadlock, db_dump, db_load,
        db_printlog, db_recover, db_stat, db_upgrade, db_verify and
        berkeley_db_svc if enabled</seg>
        <seg>libdb.[so,a], libdb_cxx.[so,a], libdb_java.[so,a] and
        libdb_tcl.[so,a]</seg>
        <seg>/usr/share/doc/db-&db-version;</seg>
      </seglistitem>
    </segmentedlist>

    <variablelist>
      <bridgehead renderas="sect3">Short Descriptions</bridgehead>
      <?dbfo list-presentation="list"?>
      <?dbhtml list-presentation="table"?>

      <varlistentry id="berkeley_db_svc">
        <term><command>berkeley_db_svc</command></term>
        <listitem>
          <para>is the <application>Berkeley DB</application>
          RPC server.</para>
          <indexterm zone="db berkeley_db_svc">
            <primary sortas="b-berkeley_db_svc">berkeley_db_svc</primary>
          </indexterm>
        </listitem>
      </varlistentry>

      <varlistentry id="db_archive">
        <term><command>db_archive</command></term>
        <listitem>
          <para>prints the pathnames of log files that are no longer in
          use.</para>
          <indexterm zone="db db_archive">
            <primary sortas="b-db_archive">db_archive</primary>
          </indexterm>
        </listitem>
      </varlistentry>

      <varlistentry id="db_checkpoint">
        <term><command>db_checkpoint</command></term>
        <listitem>
          <para>is a daemon process used to monitor and checkpoint database
          logs.</para>
          <indexterm zone="db db_checkpoint">
            <primary sortas="b-db_checkpoint">db_checkpoint</primary>
          </indexterm>
        </listitem>
      </varlistentry>

      <varlistentry id="db_deadlock">
        <term><command>db_deadlock</command></term>
        <listitem>
          <para>is used to abort lock requests when deadlocks are
          detected.</para>
          <indexterm zone="db db_deadlock">
            <primary sortas="b-db_deadlock">db_deadlock</primary>
          </indexterm>
        </listitem>
      </varlistentry>

      <varlistentry id="db_dump">
        <term><command>db_dump</command></term>
        <listitem>
          <para>converts database files to a flat file format readable by
          <command>db_load</command>.</para>
          <indexterm zone="db db_dump">
            <primary sortas="b-db_dump">db_dump</primary>
          </indexterm>
        </listitem>
      </varlistentry>

      <varlistentry id="db_load">
        <term><command>db_load</command></term>
        <listitem>
          <para>is used to create database files from flat files created with
          <command>db_dump</command>.</para>
          <indexterm zone="db db_load">
            <primary sortas="b-db_load">db_load</primary>
          </indexterm>
        </listitem>
      </varlistentry>

      <varlistentry id="db_printlog">
        <term><command>db_printlog</command></term>
        <listitem>
          <para>converts database log files to human readable text.</para>
          <indexterm zone="db db_printlog">
            <primary sortas="b-db_printlog">db_printlog</primary>
          </indexterm>
        </listitem>
      </varlistentry>

      <varlistentry id="db_recover">
        <term><command>db_recover</command></term>
        <listitem>
          <para>is used to restore a database to a consistent state after a
          failure.</para>
          <indexterm zone="db db_recover">
            <primary sortas="b-db_recover">db_recover</primary>
          </indexterm>
        </listitem>
      </varlistentry>

      <varlistentry id="db_stat">
        <term><command>db_stat</command></term>
        <listitem>
          <para>displays database environment statistics.</para>
          <indexterm zone="db db_stat">
            <primary sortas="b-db_stat">db_stat</primary>
          </indexterm>
        </listitem>
      </varlistentry>

      <varlistentry id="db_upgrade">
        <term><command>db_upgrade</command></term>
        <listitem>
          <para>is used to upgrade database files to a newer version of
          <application>Berkeley DB</application>.</para>
          <indexterm zone="db db_upgrade">
            <primary sortas="b-db_upgrade">db_upgrade</primary>
          </indexterm>
        </listitem>
      </varlistentry>

      <varlistentry id="db_verify">
        <term><command>db_verify</command></term>
        <listitem>
          <para>is used to run consistency checks on database files.</para>
          <indexterm zone="db db_verify">
            <primary sortas="b-db_verify">db_verify</primary>
          </indexterm>
        </listitem>
      </varlistentry>

    </variablelist>

  </sect2>

</sect1>