mirror of
https://github.com/berkeleydb/libdb.git
synced 2024-11-17 01:26:25 +00:00
992 lines
42 KiB
HTML
992 lines
42 KiB
HTML
|
<?xml version="1.0" encoding="UTF-8" standalone="no"?>
|
|||
|
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
|
|||
|
<html xmlns="http://www.w3.org/1999/xhtml">
|
|||
|
<head>
|
|||
|
<meta http-equiv="Content-Type" content="text/html; charset=UTF-8" />
|
|||
|
<title>Chapter 2. Enabling Transactions</title>
|
|||
|
<link rel="stylesheet" href="gettingStarted.css" type="text/css" />
|
|||
|
<meta name="generator" content="DocBook XSL Stylesheets V1.73.2" />
|
|||
|
<link rel="start" href="index.html" title="Getting Started with Berkeley DB Transaction Processing" />
|
|||
|
<link rel="up" href="index.html" title="Getting Started with Berkeley DB Transaction Processing" />
|
|||
|
<link rel="prev" href="perftune-intro.html" title="Performance Tuning" />
|
|||
|
<link rel="next" href="envopen.html" title="Opening a Transactional Environment and Database" />
|
|||
|
</head>
|
|||
|
<body>
|
|||
|
<div xmlns="" class="navheader">
|
|||
|
<div class="libver">
|
|||
|
<p>Library Version 11.2.5.2</p>
|
|||
|
</div>
|
|||
|
<table width="100%" summary="Navigation header">
|
|||
|
<tr>
|
|||
|
<th colspan="3" align="center">Chapter 2. Enabling Transactions</th>
|
|||
|
</tr>
|
|||
|
<tr>
|
|||
|
<td width="20%" align="left"><a accesskey="p" href="perftune-intro.html">Prev</a> </td>
|
|||
|
<th width="60%" align="center"> </th>
|
|||
|
<td width="20%" align="right"> <a accesskey="n" href="envopen.html">Next</a></td>
|
|||
|
</tr>
|
|||
|
</table>
|
|||
|
<hr />
|
|||
|
</div>
|
|||
|
<div class="chapter" lang="en" xml:lang="en">
|
|||
|
<div class="titlepage">
|
|||
|
<div>
|
|||
|
<div>
|
|||
|
<h2 class="title"><a id="enabletxn"></a>Chapter 2. Enabling Transactions</h2>
|
|||
|
</div>
|
|||
|
</div>
|
|||
|
</div>
|
|||
|
<div class="toc">
|
|||
|
<p>
|
|||
|
<b>Table of Contents</b>
|
|||
|
</p>
|
|||
|
<dl>
|
|||
|
<dt>
|
|||
|
<span class="sect1">
|
|||
|
<a href="enabletxn.html#environments">Environments</a>
|
|||
|
</span>
|
|||
|
</dt>
|
|||
|
<dd>
|
|||
|
<dl>
|
|||
|
<dt>
|
|||
|
<span class="sect2">
|
|||
|
<a href="enabletxn.html#filenaming">File Naming</a>
|
|||
|
</span>
|
|||
|
</dt>
|
|||
|
<dt>
|
|||
|
<span class="sect2">
|
|||
|
<a href="enabletxn.html#errorsupport">Error Support</a>
|
|||
|
</span>
|
|||
|
</dt>
|
|||
|
<dt>
|
|||
|
<span class="sect2">
|
|||
|
<a href="enabletxn.html#sharedmemory">Shared Memory Regions</a>
|
|||
|
</span>
|
|||
|
</dt>
|
|||
|
<dt>
|
|||
|
<span class="sect2">
|
|||
|
<a href="enabletxn.html#security">Security Considerations</a>
|
|||
|
</span>
|
|||
|
</dt>
|
|||
|
</dl>
|
|||
|
</dd>
|
|||
|
<dt>
|
|||
|
<span class="sect1">
|
|||
|
<a href="envopen.html">Opening a Transactional Environment and
|
|||
|
<span>Database</span>
|
|||
|
|
|||
|
|
|||
|
</a>
|
|||
|
</span>
|
|||
|
</dt>
|
|||
|
</dl>
|
|||
|
</div>
|
|||
|
<p>
|
|||
|
In order to use transactions with your application, you must turn them
|
|||
|
on. To do this you must:
|
|||
|
</p>
|
|||
|
<div class="itemizedlist">
|
|||
|
<ul type="disc">
|
|||
|
<li>
|
|||
|
<p>
|
|||
|
Use an
|
|||
|
environment (see <a class="xref" href="enabletxn.html#environments" title="Environments">Environments</a> for details).
|
|||
|
</p>
|
|||
|
</li>
|
|||
|
<li>
|
|||
|
<p>
|
|||
|
Turn on transactions for your environment.
|
|||
|
|
|||
|
|
|||
|
|
|||
|
<span>
|
|||
|
You do this by providing the <code class="literal">DB_INIT_TXN</code>
|
|||
|
flag to the
|
|||
|
<code class="methodname">DbEnv::open()</code>
|
|||
|
|
|||
|
method.
|
|||
|
</span>
|
|||
|
|
|||
|
<span>
|
|||
|
Note that initializing the transactional subsystem implies that
|
|||
|
the logging subsystem is also initialized. Also, note that
|
|||
|
if you do not initialize transactions when you first create
|
|||
|
your environment, then you cannot use transactions for that
|
|||
|
environment after that. This is because DB
|
|||
|
allocates certain structures needed for transactional
|
|||
|
locking that are not available if the environment is
|
|||
|
created without transactional support.
|
|||
|
</span>
|
|||
|
</p>
|
|||
|
</li>
|
|||
|
<li>
|
|||
|
<p>
|
|||
|
Initialize the in-memory cache by
|
|||
|
<span>
|
|||
|
passing the <code class="literal">DB_INIT_MPOOL</code>
|
|||
|
flag to the
|
|||
|
<code class="methodname">DbEnv::open()</code>
|
|||
|
|
|||
|
method.
|
|||
|
</span>
|
|||
|
|
|||
|
|
|||
|
</p>
|
|||
|
</li>
|
|||
|
<li>
|
|||
|
<p>
|
|||
|
Initialize the locking subsystem. This is what provides locking for concurrent applications. It also is used
|
|||
|
to perform deadlock detection. See <a class="xref" href="txnconcurrency.html" title="Chapter 4. Concurrency">Concurrency</a>
|
|||
|
for more information.
|
|||
|
</p>
|
|||
|
<p>
|
|||
|
You initialize the locking subsystem by
|
|||
|
<span>
|
|||
|
passing the <code class="literal">DB_INIT_LOCK</code>
|
|||
|
flag to the
|
|||
|
<code class="methodname">DbEnv::open()</code>
|
|||
|
|
|||
|
method.
|
|||
|
</span>
|
|||
|
|
|||
|
|
|||
|
</p>
|
|||
|
</li>
|
|||
|
<li>
|
|||
|
<p>
|
|||
|
Initialize the logging subsystem. While this is enabled by
|
|||
|
default for transactional applications, we suggest that
|
|||
|
you explicitly initialize it anyway for the purposes of code readability. The logging
|
|||
|
subsystem is what provides your transactional application its durability guarantee, and it is required for
|
|||
|
recoverability purposes. See <a class="xref" href="filemanagement.html" title="Chapter 5. Managing DB Files">Managing DB Files</a>
|
|||
|
for more information.
|
|||
|
</p>
|
|||
|
<p>
|
|||
|
You initialize the logging subsystem by
|
|||
|
<span>
|
|||
|
passing the <code class="literal">DB_INIT_LOG</code>
|
|||
|
flag to the
|
|||
|
<code class="methodname">DbEnv::open()</code>
|
|||
|
|
|||
|
method.
|
|||
|
</span>
|
|||
|
|
|||
|
|
|||
|
</p>
|
|||
|
</li>
|
|||
|
<li>
|
|||
|
<p>
|
|||
|
<span>
|
|||
|
Transaction-enable your databases.
|
|||
|
</span>
|
|||
|
<span>
|
|||
|
If you are using the base API, transaction-enable your databases.
|
|||
|
</span>
|
|||
|
You do this by
|
|||
|
|
|||
|
|
|||
|
<span>
|
|||
|
encapsulating the database open in a transaction.
|
|||
|
</span>
|
|||
|
|
|||
|
|
|||
|
<span>
|
|||
|
Note that the common practice is for auto commit to be used to
|
|||
|
transaction-protect the database open. To use auto-commit, you
|
|||
|
must still enable transactions as described here, but you do
|
|||
|
not have to explicitly use a transaction when you open your
|
|||
|
database. An example of this is given in the next section.
|
|||
|
</span>
|
|||
|
</p>
|
|||
|
</li>
|
|||
|
</ul>
|
|||
|
</div>
|
|||
|
<div class="sect1" lang="en" xml:lang="en">
|
|||
|
<div class="titlepage">
|
|||
|
<div>
|
|||
|
<div>
|
|||
|
<h2 class="title" style="clear: both"><a id="environments"></a>Environments</h2>
|
|||
|
</div>
|
|||
|
</div>
|
|||
|
</div>
|
|||
|
<div class="toc">
|
|||
|
<dl>
|
|||
|
<dt>
|
|||
|
<span class="sect2">
|
|||
|
<a href="enabletxn.html#filenaming">File Naming</a>
|
|||
|
</span>
|
|||
|
</dt>
|
|||
|
<dt>
|
|||
|
<span class="sect2">
|
|||
|
<a href="enabletxn.html#errorsupport">Error Support</a>
|
|||
|
</span>
|
|||
|
</dt>
|
|||
|
<dt>
|
|||
|
<span class="sect2">
|
|||
|
<a href="enabletxn.html#sharedmemory">Shared Memory Regions</a>
|
|||
|
</span>
|
|||
|
</dt>
|
|||
|
<dt>
|
|||
|
<span class="sect2">
|
|||
|
<a href="enabletxn.html#security">Security Considerations</a>
|
|||
|
</span>
|
|||
|
</dt>
|
|||
|
</dl>
|
|||
|
</div>
|
|||
|
<p>
|
|||
|
For simple DB applications, environments are optional. However, in
|
|||
|
order to transaction protect your database operations, you must use an
|
|||
|
environment.
|
|||
|
</p>
|
|||
|
<p>
|
|||
|
An <span class="emphasis"><em>environment</em></span>, represents an
|
|||
|
encapsulation of one or more databases and any associated log and
|
|||
|
region files. They are used to support multi-threaded
|
|||
|
and multi-process applications by allowing different threads of
|
|||
|
control to share the in-memory cache, the locking tables, the
|
|||
|
logging subsystem, and the file namespace. By sharing these things,
|
|||
|
your concurrent application is more efficient than if each thread
|
|||
|
of control had to manage these resources on its own.
|
|||
|
</p>
|
|||
|
<p>
|
|||
|
By default all DB databases are backed by files on disk. In
|
|||
|
addition to these files, transactional DB applications create
|
|||
|
logs that are also by default stored on disk (they can optionally
|
|||
|
be backed using shared memory). Finally, transactional
|
|||
|
DB applications also create and use shared-memory regions that
|
|||
|
are also typically backed by the filesystem. But like databases and
|
|||
|
logs, the regions can be maintained strictly in-memory if your
|
|||
|
application requires it. For an example of an application that
|
|||
|
manages all environment files in-memory, see
|
|||
|
<span><a class="xref" href="inmem_txnexample_c.html" title="In-Memory Transaction Example">In-Memory Transaction Example</a>.</span>
|
|||
|
|
|||
|
|
|||
|
|
|||
|
</p>
|
|||
|
<div class="warning" style="margin-left: 0.5in; margin-right: 0.5in;">
|
|||
|
<h3 class="title">Warning</h3>
|
|||
|
<p>
|
|||
|
Using environments with some journaling filesystems might
|
|||
|
result in log file corruption. This can occur if the operating
|
|||
|
system experiences an unclean shutdown when a log file is being
|
|||
|
created. Please see
|
|||
|
<a href="../../programmer_reference/transapp_journal.html" class="olink">Using
|
|||
|
Recovery on Journaling Filesystems</a>
|
|||
|
in the <em class="citetitle">Berkeley DB Programmer's Reference Guide</em> for more information.
|
|||
|
</p>
|
|||
|
</div>
|
|||
|
<div class="sect2" lang="en" xml:lang="en">
|
|||
|
<div class="titlepage">
|
|||
|
<div>
|
|||
|
<div>
|
|||
|
<h3 class="title"><a id="filenaming"></a>File Naming</h3>
|
|||
|
</div>
|
|||
|
</div>
|
|||
|
</div>
|
|||
|
<p>
|
|||
|
In order to operate, your DB application must be able to
|
|||
|
locate its database files, log files, and region files. If these
|
|||
|
are stored in the filesystem, then you must tell DB where
|
|||
|
they are located (a number of mechanisms exist that allow you to
|
|||
|
identify the location of these files – see below). Otherwise,
|
|||
|
by default they are located in the current working directory.
|
|||
|
</p>
|
|||
|
<div class="sect3" lang="en" xml:lang="en">
|
|||
|
<div class="titlepage">
|
|||
|
<div>
|
|||
|
<div>
|
|||
|
<h4 class="title"><a id="envhome"></a>Specifying the Environment Home Directory</h4>
|
|||
|
</div>
|
|||
|
</div>
|
|||
|
</div>
|
|||
|
<p>
|
|||
|
The environment home directory is used to determine where
|
|||
|
DB files are located. Its location
|
|||
|
is identified using one of the following mechanisms, in the
|
|||
|
following order of priority:
|
|||
|
</p>
|
|||
|
<div class="itemizedlist">
|
|||
|
<ul type="disc">
|
|||
|
<li>
|
|||
|
<p>
|
|||
|
If no information is given as to where to put the
|
|||
|
environment home, then the current working
|
|||
|
directory is used.
|
|||
|
</p>
|
|||
|
</li>
|
|||
|
<li>
|
|||
|
<p>
|
|||
|
If a home directory is specified on the
|
|||
|
|
|||
|
<code class="methodname">DbEnv::open()</code>
|
|||
|
|
|||
|
<span>method,</span>
|
|||
|
|
|||
|
then that location is always used for the environment
|
|||
|
home.
|
|||
|
</p>
|
|||
|
</li>
|
|||
|
<li>
|
|||
|
<p>
|
|||
|
If a home directory is not supplied to
|
|||
|
|
|||
|
<span><code class="methodname">DbEnv::open()</code>, </span>
|
|||
|
|
|||
|
then the directory identified by the <code class="literal">DB_HOME</code> environment variable
|
|||
|
is used <span class="emphasis"><em>if</em></span> you specify
|
|||
|
<span>
|
|||
|
either the <code class="literal">DB_USE_ENVIRON</code> or
|
|||
|
<code class="literal">DB_USE_ENVIRON_ROOT</code> flags to the
|
|||
|
|
|||
|
<code class="methodname">DbEnv::open()</code>
|
|||
|
method. Both flags allow you to identify the
|
|||
|
path to the environment's home directory
|
|||
|
using the <code class="literal">DB_HOME</code> environment variable. However,
|
|||
|
<code class="literal">DB_USE_ENVIRON_ROOT</code> is honored only if the
|
|||
|
process is run with root or administrative privileges.
|
|||
|
</span>
|
|||
|
|
|||
|
|
|||
|
</p>
|
|||
|
</li>
|
|||
|
</ul>
|
|||
|
</div>
|
|||
|
</div>
|
|||
|
<div class="sect3" lang="en" xml:lang="en">
|
|||
|
<div class="titlepage">
|
|||
|
<div>
|
|||
|
<div>
|
|||
|
<h4 class="title"><a id="filelocation"></a>Specifying File Locations</h4>
|
|||
|
</div>
|
|||
|
</div>
|
|||
|
</div>
|
|||
|
<p>
|
|||
|
By default, all DB files are created relative to the environment
|
|||
|
home directory. For example, suppose your environment home is in
|
|||
|
<code class="literal">/export/myAppHome</code>. Also suppose you name your database
|
|||
|
<span><code class="literal">data/myDatabase.db</code>.</span>
|
|||
|
|
|||
|
Then in this case, the database is placed in:
|
|||
|
<span><code class="literal">/export/myAppHome/data/myDatabase.db</code>.</span>
|
|||
|
|
|||
|
</p>
|
|||
|
<p>
|
|||
|
That said, DB always defers to absolute pathnames.
|
|||
|
This means that if you provide an absolute filename when you
|
|||
|
name your database, then that file is <span class="emphasis"><em>not</em></span>
|
|||
|
placed relative to the environment home directory. Instead, it
|
|||
|
is placed in the exact location that you specified for the
|
|||
|
filename.
|
|||
|
</p>
|
|||
|
<p>
|
|||
|
On UNIX systems, an absolute pathname is a name that begins with a
|
|||
|
forward slash ('/'). On Windows systems, an absolute pathname is a
|
|||
|
name that begins with one of the following:
|
|||
|
</p>
|
|||
|
<div class="itemizedlist">
|
|||
|
<ul type="disc">
|
|||
|
<li>
|
|||
|
<p>
|
|||
|
A backslash ('\').
|
|||
|
</p>
|
|||
|
</li>
|
|||
|
<li>
|
|||
|
<p>
|
|||
|
Any alphabetic letter, followed by a colon (':'), followed
|
|||
|
by a backslash ('\').
|
|||
|
</p>
|
|||
|
</li>
|
|||
|
</ul>
|
|||
|
</div>
|
|||
|
<div class="note" style="margin-left: 0.5in; margin-right: 0.5in;">
|
|||
|
<h3 class="title">Note</h3>
|
|||
|
<p>
|
|||
|
Try not to use absolute path names for your environment's
|
|||
|
files. Under certain recovery scenarios, absolute path
|
|||
|
names can render your environment unrecoverable. This
|
|||
|
occurs if you are attempting to recover your environment on
|
|||
|
a system that does not support the absolute path name that
|
|||
|
you used.
|
|||
|
</p>
|
|||
|
</div>
|
|||
|
</div>
|
|||
|
<div class="sect3" lang="en" xml:lang="en">
|
|||
|
<div class="titlepage">
|
|||
|
<div>
|
|||
|
<div>
|
|||
|
<h4 class="title"><a id="splittingdata"></a>Identifying Specific File Locations</h4>
|
|||
|
</div>
|
|||
|
</div>
|
|||
|
</div>
|
|||
|
<p>
|
|||
|
As described in the previous sections, DB will place all its
|
|||
|
files in or relative to the environment home directory.
|
|||
|
You can also cause a
|
|||
|
specific database file to be placed in a particular location by
|
|||
|
using an absolute path name for its name. In this
|
|||
|
situation, the environment's home directory is not
|
|||
|
considered when naming the file.
|
|||
|
</p>
|
|||
|
<p>
|
|||
|
It is frequently desirable to place database, log, and region files on separate
|
|||
|
disk drives. By spreading I/O across multiple drives, you
|
|||
|
can increase parallelism and improve throughput.
|
|||
|
Additionally, by placing log files and database files on
|
|||
|
separate drives, you improve your application's
|
|||
|
reliability by providing your application with a greater
|
|||
|
chance of surviving a disk failure.
|
|||
|
</p>
|
|||
|
<p>
|
|||
|
You can cause DB's files to be placed in specific
|
|||
|
locations using the following mechanisms:
|
|||
|
</p>
|
|||
|
<div class="informaltable">
|
|||
|
<table border="1" width="80%">
|
|||
|
<colgroup>
|
|||
|
<col />
|
|||
|
<col />
|
|||
|
</colgroup>
|
|||
|
<thead>
|
|||
|
<tr>
|
|||
|
<th>File Type</th>
|
|||
|
<th>To Override</th>
|
|||
|
</tr>
|
|||
|
</thead>
|
|||
|
<tbody>
|
|||
|
<tr>
|
|||
|
<td>database files</td>
|
|||
|
<td>
|
|||
|
<p>
|
|||
|
You can cause database files to be created
|
|||
|
in a directory other than the
|
|||
|
environment home by using the
|
|||
|
|
|||
|
<code class="methodname">DbEnv::set_data_dir()</code>
|
|||
|
|
|||
|
method.
|
|||
|
The directory identified
|
|||
|
here must exist. If a relative path is
|
|||
|
provided, then the directory location is
|
|||
|
resolved relative to the environment's home
|
|||
|
directory.
|
|||
|
</p>
|
|||
|
|
|||
|
<p>
|
|||
|
This method modifies the directory
|
|||
|
used for database files created and managed by
|
|||
|
a single environment handle; it does not
|
|||
|
configure the entire environment.
|
|||
|
<span>This
|
|||
|
method may not be called after the
|
|||
|
environment has been opened.
|
|||
|
</span>
|
|||
|
</p>
|
|||
|
|
|||
|
<p>
|
|||
|
You can also set a default data location that is used by
|
|||
|
the entire environment by using the
|
|||
|
<code class="literal">set_data_dir</code> parameter
|
|||
|
in the environment's <code class="literal">DB_CONFIG</code> file.
|
|||
|
Note that the <code class="literal">set_data_dir</code>
|
|||
|
parameter overrides any value set by the
|
|||
|
|
|||
|
<code class="methodname">DbEnv::set_data_dir()</code>
|
|||
|
|
|||
|
method.
|
|||
|
</p>
|
|||
|
</td>
|
|||
|
</tr>
|
|||
|
<tr>
|
|||
|
<td>Log files</td>
|
|||
|
<td>
|
|||
|
<p>
|
|||
|
You can cause log files to be created
|
|||
|
in a directory other than the environment home
|
|||
|
directory by using the
|
|||
|
|
|||
|
<code class="methodname">DbEnv::set_lg_dir()</code>
|
|||
|
|
|||
|
method. The directory identified
|
|||
|
here must exist. If a relative path is
|
|||
|
provided, then the directory location is
|
|||
|
resolved relative to the environment's home
|
|||
|
directory.
|
|||
|
</p>
|
|||
|
|
|||
|
<p>
|
|||
|
This method modifies the directory
|
|||
|
used for database files created and managed by
|
|||
|
a single environment handle; it does not
|
|||
|
configure the entire environment.
|
|||
|
<span>This
|
|||
|
method may not be called after the
|
|||
|
environment has been opened.
|
|||
|
</span>
|
|||
|
</p>
|
|||
|
|
|||
|
<p>
|
|||
|
You can also set a default log file location that is used by
|
|||
|
the entire environment by using the
|
|||
|
<code class="literal">set_lg_dir</code> parameter
|
|||
|
in the environment's <code class="literal">DB_CONFIG</code> file.
|
|||
|
Note that the <code class="literal">set_lg_dir</code>
|
|||
|
parameter overrides any value set by the
|
|||
|
|
|||
|
<code class="methodname">DbEnv::set_lg_dir()</code>
|
|||
|
|
|||
|
method.
|
|||
|
</p>
|
|||
|
</td>
|
|||
|
</tr>
|
|||
|
<tr>
|
|||
|
<td>Region files</td>
|
|||
|
<td>
|
|||
|
If backed by the filesystem, region
|
|||
|
files are always placed in the environment home
|
|||
|
directory.
|
|||
|
</td>
|
|||
|
</tr>
|
|||
|
</tbody>
|
|||
|
</table>
|
|||
|
</div>
|
|||
|
<p>
|
|||
|
Note that the <code class="literal">DB_CONFIG</code> must reside in the
|
|||
|
environment home directory. Parameters are specified in it one
|
|||
|
parameter to a line. Each parameter is followed by a space,
|
|||
|
which is followed by the parameter value. For example:
|
|||
|
</p>
|
|||
|
<pre class="programlisting"> set_data_dir /export1/db/env_data_files </pre>
|
|||
|
</div>
|
|||
|
</div>
|
|||
|
<div class="sect2" lang="en" xml:lang="en">
|
|||
|
<div class="titlepage">
|
|||
|
<div>
|
|||
|
<div>
|
|||
|
<h3 class="title"><a id="errorsupport"></a>Error Support</h3>
|
|||
|
</div>
|
|||
|
</div>
|
|||
|
</div>
|
|||
|
<p>
|
|||
|
To simplify error handling and to aid in application debugging, environments offer several useful
|
|||
|
methods.
|
|||
|
|
|||
|
<span>Note that many of these
|
|||
|
methods are identical to the error handling methods available for the
|
|||
|
|
|||
|
<span>Db</span>
|
|||
|
|
|||
|
|
|||
|
<span>class.</span>
|
|||
|
|
|||
|
</span>
|
|||
|
|
|||
|
They are:
|
|||
|
</p>
|
|||
|
<div class="itemizedlist">
|
|||
|
<ul type="disc">
|
|||
|
<li>
|
|||
|
<p>
|
|||
|
<code class="methodname">set_error_stream()</code>
|
|||
|
|
|||
|
</p>
|
|||
|
<p>
|
|||
|
Sets the
|
|||
|
<span>C++ <code class="classname">ostream</code></span>
|
|||
|
|
|||
|
to be used for displaying error messages issued by the DB library.
|
|||
|
</p>
|
|||
|
</li>
|
|||
|
<li>
|
|||
|
<p>
|
|||
|
<code class="methodname">set_errcall()</code>
|
|||
|
|
|||
|
</p>
|
|||
|
<p>
|
|||
|
Defines the function that is called when an error message is
|
|||
|
issued by DB. The error prefix and message are passed to
|
|||
|
this callback. It is up to the application to display this
|
|||
|
information correctly.
|
|||
|
</p>
|
|||
|
<p>
|
|||
|
This is the recommended way to get error messages from
|
|||
|
DB.
|
|||
|
</p>
|
|||
|
</li>
|
|||
|
<li>
|
|||
|
<p>
|
|||
|
<code class="methodname">set_errfile()</code>
|
|||
|
</p>
|
|||
|
<p>
|
|||
|
Sets the C library <code class="literal">FILE *</code> to be used for
|
|||
|
displaying error messages issued by the DB library.
|
|||
|
</p>
|
|||
|
</li>
|
|||
|
<li>
|
|||
|
<p>
|
|||
|
<code class="methodname">set_errpfx()</code>
|
|||
|
|
|||
|
</p>
|
|||
|
<p>
|
|||
|
Sets the prefix used to for any error messages issued by the
|
|||
|
DB library.
|
|||
|
</p>
|
|||
|
</li>
|
|||
|
<li>
|
|||
|
<p>
|
|||
|
<code class="methodname">err()</code>
|
|||
|
</p>
|
|||
|
<p>
|
|||
|
Issues an error message based upon a DB error code a message text that you supply.
|
|||
|
The error message is sent to the
|
|||
|
callback function as defined by <code class="methodname">set_errcall()</code>.
|
|||
|
If that method has not been used, then the error message is sent to the
|
|||
|
file defined by
|
|||
|
|
|||
|
<span>
|
|||
|
<code class="methodname">set_errfile()</code> or <code class="methodname">set_error_stream()</code>.
|
|||
|
</span>
|
|||
|
If none of these methods have been used, then the error message is sent to
|
|||
|
standard error.
|
|||
|
</p>
|
|||
|
<p>
|
|||
|
The error message consists of the prefix string
|
|||
|
(as defined by <code class="methodname">set_errprefix()</code>),
|
|||
|
an optional <code class="literal">printf</code>-style formatted message,
|
|||
|
the DB error message associated with the supplied error code,
|
|||
|
and a trailing newline.
|
|||
|
</p>
|
|||
|
</li>
|
|||
|
<li>
|
|||
|
<p>
|
|||
|
<code class="methodname">errx()</code>
|
|||
|
</p>
|
|||
|
<p>
|
|||
|
Behaves identically to <code class="methodname">err()</code> except
|
|||
|
that you do not provide the DB error code and so
|
|||
|
the DB message text is not displayed.
|
|||
|
</p>
|
|||
|
</li>
|
|||
|
</ul>
|
|||
|
</div>
|
|||
|
<p>
|
|||
|
In addition, you can use the <code class="function">db_strerror()</code>
|
|||
|
function to directly return the error string that corresponds to a
|
|||
|
particular error number. For more information on the
|
|||
|
<code class="function">db_strerror()</code> function, see the <code class="literal">Error Returns</code>
|
|||
|
section of the <em class="citetitle">Getting Started with Berkeley DB</em> guide.
|
|||
|
</p>
|
|||
|
</div>
|
|||
|
<div class="sect2" lang="en" xml:lang="en">
|
|||
|
<div class="titlepage">
|
|||
|
<div>
|
|||
|
<div>
|
|||
|
<h3 class="title"><a id="sharedmemory"></a>Shared Memory Regions</h3>
|
|||
|
</div>
|
|||
|
</div>
|
|||
|
</div>
|
|||
|
<p>
|
|||
|
The subsystems that you enable for an environment (in our case,
|
|||
|
transaction, logging, locking, and the memory pool)
|
|||
|
are described by one or more regions. The regions contain all of the
|
|||
|
state information that needs to be shared among threads and/or
|
|||
|
processes using the environment.
|
|||
|
</p>
|
|||
|
<p>
|
|||
|
Regions may be backed by the file system, by heap memory, or by
|
|||
|
system shared memory.
|
|||
|
</p>
|
|||
|
<div class="sect3" lang="en" xml:lang="en">
|
|||
|
<div class="titlepage">
|
|||
|
<div>
|
|||
|
<div>
|
|||
|
<h4 class="title"><a id="filebackedregions"></a>Regions Backed by Files</h4>
|
|||
|
</div>
|
|||
|
</div>
|
|||
|
</div>
|
|||
|
<p>
|
|||
|
By default, shared memory regions are created as files in the environment's
|
|||
|
home directory (<span class="emphasis"><em>not</em></span> the environment's data
|
|||
|
directory). If it is available, the POSIX <code class="literal">mmap</code>
|
|||
|
interface is used to map these files into your application's
|
|||
|
address space. If <code class="literal">mmap</code>
|
|||
|
is not available, then the UNIX <code class="literal">shmget</code> interfaces
|
|||
|
are used instead (again, if they are available).
|
|||
|
</p>
|
|||
|
<p>
|
|||
|
In this default case, the region files are named
|
|||
|
<code class="literal">__db.###</code>
|
|||
|
(for example, <code class="literal">__db.001</code>, <code class="literal">__db.002</code>,
|
|||
|
and so on).
|
|||
|
</p>
|
|||
|
</div>
|
|||
|
<div class="sect3" lang="en" xml:lang="en">
|
|||
|
<div class="titlepage">
|
|||
|
<div>
|
|||
|
<div>
|
|||
|
<h4 class="title"><a id="heapbackedregions"></a>Regions Backed by Heap Memory</h4>
|
|||
|
</div>
|
|||
|
</div>
|
|||
|
</div>
|
|||
|
<p>
|
|||
|
If heap memory is used to back your shared memory regions, then
|
|||
|
you can only open a single handle for the environment. This
|
|||
|
means that the environment cannot be accessed by multiple
|
|||
|
processes. In this case, the regions are managed only in
|
|||
|
memory, and they are not written to the filesystem. You
|
|||
|
indicate that heap memory is to be used for the region files by
|
|||
|
specifying
|
|||
|
<span>
|
|||
|
<code class="literal">DB_PRIVATE</code> to the
|
|||
|
|
|||
|
<code class="methodname">DbEnv::open()</code>
|
|||
|
method.
|
|||
|
</span>
|
|||
|
|
|||
|
|
|||
|
</p>
|
|||
|
<p>
|
|||
|
Note that you can also set this flag by using the
|
|||
|
<code class="literal">set_open_flags</code> parameter in the
|
|||
|
<code class="literal">DB_CONFIG</code> file. See the
|
|||
|
<em class="citetitle">Berkeley DB C API Reference Guide</em> for more information.
|
|||
|
</p>
|
|||
|
<p>
|
|||
|
(For an example of an entirely in-memory transactional
|
|||
|
application, see
|
|||
|
<span>
|
|||
|
<a class="xref" href="inmem_txnexample_c.html" title="In-Memory Transaction Example">In-Memory Transaction Example</a>.)
|
|||
|
</span>
|
|||
|
|
|||
|
|
|||
|
|
|||
|
</p>
|
|||
|
</div>
|
|||
|
<div class="sect3" lang="en" xml:lang="en">
|
|||
|
<div class="titlepage">
|
|||
|
<div>
|
|||
|
<div>
|
|||
|
<h4 class="title"><a id="systembackedregions"></a>Regions Backed by System Memory</h4>
|
|||
|
</div>
|
|||
|
</div>
|
|||
|
</div>
|
|||
|
<p>
|
|||
|
Finally, you can cause system memory to be used for your
|
|||
|
regions instead of memory-mapped files. You do this by providing
|
|||
|
<span>
|
|||
|
<code class="literal">DB_SYSTEM_MEM</code> to the
|
|||
|
|
|||
|
<code class="methodname">DbEnv::open()</code>
|
|||
|
method.
|
|||
|
</span>
|
|||
|
|
|||
|
|
|||
|
</p>
|
|||
|
<p>
|
|||
|
When region files are backed by system memory, DB creates a
|
|||
|
single file in the environment's home directory. This file
|
|||
|
contains information necessary to identify the system shared
|
|||
|
memory in use by the environment. By creating this file, DB
|
|||
|
enables multiple processes to share the environment.
|
|||
|
</p>
|
|||
|
<p>
|
|||
|
The system memory that is used is architecture-dependent. For
|
|||
|
example, on systems supporting X/Open-style shared memory
|
|||
|
interfaces, such as UNIX systems, the <code class="literal">shmget(2)</code>
|
|||
|
and related System V IPC interfaces are used.
|
|||
|
|
|||
|
<span>
|
|||
|
|
|||
|
Additionally, VxWorks systems use system memory. In these cases,
|
|||
|
an initial segment ID must be specified by the application to
|
|||
|
ensure that applications do not overwrite each other's
|
|||
|
environments, so that the number of segments created does not
|
|||
|
grow without bounds. See the
|
|||
|
|
|||
|
|
|||
|
<code class="methodname">DbEnv::set_shm_key()</code>
|
|||
|
|
|||
|
method for more information.
|
|||
|
</span>
|
|||
|
</p>
|
|||
|
<p>
|
|||
|
On Windows platforms, the use of system memory for the region files
|
|||
|
is problematic because the operating system uses reference counting
|
|||
|
to clean up shared objects in the paging file automatically. In
|
|||
|
addition, the default access permissions for shared objects are
|
|||
|
different from files, which may cause problems when an environment
|
|||
|
is accessed by multiple processes running as different users. See
|
|||
|
<a class="ulink" href="" target="_top">Windows notes</a>
|
|||
|
or more information.
|
|||
|
</p>
|
|||
|
</div>
|
|||
|
</div>
|
|||
|
<div class="sect2" lang="en" xml:lang="en">
|
|||
|
<div class="titlepage">
|
|||
|
<div>
|
|||
|
<div>
|
|||
|
<h3 class="title"><a id="security"></a>Security Considerations</h3>
|
|||
|
</div>
|
|||
|
</div>
|
|||
|
</div>
|
|||
|
<p>
|
|||
|
When using environments, there are some security considerations to
|
|||
|
keep in mind:
|
|||
|
</p>
|
|||
|
<div class="itemizedlist">
|
|||
|
<ul type="disc">
|
|||
|
<li>
|
|||
|
<p>
|
|||
|
Database environment permissions
|
|||
|
</p>
|
|||
|
<p>
|
|||
|
The directory used for the environment
|
|||
|
should have its permissions set to ensure that files in the
|
|||
|
environment are not accessible to users without appropriate
|
|||
|
permissions. Applications that add to the user's permissions
|
|||
|
(for example, UNIX <code class="literal">setuid</code> or
|
|||
|
<code class="literal">setgid</code> applications), must be
|
|||
|
carefully checked to not permit illegal use of those
|
|||
|
permissions such as general file access in the environment
|
|||
|
directory.
|
|||
|
</p>
|
|||
|
</li>
|
|||
|
<li>
|
|||
|
<p>
|
|||
|
Environment variables
|
|||
|
</p>
|
|||
|
<p>
|
|||
|
Setting
|
|||
|
|
|||
|
<span>
|
|||
|
the <code class="literal">DB_USE_ENVIRON</code> or
|
|||
|
<code class="literal">DB_USE_ENVIRON_ROOT</code> flags
|
|||
|
</span>
|
|||
|
|
|||
|
|
|||
|
so that environment variables can be used during file naming
|
|||
|
can be dangerous. Setting those flags in DB
|
|||
|
applications with additional permissions (for example, UNIX
|
|||
|
<code class="literal">setuid</code> or <code class="literal">setgid</code>
|
|||
|
applications) could potentially allow users
|
|||
|
to read and write databases to which they would not normally
|
|||
|
have access.
|
|||
|
</p>
|
|||
|
<p>
|
|||
|
For example, suppose you write a DB application
|
|||
|
that runs <code class="literal">setuid</code>. This means that
|
|||
|
when the application runs, it does so under a
|
|||
|
userid different than that of the application's caller.
|
|||
|
This is especially problematic if the application is
|
|||
|
granting stronger privileges to a user than the user
|
|||
|
might ordinarily have.
|
|||
|
</p>
|
|||
|
<p>
|
|||
|
Now, if
|
|||
|
<span>
|
|||
|
the <code class="literal">DB_USE_ENVIRON</code> or
|
|||
|
<code class="literal">DB_USE_ENVIRON_ROOT</code> flags
|
|||
|
are set for the environment,
|
|||
|
</span>
|
|||
|
|
|||
|
|
|||
|
|
|||
|
then the environment that the application is
|
|||
|
using is modifiable using the
|
|||
|
<code class="literal">DB_HOME</code> environment variable. In
|
|||
|
this scenario, if the uid used by the application has
|
|||
|
sufficiently broad privileges, then the application's caller
|
|||
|
can read and/or write databases owned by another user
|
|||
|
simply by setting his
|
|||
|
<code class="literal">DB_HOME</code> environment variable to the
|
|||
|
environment used by that other user.
|
|||
|
</p>
|
|||
|
<p>
|
|||
|
Note that this scenario need not be malicious; the
|
|||
|
wrong environment could be used by the application
|
|||
|
simply by inadvertently specifying the wrong path to
|
|||
|
<code class="literal">DB_HOME</code>.
|
|||
|
</p>
|
|||
|
<p>
|
|||
|
As always, you should use <code class="literal">setuid</code>
|
|||
|
sparingly, if at all. But if you do use
|
|||
|
<code class="literal">setuid</code>, then you should refrain from
|
|||
|
specifying
|
|||
|
<span>
|
|||
|
the <code class="literal">DB_USE_ENVIRON</code> or
|
|||
|
<code class="literal">DB_USE_ENVIRON_ROOT</code> flags
|
|||
|
</span>
|
|||
|
|
|||
|
for the environment open. And, of course, if you must
|
|||
|
use <code class="literal">setuid</code>, then make sure you use
|
|||
|
the weakest uid possible – preferably one that is
|
|||
|
used only by the application itself.
|
|||
|
</p>
|
|||
|
</li>
|
|||
|
<li>
|
|||
|
<p>
|
|||
|
File permissions
|
|||
|
</p>
|
|||
|
<p>
|
|||
|
By default, DB always creates database and log files readable and
|
|||
|
writable by the owner and the group (that is,
|
|||
|
<code class="literal">S_IRUSR</code>,
|
|||
|
<code class="literal">S_IWUSR</code>, <code class="literal">S_IRGRP</code> and
|
|||
|
<code class="literal">S_IWGRP</code>; or octal mode 0660 on historic
|
|||
|
UNIX systems). The group ownership of created files is based
|
|||
|
on the system and directory defaults, and is not further
|
|||
|
specified by DB.
|
|||
|
</p>
|
|||
|
</li>
|
|||
|
<li>
|
|||
|
<p>
|
|||
|
Temporary backing files
|
|||
|
</p>
|
|||
|
<p>
|
|||
|
If an unnamed database is created and the cache is too small
|
|||
|
to hold the database in memory, Berkeley DB will create a
|
|||
|
temporary physical file to enable it to page the database to
|
|||
|
disk as needed. In this case, environment variables such as
|
|||
|
<code class="literal">TMPDIR</code> may be used to specify the
|
|||
|
location of that temporary file. Although temporary backing
|
|||
|
files are created readable and writable by the owner only
|
|||
|
(<code class="literal">S_IRUSR</code> and <code class="literal">S_IWUSR</code>,
|
|||
|
or octal mode 0600 on historic UNIX systems), some
|
|||
|
filesystems may not sufficiently protect temporary files
|
|||
|
created in random directories from improper access. To be
|
|||
|
absolutely safe, applications storing sensitive data in
|
|||
|
unnamed databases should use the
|
|||
|
|
|||
|
<code class="methodname">DbEnv::set_tmp_dir()</code>
|
|||
|
|
|||
|
method to specify a temporary directory with known permissions.
|
|||
|
</p>
|
|||
|
</li>
|
|||
|
</ul>
|
|||
|
</div>
|
|||
|
</div>
|
|||
|
</div>
|
|||
|
</div>
|
|||
|
<div class="navfooter">
|
|||
|
<hr />
|
|||
|
<table width="100%" summary="Navigation footer">
|
|||
|
<tr>
|
|||
|
<td width="40%" align="left"><a accesskey="p" href="perftune-intro.html">Prev</a> </td>
|
|||
|
<td width="20%" align="center"> </td>
|
|||
|
<td width="40%" align="right"> <a accesskey="n" href="envopen.html">Next</a></td>
|
|||
|
</tr>
|
|||
|
<tr>
|
|||
|
<td width="40%" align="left" valign="top">Performance Tuning </td>
|
|||
|
<td width="20%" align="center">
|
|||
|
<a accesskey="h" href="index.html">Home</a>
|
|||
|
</td>
|
|||
|
<td width="40%" align="right" valign="top"> Opening a Transactional Environment and
|
|||
|
<span>Database</span>
|
|||
|
|
|||
|
|
|||
|
</td>
|
|||
|
</tr>
|
|||
|
</table>
|
|||
|
</div>
|
|||
|
</body>
|
|||
|
</html>
|