The SWI-Prolog interface for DB allows for fast storage of arbitrary Prolog terms in the database.
The native Prolog database is not very well suited for either very large data-sets or dynamically changing large data-sets that need to be communicated between Prolog instances or need to be safely guarded against system failure. These cases ask for an external database that can be attached quickly and provides protection against system failure.
The Berkeley DB package is an open source library realising the bottom-layers of a database. It is a modular system, which in it's simplest deals with resource management on a mapped file and in its most complex form deals with network transparency, transaction management, locking, recovery, life-backup, etc.
The DB library maps keys to values. Optionally multiple values can be associated with a key. Both key and value are arbitrary-length binary objects.
This package stores arbitrary Prolog terms into the database, serializing them using PL_record_external(). This provides an interface similar to the recorded-database (recorda/3), which supports terms with internal sharing, cycles and attributes. In addition, it can store restricted data types such as atoms, strings and integers using standard representations which allows for sharing the database with other languages.
This manual is by no means complete. The Berkeley DB documentation should be consulted directly to resolve details on security, resource usage, formats, configuration options etc. This interface passed default values for most DB API calls. Supported options hint to the corresponding DB API calls, which should be consulted for details.
This package realises a binding to Berkeley DB, originally by Sleepycat Software, now managed by Oracle. The DB library implements modular support for the bottom layers of a database. In can be configured for single-threaded access to a file, multi-threaded access with transactions, remote access as well as database replication.
Berkeley DB is an embedded database. This implies the library provides access to a file containing one or more database tables. The Berkeley DB database tables are always binary, mapping a key to a value. The SWI-Prolog interface to Berkeley DB allows for fast storage of arbitrary Prolog terms including cycles and constraints in the database.
Accessing a database consists of four steps:
Errors reported by the underlying database are mapped to an
exception of the form error(bdb(Code,Message,Object), _),
where Code is an atom for well known errors and an integer
for less known ones. Message is the return from the db_strerror()
function and Object is the most related Prolog object,
typically a database or database environment handle. If Code
is an atom, it is the lowercase version of the associated C macro after
string the DB_ prefix. Currently the following atom-typed
codes are defined: lock_deadlock, runrecovery,
notfound, keyempty, keyexist, lock_notgranted
and
secondary_bad.
environment(+Environment) option. If bdb_init/1
is called, it must be called before the first call to bdb_open/4
that uses the default environment. If bdb_init/1
is not called, the default environment can only handle plain files and
does not support multiple threads, locking, crash recovery, etc.
Initializing a BDB environment always requires the home(+Dir)
option. If the environment contains no databases, the argument
create(true) must be supplied as well.
The currently supported options are listed below. The name of the
boolean options are derived from the DB flags by dropping the =DB_=
prefix and using lowercase, e.g. DB_INIT_LOCK becomes init_lock.
For details, please refer to the DB manual.
true, create any underlying file as required. By
default, no new files are created. This option should be set for
prograns that create new databases.DB_INIT_LOCK). Implied if transactions are
used.DB_INIT_LOG). Logging
enables recovery of databases in case of system failure. Normally it is
used in combination with transactions.mp_size(+Size) or
mp_mmapsize(+Size) is specified.init_log(true).DB_INIT_MPOOL). The
mp_size option sets the memory-pool used for caching, while
the mp_mmapsize controls the maximum size of a DB file
mapped entirely into memory.berkeley_db_svc. Optionally additional options may be
specified:
DB_ENV->set_thread_count().read,
providing read-only access or update, providing read/write
access.
Options is a list of options. Supported options are below.
The boolean options are passed as flags to DB->open().
The option name is derived from the flag name by stripping the
DB_ prefix and converting to lower case. Consult the
Berkeley DB documentation for details.
create(true), fail if the database already
exists.| DB | is unified with a blob of type db.
Database handles are subject to atom garbage collection. |
permission_error(access, bdb_environment, Env) if an
environment is not thread-enabled and accessed from multiple threads.bdb_put(DB, f(X), 42), we get the following query results:
bdb_get(DB, f(Y), V) binds Value to 42,
while Y is left unbound.bdb_get(DB, f(a), V) fails.bdb_enum(DB, f(a), V) succeeds, but does not perform
any indexing, i.e., it enumerates all key-value pairs and performs the
unification.error(package(db, deadlock), _)
This exception indicates a deadlock was raised by one of the DB predicates. Deadlocks may arise if multiple processes or threads access the same keys in a different order. The DB infra-structure causes one of the processes involved in the deadlock to abort its transaction. This process may choose to restart the transaction.
For example, a DB application may define {Goal} to
realise transactions and restart these automatically is a deadlock is
raised:
{Goal} :-
catch(bdb_transaction(Goal), E, true),
( var(E)
-> true
; E = error(package(db, deadlock), _)
-> {Goal}
; throw(E)
).
| Environment | defines the environment to which the transaction applies. If omitted, the default environment is used. See bdb_init/1 and bdb_init/2. |
DB_VERSION_MAJOR*10000 + DB_VERSION_MINOR*100 + DB_VERSION_PATCH
The SWI-Prolog interface code is licensed under the same conditions as SWI-Prolog itself.
The following is the license that applies to this copy of the Berkeley DB software. For a license to use the Berkeley DB software under conditions other than those described here, or to purchase support for this software, please contact Oracle at berkeleydb-info_us@oracle.com.
/* * Copyright (c) 1990, 2010 Oracle and/or its affiliates. All rights reserved. * * Redistribution and use in source and binary forms, with or without * modification, are permitted provided that the following conditions * are met: * 1. Redistributions of source code must retain the above copyright * notice, this list of conditions and the following disclaimer. * 2. Redistributions in binary form must reproduce the above copyright * notice, this list of conditions and the following disclaimer in the * documentation and/or other materials provided with the distribution. * 3. Redistributions in any form must be accompanied by information on * how to obtain complete source code for the DB software and any * accompanying software that uses the DB software. The source code * must either be included in the distribution or be available for no * more than the cost of distribution plus a nominal fee, and must be * freely redistributable under reasonable conditions. For an * executable file, complete source code means the source code for all * modules it contains. It does not include source code for modules or * files that typically accompany the major components of the operating * system on which the executable file runs. * * THIS SOFTWARE IS PROVIDED BY ORACLE ``AS IS'' AND ANY EXPRESS OR * IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED * WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, OR * NON-INFRINGEMENT, ARE DISCLAIMED. IN NO EVENT SHALL ORACLE BE LIABLE * FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR * CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF * SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR * BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, * WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE * OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN * IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. */ /* * Copyright (c) 1990, 1993, 1994, 1995 * The Regents of the University of California. All rights reserved. * * Redistribution and use in source and binary forms, with or without * modification, are permitted provided that the following conditions * are met: * 1. Redistributions of source code must retain the above copyright * notice, this list of conditions and the following disclaimer. * 2. Redistributions in binary form must reproduce the above copyright * notice, this list of conditions and the following disclaimer in the * documentation and/or other materials provided with the distribution. * 3. Neither the name of the University nor the names of its contributors * may be used to endorse or promote products derived from this software * without specific prior written permission. * * THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND * ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE * ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE * FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL * DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS * OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) * HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT * LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY * OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF * SUCH DAMAGE. */ /* * Copyright (c) 1995, 1996 * The President and Fellows of Harvard University. All rights reserved. * * Redistribution and use in source and binary forms, with or without * modification, are permitted provided that the following conditions * are met: * 1. Redistributions of source code must retain the above copyright * notice, this list of conditions and the following disclaimer. * 2. Redistributions in binary form must reproduce the above copyright * notice, this list of conditions and the following disclaimer in the * documentation and/or other materials provided with the distribution. * 3. Neither the name of the University nor the names of its contributors * may be used to endorse or promote products derived from this software * without specific prior written permission. * * THIS SOFTWARE IS PROVIDED BY HARVARD AND ITS CONTRIBUTORS ``AS IS'' AND * ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE * ARE DISCLAIMED. IN NO EVENT SHALL HARVARD OR ITS CONTRIBUTORS BE LIABLE * FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL * DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS * OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) * HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT * LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY * OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF * SUCH DAMAGE. */ =-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-= /*** * ASM: a very small and fast Java bytecode manipulation framework * Copyright (c) 2000-2005 INRIA, France Telecom * All rights reserved. * * Redistribution and use in source and binary forms, with or without * modification, are permitted provided that the following conditions * are met: * 1. Redistributions of source code must retain the above copyright * notice, this list of conditions and the following disclaimer. * 2. Redistributions in binary form must reproduce the above copyright * notice, this list of conditions and the following disclaimer in the * documentation and/or other materials provided with the distribution. * 3. Neither the name of the copyright holders nor the names of its * contributors may be used to endorse or promote products derived from * this software without specific prior written permission. * * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE * ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE * LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR * CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF * SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS * INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN * CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) * ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF * THE POSSIBILITY OF SUCH DAMAGE. */