Edgewall Software


Bitten's database schema is versioned using the bitten_version entry in Trac's system table. If you install a version of Bitten with a more recent schema you will need to run trac-admin update after installing Bitten to update your database. Until this done Trac will not activate your new Bitten installation.


You should back up your Trac database and Trac environment before running trac-admin upgrade.


If you are using a SQLite database file, Trac automatically creates a copy before proceeding with the update. This should not be relied upon but can be useful if you have ignored the advice above.

Bitten's upgrade scripts attempt to commit changes made to the database each time a new schema version is reached. This ensures that if an upgrade fails to complete the Bitten database is left in the most up-to-date state possible.

For example, if you were upgrading from Bitten schema 6 to schema version 12 and duplicate builds were found during the attempt to upgrade to schema 10, your database would be left at schema 9.

1   Removing Duplicate Builds

Bitten schema version 10 adds a unique index on the columns (config, platform, rev) to the bitten_build table. This constraint is relied on by Bitten but was not enforced in earlier versions and duplicate builds could arise. Before the upgrade to schema version 10 can complete, these duplicate builds must be removed. The trac-admin upgrade will produce a list of duplicates but the decision on which to keep remains with the user.

A script for removing builds is provided. This scripts supports schema versions 9 through 12.

2   Reporting Upgrade Issues

Debugging upgrade issues can be difficult since the Bitten development team does not have access to your database. Attaching a description of your database schema before and after running trac-admin upgrade to your request for assistance may help others diagnose the problem more swiftly.

You can create such a schema description using Gerald or a similar tool.

3   Upgrade history

The current version of the Bitten schema is version 12.

3.1   Version 12

  • last activity column added to bitten_build.

3.2   Version 11

  • Badly named log level files that ended with .log.level created by earlier versions of Bitten were renamed to end in .log.levels which is the correct extension.
  • Log level files that had not been correctly deleted by earlier versions of Bitten were cleaned up.

3.3   Version 10

  • PostgreSQL sequences on the id column that had not been correctly updated by previous Bitten upgrade scripts were corrected. This affected four tables: bitten_build, bitten_log, bitten_platform and bitten_report.
  • A unique index on the columns (config, platform, rev) was added to the bitten_build table and an old unique index on (config, rev, slave) was removed.


The lack of an index on (config, platform, rev) in ealier versions of Bitten allowed duplicate builds to be created in the database under some conditions. These duplicate builds need to be manually removed before the upgrade to version 10 can complete.

3.4   Version 9

  • The id column of the bitten_rule table was converted from a text column to an integer one.

3.5   Version 8

  • Log messages that had been stored in the bitten_log_messages table were migrated to files.
  • A filename field was added to the bitten_log table to record the location of the new log files.

3.6   Version 7

  • The bitten_error table as added to record the reasons for step failures.

3.7   Version 6

  • Filenames stored in the value column of bitten_report_item where normalized to use / as the path separator.
  • The generator columns in bitten_log and bitten_report previously stored just the short tag name of the associated generator. These were updated to store the full tag name of the generator (including the XML namespace). For example, pipe was changed to http://bitten.edgewall.org/tools/sh#pipe.

3.8   Version 5

  • An orderno column was added to the bitten_log table to record the order in which sets of log messages were generated.
  • The bitten_report and bitten_report_item tables were added to record reports generated by unit tests and other build tools.
  • Report data was imported from the old Berkeley DB XML store into the new database tables.

3.9   Version 4

  • The build configuration that generated a report was added to the report metadata in the Berkeley DB XML store.

3.10   Version 3

  • The recipe column was added to bitten_config to store the recipe XML.

3.11   Version 2

  • The bitten_log and bitten_log_message tables were created for storing log messages.
  • The log column was removed from bitten_step and the log messages where migrated to the two new logging tables.

3.12   Version 1

  • The first Bitten database schema.

See also: Documentation

Last modified 7 years ago Last modified on Dec 10, 2015, 6:20:00 AM