= Trac Database Upgrade Scripts =

Whenever a change to the database schema becomes necessary (or in fact any kind of change that requires updating existing environments) you need to provide an upgrade script. These scripts are provided as Python files following a certain naming convention in the [source:/trunk/trac/upgrades#latest trac/upgrades] directory.

== How it works ==

A Trac environment stores the version of the database schema in the database itself:
{{{
 $ sqlite3 /var/trac/test/db/trac.db "SELECT * FROM system"
 database_version|12
}}}

On the other side, the Trac code stores the version number it requires in the {{{trac.db_default}}} module:
{{{
 $ PYTHONPATH=. python
 Python 2.3.5 (#1, Mar 20 2005, 20:38:20) 
 [GCC 3.3 20030304 (Apple Computer, Inc. build 1809)] on darwin
 Type "help", "copyright", "credits" or "license" for more information.
 >>> from trac import db_default
 >>> db_default.db_version
 12
}}}

Both these numbers need to be in sync for Trac to work properly. If the version number in the database is smaller than the version number in the code the database needs to be upgraded using the {{{upgrade}}} command in [wiki:TracAdmin trac-admin]. The upgrade works by retrieving all the upgrade scripts in {{{trac/upgrades}}} and applying them in order until the version numbers match again. To protect against data loss due to a bad script, a backup of the existing database file is made before the upgrade is performed.

This is where the naming pattern for the upgrade scripts come in. For example, an upgrade scripts that upgrades the database from version 12 to 13 must be named {{{db13.py}}}. This file must define a function called {{{do_upgrade()}}} which should do anything that's necessary to get the database upgraded. See the file [source:/trunk/trac/upgrades/db13.py#latest db13.py] to see how an upgrade script works.

Database version numbers do not correspond to releases. Indeed, there can be multiple upgrade scripts per release. This is to make it easier for users and developers to follow development in trunk, as they would otherwise need to perform the upgrade manually.

----
See also: TracDev