Switch from MySQL-python to PyMySQL

As discussed in the Liberty Design Summit "Moving apps to Python 3"
cross-project workshop, the way forward in the near future is to
switch to the pure-python PyMySQL library as a default.

Added a special test environment to keep MySQL-python support.
Documentation modified.

https://etherpad.openstack.org/p/liberty-cross-project-python3

Change-Id: I12b32dc097a121bd43991bc38dd4d289b65e86c1

1 files changed, 25 insertions, 4 deletions

diff --git a/doc/source/installation.rst b/doc/source/installation.rst
index 96e0ec2..1262160 100644
--- a/doc/source/installation.rst
+++ b/doc/source/installation.rst
@@ -8,16 +8,37 @@ At the command line::
 
 You will also need to install at least one SQL backend::
 
-    $ pip install MySQL-python
+    $ pip install psycopg2
+
+Or::
+
+    $ pip install PyMySQL
 
 Or::
 
     $ pip install pysqlite
 
-Using with MySQL
-----------------
 
-If using MySQL make sure to install the MySQL client development package for
+Using with PostgreSQL
+---------------------
+
+If you are using PostgreSQL make sure to install the PostgreSQL client
+development package for your distro. On Ubuntu this is done as follows::
+
+    $ sudo apt-get install libpq-dev
+    $ pip install psycopg2
+
+The installation of psycopg2 will fail if libpq-dev is not installed first.
+Note that even in a virtual environment the libpq-dev will be installed
+system wide.
+
+
+Using with MySQL-python
+-----------------------
+
+PyMySQL is a default MySQL DB API driver for oslo.db, as well as for the whole
+OpenStack. But you still can use MySQL-python as an alternative DB API driver.
+For MySQL-python you must install the MySQL client development package for
 your distro. On Ubuntu this is done as follows::
 
     $ sudo apt-get install libmysqlclient-dev