# HG changeset patch
# User Alexandre Fayolle <alexandre.fayolle@logilab.fr>
# Date 1280830894 -7200
# Node ID 47f84adcd676db240f6e4b068445e879ad788f38
# Parent  151b6b73acc61007656c5a551bad68f8abd59854
added tip on config file migration in scripts

diff -r 151b6b73acc6 -r 47f84adcd676 doc/book/en/devrepo/migration.rst
--- a/doc/book/en/devrepo/migration.rst	Tue Aug 03 12:19:02 2010 +0200
+++ b/doc/book/en/devrepo/migration.rst	Tue Aug 03 12:21:34 2010 +0200
@@ -182,6 +182,40 @@
 
 * `option_removed(oldname, newname)`, indicates that an option has been deleted.
 
+The `config` variable is an object which can be used to access the
+configuration values, for reading and updating, with a dictionary-like
+syntax. 
+
+Example 1: migration script changing the variable 'sender-addr' in
+all-in-one.conf. The script also checks that in that the instance is
+configured with a known value for that variable, and only updates the
+value in that case.
+
+.. sourcecode:: python
+
+ wrong_addr = 'cubicweb@loiglab.fr' # known wrong address
+ fixed_addr = 'cubicweb@logilab.fr'
+ configured_addr = config.get('sender-addr')
+ # check that the address has not been hand fixed by a sysadmin
+ if configured_addr == wrong_addr: 
+     config['sender-addr'] = fixed-addr
+     config.save()
+
+Example 2: checking the value of the database backend driver, which
+can be useful in case you need to issue backend-dependent raw SQL
+queries in a migration script.
+
+.. sourcecode:: python
+
+ dbdriver  = config.sources()['system']['db-driver']
+ if dbdriver == "sqlserver2005":
+     # this is now correctly handled by CW :-)
+     sql('ALTER TABLE cw_Xxxx ALTER COLUMN cw_name varchar(64) NOT NULL;')
+     commit()
+ else: # postgresql
+     sync_schema_props_perms(ertype=('Xxxx', 'name', 'String'),
+     syncperms=False)
+
 
 Others migration functions
 --------------------------