fix the mysql restore pb by documenting that backup/restore command may

return command either as a list or as string (in which case a subshell
has to be used to run it)

2 files changed, 16 insertions, 14 deletions

diff --git a/ChangeLog b/ChangeLog
index d8bc939..ad58c71 100644
--- a/ChangeLog
+++ b/ChangeLog
@@ -4,9 +4,9 @@ ChangeLog for logilab.common
  --
     * adbh: changed backup / restore api (BREAKS COMPAT):
       - backup_command is now backup_commands (eg return a list of commands)
-      - each command returned in backup_commands/restore_commands is now
-        a list that may be used as argument to subprocess.call
-        (XXX except for the mysql helper that still needs update)
+      - each command returned in backup_commands/restore_commands may now
+        be list that may be used as argument to subprocess.call, or a string
+	which will the requires a subshell
     * deprecation: deprecated now takes an optional 'stacklevel' argument, default to 2
 
 2009-12-23  --  0.46.0
diff --git a/adbh.py b/adbh.py
index 4fbc7e0..d6093e8 100644
--- a/adbh.py
+++ b/adbh.py
@@ -169,12 +169,23 @@ class _GenericAdvFuncHelper:
 
     def backup_commands(self, dbname, dbhost, dbuser, backupfile,
                        keepownership=True):
-        """return a list of commands to backup the given database"""
+        """return a list of commands to backup the given database.
+
+        Each command may be given as a list or as a string. In the latter case,
+        expected to be used with a subshell (for instance using `os.system(cmd)`
+        or `subprocess.call(cmd, shell=True)`
+        """
         raise NotImplementedError('not supported by this DBMS')
 
     def restore_commands(self, dbname, dbhost, dbuser, backupfile,
                          encoding='utf-8', keepownership=True, drop=True):
-        """return a list of commands to restore a backup of the given database"""
+        """return a list of commands to restore a backup of the given database
+
+
+        Each command may be given as a list or as a string. In the latter case,
+        expected to be used with a subshell (for instance using `os.system(cmd)`
+        or `subprocess.call(cmd, shell=True)`
+        """
         raise NotImplementedError('not supported by this DBMS')
 
 
@@ -317,7 +328,6 @@ class _PGAdvFuncHelper(_GenericAdvFuncHelper):
 
     def backup_commands(self, dbname, dbhost, dbuser, backupfile,
                        keepownership=True):
-        """return a command to backup the given database"""
         cmd = ['pg_dump', '-Fc']
         if dbhost:
             cmd.append('--host=%s' % dbhost)
@@ -332,7 +342,6 @@ class _PGAdvFuncHelper(_GenericAdvFuncHelper):
 
     def restore_commands(self, dbname, dbhost, dbuser, backupfile,
                          encoding='utf-8', keepownership=True, drop=True):
-        """return a list of commands to restore a backup the given database"""
         cmds = []
         if drop:
             cmd = pgdbcmd('dropdb', dbhost, dbuser)
@@ -429,12 +438,10 @@ class _SqliteAdvFuncHelper(_GenericAdvFuncHelper):
 
     def backup_commands(self, dbname, dbhost, dbuser, backupfile,
                        keepownership=True):
-        """return a list of commands to backup the given database"""
         return [['gzip', dbname], ['mv', dbname + '.gz', backupfile]]
 
     def restore_commands(self, dbname, dbhost, dbuser, backupfile,
                          encoding='utf-8', keepownership=True, drop=True):
-        """return a list of commands to restore a backup the given database"""
         gunziped, ext = os.pathsplitext(backupfile)
         assert ext.lower() in ('.gz', '.z') # else gunzip will fail anyway
         return [['gunzip', backupfile], ['mv', gunziped, dbname]]
@@ -487,7 +494,6 @@ class _MyAdvFuncHelper(_GenericAdvFuncHelper):
 
     def backup_commands(self, dbname, dbhost, dbuser, backupfile,
                        keepownership=True):
-        """return a command to backup the given database"""
         cmd = ['mysqldump']
         # XXX compress
         if dbhost is not None:
@@ -497,8 +503,6 @@ class _MyAdvFuncHelper(_GenericAdvFuncHelper):
 
     def restore_commands(self, dbname, dbhost, dbuser, backupfile,
                          encoding='utf-8', keepownership=True, drop=True):
-        """return a list of commands to restore a backup the given database"""
-        # XXX to upgrade to use command as list (pipe usage...)
         cmds = []
         host_option = ''
         if dbhost is not None:
@@ -605,14 +609,12 @@ class _SqlServer2005FuncHelper(_GenericAdvFuncHelper):
 
     def backup_commands(self, dbname, dbhost, dbuser, backupfile,
                        keepownership=True):
-        """return a command to backup the given database"""
         return [[sys.executable, os.path.normpath(__file__),
                  "_SqlServer2005FuncHelper._do_backup", dbhost, dbname, backupfile]
                 ]
 
     def restore_commands(self, dbname, dbhost, dbuser, backupfile,
                          encoding='utf-8', keepownership=True, drop=True):
-        """return a list of commands to restore a backup of the given database"""
         return [[sys.executable, os.path.normpath(__file__),
                 "_SqlServer2005FuncHelper._do_restore", dbhost, dbname, backupfile],
                 ]