Deprecate MySQL support #191

docs/changelog.rst

@@ -21,6 +21,11 @@ Please make sure you have a fresh **database backup** before upgrading! Upgradin
 v1.6.0 - 2017-xx-xx
 ^^^^^^^^^^^^^^^^^^^
 
+.. warning::
+
+    Support for ``MySQL`` has been **deprecated** since ``DSMR-reader v1.6`` and will be discontinued completely in a later release.
+    Please use a PostgreSQL database instead. Users already running MySQL will be supported in migrating at a later moment.
+
 .. note::
 
     **Change in API:**

docs/conf.py

@@ -56,9 +56,9 @@
 # built documents.
 #
 # The short X.Y version.
-version = '1.5'
+version = '1.x'
 # The full version, including alpha/beta/rc tags.
-release = '1.5.0'
+release = '1.x'
 
 # The language for content autogenerated by Sphinx. Refer to documentation
 # for a list of supported languages.
@@ -298,4 +298,4 @@
 #texinfo_no_detailmenu = False
 
 locale_dirs = ['locale/']   # path is example but recommended.
-gettext_compact = True
+gettext_compact = False

docs/faq.rst

@@ -189,6 +189,8 @@ Only want to restore the database?
 
 - Stop the application first with ``sudo supervisorctl stop all``. This will disconnect it from the database as well.
 
+- Importing the data could take a long time. It took MySQL 15 minutes to import nearly 3 million readings, from a compressed backup, on a RaspberryPi 3. 
+
 For **PostgreSQL** restores::
 
     sudo sudo -u postgres dropdb dsmrreader
@@ -209,12 +211,12 @@ For **MySQL** restores::
     sudo mysqladmin drop dsmrreader
     
     # Either restore an uncompressed (.sql) backup:
-    cat <PATH-TO-MYSQL-BACKUP.sql.gz> | sudo mysql -D dsmrreader --defaults-file=/etc/mysql/debian.cnf
+    cat <PATH-TO-MYSQL-BACKUP.sql.gz> | sudo mysql --defaults-file=/etc/mysql/debian.cnf -D dsmrreader
     
     # OR
     
     # Restore a compressed (.gz) backup with:
-    zcat <PATH-TO-MYSQL-BACKUP.sql.gz> | sudo mysql -D dsmrreader --defaults-file=/etc/mysql/debian.cnf
+    zcat <PATH-TO-MYSQL-BACKUP.sql.gz> | sudo mysql --defaults-file=/etc/mysql/debian.cnf -D dsmrreader
 
 
 - Start the application again with ``sudo supervisorctl start all``.

docs/installation.rst

@@ -14,14 +14,18 @@ Dependencies & requirements
 ---------------------------
 - **RaspberryPi 2 or 3**
 
- - The RaspberryPi 1 tends to be **too slow** for this project, as it requires multi core processing.
-
 .. note::
 
     - **Alternative #1**: You can also run it on any server near your smart meter, as long as it satisfies the other requirements.
 
     - **Alternative #2**: The application supports receiving P1 telegrams using an API, so you can also run it on a server outside your home. (:doc:`API DOCS<api>`)
 
+.. warning::
+
+    The RaspberryPi 1 tends to be **too slow** for this project, as it requires multi core processing.
+
+    You can however run just the datalogger client on an old RaspberryPi, :doc:`see for the API for a howto and example scripts<api>`.
+
 - **Raspbian OS**
 
  - Recommended and tested with, but any OS satisfying the requirements should do fine.
@@ -32,13 +36,16 @@ Dependencies & requirements
 
     Support for ``Python 3.3`` has been **discontinued** since ``DSMR-reader v1.5`` (due to Django).
 
-- **PostgreSQL 9+ or MySQL / MariaDB 5.5+**
+- **PostgreSQL 9+ database**
+
+.. warning::
 
- - I **highly recommend** ``PostgreSQL`` due to builtin support for timezones.
+    Support for ``MySQL`` has been **deprecated** since ``DSMR-reader v1.6`` and will be discontinued completely in a later release.
+    Please use a PostgreSQL database instead. Users already running MySQL will be supported in migrating at a later moment.
 
 - **Smart Meter** with support for **at least DSMR 4.x+** and a **P1 telegram port**
 
