mirror of
https://github.com/MariaDB/server.git
synced 2025-11-09 11:41:36 +03:00
301 lines
17 KiB
HTML
301 lines
17 KiB
HTML
<!--$Id: db_open.so,v 11.18 2000/11/27 18:14:47 sue Exp $-->
|
|
<!--$Id: m4.tcl,v 11.17 2000/04/24 17:31:11 sue Exp $-->
|
|
<!--Copyright 1997, 1998, 1999, 2000 by Sleepycat Software, Inc.-->
|
|
<!--All rights reserved.-->
|
|
<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,b+tree,btree,hash,hashing,transaction,transactions,locking,logging,access method,access methods,java,C,C++">
|
|
</head>
|
|
<body bgcolor=white>
|
|
<a name="2"><!--meow--></a>
|
|
<table><tr valign=top>
|
|
<td>
|
|
<h1><b>berkdb open</b></h1>
|
|
</td>
|
|
<td width="1%">
|
|
<a href="../api_tcl/tcl_index.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>
|
|
<h3><pre>berkdb open
|
|
[-btree | -hash | -recno | -queue | -unknown]
|
|
[-cachesize {gbytes bytes ncache}]
|
|
[-create]
|
|
[-delim delim]
|
|
[-dup]
|
|
[-dupsort]
|
|
[-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]
|
|
[-upgrade]
|
|
[--]
|
|
[file [database]]
|
|
</pre></h3>
|
|
<h1>Description</h1>
|
|
<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 (e.g., db0 and db1).
|
|
It is through this Tcl command that the script accesses the database
|
|
methods.
|
|
<p>The options are as follows:
|
|
<p><dl compact>
|
|
<p><dt>-btree<dd>Open/create a database of type Btree. The Btree format
|
|
is a representation of a sorted, balanced tree structure.
|
|
<p><dt>-hash<dd>Open/create a database of type Hash. The Hash format is
|
|
an extensible, dynamic hashing scheme.
|
|
<p><dt>-queue<dd>Open/create a database of type Queue. The Queue format
|
|
supports fast access to fixed-length records accessed by sequentially or
|
|
logical record number.
|
|
<p><dt>-recno<dd>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.
|
|
<p><dt>-unknown<dd>The database is of an unknown type, and must already exist.
|
|
<p><dt>-cachesize {gbytes bytes ncache}<dd>Set the size of the database's shared memory buffer pool, i.e., 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>It is possible to specify caches to Berkeley DB that are large enough so that
|
|
they cannot be allocated contiguously on some architectures, e.g., 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>For information on tuning the Berkeley DB cache size, see
|
|
<a href="../ref/am_conf/cachesize.html">Selecting a cache size</a>.
|
|
<p>As 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><dt>-create<dd>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.
|
|
<p><dt>-delim delim<dd>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 (i.e. ASCII 0x0a) are interpreted as end-of-record markers.
|
|
<p><dt>-dup<dd>Permit duplicate data items in the tree, i.e. 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>It is an error to specify both <b>-dup</b> and <b>-recnum</b>.
|
|
<p><dt>-dupsort<dd>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.
|
|
<p><dt>-env env<dd>If no <b>-env</b> argument is given, the database is standalone, i.e.,
|
|
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, then the access methods will automatically acquire the correct
|
|
locks when reading and writing pages of the database.
|
|
<p><dt>-errfile filename<dd>
|
|
<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>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>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 (e.g., env0), otherwise it will be the database command
|
|
name (e.g., db0).
|
|
<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>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><dt>-excl<dd>Return an error if the file already exists. Underlying filesystem
|
|
primitives are used to implement this flag. For this reason it is only
|
|
applicable to the physical database file and cannot be used to test if a
|
|
database in a file already exists.
|
|
<p><dt>-extent size<dd>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.
|
|
<p>For information on tuning the extent size, see
|
|
<a href="../ref/am_conf/extentsize.html">Selecting a extent size</a>.
|
|
<p><dt>-ffactor density<dd>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
|
|
<p><dt>-len len<dd>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>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>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><dt>-mode mode<dd>
|
|
<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 writeable by both
|
|
owner and group. On Windows systems, the mode argument is ignored.
|
|
<p><dt>-nelem size<dd>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><dt>-pad pad<dd>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 (i.e.,
|
|
ASCII 0x20) are used for padding.
|
|
<p><dt>-pagesize pagesize<dd>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><dt>-rdonly<dd>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.
|
|
<p><dt>-recnum<dd>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>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>It is an error to specify both <b>-dup</b> and <b>-recnum</b>.
|
|
<p><dt>-renumber<dd>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 1. If a cursor was
|
|
positioned to record number 4 before the deletion, it will reference 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 1 logical record, continuing to reference 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>If a created record is not at the end of the database, all records following
|
|
the new record will be automatically renumbered upward by 1. For example,
|
|
the creation of a new record numbered 8 causes records numbered 8 and
|
|
greater to be renumbered upward by 1. If a cursor was positioned to record
|
|
number 8 or greater before the insertion, it will be shifted upward 1
|
|
logical record, continuing to reference the same record as it did before.
|
|
<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><dt>-snapshot<dd>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.
|
|
<p><dt>-source file<dd>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>In addition, when cached data would normally be written back to the
|
|
underlying database file (e.g., 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>By default, the backing source file is read lazily, i.e., 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><b>Reading and writing the backing source file specified by <b>-source</b>
|
|
cannot be transactionally 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,
|
|
i.e., no <b>file</b> argument was specified to the <b>berkdb open</b> call,
|
|
it is possible to lose the contents of the <b>-file</b> file, e.g., if
|
|
the system crashes at the right instant. If a file is used to hold the
|
|
database, i.e., a file name 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>The <b>-source</b> file must already exist (but may be zero-length) when
|
|
<b>berkdb open</b> is called.
|
|
<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>For all of the above 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, e.g., a text editor.
|
|
<p><dt>-truncate<dd>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><dt>-upgrade<dd>Upgrade the database represented by <b>file</b>, if necessary.
|
|
<p><b>Note: Database upgrades are done in place and are
|
|
destructive, e.g., if pages need to be allocated and no disk space is
|
|
available, the database may be left corrupted. Backups should be made
|
|
before databases are upgraded. See <a href="../ref/am/upgrade.html">Upgrading databases</a> for more information.</b>
|
|
<p><dt>--<dd>Mark the end of the command arguments.
|
|
<p><dt>file<dd>The name of a single physical file on disk that will be used to back the
|
|
database.
|
|
<p><dt>database<dd>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.
|
|
</dl>
|
|
<p>The <b>berkdb open</b> command returns a database handle on success.
|
|
<p>In the case of error, a Tcl error is thrown.
|
|
</tt>
|
|
<table><tr><td><br></td><td width="1%">
|
|
<a href="../api_tcl/tcl_index.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><a href="http://www.sleepycat.com">Copyright Sleepycat Software</a></font>
|
|
</body>
|
|
</html>
|