| Current Path : /usr/share/doc/db4-devel-4.7.25/gsg_txn/C/ |
| Current File : //usr/share/doc/db4-devel-4.7.25/gsg_txn/C/enabletxn.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.62.4" />
<link rel="home" 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="previous" href="perftune-intro.html" title="Performance Tuning" />
<link rel="next" href="envopen.html" title="Opening a Transactional Environment and Database " />
</head>
<body>
<div class="navheader">
<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>
</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
Database
</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 href="enabletxn.html#environments">Environments</a> for details).
</p>
</li>
<li>
<p>
Turn on transactions for your environment.
<span>
You do this by providing the <tt class="literal">DB_INIT_TXN</tt>
flag to the
<tt class="methodname">DB_ENV->open()</tt>
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 <tt class="literal">DB_INIT_MPOOL</tt>
flag to the
<tt class="methodname">DB_ENV->open()</tt>
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 href="txnconcurrency.html">Concurrency</a>
for more information.
</p>
<p>
You initialize the locking subsystem by
<span>
passing the <tt class="literal">DB_INIT_LOCK</tt>
flag to the
<tt class="methodname">DB_ENV->open()</tt>
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 href="filemanagement.html">Managing DB Files</a>
for more information.
</p>
<p>
You initialize the logging subsystem by
<span>
passing the <tt class="literal">DB_INIT_LOG</tt>
flag to the
<tt class="methodname">DB_ENV->open()</tt>
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>
</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 href="inmem_txnexample_c.html">In-Memory Transaction Example</a>.</span>
</p>
<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></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></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
<tt class="methodname">DB_ENV->open()</tt>
<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><tt class="methodname">DB_ENV->open()</tt>, </span>
then the directory identified by the <tt class="literal">DB_HOME</tt> environment variable
is used <span class="emphasis"><em>if</em></span> you specify
<span>
either the <tt class="literal">DB_USE_ENVIRON</tt> or
<tt class="literal">DB_USE_ENVIRON_ROOT</tt> flags to the
<tt class="methodname">DB_ENV->open()</tt>
method. Both flags allow you to identify the
path to the environment's home directory
using the <tt class="literal">DB_HOME</tt> environment variable. However,
<tt class="literal">DB_USE_ENVIRON_ROOT</tt> 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></div>
</div>
<p>
By default, all DB files are created relative to the environment
home directory. For example, suppose your environment home is in
<tt class="literal">/export/myAppHome</tt>. Also suppose you name your database
<span><tt class="literal">data/myDatabase.db</tt>.</span>
Then in this case, the database is placed in:
<span><tt class="literal">/export/myAppHome/data/myDatabase.db</tt>.</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
you 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></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
<tt class="methodname">DB_ENV->set_data_dir()</tt>
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
<tt class="literal">set_data_dir</tt> parameter
in the environment's <tt class="literal">DB_CONFIG</tt> file.
Note that the <tt class="literal">set_data_dir</tt>
parameter overrides any value set by the
<tt class="methodname">DB_ENV->set_data_dir()</tt>
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
<tt class="methodname">DB_ENV->set_lg_dir()</tt>
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
<tt class="literal">set_lg_dir</tt> parameter
in the environment's <tt class="literal">DB_CONFIG</tt> file.
Note that the <tt class="literal">set_lg_dir</tt>
parameter overrides any value set by the
<tt class="methodname">DB_ENV->set_lg_dir()</tt>
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 <tt class="literal">DB_CONFIG</tt> 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></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>structure.</span>
</span>
They are:
</p>
<div class="itemizedlist">
<ul type="disc">
<li>
<p>
<tt class="methodname">set_errcall()</tt>
</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>
</li>
<li>
<p>
<tt class="methodname">set_errfile()</tt>
</p>
<p>
Sets the C library <tt class="literal">FILE *</tt> to be used for
displaying error messages issued by the DB library.
</p>
</li>
<li>
<p>
<tt class="methodname">set_errpfx()</tt>
</p>
<p>
Sets the prefix used to for any error messages issued by the
DB library.
</p>
</li>
<li>
<p>
<tt class="methodname">err()</tt>
</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 <tt class="methodname">set_errcall()</tt>.
If that method has not been used, then the error message is sent to the
file defined by
<span><tt class="methodname">set_errfile()</tt>.</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 <tt class="methodname">set_errprefix()</tt>),
an optional <tt class="literal">printf</tt>-style formatted message,
the DB error message associated with the supplied error code,
and a trailing newline.
</p>
</li>
<li>
<p>
<tt class="methodname">errx()</tt>
</p>
<p>
Behaves identically to <tt class="methodname">err()</tt> 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 <tt class="function">db_strerror()</tt>
function to directly return the error string that corresponds to a
particular error number. For more information on the
<tt class="function">db_strerror()</tt> function, see the <tt class="literal">Error Returns</tt>
section of the <i class="citetitle">Getting Started with Berkeley DB</i> 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></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></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 <tt class="literal">mmap</tt>
interface is used to map these files into your application's
address space. If <tt class="literal">mmap</tt>
is not available, then the UNIX <tt class="literal">shmget</tt> interfaces
are used instead (again, if they are available).
</p>
<p>
In this default case, the region files are named
<tt class="literal">__db.###</tt>
(for example, <tt class="literal">__db.001</tt>, <tt class="literal">__db.002</tt>,
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></div>
</div>
<p>
If heap memory is used to back your shared memory regions,
the environment may only be
accessed by a single process, although that process may be
multi-threaded. 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>
<tt class="literal">DB_PRIVATE</tt> to the
<tt class="methodname">DB_ENV->open()</tt>
method.
</span>
</p>
<p>
(For an example of an entirely in-memory transactional
application, see
<span>
<a href="inmem_txnexample_c.html">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></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>
<tt class="literal">DB_SYSTEM_MEM</tt> to the
<tt class="methodname">DB_ENV->open()</tt>
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 <tt class="literal">shmget(2)</tt>
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
<tt class="methodname">DB_ENV->set_shm_key()</tt>
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 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></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 <tt class="literal">setuid</tt> or
<tt class="literal">setgid</tt> 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 <tt class="literal">DB_USE_ENVIRON</tt> or
<tt class="literal">DB_USE_ENVIRON_ROOT</tt> 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
<tt class="literal">setuid</tt> or <tt class="literal">setgid</tt>
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 <tt class="literal">setuid</tt>. 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 <tt class="literal">DB_USE_ENVIRON</tt> or
<tt class="literal">DB_USE_ENVIRON_ROOT</tt> flags
are set for the environment,
</span>
then the environment that the application is
using is modifiable using the
<tt class="literal">DB_HOME</tt> 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
<tt class="literal">DB_HOME</tt> 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
<tt class="literal">DB_HOME</tt>.
</p>
<p>
As always, you should use <tt class="literal">setuid</tt>
sparingly, if at all. But if you do use
<tt class="literal">setuid</tt>, then you should refrain from
specifying
<span>
the <tt class="literal">DB_USE_ENVIRON</tt> or
<tt class="literal">DB_USE_ENVIRON_ROOT</tt> flags
</span>
for the environment open. And, of course, if you must
use <tt class="literal">setuid</tt>, 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,
<tt class="literal">S_IRUSR</tt>,
<tt class="literal">S_IWUSR</tt>, <tt class="literal">S_IRGRP</tt> and
<tt class="literal">S_IWGRP</tt>; 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
<tt class="literal">TMPDIR</tt> may be used to specify the
location of that temporary file. Although temporary backing
files are created readable and writable by the owner only
(<tt class="literal">S_IRUSR</tt> and <tt class="literal">S_IWUSR</tt>,
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
<tt class="methodname">DB_ENV->set_tmp_dir()</tt>
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">
<a accesskey="u" href="index.html">Up</a>
</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
Database
</td>
</tr>
</table>
</div>
</body>
</html>
Copyright 2K16 - 2K18 Indonesian Hacker Rulez
;?>)