Extension Point : IEnvironmentSetupParticipant

Interface	IEnvironmentSetupParticipant	Since	TBD
Module	trac.env	Source	env.py​

The IEnvironmentSetupParticipant is responsible for either creating a new environment or to upgrade (aka migrate) an existing environment to a newer version of that environment.

Implementations of the extension point interface will be called during both trac-admin <env-dir> initenv and on trac-admin <env-dir> upgrade.

Purpose

Responsibilities of the interface are to participate in the creation of a new environment. This includes adding information to the database schema, such as table declarations and so on. Some implementations, see below, might also opt in for adding default data to the newly created database, or to set up the folder where the environment will be created in.

On environment upgrade, the responsibilities of the participant are to non-destructively migrate existing user data to a newer database schema, provided that the data model has changed at the SQL level, and of course to migrate the environment's folder structure and content to meet the requirements of the participant.

Usage

Implementing the interface follows the standard guidelines found in TracDev/ComponentArchitecture and of course TracDev/PluginDevelopment.

Examples

The following example basically does nothing more than logging to the standard log file during either trac-admin <env-dir> initenv or trac-admin <env-dir> upgrade.

from trac.core import implements, Component

class SampleEnvironmentSetupParticipant(Component):

    implements(IEnvironmentSetupParticipant)

    # IEnvironmentSetupParticipant methods

    def environment_created():
        self.log.debug("creating environment for sample plugin.")
        pass

    def environment_needs_upgrade(db):
        self.log.debug("the existing environment requires an upgrade for sample plugin.")
        return True

    def upgrade_environment(db):
        self.log.debug("upgrading existing environment for sample plugin.")
        pass

Available Implementations

• trac.env.EnvironmentSetup​
  This is the setup participant that will initialize the trac database and also the sample configuration provided with each trac instance, providing sane initial defaults for use with both an existing environment and a newly created one. For the creation of a new environment it uses the default db structure​. and on upgrade it will use a db upgrade path defined in the individual db*.py modules therein. The version number of the trac database schema is available from the system table, the key to look for is database_version. The value of this system property will be updated on environment upgrade. In addition to that, trac will also keep track of the initial database version that was installed when first creating the environment. The key to look for in the system table is initial_database_version.