source: server/databases/db.xml@ 4c77a949

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

  <!ENTITY db-download-http "http://download-east.oracle.com/berkeley-db/db-&db-version;.tar.gz">
  <!ENTITY db-download-ftp  "&gentoo-ftp-repo;/db-&db-version;.tar.gz">
  <!ENTITY db-md5sum        "88466dd6c13d5d8cddb406be8a1d4d92">
  <!ENTITY db-size          "33 MB">
  <!ENTITY db-buildsize     "181 MB (additional 100 MB to run parallel standard test suite)">
  <!ENTITY db-time          "1.4 SBU (builds all bindings, add an additional 145 SBU to run parallel standard test suite)">
]>

<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>

    &lfs71_checked;

    <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 role="optional">
      <xref linkend="tcl"/>,
      <xref linkend="icedtea6"/> or <xref linkend="jdk"/>, and
      <xref linkend='sharutils'/> (for the <command>uudecode</command> command)
    </para>

    <para condition="html" role="usernotes">User Notes:
    <ulink url="&blfs-wiki;/db"/></para>

  </sect2>

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

    <para>You may want to skip ahead to <xref linkend="bdb-installation"/>. The
    test suite can take up to 150 SBUs and has a few bugs causing a report of
    <quote>Regression tests failed</quote>. However, running the test suite is
    a very exhaustive test of your hardware, perhaps pushing your machine
    harder (especially disk I/O) than it will ever see during production use.
    Note that you must have <application>Tcl</application> installed to run the
    test suite.</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  \
                  --enable-dbm  \
                  --with-tcl=/usr/lib &amp;&amp;
make</userinput></screen>

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

<screen><userinput>tclsh</userinput></screen>

    <para>From the <command>tclsh</command> prompt (<prompt>%&nbsp;</prompt>),
    run:</para>

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

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

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

    <note><para>Test127.f and Repmgr026.c are known to fail.</para></note>

    <para>There are additional testing suites in the <filename
    class='directory'>test/c</filename> and <filename
    class='directory'>test/cxx</filename> directories.  See the
    <filename>README</filename> in each directory for instructions on how to
    run the tests.</para>

  </sect2>

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

    <note>
      <para>If you plan on installing <application>Berkeley DB</application>
      with Java support, you should check the system for certain versions
      of <xref linkend="jdk"/> and <xref linkend="gmime"/>. Specifically, if
      <application>JDK</application>-6 Update X and the
      <command>uudecode</command> program from the
      <application>GMime</application> program is on the system, the build will
      fail (unless you run the modified <command>./configure</command> command
      shown below). You can run two commands (<command>javac -version</command>
      and <command>uudecode --version</command>) to determine what versions are
      installed. You can also download and run a shell script from
      <ulink url="&files-anduin;/jdk-uudecode-check.sh"/> that will alert
      you to a non-working condition. If the identified programs exist on the
      system, you must modify the
      <command>./configure</command> command as shown below.</para>

<screen><userinput>uudecode="no" ../dist/configure --(use the parameters shown below)</userinput></screen>
    </note>

    <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-dbm  \
                  --enable-cxx &amp;&amp;
make</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 -v -R root:root \
      /usr/bin/db_* \
      /usr/include/db{,_185,_cxx}.h \
      /usr/lib/libdb*.{so,a,la} \
      /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 the DB-1.85 compatibility API.</para>

    <para><parameter>--enable-cxx</parameter>: This switch enables building
    C++ API libraries.</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-dbm</parameter>: Enables legacy interface support
    support needed by some older packages.</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><command>make docdir=/usr/share/doc/db-&db-version;
    install</command>: This installs the documentation in
    the standard location instead of
    <filename class='directory'>/usr/docs</filename>.</para>

    <para><command>chown -v -R root:root ...</command>:This command changes
    the ownership of various installed files from the uid:gid of the
    builder to root:root.</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</seg>
        <seg>libdb.{so,a}, libdb_cxx.{so,a}, libdb_java.{so,a},
        libdb_tcl.{so,a} and db.jar</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="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>