.. -*- mode: rst; encoding: utf-8 -*-

=========
Upgrading
=========

.. contents:: Contents
   :depth: 1
.. sectnum::


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.

.. note::

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

.. note::

   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.
      

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.

.. _script: http://bitten.edgewall.org/browser/trunk/contrib/deletebuild.py


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.

.. _gerald: http://pypi.python.org/pypi/gerald


Upgrade history
===============

The current version of the Bitten schema is version 12.

Version 12
----------

* `last activity` column added to `bitten_build`.

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.

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.

.. note::

  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. 
   
Version 9
---------

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

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.

Version 7
---------

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

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`.

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.

Version 4
---------

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

Version 3
---------

* The `recipe` column was added to `bitten_config` to store the recipe XML.

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.

Version 1
---------

* The first Bitten database schema.