- - Tested so far with Landis+Gyr E350, Kaifa. Telegram port looks like an RJ11 (phone) socket.
+ - Tested so far with Landis+Gyr E350, Kaifa.
 
 - **Minimal 1 GB of disk space on RaspberryPi (card)** (for application installation & virtualenv). 
 
@@ -54,24 +61,21 @@ Dependencies & requirements
  - It just really helps if you know what you are doing.
 
 
-1. Database backend
--------------------
-
-The application stores by default all readings taken from the serial cable. Depending on your needs, you can choose for either (Option A.) **PostgreSQL** (Option B.) **MySQL/MariaDB**. 
-
-.. note::
+1. Database backend (PostgreSQL)
+--------------------------------
 
-    If you have no idea what to choose, I generally advise to pick PostgreSQL, as it has builtin support for (local) timezone handling (required for daylight saving time transitions).
+The application stores by default all readings taken from the serial cable.
+There is support for **PostgreSQL**, and there used to be support for **MySQL/MariaDB** as well.
+The latter is currently deprecated by this project and support will be discontinued in a future release. 
 
-(Option A.) PostgreSQL
-^^^^^^^^^^^^^^^^^^^^^^
 Install PostgreSQL, ``postgresql-server-dev-all`` is required for the virtualenv installation later in this guide.
 
 - Install database::
 
     sudo apt-get install -y postgresql postgresql-server-dev-all
 
-Does Postgres not start due to locales? Try: ``dpkg-reconfigure locales``.  Still no luck? Try editing ``/etc/environment``, add ``LC_ALL="en_US.utf-8"`` and reboot.
+Does Postgres not start due to locales? Try: ``dpkg-reconfigure locales``. 
+Still no luck? Try editing ``/etc/environment``, add ``LC_ALL="en_US.utf-8"`` and reboot.
 
 (!) Ignore any '*could not change directory to "/root": Permission denied*' errors for the following three commands.
 
@@ -99,18 +103,25 @@ Does Postgres not start due to locales? Try: ``dpkg-reconfigure locales``.  Stil
     
         zcat <PATH-TO-POSTGRESQL-BACKUP.sql.gz> | sudo sudo -u postgres psql dsmrreader
 
+Now continue at chapter 2 below (Dependencies).
 
-(Option B.) MySQL/MariaDB
+(Legacy) MySQL/MariaDB
 ^^^^^^^^^^^^^^^^^^^^^^^^^
-Install MariaDB. You can also choose to install the closed source MySQL, as they should be interchangeable anyway. ``libmysqlclient-dev`` is required for the virtualenv installation later in this guide.
+.. warning::
+
+    Support for the MySQL database backend is deprecated and will be removed in a later release.
+    Please use a PostgreSQL database instead. Users already running MySQL will be supported in migrating at a later moment.
+
+Install MariaDB. You can also choose to install the closed source MySQL, as they should be interchangeable anyway. 
+``libmysqlclient-dev`` is required for the virtualenv installation later in this guide.
 
 - Install database::
 
     sudo apt-get install -y mariadb-server-10.0 libmysqlclient-dev
 
 - Create database::
 
-    sudo mysqladmin create dsmrreader
+    sudo mysqladmin --defaults-file=/etc/mysql/debian.cnf create dsmrreader
 
 - Create database user::
 
@@ -122,19 +133,19 @@ Install MariaDB. You can also choose to install the closed source MySQL, as they
 
 - Flush privileges to activate them::
 
-    sudo mysqladmin reload --defaults-file=/etc/mysql/debian.cnf
+    sudo mysqladmin --defaults-file=/etc/mysql/debian.cnf reload
 
 .. note::
 
     **Optional**: Do you need to restore a **MySQL** database backup as well?
 
     Restore an uncompressed (``.sql``) backup with::
     
