db4* > This port is marked DEPRECATED

Matthias Andree mandree at FreeBSD.org
Sat Dec 14 12:43:49 UTC 2013

Am 14.12.2013 11:21, schrieb Per olof Ljungmark:
> Hello list,
> Before I go ahead and replace db4* with db5* everywhere, are there any
> caveats to it? I saw no notes in UPDATING but perhaps I missed it?

I have not added them yet.

> I suppose it should be as easy as shutting down the running application,
> upgrade and start again?
> Don't want to shoot myself in foot for the nth. time...

I have added information to

and will link to it from UPDATING.

Here is a summary:

That depends on the application and how exactly it uses Berkeley DB.
Applications should document their upgrade requirements.

Bogofilter for instance does, see its doc/README.db.

I will first show the Oracle links that document the process, and then
give a summary overview below.


The reference documentation is at

and detailed information on the version upgrades is at:

- for versions up to 4.7: (older versions at the bottom)

- for versions 4.8 to 6: (older versions at the bottom)


Warnings and Hints:

- when you are using transactional databases (those that store log.*
files), you must make sure that databases are consistent.  A newer
Berkeley DB version (even a minor) can usually *not* recover from logs
that an older version has written.


- if you've been using *queue* databases in db 4, 4.0 or 4.1 with
certain features, you may need to dump them before the upgrade and
reload them after the upgrade. See
to see if that applies for your application.

- if you've been using *hash* databases with a version 4.5 or older, and
are upgrading to 4.6 or newer, dumping/reloading the databases can
improve performance


Summary overview:

If the application just uses Berkeley DB as a trivial key/value database
(single .db file, no __db.* files, no log.* files), then it's as simple
as you describe.  DB 6 is documented to still be able to read DB 4.0

However, when transaction log.* files are used, they are usually
incompatible between one version and the next, so

If the application uses any sophisticated features, make sure that all
databases are consistent before upgrading.

If the application sets up an environment, that may need recovery and

If it applications use Berkeley DB in transactional mode
(log.0123456789-like files), which brings with it an environment,
or otherwise set up Berkeley DB environments (__db.001 files) for
instance for locking, then make sure that you:

1. shut down all application instances (processes) orderly

2. see to it that all databases are consistent (run recovery if
necessary - there are dbXX_recover and for some versions db_recover-XX
utilities to achieve that)

3. backup databases, environments, logfiles

4. if the application offers a "database dump to text"-like utility, use
it and backup the result.  Else you can use db*_dump* and db*_load*

5. in doubt, remove the database environment, the application would
normally recreate it on start

6. install the new Berkeley DB version (you can also upgrade to db6, but
there has been a license change to Affero GPL meaning you must
opensource software-as-a-service; so I am recommending db5 which still
has the SleepyCat license, and I have no plans to deprecate db5 due to
the different license).

7. rebuild the applications to use the new Berkeley DB version, you can
set WITH_BDB_VER=5 or WITH_BDB_VER=6 in /etc/make.conf, or
uniquename_WITH_BDB_VER=5 (where uniquename is what your port's
UNIQUENAME is, for instance, bogofilter_WITH_BDB_VER=6)

8. restart applications

a. If applications fail to restart after the upgrade complaining about
incompatible options, you may need to edit DB_CONFIG files if one of the
options you were using was renamed or removed.

b. If applications fail to restart after the upgrade and complaining
they are unable to join an environment, removing the environment (__db.*
files) usually suffices.

Hope that helps, and do not hesitate to ask.

More information about the freebsd-ports mailing list