Edgewall Software

Changes between Version 13 and Version 14 of TracDev/PluginDevelopment/ExtensionPoints/trac.env.IEnvironmentSetupParticipant


Ignore:
Timestamp:
Mar 26, 2015, 9:01:11 PM (9 years ago)
Author:
Peter Suter
Comment:

Example plugin from #8172

Legend:

Unmodified
Added
Removed
Modified

  • TracDev/PluginDevelopment/ExtensionPoints/trac.env.IEnvironmentSetupParticipant

    v13 v14  
    1 == Extension Point : ''IEnvironmentSetupParticipant'' ==
     1== Extension Point : ''IEnvironmentSetupParticipant''
    22
    33||'''Interface'''||''IEnvironmentSetupParticipant''||'''Since'''||0.9||
    … …  
    66The ''IEnvironmentSetupParticipant'' will be called during both the creation of a new environment (''trac-admin <env-dir> initenv'') and on upgrade of an existing environment (''trac-admin <env-dir> upgrade'').
    77
    8 == Purpose ==
     8== Purpose
    99
    1010Responsibilities of the interface are to both participate in the creation of a new environment and during upgrade of an existing 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.
    … …  
    1212On 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.
    1313
    14 == Usage ==
     14== Usage
    1515
    1616Implementing the interface follows the standard guidelines found in [wiki:TracDev/ComponentArchitecture] and of course [wiki:TracDev/PluginDevelopment].
    1717
    18 == Examples ==
     18== Examples
    1919
    2020The 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''.
    … …  
    4343}}}
    4444
    45 == Available Implementations ==
     45=== DB upgrades
     46
     47A more realistic use case would be a plugin that maintains its own database tables and provides scripts for automatically upgrading the database schema.
     48
     49The `DatabaseManager` class provides several methods that can be used to run these scripts. (Since Trac 1.1.5, see #8172)
     50
     51An entire example plugin would consists of the following files and directories:
     52
     53* `example/`
     54  * `upgrades`
     55    * `__init__.py` (empty)
     56    * `db2.py`
     57{{{#!python
     58def do_upgrade(env, ver, cursor):
     59    pass # Change the database schema here
     60}}}
     61  * `__init__.py` (empty)
     62  * `core.py`
     63{{{#!python
     64from trac.core import *
     65from trac.env import *
     66from trac.db.api import DatabaseManager
     67from trac.db.schema import Table, Column
     68
     69PLUGIN_NAME = 'ExamplePlugin'
     70PLUGIN_VERSION = 2
     71PLUGIN_SCHEMA = [
     72    Table('table1', key='name')[
     73        Column('name'),
     74        Column('value')]]
     75INITIAL_PLUGIN_DATA = (
     76    ('table1',
     77      ('name', 'value'),
     78        (('name1', 'value1'),
     79         ('name2', 'value2'))),)
     80
     81class ExamplePlugin(Component):
     82
     83    implements(IEnvironmentSetupParticipant)
     84
     85    # IEnvironmentSetupParticipant methods
     86
     87    def environment_created(self):
     88        dbm = DatabaseManager(self.env)
     89        dbm.create_tables(PLUGIN_SCHEMA)
     90        dbm.insert_into_tables(INITIAL_PLUGIN_DATA)
     91        dbm.set_database_version(PLUGIN_VERSION, PLUGIN_NAME)
     92
     93    def environment_needs_upgrade(self):
     94        dbm = DatabaseManager(self.env)
     95        return dbm.needs_upgrade(PLUGIN_VERSION, PLUGIN_NAME)
     96
     97    def upgrade_environment(self):
     98        dbm = DatabaseManager(self.env)
     99        if dbm.get_database_version(PLUGIN_NAME) == 0:
     100            dbm.create_tables(PLUGIN_SCHEMA)
     101            dbm.insert_into_tables(INITIAL_PLUGIN_DATA)
     102            dbm.set_database_version(PLUGIN_VERSION, PLUGIN_NAME)
     103        else:
     104            dbm.upgrade(PLUGIN_VERSION, PLUGIN_NAME, 'example.upgrades')
     105}}}
     106* `setup.py`
     107{{{#!python
     108#!/usr/bin/env python
     109from setuptools import setup
     110setup(name = 'example', version = '1.0',
     111      packages = ['example', 'example.upgrades'],
     112      entry_points = {'trac.plugins': ['example.core = example.core']})
     113}}}
     114
     115== Available Implementations
    46116
    47117 * [source:trunk/trac/env.py#L556 trac.env.EnvironmentSetup][[br]]
    … …  
    49119
    50120
    51 == Additional Information and References ==
     121== Additional Information and References
    52122
    53123 * Preventing data corruption on upgrade[[br]]
    … …  
    64134 * #8172 aims to introduce more helper methods that simplify implementing this interface according to best practices.
    65135
    66 ==== API History ====
     136==== API History
    67137
    68138* 0.9 introduced the interface. (changeset:1785)