-        cat <PATH-TO-MYSQL-BACKUP.sql.gz> | sudo mysql -D dsmrreader --defaults-file=/etc/mysql/debian.cnf
+        cat <PATH-TO-MYSQL-BACKUP.sql.gz> | sudo mysql --defaults-file=/etc/mysql/debian.cnf -D dsmrreader
 
     Or restore a compressed (``.gz``) backup with::
     
-        zcat <PATH-TO-MYSQL-BACKUP.sql.gz> | sudo mysql -D dsmrreader --defaults-file=/etc/mysql/debian.cnf
+        zcat <PATH-TO-MYSQL-BACKUP.sql.gz> | sudo mysql --defaults-file=/etc/mysql/debian.cnf -D dsmrreader
 
 
 2. Dependencies
@@ -143,7 +154,8 @@ Now you'll have to install several utilities, required for the Nginx webserver,
 
     sudo apt-get install -y nginx supervisor git python3 python3-pip python3-virtualenv virtualenvwrapper
 
-Install ``cu``. The CU program allows easy testing for your DSMR serial connection. It's very basic but also very effective to simply test whether your serial cable setup works properly. ::
+Install ``cu``. The CU program allows easy testing for your DSMR serial connection. 
+It's very basic but also very effective to simply test whether your serial cable setup works properly::
 
     sudo apt-get install -y cu
 
@@ -255,36 +267,44 @@ Make sure you've read and executed the note above, because you'll need it for th
 
 7. Application configuration & setup
 ------------------------------------
-Earlier in this guide you had to choose for either **(A.) PostgreSQL** or **(B.) MySQL/MariaDB**. Our application needs to know which backend used in order to communicate with it. 
-
-Therefor I created two default (Django-)settings files you can copy, one for each backend. The application will also need the appropriate database client, which is not installed by default. For this I also created two ready-to-use requirements files, which will also install all other dependencies required, such as the Django framework. 
+The application will also need the appropriate database client, which is not installed by default. 
+For this I created two ready-to-use requirements files, which will also install all other dependencies required, such as the Django framework. 
 
 The ``base.txt`` contains requirements which the application needs anyway, no matter which backend you've choosen.
 
 .. note::
 
     **Installation of the requirements below might take a while**, depending on your Internet connection, RaspberryPi speed and resources (generally CPU) available. Nothing to worry about. :]
 
-(Option A.) PostgreSQL
+PostgreSQL
 ^^^^^^^^^^^^^^^^^^^^^^
 - Did you choose PostgreSQL? Then execute these two lines::
 
     cp dsmrreader/provisioning/django/postgresql.py dsmrreader/settings.py
 
     pip3 install -r dsmrreader/provisioning/requirements/base.txt -r dsmrreader/provisioning/requirements/postgresql.txt
 
-(Option B.) MySQL/MariaDB
+
+Did everything install without fatal errors? If the database client refuses to install due to missing files/configs, 
+make sure you've installed ``postgresql-server-dev-all`` earlier in the process, when you installed the database server itself.
+
+Continue to chapter 8 (Bootstrapping).
+
+(Legacy) MySQL/MariaDB
 ^^^^^^^^^^^^^^^^^^^^^^^^^
+.. warning::
+
+    Support for the MySQL database backend is deprecated and will be removed in a later release.
+    Please use a PostgreSQL database instead. Users already running MySQL will be supported in migrating at a later moment.
+
 - Or did you choose MySQL/MariaDB? Execute these two commands::
 
     cp dsmrreader/provisioning/django/mysql.py dsmrreader/settings.py
 
     pip3 install -r dsmrreader/provisioning/requirements/base.txt -r dsmrreader/provisioning/requirements/mysql.txt
 
-
-Did everything install without fatal errors? If either of the database clients refuses to install due to missing files/configs, 
-make sure you've installed ``postgresql-server-dev-all`` (for **PostgreSQL**) or ``libmysqlclient-dev`` (for **MySQL**) earlier in the process, 
-when you installed the database server itself.
+Did everything install without fatal errors? If the database client refuses to install due to missing files/configs, 
+make sure you've installed ``libmysqlclient-dev`` earlier in the process, when you installed the database server itself.
 
 
 8. Bootstrapping