Berkeley DB Reference Guide: RPC Client/Server

Client program

Changing a Berkeley DB application to remotely call a server program requires only a few changes on the client side:

1. The client application must create and use a Berkeley DB environment, that is, it cannot simply call the db_create interface, but must first call the db_env_create interface to create an environment in which the database will live.

2. The client application must call db_env_create using the DB_CLIENT flag.

3. The client application must call the additional DB_ENV method DBENV->set_server to specify the database server. This call must be made before opening the environment with the DBENV->open call.

The client application provides three pieces of information to Berkeley DB as part of the DBENV->set_server call:

1. The hostname of the server. The hostname format is not specified by Berkeley DB, but must be in a format acceptable to the local network support, specifically, the RPC clnt_create interface.

2. The client timeout. This is the number of seconds the client will wait for the server to respond to its requests. A default is used if this value is zero.

3. The server timeout. This is the number of seconds the server will allow client resources to remain idle before releasing those resources. The resources this applies to are transactions and cursors, as those objects hold locks and if a client dies, the server needs to release those resources in a timely manner. This value is really a hint to the server, as the server may choose to override this value with its own.

The only other item of interest to the client is the home directory that is given to the DBENV->open call. The server is started with a list of allowed home directories. The client must use one of those names (where a name is the last component of the home directory). This allows the pathname structure on the server to change without client applications needing to be aware of it.

Once the DBENV->set_server call has been made, the client is connected to the server and all subsequent Berkeley DB operations will be forwarded to the server. The client does not need to be otherwise aware that it is using a database server rather than accessing the database locally.

It is important to realize that the client portion of the Berkeley DB library acts as a simple conduit, forwarding Berkeley DB interface arguments to the server without interpretation. This has two important implications. First, all pathnames must be specified relative to the server. For example, the home directory and other configuration information passed by the application when creating its environment or databases must be pathnames for the server, not the client system. In addition, as there is no logical bundling of operations at the server, performance is usually significantly less than when Berkeley DB is embedded within the client's address space, even if the RPC is to a local address.

Copyright Sleepycat Software