8.3.2 Changing the Schema

To make a change to the database schema, follow these steps:

1. Increment CURRENT_VERSION in buildbot/db/schema/manager.py by one. This is your new version number.
2. Create buildbot/db/schema/vN.py, where N is your version number, by copying the previous script and stripping it down. This script should define a subclass of buildbot.db.schema.base.Updater named Updater.

   The class must define the method upgrade, which takes no arguments. It should upgrade the database from the previous version to your version, including incrementing the number in the VERSION table, probably with an UPDATE query.

   Consult the API documentation for the base class for information on the attributes that are available.

3. Edit buildbot/test/unit/test_db_schema_master.py. If your upgrade involves moving data from the basedir into the database proper, then edit fill_basedir to add some test data.

   Add code to assertDatabaseOKEmpty to check that your upgrade works on an empty database.

   Add code to assertDatabaseOKFull to check that your upgrade works on a database with pre-existing data. Do this even if your changes do not move any data from the basedir.

   Run the tests to find the bugs you introduced in step 2.

4. Increment the version number in the test_get_current_version test in the same file. Only do this after you've finished the previous step - a failure of this test is a good reminder that testing isn't done yet.
5. Updated the version number in buildbot/db/schema/tables.sql, too.
6. Finally, make the corresponding changes to buildbot/db/schema/tables.sql.