The Berkeley DB Upgrade Tests

Quick ref:

    Running the tests:
	(in tclsh)
	% source ../test/test.tcl
	% upgrade

    Generating the test databases:
	(in tclsh)
	% source ../test/test.tcl
	% gen_upgrade /where/you/want/them

	(in your shell)
	$ cd /where/you/want/them
	$ perl $db_dir/upgrade/scripts/pack-3.0.pl
	$ mv 3.0 $db_dir/upgrade/databases

What they are:

The DB upgrade tests are a framework for testing two main features of
Berkeley DB:  the db_dump utility, and the "DB_UPGRADE" flag to DB->open.
They work by taking a tarred, gzipped set of test databases and dumps, and
verifying that the set of items is the same in the original database (as
dumped by the version of DB that created it) as in the upgraded one,
and is the same in the original database and in a new database generated by
db_loading a db_dump.

In db 3.X and higher, the upgrade test is repeated on a database with
the opposite endianness to the system the database was generated on.

How to generate test databases:

Ordinarily, this is something that only very rarely has to occur;
an archive of upgrade test databases can and should be kept, so ideally
the generation step only needs to be done once for each major DB release.

To generate the test databases, execute the command "gen_upgrade <dir>"
inside a tclsh.  The method tests will run twice, once for each endianness,
and all the databases will be saved in a hierarchy named by <dir>.

Once the databases have been built, the archives expected by the upgrade tests
must be built using the "pack" script, in upgrade/scripts/pack-<version>.pl.
This script must be edited slightly to specify the location on a given system
of the DB source tree and utilities;  it then converts the set of databases
under the current working directory into a set of .tar.gz files containing
the databases as well as flat files with their contents in item-by-item and
db_dump formats.

How to run the upgrade tests:

Run "upgrade" from tclsh in the DB build directory.  By default, this
looks in upgrade/databases, in the DB source tree.  An optional first argument
can be used to specify an alternate directory.

A note on 2.X tests:

The 2.X packing script, as well as a patch against a 2.6.6 test directory
to allow it to generate test databases, is in upgrade/generate-2.X.

Note that the upgrade tests can be *run* on an the 2.X test archives
without anything in this directory.  It is provided only for
archival reasons, in case there is ever reason to generate a new
set of test databases.

XXX: Note also that it quite likely has paths hard-coded for a specific
system that is not yours.

Known Issues:

1. The following 2.X databases trigger a bug in the db 2.X hash code.
This bug affects only empty and near-empty databases, and has been
corrected in db 3.X, but it will prevent the following from passing
the db_dump test.  (They have been removed from the canonical database
collection.)

    2.X hash -- test026
    2.X hash -- test038
    2.X hash -- test039
    2.X hash -- test040

2. The 2.X recno versions of test043 cannot be made to pass the db_dump
test because the 2.X version of db_dump has no -k flag and cannot preserve
sparsely populated databases.