Changes between Version 13 and Version 14 of TracDev/PluginDevelopment/ExtensionPoints/trac.env.IEnvironmentSetupParticipant
- Timestamp:
- Mar 26, 2015, 9:01:11 PM (9 years ago)
Legend:
- Unmodified
- Added
- Removed
- Modified
-
TracDev/PluginDevelopment/ExtensionPoints/trac.env.IEnvironmentSetupParticipant
v13 v14 1 == Extension Point : ''IEnvironmentSetupParticipant'' ==1 == Extension Point : ''IEnvironmentSetupParticipant'' 2 2 3 3 ||'''Interface'''||''IEnvironmentSetupParticipant''||'''Since'''||0.9|| … … 6 6 The ''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''). 7 7 8 == Purpose ==8 == Purpose 9 9 10 10 Responsibilities 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. … … 12 12 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. 13 13 14 == Usage ==14 == Usage 15 15 16 16 Implementing the interface follows the standard guidelines found in [wiki:TracDev/ComponentArchitecture] and of course [wiki:TracDev/PluginDevelopment]. 17 17 18 == Examples ==18 == Examples 19 19 20 20 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''. … … 43 43 }}} 44 44 45 == Available Implementations == 45 === DB upgrades 46 47 A more realistic use case would be a plugin that maintains its own database tables and provides scripts for automatically upgrading the database schema. 48 49 The `DatabaseManager` class provides several methods that can be used to run these scripts. (Since Trac 1.1.5, see #8172) 50 51 An 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 58 def do_upgrade(env, ver, cursor): 59 pass # Change the database schema here 60 }}} 61 * `__init__.py` (empty) 62 * `core.py` 63 {{{#!python 64 from trac.core import * 65 from trac.env import * 66 from trac.db.api import DatabaseManager 67 from trac.db.schema import Table, Column 68 69 PLUGIN_NAME = 'ExamplePlugin' 70 PLUGIN_VERSION = 2 71 PLUGIN_SCHEMA = [ 72 Table('table1', key='name')[ 73 Column('name'), 74 Column('value')]] 75 INITIAL_PLUGIN_DATA = ( 76 ('table1', 77 ('name', 'value'), 78 (('name1', 'value1'), 79 ('name2', 'value2'))),) 80 81 class 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 109 from setuptools import setup 110 setup(name = 'example', version = '1.0', 111 packages = ['example', 'example.upgrades'], 112 entry_points = {'trac.plugins': ['example.core = example.core']}) 113 }}} 114 115 == Available Implementations 46 116 47 117 * [source:trunk/trac/env.py#L556 trac.env.EnvironmentSetup][[br]] … … 49 119 50 120 51 == Additional Information and References ==121 == Additional Information and References 52 122 53 123 * Preventing data corruption on upgrade[[br]] … … 64 134 * #8172 aims to introduce more helper methods that simplify implementing this interface according to best practices. 65 135 66 ==== API History ====136 ==== API History 67 137 68 138 * 0.9 introduced the interface. (changeset:1785)