Edgewall Software

Changes between Initial Version and Version 1 of TracDev/DatabaseUpgrades


Ignore:
Timestamp:
May 18, 2005, 5:47:20 PM (17 years ago)
Author:
Christopher Lenz
Comment:

Some documentation about database upgrades

Legend:

Unmodified
Added
Removed
Modified
  • TracDev/DatabaseUpgrades

    v1 v1  
     1= Trac Database Upgrade Scripts =
     2
     3Whenever 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.
     4
     5== How it works ==
     6
     7A Trac environment stores the version of the database schema in the database itself:
     8{{{
     9 $ sqlite3 /var/trac/test/db/trac.db "SELECT * FROM system"
     10 database_version|12
     11}}}
     12
     13On the other side, the Trac code stores the version number it requires in the {{{trac.db_default}}} module:
     14{{{
     15 $ PYTHONPATH=. python
     16 Python 2.3.5 (#1, Mar 20 2005, 20:38:20)
     17 [GCC 3.3 20030304 (Apple Computer, Inc. build 1809)] on darwin
     18 Type "help", "copyright", "credits" or "license" for more information.
     19 >>> from trac import db_default
     20 >>> db_default.db_version
     21 12
     22}}}
     23
     24Both 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.
     25
     26This 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.
     27
     28Database 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.
     29
     30----
     31See also: TracDev