mirror of
https://github.com/berkeleydb/libdb.git
synced 2024-11-16 17:16:25 +00:00
994 lines
43 KiB
HTML
994 lines
43 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 Store or Database" />
|
||
</head>
|
||
<body>
|
||
<div xmlns="" class="navheader">
|
||
<div class="libver">
|
||
<p>Library Version 11.2.5.3</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>Store or 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 using the
|
||
<code class="methodname">EnvironmentConfig.setTransactional()</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 <code class="literal">true</code> to the
|
||
<code class="methodname">EnvironmentConfig.setInitializeCache()</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 <code class="literal">true</code> to the
|
||
<code class="methodname">EnvironmentConfig.setInitializeLocking()</code>
|
||
method.
|
||
</span>
|
||
</p>
|
||
</li>
|
||
<li>
|
||
<p>
|
||
If you are using the DPL, transaction-enable your stores.
|
||
You do this by using the
|
||
<code class="methodname">StoreConfig.setTransactional() method.</code>
|
||
</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>
|
||
using the
|
||
<code class="methodname">DatabaseConfig.setTransactional()</code>
|
||
method, and then opening the database from within 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_java.html" title="Base API In-Memory Transaction Example">Base API 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">Environment()</code>
|
||
|
||
<span>constructor,</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">Environment()</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>
|
||
<code class="literal">true</code> to either the
|
||
<code class="methodname">EnvironmentConfig.setUseEnvironment()</code>
|
||
or
|
||
<code class="methodname">EnvironmentConfig.setUseEnvironmentRoot()</code>
|
||
method. Both methods allow you to identify the
|
||
path to the environment's home directory
|
||
using <code class="literal">DB_HOME</code>. However,
|
||
<code class="methodname">EnvironmentConfig.setUseEnvironmentRoot()</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">EnvironmentConfig.addDataDir()</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.
|
||
|
||
</p>
|
||
|
||
<p>
|
||
You can also set a default data location that is used by
|
||
the entire environment by using the
|
||
<code class="literal">add_data_dir</code> parameter
|
||
in the environment's <code class="literal">DB_CONFIG</code> file.
|
||
Note that the <code class="literal">add_data_dir</code>
|
||
parameter overrides any value set by the
|
||
|
||
|
||
<code class="methodname">EnvironmentConfig.addDataDir()</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">EnvironmentConfig.LogDirectory()</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.
|
||
|
||
</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">EnvironmentConfig.setLogDirectory()</code>
|
||
method.
|
||
</p>
|
||
</td>
|
||
</tr>
|
||
<tr>
|
||
<td>Temporary files</td>
|
||
<td>
|
||
<p>
|
||
You can cause temporary files required by the
|
||
environment to be created
|
||
in a directory other than the environment home
|
||
directory by using the
|
||
|
||
|
||
<code class="methodname">EnvironmentConfig.setTemporaryDirectory()</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>
|
||
You can also set a temporary file location
|
||
by using the
|
||
<code class="literal">set_tmp_dir</code> parameter
|
||
in the environment's <code class="literal">DB_CONFIG</code> file.
|
||
Note that the <code class="literal">set_tmp_dir</code>
|
||
parameter overrides any value set by the
|
||
|
||
|
||
<code class="methodname">EnvironmentConfig.setTemporaryDirectory()</code>
|
||
method.
|
||
</p>
|
||
</td>
|
||
</tr>
|
||
<tr>
|
||
<td>Metadata files</td>
|
||
<td>
|
||
<p>
|
||
You can cause persistent metadata files required by the
|
||
replicated applications to be created
|
||
in a directory other than the environment home
|
||
directory by using the
|
||
|
||
|
||
<code class="methodname">EnvironmentConfig.setMetadataDir()</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>
|
||
You can also set a metadata directory location
|
||
by using the
|
||
<code class="literal">set_metadata_dir</code> parameter
|
||
in the environment's <code class="literal">DB_CONFIG</code> file.
|
||
Note that the <code class="literal">set_metadata_dir</code>
|
||
parameter overrides any value set by the
|
||
|
||
|
||
<code class="methodname">EnvironmentConfig.setMetadataDir()</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"> add_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>DatabaseConfig</span>
|
||
|
||
<span>class.</span>
|
||
|
||
</span>
|
||
|
||
They are:
|
||
</p>
|
||
<div class="itemizedlist">
|
||
<ul type="disc">
|
||
<li>
|
||
<p>
|
||
|
||
<code class="methodname">EnvironmentConfig.setErrorStream()</code>
|
||
</p>
|
||
<p>
|
||
Sets the
|
||
|
||
<span>Java <code class="classname">OutputStream</code></span>
|
||
to be used for displaying error messages issued by the DB library.
|
||
</p>
|
||
</li>
|
||
<li>
|
||
<p>
|
||
|
||
<code class="methodname">EnvironmentConfig.setErrorHandler()</code>
|
||
</p>
|
||
<p>
|
||
Defines the message handler 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>
|
||
Note that the message handler must be an implementation of the
|
||
<code class="classname">com.sleepycat.db.ErrorHandler</code>
|
||
interface.
|
||
</p>
|
||
<p>
|
||
This is the recommended way to get error messages from
|
||
DB.
|
||
</p>
|
||
</li>
|
||
<li>
|
||
<p>
|
||
|
||
<code class="methodname">EnvironmentConfig.setErrorPrefix()</code>
|
||
</p>
|
||
<p>
|
||
Sets the prefix used to for any error messages issued by the
|
||
DB library.
|
||
</p>
|
||
</li>
|
||
</ul>
|
||
</div>
|
||
</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="note" style="margin-left: 0.5in; margin-right: 0.5in;">
|
||
<h3 class="title">Note</h3>
|
||
<p>
|
||
When DB dynamically obtains memory, it uses memory outside of the JVM. Normally the amount of memory
|
||
that DB obtains is trivial, a few bytes here and there, so you might not notice it. However, if
|
||
heap or system memory is used to back your region files, then this can represent a significant amount of
|
||
memory being used by DB above and beyond the memory required by the JVM process. As a result, the
|
||
JVM process may appear to be using more memory than you told the process it could use.
|
||
</p>
|
||
</div>
|
||
<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">true</code> to the
|
||
<code class="methodname">EnvironmentConfig.setPrivate()</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_java.html" title="Base API In-Memory Transaction Example">Base API 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">true</code> to the
|
||
<code class="methodname">EnvironmentConfig.setSystemMemory()</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">EnvironmentConfig.setSegmentId()</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>
|
||
<code class="literal">true</code> for <code class="methodname">EnvironmentConfig.setUseEnvironment()</code>
|
||
or
|
||
<code class="methodname">EnvironmentConfig.setUseEnvironmentRoot()</code>
|
||
</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>
|
||
<code class="literal">true</code> is specified
|
||
for <code class="methodname">EnvironmentConfig.setUseEnvironment()</code>
|
||
or
|
||
<code class="methodname">EnvironmentConfig.setUseEnvironmentRoot()</code>,
|
||
</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>
|
||
<code class="literal">true</code> for <code class="methodname">EnvironmentConfig.setUseEnvironment()</code>
|
||
or
|
||
<code class="methodname">EnvironmentConfig.setUseEnvironmentRoot()</code>
|
||
</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">EnvironmentConfig.setTemporaryDirectory()</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>Store or Database</span>
|
||
|
||
</td>
|
||
</tr>
|
||
</table>
|
||
</div>
|
||
</body>
|
||
</html>
|