Berkeley DB Reference Guide: RPC Client/Server

Introduction

Berkeley DB includes an implementation of a client-server protocol using Sun Microsystem's Remote Procedure Call Protocol. RPC support is available only for UNIX systems, and is not included in the Berkeley DB library by default, but must be enabled during configuration. See Configuring Berkeley DB for more information. For more information on RPC itself, see your UNIX system documentation or RPC: Remote Procedure Call Protocol Specification, RFC1831, Sun Microsystems, Inc., USC-ISI.

Only some of the complete Berkeley DB functionality is available when using RPC. The following functionality is available:

1. The db_env_create function and the DB_ENV handle methods.
2. The db_create function and the DB handle methods.
3. The DB_ENV->txn_begin, DB_TXN->commit, and DB_TXN->abort methods.

The DB_THREAD flag to the DB_ENV->open and DB->open methods may not be specified, that is, DB_ENV and DB handles used in RPC clients are not free-threaded.

The RPC client/server code does not support any of the user-defined comparison or allocation functions; for example, an application using the RPC support may not specify its own Btree comparison function. If your application requires only those portions of Berkeley DB, then using RPC is fairly simple. If your application requires other Berkeley DB functionality, such as direct access to locking, logging or shared memory buffer memory pools, then your application cannot use the RPC support.

Although a client cannot specify a callback, Berkeley DB does support the DB->associate call in a limited manner. A client program wanting to use a secondary index may do so only in a read-only fashion. The primary and secondary databases must have been created locally on the server machine. Client programs must then open both the primary and secondary databases with the DB_RDONLY flag set. The client must also specify a NULL callback for the DB->associate call.

The Berkeley DB RPC code requires that the client and server programs be running the exact same version numbers. The Berkeley DB RPC protocol version number is tied to the Berkeley DB major and minor release numbers. As such, the server program will reject requests from clients using a different version number.

The Berkeley DB RPC support does not provide any security or authentication of any kind. Sites needing any kind of data security measures must modify the client and server code to provide whatever level of security they require.

One particularly interesting use of the RPC support is for debugging Berkeley DB applications. The seamless nature of the interface means that with very minor application code changes, an application can run outside of the Berkeley DB address space, making it far easier to track down many types of errors -- such as memory misuse.

Using the RPC mechanisms in Berkeley DB involves two basic steps:

1. Modify your Berkeley DB application to act as a client and call the RPC server.
2. Run the berkeley_db_svc server program on the system where the database resides.

Copyright (c) 1996-2003 Sleepycat Software, Inc. - All rights reserved.