Ticket #8172: db-upgrade-helpers.patch

trac/env.py

@@ -560 +560 @@
         :since 0.13: deprecation warning: the `db` parameter is no
                      longer used and will be removed in version 0.14
         """
-        rows = self.db_query("""
-                SELECT value FROM system WHERE name='%sdatabase_version'
-                """ % ('initial_' if initial else ''))
-        return rows and int(rows[0][0])
+        return get_environment_version_for_module(self, 
+            'initial_database_version' if initial else 'database_version')
 
     def setup_config(self):
         """Load the configuration file."""
@@ -706 +704 @@
 
     def environment_created(self):
         """Insert default data into the database."""
-        with self.env.db_transaction as db:
-            for table, cols, vals in db_default.get_data(db):
-                db.executemany("INSERT INTO %s (%s) VALUES (%s)"
-                   % (table, ','.join(cols), ','.join(['%s' for c in cols])),
-                   vals)
+        init_environment_data_for_module(self.env, db_default.get_data)
         self._update_sample_config()
 
     def environment_needs_upgrade(self, db):
-        dbver = self.env.get_version(db)
-        if dbver == db_default.db_version:
-            return False
-        elif dbver > db_default.db_version:
-            raise TracError(_('Database newer than Trac version'))
-        self.log.info("Trac database schema version is %d, should be %d",
-                      dbver, db_default.db_version)
-        return True
+        return environment_needs_upgrade_for_module(self.env, 'Trac',
+                                                    'database_version',
+                                                    db_default.db_version)
 
     def upgrade_environment(self, db):
         """Each db version should have its own upgrade module, named
         upgrades/dbN.py, where 'N' is the version number (int).
         """
-        cursor = db.cursor()
-        dbver = self.env.get_version()
-        for i in range(dbver + 1, db_default.db_version + 1):
-            name  = 'db%i' % i
-            try:
-                upgrades = __import__('upgrades', globals(), locals(), [name])
-                script = getattr(upgrades, name)
-            except AttributeError:
-                raise TracError(_("No upgrade module for version %(num)i "
-                                  "(%(version)s.py)", num=i, version=name))
-            script.do_upgrade(self.env, i, cursor)
-            cursor.execute("""
-                UPDATE system SET value=%s WHERE name='database_version'
-                """, (i,))
-            self.log.info("Upgraded database version from %d to %d", i - 1, i)
-            db.commit()
+        upgrade_environment_for_module(self.env, 'Trac', 'database_version',
+                                       db_default.db_version,
+                                       'upgrades')
         self._update_sample_config()
 
     # Internal methods
@@ -817 +793 @@
 
     return env
 
+def init_environment_version_for_module(env, name, version):
+    """Set the current module version in the database.
+    
+    :since: 0.13
+    """
+    with env.db_transaction as db:
+        cursor = db.cursor()
+        cursor.execute("""
+            INSERT INTO system (name, value)
+            VALUES (%s, %s)
+            """, (name, version))
+
+def init_environment_schema_for_module(env, schema):
+    """Setup db schema for this module in the database.
+    
+    :since: 0.13
+    """
+    db_connector, _ = DatabaseManager(env).get_connector()
+    with env.db_transaction as db:
+        cursor = db.cursor()
+        for table in schema:
+            for stmt in db_connector.to_sql(table):
+                cursor.execute(stmt)
+
+def init_environment_data_for_module(env, get_initial_data):
+    """Insert initial data into the database.
+    
+    :since: 0.13
+    """
+    with env.db_transaction as db:
+        for table, cols, vals in get_initial_data(db):
+                db.executemany("INSERT INTO %s (%s) VALUES (%s)"
+                   % (table, ','.join(cols), ','.join(['%s' for c in cols])),
+                   vals)
+
+def get_environment_version_for_module(env, name):
+    """Get the current module version from the database.
+
+    Returns `False` if the environment has not been setup for this module,
+    which is "older" than any db version number.
+
+    :since: 0.13
+    """
+    rows = env.db_query("""
+            SELECT value FROM system WHERE name='%s'
+            """ % name)
+    return rows and int(rows[0][0])
+
+def environment_needs_upgrade_for_module(env, name, field, version):
+    """Check whether the environment needs to be upgraded for this module.
+
+    Commonly called from `IEnvironmentSetupParticipant` modules and plugins
+    to implement the method `environment_needs_upgrade`.
+    
+    :since: 0.13
+    """
+    dbver = get_environment_version_for_module(env, field)
+    if dbver == version:
+        return False
+    elif dbver > version:
+        raise TracError(_("Database newer than %(name)s version.", name=name))
+    env.log.info("%s database schema version is %d, should be %d",
+                  name, dbver, version)
+    return True
+
+def upgrade_environment_for_module(env, name, field, version, 
+                                   upgrades_pkg_name):
+    """Invoke `do_upgrade(env, version, cursor)` in module 
+    `"%s/db%i.py" % (upgrades_pkg_name, version)` for each 
+    required version upgrade.
+    
+    :since: 0.13
+    """
+    dbver = get_environment_version_for_module(env, field)
+    with env.db_transaction as db:
+        cursor = db.cursor()
+        for i in range(dbver + 1, version + 1):
+            module  = 'db%i' % i
+            try:
+                upgrades = __import__(upgrades_pkg_name, globals(), locals(),
+                                      [module])
+                script = getattr(upgrades, module)
+            except AttributeError:
+                msg = 
+                raise TracError(_("No upgrade module for version %(num)i "
+                                  "(%(module)s.py)", num=i, module=module)
+            script.do_upgrade(env, i, cursor)
+            cursor.execute("""
+                UPDATE system SET value=%s WHERE name='%s'
+                """, (i, name))
+            env.log.info("Upgraded database version from %d to %d"
+                          " for module %s", i - 1, i, name)
+            db.commit()
+
 
 class EnvironmentAdmin(Component):
     """trac-admin command provider for environment administration."""