Monday, November 10, 2014

PyMySQL, a pure-Python client library for MySQL

By Vasudev Ram

I came across PyMySQL on github today. Excerpt from the PyMySQL Github page:

[ This package contains a pure-Python MySQL client library. The goal of PyMySQL is to be a drop-in replacement for MySQLdb and work on CPython, PyPy, IronPython and Jython. ]

In other words, PyMySQL is a pure-Python MySQL driver, and as the docs say, it aims to be a drop-in replacement for MySQLdb, which is a Python driver for MySQL, but implemented as a Python C extension. One of the advantages of using a pure-Python library instead of a C extension, is that you do not have to build it from source, and also, potentially, that it may work without any build steps or changes to the code, on various versions of Python, such as CPython, PyPy, etc., as the excerpt above says. Also see this Stack Overflow question:

What actually is pymysql and how it differs from mysqldb?

Here is PyMySQL on PyPI, (the Python Package Index).

The statistics for PyMySQL on PyPI show this:

Downloads (All Versions):
104 downloads in the last day
7168 downloads in the last week
49124 downloads in the last month

So I tried out PyMySQL a bit, on CPython 2.7.8 on Ubuntu Linux.

To install PyMySQL, do:

$ pip install pymysql
Checked whether it was properly installed with:
$ python
>>> import PyMySQL
Oops, didn't work. I then tried:
>>> import pymysql
That did work.
Here is the schema of the MySQL table (called sales, in a database also called sales) that I used to try PyMySQL:
$ mysql -u root
mysql> use sales;

Database changed
mysql> desc sales;
| Field      | Type        | Null | Key | Default | Extra |
| id         | int(11)     | YES  |     | NULL    |       |
| region     | varchar(6)  | YES  |     | NULL    |       |
| item       | varchar(15) | YES  |     | NULL    |       |
| unit_price | int(11)     | YES  |     | NULL    |       |
| quantity   | int(11)     | YES  |     | NULL    |       |
5 rows in set (0.01 sec)

Basically, it is a table to record sales data by region, for items with unit prices and quantities sold.
And here is my Python program to try PyMySQL:
$ cat

import pymysql
conn = pymysql.connect(host='localhost', port=3306, user='some_user', passwd='some_password', db='sales')
curs = conn.cursor()
curs.execute('select * from sales')
# Added this to give a proper header for the output, with field names.
field_names = [ item[0] for item in curs.description ]
for field_name in field_names:
    print field_name.rjust(12),
for row in curs:
    for col in row:
        print str(col).rjust(12),
I ran the program and got the correct output:
$ python
id       region         item   unit_price     quantity
1        North        Chair          100            2
2        North        Table          200            3
3        South         Desk          300            1
3        South        Shelf          400            2
I also ran this other SQL query with the GROUP BY clause, to get the region-wise sales:
curs.execute('select region, sum(unit_price * quantity) as value from sales group by region order by 1')
and got the expected output:
$ python
      region        value
       North          800
       South         1100
The PyMySQL Github page shows how it works: PyMySQL implements the client side of the MySQL Client/Server Protocol. The MySQL database server listens for database requests from clients on port 3306, and the clients (which may be on the same machine or on another machine on the network), send the request to that server at that port. The protocol also supports UNIX domain sockets, so the connect method has a named parameter unix_socket=None.

Related links:

PyPy, a Python interpreter and Just-In-Time compiler

IronPython, Python for .NET

Jython, Python for the JVM


- Vasudev Ram - Dancing Bison Enterprises

Signup for email about new products that I create.

Contact Page


garylinux said...

I first ran across pymysql about 2 years ago. I have been using it since. It is nice and i find it more portable than the c module.

Vasudev Ram said...

@garylinux: good to know, thanks for sharing.

Chris Lasher said...

Oracle also offers their own FOSS pure-Python MySQL driver, MySQL Connector.

Vasudev Ram said...

@Chris: Thanks. I did know about the existence of MySQL Connector, but don't think I knew it was pure-Python.