315 lines
19 KiB
HTML
315 lines
19 KiB
HTML
<!--$Id: db_open.html 63573 2008-05-23 21:43:21Z trent.nelson $-->
|
|
<!--$Id: db_open.html 63573 2008-05-23 21:43:21Z trent.nelson $-->
|
|
<!--Copyright (c) 1997,2008 Oracle. All rights reserved.-->
|
|
<!--See the file LICENSE for redistribution information.-->
|
|
<html>
|
|
<head>
|
|
<title>Berkeley DB: berkdb open</title>
|
|
<meta name="description" content="Berkeley DB: An embedded database programmatic toolkit.">
|
|
<meta name="keywords" content="embedded,database,programmatic,toolkit,btree,hash,hashing,transaction,transactions,locking,logging,access method,access methods,Java,C,C++">
|
|
</head>
|
|
<body bgcolor=white>
|
|
<table width="100%"><tr valign=top>
|
|
<td>
|
|
<b><b>berkdb open</b></b>
|
|
</td>
|
|
<td align=right>
|
|
<a href="../api_tcl/api_tcl.html"><img src="../images/api.gif" alt="API"></a>
|
|
<a href="../ref/toc.html"><img src="../images/ref.gif" alt="Ref"></a></td>
|
|
</tr></table>
|
|
<hr size=1 noshade>
|
|
<tt>
|
|
<b><pre>berkdb open
|
|
[-auto_commit]
|
|
[-btree | -hash | -recno | -queue | -unknown]
|
|
[-cachesize {gbytes bytes ncache}]
|
|
[-create]
|
|
[-delim delim]
|
|
[-dup]
|
|
[-dupsort]
|
|
[-encrypt]
|
|
[-encryptaes passwd]
|
|
[-encryptany passwd]
|
|
[-env env]
|
|
[-errfile filename]
|
|
[-excl]
|
|
[-extent size]
|
|
[-ffactor density]
|
|
[-len len]
|
|
[-mode mode]
|
|
[-nelem size]
|
|
[-pad pad]
|
|
[-pagesize pagesize]
|
|
[-rdonly]
|
|
[-recnum]
|
|
[-renumber]
|
|
[-snapshot]
|
|
[-source file]
|
|
[-truncate]
|
|
[-txn txnid]
|
|
[--]
|
|
[file [database]]
|
|
</pre></b>
|
|
<b>Description(berkdb open)</b>
|
|
<p>The <b>berkdb open</b> command opens and optionally creates a database.
|
|
The returned database handle is bound to a Tcl command of the form
|
|
<b>dbN</b>, where N is an integer starting at 0 (for example, db0 and
|
|
db1). It is through this Tcl command that the script accesses the
|
|
database methods.</p>
|
|
<p>The options are as follows:</p>
|
|
<br>
|
|
<b>-auto_commit</b><ul compact><li>Enclose the call within a transaction. If the call succeeds, the open
|
|
operation will be recoverable and all subsequent database modification
|
|
operations based on this handle will be transactionally protected. If
|
|
the call fails, no database will have been created.</ul>
|
|
<b>-btree</b><ul compact><li>Open/create a database of type Btree. The Btree format
|
|
is a representation of a sorted, balanced tree structure.</ul>
|
|
<b>-hash</b><ul compact><li>Open/create a database of type Hash. The Hash format is
|
|
an extensible, dynamic hashing scheme.</ul>
|
|
<b>-queue</b><ul compact><li>Open/create a database of type Queue. The Queue format
|
|
supports fast access to fixed-length records accessed by sequentially or
|
|
logical record number.</ul>
|
|
<b>-recno</b><ul compact><li>Open/create a database of type Recno. The Recno format
|
|
supports fixed- or variable-length records, accessed sequentially or by
|
|
logical record number, and optionally retrieved from a flat text file.</ul>
|
|
<b>-unknown</b><ul compact><li>The database is of an unknown type, and must already exist.</ul>
|
|
<b>-cachesize {gbytes bytes ncache}</b><ul compact><li>Set the size of the database's shared memory buffer pool (that is, the
|
|
cache), to <b>gbytes</b> gigabytes plus <b>bytes</b>. The cache
|
|
should be the size of the normal working data set of the application,
|
|
with some small amount of additional memory for unusual situations.
|
|
(Note: The working set is not the same as the number of simultaneously
|
|
referenced pages, and should be quite a bit larger!)
|
|
<p>The default cache size is 256KB, and may not be specified as less than
|
|
20KB. Any cache size less than 500MB is automatically increased by 25%
|
|
to account for buffer pool overhead; cache sizes larger than 500MB are
|
|
used as specified.</p>
|
|
<p>It is possible to specify caches to Berkeley DB that are large enough so that
|
|
they cannot be allocated contiguously on some architectures; for example,
|
|
some releases of Solaris limit the amount of memory that may be
|
|
allocated contiguously by a process. If <b>ncache</b> is 0 or 1, the
|
|
cache will be allocated contiguously in memory. If it is greater than
|
|
1, the cache will be broken up into <b>ncache</b> equally sized
|
|
separate pieces of memory.</p>
|
|
<p>For information on tuning the Berkeley DB cache size, see
|
|
<a href="../ref/am_conf/cachesize.html">Selecting a cache size</a>.</p>
|
|
<p>Because databases opened within Berkeley DB environments use the cache
|
|
specified to the environment, it is an error to attempt to set a cache
|
|
in a database created within an environment.</p></ul>
|
|
<b>-create</b><ul compact><li>Create any underlying files, as necessary. If the files do not already
|
|
exist and the <b>-create</b> argument is not specified, the call will
|
|
fail.</ul>
|
|
<b>-delim delim</b><ul compact><li>Set the delimiting byte used to mark the end of a record in the backing
|
|
source file for the Recno access method.
|
|
<p>This byte is used for variable length records if the <b>-source</b>
|
|
argument file is specified. If the <b>-source</b> argument file is
|
|
specified and no delimiting byte was specified, <newline>
|
|
characters (that is, ASCII 0x0a) are interpreted as end-of-record
|
|
markers.</p></ul>
|
|
<b>-dup</b><ul compact><li>Permit duplicate data items in the tree, that is, insertion when the
|
|
key of the key/data pair being inserted already exists in the tree will
|
|
be successful. The ordering of duplicates in the tree is determined by
|
|
the order of insertion unless the ordering is otherwise specified by
|
|
use of a cursor or a duplicate comparison function. <p>error to specify both <b>-dup</b> and <b>-recnum</b>.</p></ul>
|
|
<b>-dupsort</b><ul compact><li>Sort duplicates within a set of data items. A default lexical
|
|
comparison will be used. Specifying that duplicates are to be sorted
|
|
changes the behavior of the <i>db</i> <b>put</b> operation as well as the
|
|
<i>dbc</i> <b>put</b> operation when the <b>-keyfirst</b>, <b>-keylast</b>
|
|
and <b>-current</b> options are specified.</ul>
|
|
<b>-encrypt</b><ul compact><li>Specify the database in an environment should be encrypted with the
|
|
same password that is being used in the environment.</ul>
|
|
<b>-encryptaes passwd</b><ul compact><li>Specify the database should be encrypted with the given password
|
|
using the Rijndael/AES (also known as the Advanced Encryption Standard
|
|
and Federal Information Processing Standard (FIPS) 197) algorithm.</ul>
|
|
<b>-encryptany passwd</b><ul compact><li>Specify the already existing database should be opened
|
|
with the given password. This option is used if the database is
|
|
known to be encrypted, but the specific algorithm used is not known.</ul>
|
|
<b>-env env</b><ul compact><li>If no <b>-env</b> argument is given, the database is standalone; that
|
|
is, it is not part of any Berkeley DB environment.
|
|
<p>If a <b>-env</b> argument is given, the database is created within the
|
|
specified Berkeley DB environment. The database access methods automatically
|
|
make calls to the other subsystems in Berkeley DB, based on the enclosing
|
|
environment. For example, if the environment has been configured to use
|
|
locking, the access methods will automatically acquire the correct locks
|
|
when reading and writing pages of the database.</p></ul>
|
|
<b>-errfile filename</b><ul compact><li><p>When an error occurs in the Berkeley DB library, a Berkeley DB error or an error
|
|
return value is returned by the function. In some cases, however, the
|
|
errno value may be insufficient to completely describe the cause of the
|
|
error especially during initial application debugging.</p>
|
|
<p>The <b>-errfile</b> argument is used to enhance the mechanism for
|
|
reporting error messages to the application by specifying a file to be
|
|
used for displaying additional Berkeley DB error messages. In some cases, when
|
|
an error occurs, Berkeley DB will output an additional error message to the
|
|
specified file reference.</p>
|
|
<p>The error message will consist of a Tcl command name and a colon (":"),
|
|
an error string, and a trailing <newline> character. If
|
|
the database was opened in an environment, the Tcl command name will be
|
|
the environment name (for example, env0), otherwise it will be the
|
|
database command name (for example, db0).</p>
|
|
<p>This error-logging enhancement does not slow performance or significantly
|
|
increase application size, and may be run during normal operation as well
|
|
as during application debugging.</p>
|
|
<p>For database handles opened inside of Berkeley DB environments, specifying the
|
|
<b>-errfile</b> argument affects the entire environment and is equivalent
|
|
to specifying the same argument to the <b>berkdb env</b> command.</p></ul>
|
|
<b>-excl</b><ul compact><li>Return an error if the database already exists.</ul>
|
|
<b>-extent size</b><ul compact><li>Set the size of the extents of the Queue database; the size is specified
|
|
as the number of pages in an extent. Each extent is created as a
|
|
separate physical file. If no extent size is set, the default behavior
|
|
is to create only a single underlying database file.</ul>
|
|
<p>For information on tuning the extent size, see
|
|
<a href="../ref/am_conf/extentsize.html">Selecting a extent size</a>.</p>
|
|
<b>-ffactor density</b><ul compact><li>Set the desired density within the hash table.
|
|
<p>The density is an approximation of the number of keys allowed to
|
|
accumulate in any one bucket</ul>
|
|
<b>-len len</b><ul compact><li>For the Queue access method, specify that the records are of length
|
|
<b>len</b>.
|
|
<p>For the Recno access method, specify that the records are fixed-length,
|
|
not byte-delimited, and are of length <b>len</b>.</p>
|
|
<p>Any records added to the database that are less than <b>len</b> bytes
|
|
long are automatically padded (see the <b>-pad</b> argument for more
|
|
information).</p>
|
|
<p>Any attempt to insert records into the database that are greater than
|
|
<b>len</b> bytes long will cause the call to fail immediately and return
|
|
an error.</p></ul>
|
|
<b>-mode mode</b><ul compact><li><p>On UNIX systems, or in IEEE/ANSI Std 1003.1 (POSIX) environments, all files created by the access methods
|
|
are created with mode <b>mode</b> (as described in <b>chmod</b>(2)) and
|
|
modified by the process' umask value at the time of creation (see
|
|
<b>umask</b>(2)). The group ownership of created files is based on
|
|
the system and directory defaults, and is not further specified by Berkeley DB.
|
|
If <b>mode</b> is 0, files are created readable and writable by both
|
|
owner and group. On Windows systems, the mode argument is ignored.</p></ul>
|
|
<b>-nelem size</b><ul compact><li>Set an estimate of the final size of the hash table.
|
|
<p>If not set or set too low, hash tables will still expand gracefully as
|
|
keys are entered, although a slight performance degradation may be
|
|
noticed.</p></ul>
|
|
<b>-pad pad</b><ul compact><li>Set the padding character for short, fixed-length records for the Queue
|
|
and Recno access methods.
|
|
<p>If no pad character is specified, <space> characters (that is,
|
|
ASCII 0x20) are used for padding.</p></ul>
|
|
<b>-pagesize pagesize</b><ul compact><li>Set the size of the pages used to hold items in the database, in bytes.
|
|
The minimum page size is 512 bytes, and the maximum page size is 64K
|
|
bytes. If the page size is not explicitly set, one is selected based
|
|
on the underlying filesystem I/O block size. The automatically selected
|
|
size has a lower limit of 512 bytes and an upper limit of 16K bytes.
|
|
<p>For information on tuning the Berkeley DB page size, see
|
|
<a href="../ref/am_conf/pagesize.html">Selecting a page size</a>.</p></ul>
|
|
<b>-rdonly</b><ul compact><li>Open the database for reading only. Any attempt to modify items in the
|
|
database will fail, regardless of the actual permissions of any
|
|
underlying files.</ul>
|
|
<b>-recnum</b><ul compact><li>Support retrieval from the Btree using record numbers.
|
|
<p>Logical record numbers in Btree databases are mutable in the face of
|
|
record insertion or deletion. See the <b>-renumber</b> argument for
|
|
further discussion.</p>
|
|
<p>Maintaining record counts within a Btree introduces a serious point of
|
|
contention, namely the page locations where the record counts are stored. In
|
|
addition, the entire tree must be locked during both insertions and
|
|
deletions, effectively single-threading the tree for those operations.
|
|
Specifying <b>-recnum</b> can result in serious performance degradation
|
|
for some applications and data sets.</p>
|
|
<p>It is an error to specify both <b>-dup</b> and <b>-recnum</b>.</p></ul>
|
|
<b>-renumber</b><ul compact><li>Specifying the <b>-renumber</b> argument causes the logical record
|
|
numbers to be mutable, and change as records are added to and deleted from
|
|
the database. For example, the deletion of record number 4 causes records
|
|
numbered 5 and greater to be renumbered downward by one. If a cursor was
|
|
positioned to record number 4 before the deletion, it will refer to the
|
|
new record number 4, if any such record exists, after the deletion. If a
|
|
cursor was positioned after record number 4 before the deletion, it will
|
|
be shifted downward one logical record, continuing to refer to the same
|
|
record as it did before.
|
|
<p>Using the <i>db</i> <b>put</b> or <i>dbc</i> <b>put</b> interfaces to create new records will
|
|
cause the creation of multiple records if the record number is more than one
|
|
greater than the largest record currently in the database. For example,
|
|
creating record 28 when record 25 was previously the last record in the
|
|
database, will create records 26 and 27 as well as 28.</p>
|
|
<p>If a created record is not at the end of the database, all records following
|
|
the new record will be automatically renumbered upward by one. For example,
|
|
the creation of a new record numbered 8 causes records numbered 8 and
|
|
greater to be renumbered upward by one. If a cursor was positioned to record
|
|
number 8 or greater before the insertion, it will be shifted upward one
|
|
logical record, continuing to refer to the same record as it did before.</p>
|
|
<p>For these reasons, concurrent access to a Recno database with the
|
|
<b>-renumber</b> flag specified may be largely meaningless, although it
|
|
is supported.</p></ul>
|
|
<b>-snapshot</b><ul compact><li>This argument specifies that any specified <b>-source</b> file be read
|
|
in its entirety when the database is opened. If this argument is not
|
|
specified, the <b>-source</b> file may be read lazily.</ul>
|
|
<b>-source file</b><ul compact><li>Set the underlying source file for the Recno access method. The purpose
|
|
of the <b>-source</b> file is to provide fast access and modification
|
|
to databases that are normally stored as flat text files.
|
|
<p>If the <b>-source</b> argument is give, it specifies an underlying flat
|
|
text database file that is read to initialize a transient record number
|
|
index. In the case of variable length records, the records are separated
|
|
as specified by <b>-delim</b>. For example, standard UNIX byte stream
|
|
files can be interpreted as a sequence of variable length records
|
|
separated by <newline> characters.</p>
|
|
<p>In addition, when cached data would normally be written back to the
|
|
underlying database file (for example, when the <i>db</i> <b>close</b> or
|
|
<i>db</i> <b>sync</b> commands are called), the in-memory copy of the database
|
|
will be written back to the <b>-source</b> file.</p>
|
|
<p>By default, the backing source file is read lazily, that is, records
|
|
are not read from the file until they are requested by the application.
|
|
<b>If multiple processes (not threads) are accessing a Recno database
|
|
concurrently and either inserting or deleting records, the backing source
|
|
file must be read in its entirety before more than a single process
|
|
accesses the database, and only that process should specify the backing
|
|
source argument as part of the <b>berkdb open</b> call. See the <b>-snapshot</b>
|
|
argument for more information.</b></p>
|
|
<p><b>Reading and writing the backing source file specified by <b>-source</b>
|
|
cannot be transaction protected because it involves filesystem
|
|
operations that are not part of the Berkeley DB transaction methodology.</b>
|
|
For this reason, if a temporary database is used to hold the records,
|
|
it is possible to lose the contents of the <b>-file</b> file, for
|
|
example, if the system crashes at the right instant. If a file is used
|
|
to hold the database, that is, a filename was specified as the
|
|
<b>file</b> argument to <b>berkdb open</b>, normal database recovery on
|
|
that file can be used to prevent information loss, although it is still
|
|
possible that the contents of <b>-source</b> will be lost if the system
|
|
crashes.</p>
|
|
<p>The <b>-source</b> file must already exist (but may be zero-length) when
|
|
<b>berkdb open</b> is called.</p>
|
|
<p>It is not an error to specify a read-only <b>-source</b> file when
|
|
creating a database, nor is it an error to modify the resulting database.
|
|
However, any attempt to write the changes to the backing source file using
|
|
either the <i>db</i> <b>close</b> or <i>db</i> <b>sync</b> commands will fail, of course.
|
|
Specify the <b>-nosync</b> argument to the <i>db</i> <b>close</b> command will
|
|
stop it from attempting to write the changes to the backing file; instead,
|
|
they will be silently discarded.</p>
|
|
<p>For all of the previous reasons, the <b>-source</b> file is generally
|
|
used to specify databases that are read-only for Berkeley DB applications,
|
|
and that are either generated on the fly by software tools, or modified
|
|
using a different mechanism such as a text editor.</p></ul>
|
|
<b>-truncate</b><ul compact><li>Physically truncate the underlying file, discarding all previous databases
|
|
it might have held. Underlying filesystem primitives are used to
|
|
implement this flag. For this reason, it is only applicable to the
|
|
physical file and cannot be used to discard databases within a file.
|
|
<p>The <b>-truncate</b> argument cannot be transaction-protected, and it is
|
|
an error to specify it in a transaction-protected environment.</p></ul>
|
|
<b>-txn txnid</b><ul compact><li>If the operation is part of an application-specified transaction, the
|
|
<b>txnid</b> parameter is a transaction handle returned from
|
|
<i>env</i> <b>txn</b>. If no transaction handle is specified, but the
|
|
-auto_commit flag is specified,
|
|
the operation will be implicitly transaction protected.</ul>
|
|
<b>--</b><ul compact><li>Mark the end of the command arguments.</ul>
|
|
<b>file</b><ul compact><li>The name of a single physical file on disk that will be used to back the
|
|
database.</ul>
|
|
<b>database</b><ul compact><li>The <b>database</b> argument allows applications to have multiple
|
|
databases inside of a single physical file. This is useful when the
|
|
databases are both numerous and reasonably small, in order to avoid
|
|
creating a large number of underlying files. It is an error to attempt
|
|
to open a second database file that was not initially created using a
|
|
<b>database</b> name.
|
|
<p>Applications opening multiple databases in a single file will almost
|
|
certainly need to create a shared database environment. See
|
|
<a href="../ref/am/opensub.html">Opening multiple databases in a single
|
|
file</a> for more information.</p></ul>
|
|
<br>
|
|
<p>The <b>berkdb open</b> command returns a database handle on success.</p>
|
|
<p>In the case of error, a Tcl error is thrown.</p>
|
|
</tt>
|
|
<table width="100%"><tr><td><br></td><td align=right>
|
|
<a href="../api_tcl/api_tcl.html"><img src="../images/api.gif" alt="API"></a><a href="../ref/toc.html"><img src="../images/ref.gif" alt="Ref"></a>
|
|
</td></tr></table>
|
|
<p><font size=1>Copyright (c) 1996,2008 Oracle. All rights reserved.</font>
|
|
</body>
|
|
</html>
|