source: server/databases/db.xml@ a647555

<?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 "&sources-anduin-http;/bdb/db-&db-version;.tar.gz">
  <!ENTITY db-download-ftp  " ">
  <!ENTITY db-md5sum        "b99454564d5b4479750567031d66fe24">
  <!ENTITY db-size          "34 MB">
  <!ENTITY db-buildsize     "265 MB">
  <!ENTITY db-time          "0.6 SBU">
]>

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


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

    &lfs113_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"/> and -->
      <xref linkend="libnsl"/> and
      <xref linkend="sharutils"/> (for the <command>uudecode</command> command)

      <!--,
      <xref linkend="openjdk"/> or <xref linkend="java"/>, and
- -          This is currently broken, removed for now.                - -
      <xref linkend="sharutils"/> (for the <command>uudecode</command> command
      - Java bindings are required) -->
    </para>

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

  <!-- <sect2 role="testing">
    <title>Testing Berkeley DB before the real install</title>

    <para>
      If you can't wait 12 hours or so you may want to skip ahead to
      <xref linkend="bdb-installation"/>. The test suite can take a long time
      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 -&#45;prefix=/usr       \
                  -&#45;enable-test       \
                  -&#45;enable-tcl        \
                  -&#45;enable-dbm        \
                  -&#45;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>

    <para>
      First apply a fix so that this will compile with current versions of
      <command>g++</command>:
    </para>

<screen><userinput>sed -i 's/\(__atomic_compare_exchange\)/\1_db/' src/dbinc/atomic.h</userinput></screen>

  <!-- move parts of hte testing to here, possibly as sect3 -->

    <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       \
                  --disable-static   \
                  --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,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-dbm</parameter>: Enables legacy interface support
      needed by some older packages.
    </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>

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

    <para>
      <option>--enable-java</option>: Enables <application>Java</application>
      support in DB and creates the
      <filename class="libraryfile">libdb_java</filename> libraries.
<!--
checking if java works... yes
checking for javac... /opt/jdk/bin/javac
checking absolute path of javac... /opt/jdk/bin/javac
checking java version... 10.0.1
configure: error: Java version 1.3 or higher required, got 10.0.1
-->
      Support is currently broken with Java-&openjdk-build;.x.
    </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_hotbackup,
          db_load,
          db_log_verify,
          db_printlog,
          db_recover,
          db_replicate,
          db_stat,
          db_tuner,
          db_upgrade, and
          db_verify
        </seg>
        <seg>
          libdb.so,
          libdb_cxx.so, and
<!--      libdb_java.so, and -->
          libdb_tcl.so
        </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_hotbackup">
        <term><command>db_hotbackup</command></term>
        <listitem>
          <para>
            creates "hot backup" or "hot failover" snapshots of Berkeley DB
            databases
          </para>
          <indexterm zone="db db_hotbackup">
            <primary sortas="b-db_hotbackup">db_hotbackup</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_log_verify">
        <term><command>db_log_verify</command></term>
        <listitem>
          <para>
            verifies the log files of a database
          </para>
          <indexterm zone="db db_log_verify">
            <primary sortas="b-db_log_verify">db_log_verify</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_replicate">
        <term><command>db_replicate</command></term>
        <listitem>
          <para>
            is a daemon process that provides replication/HA services on a
            transactional environment
          </para>
          <indexterm zone="db db_replicate">
            <primary sortas="b-db_replicate">db_replicate</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_tuner">
        <term><command>db_tuner</command></term>
        <listitem>
          <para>
            analyzes the data in a btree database, and suggests a page size that
            is likely to deliver optimal operation
          </para>
          <indexterm zone="db db_tuner">
            <primary sortas="b-db_tuner">db_tuner</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>