Packages are available at the Connector/Python download site. For some packaging formats, there are different packages for different versions of Python; choose the one appropriate for the version of Python installed on your system.

Connector/Python installers in native package formats are available for Windows and for Unix and Unix-like systems:

You may need root or administrator privileges to perform the installation operation.

Binary distributions that provide the C Extension link to an already installed C client library provided by a MySQL Server installation. For those distributions that are not statically linked, you must install MySQL Server if it is not already present on your system. To obtain it, visit the MySQL download site.

Installing Connector/Python with pip

Use pip to install Connector/Python on most any operating system:

$> pip install mysql-connector-python

Installing Connector/Python on Microsoft Windows

Managing all of your MySQL products, including MySQL Connector/Python, with MySQL Installer is the recommended approach. It handles all requirements and prerequisites, configurations, and upgrades.

Prerequisite.  The Microsoft Visual C++ 2015 Redistributable must be installed on your system.

Alternatively, to run the installer from the command line, use this command in a console window, where VER and PYVER are the respective Connector/Python and Python version numbers in the installer file name:

$> msiexec /i mysql-connector-python-VER-pyPYVER.msi

Subsequent executions of Connector/Python using the MSI installer permit you to either repair or remove the existing Connector/Python installation.

Installing Connector/Python on Linux Using the MySQL Yum Repository

For EL7 or EL8-based platforms and Fedora, you can install Connector/Python using the MySQL Yum repository (see Installing Additional MySQL Products and Components with Yum). You must have the MySQL Yum repository on your system's repository list (for details, see Adding the MySQL Yum Repository). To make sure that your Yum repository is up-to-date, use this command:

$> sudo yum update mysql-community-release

Prerequisite.  Although optional, the mysql-community-client-plugins package is required to use newer authentication methods, such as caching_sha2_password that's the default authentication method as of MySQL 8.0.

$> sudo yum mysql-community-client-plugins

Then install Connector/Python as follows:

$> sudo yum install mysql-connector-python

Installing Connector/Python on Linux Using an RPM Package

Connector/Python Linux RPM packages (.rpm files) are available from the Connector/Python download site (see Section 4.1, “Obtaining Connector/Python”).

To install a Connector/Python RPM package (denoted here as PACKAGE.rpm), use this command:

$> rpm -i PACKAGE.rpm

Prerequisite.  Although optional, the mysql-community-client-plugins package is required to use newer authentication methods, such as caching_sha2_password that's the default authentication method as of MySQL 8.0.

RPM provides a feature to verify the integrity and authenticity of packages before installing them. To learn more, see Verifying Package Integrity Using MD5 Checksums or GnuPG.

Installing Connector/Python on Linux Using a Debian Package

Connector/Python Debian packages (.deb files) are available for Debian or Debian-like Linux systems from the Connector/Python download site (see Section 4.1, “Obtaining Connector/Python”).

Prerequisite.  Although optional, the mysql-community-client-plugins package is required to use newer authentication methods, such as caching_sha2_password that's the default authentication method as of MySQL 8.0.

To install a Connector/Python Debian package (denoted here as PACKAGE.deb), use this command:

$> dpkg -i PACKAGE.deb

Installing Connector/Python on macOS Using a Disk Image

Connector/Python macOS disk images (.dmg files) are available from the Connector/Python download site (see Section 4.1, “Obtaining Connector/Python”). As of Connector/Python 2.1.1, macOS disk images include the C Extension; it need not be installed separately.

Download the .dmg file and install Connector/Python by opening it and double clicking the resulting .pkg file.

Connector/Python source distributions are platform independent and can be used on any platform. Source distributions are packaged in two formats:

Either packaging format can be used on any platform, but Zip archives are more commonly used on Windows systems and tar archives on Unix and Unix-like systems.

Prerequisites for Compiling Connector/Python with the C Extension

As of Connector/Python 2.1.1, source distributions include the C Extension that interfaces with the MySQL C client library. You can build the distribution with or without support for this extension. To build Connector/Python with support for the C Extension, you must satisfy the following prerequisites.

You must install MySQL Server if it is not already present on your system. To obtain it, visit the MySQL download site.

For certain platforms, MySQL development files are provided in separate packages. This is true for RPM and Debian packages, for example.

Installing Connector/Python from Source on Microsoft Windows

A Connector/Python Zip archive (.zip file) is available from the Connector/Python download site (see Section 4.1, “Obtaining Connector/Python”).

To install Connector/Python from a Zip archive, download the latest version and follow these steps:

To see all options and commands supported by setup.py, use this command:

$> python setup.py --help

Installing Connector/Python from Source on Unix and Unix-Like Systems

For Unix and Unix-like systems such as Linux, Solaris, macOS, and FreeBSD, a Connector/Python tar archive (.tar.gz file) is available from the Connector/Python download site (see Section 4.1, “Obtaining Connector/Python”).

To install Connector/Python from a tar archive, download the latest version (denoted here as VER), and execute these commands:

$> tar xzf mysql-connector-python-VER.tar.gz
$> cd mysql-connector-python-VER

$> sudo python setup.py install \
--with-protobuf-include-dir=/dir/to/protobuf/include \
--with-protobuf-lib-dir=/dir/to/protobuf/lib \
--with-protoc=/path/to/protoc/binary

To include the C Extension (available as of Connector/Python 2.1.1) that interfaces with the MySQL C client library, also add the --with-mysql-capi such as:

$> sudo python setup.py install \
  --with-protobuf-include-dir=/dir/to/protobuf/include \
  --with-protobuf-lib-dir=/dir/to/protobuf/lib \
  --with-protoc=/path/to/protoc/binary \
  --with-mysql-capi="path_name

The argument to --with-mysql-capi is the path to the installation directory of MySQL Server, or the path to the mysql_config command.

To see all options and commands supported by setup.py, use this command:

$> python setup.py --help

On Windows, the default Connector/Python installation location is C:\PythonX.Y\Lib\site-packages\, where X.Y is the Python version you used to install the connector.

On Unix-like systems, the default Connector/Python installation location is /prefix/pythonX.Y/site-packages/, where prefix is the location where Python is installed and X.Y is the Python version. See How installation works in the Python manual.

The C Extension is installed as _mysql_connector.so in the site-packages directory, not in the mysql/connector directory.

Depending on your platform, the installation path might differ from the default. If you are not sure where Connector/Python is installed, do the following to determine its location. The output here shows installation locations as might be seen on macOS:

$> python
>>> from distutils.sysconfig import get_python_lib

>>> print get_python_lib()            # Python v2.x
/Library/Python/2.7/site-packages

>>> print(get_python_lib())           # Python v3.x
/Library/Frameworks/Python.framework/Versions/3.1/lib/python3.1/site-packages

To test that your Connector/Python installation is working and able to connect to MySQL Server, you can run a very simple program where you supply the login credentials and host information required for the connection. For an example, see Section 5.1, “Connecting to MySQL Using Connector/Python”.

The connect() constructor creates a connection to the MySQL server and returns a MySQLConnection object.

The following example shows how to connect to the MySQL server:

import mysql.connector

cnx = mysql.connector.connect(user='scott', password='password',
                              host='127.0.0.1',
                              database='employees')
cnx.close()

Section 7.1, “Connector/Python Connection Arguments” describes the permitted connection arguments.

It is also possible to create connection objects using the connection.MySQLConnection() class:

from mysql.connector import (connection)

cnx = connection.MySQLConnection(user='scott', password='password',
                                 host='127.0.0.1',
                                 database='employees')
cnx.close()

Both forms (either using the connect() constructor or the class directly) are valid and functionally equal, but using connect() is preferred and used by most examples in this manual.

To handle connection errors, use the try statement and catch all errors using the errors.Error exception:

import mysql.connector
from mysql.connector import errorcode

try:
  cnx = mysql.connector.connect(user='scott',
                                database='employ')
except mysql.connector.Error as err:
  if err.errno == errorcode.ER_ACCESS_DENIED_ERROR:
    print("Something is wrong with your user name or password")
  elif err.errno == errorcode.ER_BAD_DB_ERROR:
    print("Database does not exist")
  else:
    print(err)
else:
  cnx.close()

Defining connection arguments in a dictionary and using the ** operator is another option:

import mysql.connector

config = {
  'user': 'scott',
  'password': 'password',
  'host': '127.0.0.1',
  'database': 'employees',
  'raise_on_warnings': True
}

cnx = mysql.connector.connect(**config)

cnx.close()

Using the Connector/Python Python or C Extension

Connector/Python offers two implementations: a pure Python interface and a C extension that uses the MySQL C client library (see Chapter 8, The Connector/Python C Extension). This can be configured at runtime using the use_pure connection argument. It defaults to False as of MySQL 8, meaning the C extension is used. If the C extension is not available on the system then use_pure defaults to True. Setting use_pure=False causes the connection to use the C Extension if your Connector/Python installation includes it, while use_pure=True to False means the Python implementation is used if available.

The following example shows how to set use_pure to False.

import mysql.connector

cnx = mysql.connector.connect(user='scott', password='password',
                              host='127.0.0.1',
                              database='employees',
                              use_pure=False)
cnx.close()

It is also possible to use the C Extension directly by importing the _mysql_connector module rather than the mysql.connector module. For more information, see Section 8.2, “The _mysql_connector C Extension Module”.

All DDL (Data Definition Language) statements are executed using a handle structure known as a cursor. The following examples show how to create the tables of the Employee Sample Database. You need them for the other examples.

In a MySQL server, tables are very long-lived objects, and are often accessed by multiple applications written in different languages. You might typically work with tables that are already set up, rather than creating them within your own application. Avoid setting up and dropping tables over and over again, as that is an expensive operation. The exception is temporary tables, which can be created and dropped quickly within an application.

from __future__ import print_function

import mysql.connector
from mysql.connector import errorcode

DB_NAME = 'employees'

TABLES = {}
TABLES['employees'] = (
    "CREATE TABLE `employees` ("
    "  `emp_no` int(11) NOT NULL AUTO_INCREMENT,"
    "  `birth_date` date NOT NULL,"
    "  `first_name` varchar(14) NOT NULL,"
    "  `last_name` varchar(16) NOT NULL,"
    "  `gender` enum('M','F') NOT NULL,"
    "  `hire_date` date NOT NULL,"
    "  PRIMARY KEY (`emp_no`)"
    ") ENGINE=InnoDB")

TABLES['departments'] = (
    "CREATE TABLE `departments` ("
    "  `dept_no` char(4) NOT NULL,"
    "  `dept_name` varchar(40) NOT NULL,"
    "  PRIMARY KEY (`dept_no`), UNIQUE KEY `dept_name` (`dept_name`)"
    ") ENGINE=InnoDB")

TABLES['salaries'] = (
    "CREATE TABLE `salaries` ("
    "  `emp_no` int(11) NOT NULL,"
    "  `salary` int(11) NOT NULL,"
    "  `from_date` date NOT NULL,"
    "  `to_date` date NOT NULL,"
    "  PRIMARY KEY (`emp_no`,`from_date`), KEY `emp_no` (`emp_no`),"
    "  CONSTRAINT `salaries_ibfk_1` FOREIGN KEY (`emp_no`) "
    "     REFERENCES `employees` (`emp_no`) ON DELETE CASCADE"
    ") ENGINE=InnoDB")

TABLES['dept_emp'] = (
    "CREATE TABLE `dept_emp` ("
    "  `emp_no` int(11) NOT NULL,"
    "  `dept_no` char(4) NOT NULL,"
    "  `from_date` date NOT NULL,"
    "  `to_date` date NOT NULL,"
    "  PRIMARY KEY (`emp_no`,`dept_no`), KEY `emp_no` (`emp_no`),"
    "  KEY `dept_no` (`dept_no`),"
    "  CONSTRAINT `dept_emp_ibfk_1` FOREIGN KEY (`emp_no`) "
    "     REFERENCES `employees` (`emp_no`) ON DELETE CASCADE,"
    "  CONSTRAINT `dept_emp_ibfk_2` FOREIGN KEY (`dept_no`) "
    "     REFERENCES `departments` (`dept_no`) ON DELETE CASCADE"
    ") ENGINE=InnoDB")

TABLES['dept_manager'] = (
    "  CREATE TABLE `dept_manager` ("
    "  `emp_no` int(11) NOT NULL,"
    "  `dept_no` char(4) NOT NULL,"
    "  `from_date` date NOT NULL,"
    "  `to_date` date NOT NULL,"
    "  PRIMARY KEY (`emp_no`,`dept_no`),"
    "  KEY `emp_no` (`emp_no`),"
    "  KEY `dept_no` (`dept_no`),"
    "  CONSTRAINT `dept_manager_ibfk_1` FOREIGN KEY (`emp_no`) "
    "     REFERENCES `employees` (`emp_no`) ON DELETE CASCADE,"
    "  CONSTRAINT `dept_manager_ibfk_2` FOREIGN KEY (`dept_no`) "
    "     REFERENCES `departments` (`dept_no`) ON DELETE CASCADE"
    ") ENGINE=InnoDB")

TABLES['titles'] = (
    "CREATE TABLE `titles` ("
    "  `emp_no` int(11) NOT NULL,"
    "  `title` varchar(50) NOT NULL,"
    "  `from_date` date NOT NULL,"
    "  `to_date` date DEFAULT NULL,"
    "  PRIMARY KEY (`emp_no`,`title`,`from_date`), KEY `emp_no` (`emp_no`),"
    "  CONSTRAINT `titles_ibfk_1` FOREIGN KEY (`emp_no`)"
    "     REFERENCES `employees` (`emp_no`) ON DELETE CASCADE"
    ") ENGINE=InnoDB")

The preceding code shows how we are storing the CREATE statements in a Python dictionary called TABLES. We also define the database in a global variable called DB_NAME, which enables you to easily use a different schema.

cnx = mysql.connector.connect(user='scott')
cursor = cnx.cursor()

A single MySQL server can manage multiple databases. Typically, you specify the database to switch to when connecting to the MySQL server. This example does not connect to the database upon connection, so that it can make sure the database exists, and create it if not:

def create_database(cursor):
    try:
        cursor.execute(
            "CREATE DATABASE {} DEFAULT CHARACTER SET 'utf8'".format(DB_NAME))
    except mysql.connector.Error as err:
        print("Failed creating database: {}".format(err))
        exit(1)

try:
    cursor.execute("USE {}".format(DB_NAME))
except mysql.connector.Error as err:
    print("Database {} does not exists.".format(DB_NAME))
    if err.errno == errorcode.ER_BAD_DB_ERROR:
        create_database(cursor)
        print("Database {} created successfully.".format(DB_NAME))
        cnx.database = DB_NAME
    else:
        print(err)
        exit(1)

We first try to change to a particular database using the database property of the connection object cnx. If there is an error, we examine the error number to check if the database does not exist. If so, we call the create_database function to create it for us.

On any other error, the application exits and displays the error message.

After we successfully create or change to the target database, we create the tables by iterating over the items of the TABLES dictionary:

for table_name in TABLES:
    table_description = TABLES[table_name]
    try:
        print("Creating table {}: ".format(table_name), end='')
        cursor.execute(table_description)
    except mysql.connector.Error as err:
        if err.errno == errorcode.ER_TABLE_EXISTS_ERROR:
            print("already exists.")
        else:
            print(err.msg)
    else:
        print("OK")

cursor.close()
cnx.close()

To handle the error when the table already exists, we notify the user that it was already there. Other errors are printed, but we continue creating tables. (The example shows how to handle the “table already exists” condition for illustration purposes. In a real application, we would typically avoid the error condition entirely by using the IF NOT EXISTS clause of the CREATE TABLE statement.)

The output would be something like this:

Database employees does not exists.
Database employees created successfully.
Creating table employees: OK
Creating table departments: already exists.
Creating table salaries: already exists.
Creating table dept_emp: OK
Creating table dept_manager: OK
Creating table titles: OK 

To populate the employees tables, use the dump files of the Employee Sample Database. Note that you only need the data dump files that you will find in an archive named like employees_db-dump-files-1.0.5.tar.bz2. After downloading the dump files, execute the following commands, adding connection options to the mysql commands if necessary:

$> tar xzf employees_db-dump-files-1.0.5.tar.bz2
$> cd employees_db
$> mysql employees < load_employees.dump
$> mysql employees < load_titles.dump
$> mysql employees < load_departments.dump
$> mysql employees < load_salaries.dump
$> mysql employees < load_dept_emp.dump
$> mysql employees < load_dept_manager.dump

Inserting or updating data is also done using the handler structure known as a cursor. When you use a transactional storage engine such as InnoDB (the default in MySQL 5.5 and higher), you must commit the data after a sequence of INSERT, DELETE, and UPDATE statements.

This example shows how to insert new data. The second INSERT depends on the value of the newly created primary key of the first. The example also demonstrates how to use extended formats. The task is to add a new employee starting to work tomorrow with a salary set to 50000.

from __future__ import print_function
from datetime import date, datetime, timedelta
import mysql.connector

cnx = mysql.connector.connect(user='scott', database='employees')
cursor = cnx.cursor()

tomorrow = datetime.now().date() + timedelta(days=1)

add_employee = ("INSERT INTO employees "
               "(first_name, last_name, hire_date, gender, birth_date) "
               "VALUES (%s, %s, %s, %s, %s)")
add_salary = ("INSERT INTO salaries "
              "(emp_no, salary, from_date, to_date) "
              "VALUES (%(emp_no)s, %(salary)s, %(from_date)s, %(to_date)s)")

data_employee = ('Geert', 'Vanderkelen', tomorrow, 'M', date(1977, 6, 14))

# Insert new employee
cursor.execute(add_employee, data_employee)
emp_no = cursor.lastrowid

# Insert salary information
data_salary = {
  'emp_no': emp_no,
  'salary': 50000,
  'from_date': tomorrow,
  'to_date': date(9999, 1, 1),
}
cursor.execute(add_salary, data_salary)

# Make sure data is committed to the database
cnx.commit()

cursor.close()
cnx.close()

We first open a connection to the MySQL server and store the connection object in the variable cnx. We then create a new cursor, by default a MySQLCursor object, using the connection's cursor() method.

We could calculate tomorrow by calling a database function, but for clarity we do it in Python using the datetime module.

Both INSERT statements are stored in the variables called add_employee and add_salary. Note that the second INSERT statement uses extended Python format codes.

The information of the new employee is stored in the tuple data_employee. The query to insert the new employee is executed and we retrieve the newly inserted value for the emp_no column (an AUTO_INCREMENT column) using the lastrowid property of the cursor object.

Next, we insert the new salary for the new employee, using the emp_no variable in the dictionary holding the data. This dictionary is passed to the execute() method of the cursor object if an error occurred.

Since by default Connector/Python turns autocommit off, and MySQL 5.5 and higher uses transactional InnoDB tables by default, it is necessary to commit your changes using the connection's commit() method. You could also roll back using the rollback() method.

The following example shows how to query data using a cursor created using the connection's cursor() method. The data returned is formatted and printed on the console.

The task is to select all employees hired in the year 1999 and print their names and hire dates to the console.

import datetime
import mysql.connector

cnx = mysql.connector.connect(user='scott', database='employees')
cursor = cnx.cursor()

query = ("SELECT first_name, last_name, hire_date FROM employees "
         "WHERE hire_date BETWEEN %s AND %s")

hire_start = datetime.date(1999, 1, 1)
hire_end = datetime.date(1999, 12, 31)

cursor.execute(query, (hire_start, hire_end))

for (first_name, last_name, hire_date) in cursor:
  print("{}, {} was hired on {:%d %b %Y}".format(
    last_name, first_name, hire_date))

cursor.close()
cnx.close()

We first open a connection to the MySQL server and store the connection object in the variable cnx. We then create a new cursor, by default a MySQLCursor object, using the connection's cursor() method.

In the preceding example, we store the SELECT statement in the variable query. Note that we are using unquoted %s-markers where dates should have been. Connector/Python converts hire_start and hire_end from Python types to a data type that MySQL understands and adds the required quotes. In this case, it replaces the first %s with '1999-01-01', and the second with '1999-12-31'.

We then execute the operation stored in the query variable using the execute() method. The data used to replace the %s-markers in the query is passed as a tuple: (hire_start, hire_end).

After executing the query, the MySQL server is ready to send the data. The result set could be zero rows, one row, or 100 million rows. Depending on the expected volume, you can use different techniques to process this result set. In this example, we use the cursor object as an iterator. The first column in the row is stored in the variable first_name, the second in last_name, and the third in hire_date.

We print the result, formatting the output using Python's built-in format() function. Note that hire_date was converted automatically by Connector/Python to a Python datetime.date object. This means that we can easily format the date in a more human-readable form.

The output should be something like this:

..
Wilharm, LiMin was hired on 16 Dec 1999
Wielonsky, Lalit was hired on 16 Dec 1999
Kamble, Dannz was hired on 18 Dec 1999
DuBourdieux, Zhongwei was hired on 19 Dec 1999
Fujisawa, Rosita was hired on 20 Dec 1999
..

The following example script gives a long-overdue 15% raise effective tomorrow to all employees who joined in the year 2000 and are still with the company.

To iterate through the selected employees, we use buffered cursors. (A buffered cursor fetches and buffers the rows of a result set after executing a query; see Section 10.6.1, “cursor.MySQLCursorBuffered Class”.) This way, it is unnecessary to fetch the rows in a new variables. Instead, the cursor can be used as an iterator.

from __future__ import print_function

from decimal import Decimal
from datetime import datetime, date, timedelta

import mysql.connector

# Connect with the MySQL Server
cnx = mysql.connector.connect(user='scott', database='employees')

# Get two buffered cursors
curA = cnx.cursor(buffered=True)
curB = cnx.cursor(buffered=True)

# Query to get employees who joined in a period defined by two dates
query = (
  "SELECT s.emp_no, salary, from_date, to_date FROM employees AS e "
  "LEFT JOIN salaries AS s USING (emp_no) "
  "WHERE to_date = DATE('9999-01-01')"
  "AND e.hire_date BETWEEN DATE(%s) AND DATE(%s)")

# UPDATE and INSERT statements for the old and new salary
update_old_salary = (
  "UPDATE salaries SET to_date = %s "
  "WHERE emp_no = %s AND from_date = %s")
insert_new_salary = (
  "INSERT INTO salaries (emp_no, from_date, to_date, salary) "
  "VALUES (%s, %s, %s, %s)")

# Select the employees getting a raise
curA.execute(query, (date(2000, 1, 1), date(2000, 12, 31)))

# Iterate through the result of curA
for (emp_no, salary, from_date, to_date) in curA:

  # Update the old and insert the new salary
  new_salary = int(round(salary * Decimal('1.15')))
  curB.execute(update_old_salary, (tomorrow, emp_no, from_date))
  curB.execute(insert_new_salary,
               (emp_no, tomorrow, date(9999, 1, 1,), new_salary))

  # Commit the changes
  cnx.commit()

cnx.close()

A connection with the MySQL server can be established using either the mysql.connector.connect() function or the mysql.connector.MySQLConnection() class:

cnx = mysql.connector.connect(user='joe', database='test')
cnx = MySQLConnection(user='joe', database='test')

The following table describes the arguments that can be used to initiate a connection. An asterisk (*) following an argument indicates a synonymous argument name, available only for compatibility with other Python MySQL drivers. Oracle recommends not to use these alternative names.

MySQL Authentication Options

Authentication with MySQL uses username and password.

When the database argument is given, the current database is set to the given value. To change the current database later, execute a USE SQL statement or set the database property of the MySQLConnection instance.

By default, Connector/Python tries to connect to a MySQL server running on the local host using TCP/IP. The host argument defaults to IP address 127.0.0.1 and port to 3306. Unix sockets are supported by setting unix_socket. Named pipes on the Windows platform are not supported.

Connector/Python 1.2.1 and up supports authentication plugins available as of MySQL 5.6. This includes mysql_clear_password and sha256_password, both of which require an SSL connection. The sha256_password plugin does not work over a non-SSL connection because Connector/Python does not support RSA encryption.

The connect() method supports an auth_plugin argument that can be used to force use of a particular plugin. For example, if the server is configured to use sha256_password by default and you want to connect to an account that authenticates using mysql_native_password, either connect using SSL or specify auth_plugin='mysql_native_password'.

Character Encoding

By default, strings coming from MySQL are returned as Python Unicode literals. To change this behavior, set use_unicode to False. You can change the character setting for the client connection through the charset argument. To change the character set after connecting to MySQL, set the charset property of the MySQLConnection instance. This technique is preferred over using the SET NAMES SQL statement directly. Similar to the charset property, you can set the collation for the current MySQL session.

Transactions

The autocommit value defaults to False, so transactions are not automatically committed. Call the commit() method of the MySQLConnection instance within your application after doing a set of related insert, update, and delete operations. For data consistency and high throughput for write operations, it is best to leave the autocommit configuration option turned off when using InnoDB or other transactional tables.

Time Zones

The time zone can be set per connection using the time_zone argument. This is useful, for example, if the MySQL server is set to UTC and TIMESTAMP values should be returned by MySQL converted to the PST time zone.

SQL Modes

MySQL supports so-called SQL Modes. which change the behavior of the server globally or per connection. For example, to have warnings raised as errors, set sql_mode to TRADITIONAL. For more information, see Server SQL Modes.

Troubleshooting and Error Handling

Warnings generated by queries are fetched automatically when get_warnings is set to True. You can also immediately raise an exception by setting raise_on_warnings to True. Consider using the MySQL sql_mode setting for turning warnings into errors.

To set a timeout value for connections, use connection_timeout.

Enabling and Disabling Features Using Client Flags

MySQL uses client flags to enable or disable features. Using the client_flags argument, you have control of what is set. To find out what flags are available, use the following:

from mysql.connector.constants import ClientFlag
print '\n'.join(ClientFlag.get_full_info())

If client_flags is not specified (that is, it is zero), defaults are used for MySQL 4.1 and higher. If you specify an integer greater than 0, make sure all flags are set properly. A better way to set and unset flags individually is to use a list. For example, to set FOUND_ROWS, but disable the default LONG_FLAG:

flags = [ClientFlag.FOUND_ROWS, -ClientFlag.LONG_FLAG]
mysql.connector.connect(client_flags=flags)

Result Set Handling

By default, MySQL Connector/Python does not buffer or prefetch results. This means that after a query is executed, your program is responsible for fetching the data. This avoids excessive memory use when queries return large result sets. If you know that the result set is small enough to handle all at once, you can fetch the results immediately by setting buffered to True. It is also possible to set this per cursor (see Section 10.2.6, “MySQLConnection.cursor() Method”).

Results generated by queries normally are not read until the client program fetches them. To automatically consume and discard result sets, set the consume_results option to True. The result is that all results are read, which for large result sets can be slow. (In this case, it might be preferable to close and reopen the connection.)

Type Conversions

By default, MySQL types in result sets are converted automatically to Python types. For example, a DATETIME column value becomes a datetime.datetime object. To disable conversion, set the raw option to True. You might do this to get better performance or perform different types of conversion yourself.

Connecting through SSL

Using SSL connections is possible when your Python installation supports SSL, that is, when it is compiled against the OpenSSL libraries. When you provide the ssl_ca, ssl_key and ssl_cert options, the connection switches to SSL, and the client_flags option includes the ClientFlag.SSL value automatically. You can use this in combination with the compressed option set to True.

As of Connector/Python 2.2.2, if the MySQL server supports SSL connections, Connector/Python attempts to establish a secure (encrypted) connection by default, falling back to an unencrypted connection otherwise.

From Connector/Python 1.2.1 through Connector/Python 2.2.1, it is possible to establish an SSL connection using only the ssl_ca opion. The ssl_key and ssl_cert arguments are optional. However, when either is given, both must be given or an AttributeError is raised.

# Note (Example is valid for Python v2 and v3)
from __future__ import print_function

import sys

#sys.path.insert(0, 'python{0}/'.format(sys.version_info[0]))

import mysql.connector
from mysql.connector.constants import ClientFlag

config = {
    'user': 'ssluser',
    'password': 'password',
    'host': '127.0.0.1',
    'client_flags': [ClientFlag.SSL],
    'ssl_ca': '/opt/mysql/ssl/ca.pem',
    'ssl_cert': '/opt/mysql/ssl/client-cert.pem',
    'ssl_key': '/opt/mysql/ssl/client-key.pem',
}

cnx = mysql.connector.connect(**config)
cur = cnx.cursor(buffered=True)
cur.execute("SHOW STATUS LIKE 'Ssl_cipher'")
print(cur.fetchone())
cur.close()
cnx.close()

Connection Pooling

With either the pool_name or pool_size argument present, Connector/Python creates the new pool. If the pool_name argument is not given, the connect() call automatically generates the name, composed from whichever of the host, port, user, and database connection arguments are given, in that order. If the pool_size argument is not given, the default size is 5 connections.

The pool_reset_session permits control over whether session variables are reset when the connection is returned to the pool. The default is to reset them.

For additional information about connection pooling, see Section 9.1, “Connector/Python Connection Pooling”.

Protocol Compression

The boolean compress argument indicates whether to use the compressed client/server protocol (default False). This provides an easier alternative to setting the ClientFlag.COMPRESS flag. This argument is available as of Connector/Python 1.1.2.

Converter Class

The converter_class argument takes a class and sets it when configuring the connection. An AttributeError is raised if the custom converter class is not a subclass of conversion.MySQLConverterBase.

Server Failover

The connect() method accepts a failover argument that provides information to use for server failover in the event of connection failures. The argument value is a tuple or list of dictionaries (tuple is preferred because it is nonmutable). Each dictionary contains connection arguments for a given server in the failover sequence. Permitted dictionary values are: user, password, host, port, unix_socket, database, pool_name, pool_size. This failover option was added in Connector/Python 1.2.1.

Option File Support

As of Connector/Python 2.0.0, option files are supported using two options for connect():

For more information, see Section 7.2, “Connector/Python Option-File Support”.

LOAD DATA LOCAL INFILE

Prior to Connector/Python 2.0.0, to enable use of LOAD DATA LOCAL INFILE, clients had to explicitly set the ClientFlag.LOCAL_FILES flag. As of 2.0.0, this flag is enabled by default. To disable it, the allow_local_infile connection option can be set to False at connect time (the default is True).

Compatibitility with Other Connection Interfaces

passwd, db and connect_timeout are valid for compatibility with other MySQL interfaces and are respectively the same as password, database and connection_timeout. The latter take precedence. Data source name syntax or dsn is not used; if specified, it raises a NotSupportedError exception.

Client/Server Protocol Implementation

Connector/Python can use a pure Python interface to MySQL, or a C Extension that uses the MySQL C client library. The use_pure mysql.connector.connect() connection argument determines which. The default changed in Connector/Python 8 from True (use the pure Python implementation) to False. Setting use_pure changes the implementation used.

The use_pure argument is available as of Connector/Python 2.1.1. For more information about the C extension, see Chapter 8, The Connector/Python C Extension.

As of version 2.0.0, Connector/Python has the capability of reading options from option files. (For general information about option files in MySQL, see Using Option Files.) Two arguments for the connect() call control use of option files in Connector/Python programs:

Connector/Python also supports the !include and !includedir inclusion directives within option files. These directives work the same way as for other MySQL programs (see Using Option Files).

This example specifies a single option file as a string:

cnx = mysql.connector.connect(option_files='/etc/mysql/connectors.cnf')

This example specifies multiple option files as a sequence of strings:

mysql_option_files = [
    '/etc/mysql/connectors.cnf',
    './development.cnf',
]
cnx = mysql.connector.connect(option_files=mysql_option_files)

Connector/Python reads no option files by default, for backward compatibility with versions older than 2.0.0. This differs from standard MySQL clients such as mysql or mysqldump, which do read option files by default. To find out which option files the standard clients read on your system, invoke one of them with its --help option and examine the output. For example:

$> mysql --help
...
Default options are read from the following files in the given order:
/etc/my.cnf /etc/mysql/my.cnf /usr/local/mysql/etc/my.cnf ~/.my.cnf
...

If you specify the option_files connection argument to read option files, Connector/Python reads the [client] and [connector_python] option groups by default. To specify explicitly which groups to read, use the option_groups connection argument. The following example causes only the [connector_python] group to be read:

cnx = mysql.connector.connect(option_files='/etc/mysql/connectors.cnf',
                              option_groups='connector_python')

Other connection arguments specified in the connect() call take precedence over options read from option files. Suppose that /etc/mysql/connectors.conf contains these lines:

[client]
database=cpyapp

The following connect() call includes no database connection argument. The resulting connection uses cpyapp, the database specified in the option file:

cnx = mysql.connector.connect(option_files='/etc/mysql/connectors.cnf')

By contrast, the following connect() call specifies a default database different from the one found in the option file. The resulting connection uses cpyapp_dev as the default database, not cpyapp:

cnx2 = mysql.connector.connect(option_files='/etc/mysql/connectors.cnf',
                               database='cpyapp_dev')

Connector/Python raises a ValueError if an option file cannot be read, or has already been read. This includes files read by inclusion directives.

For the [connector_python] group, only options supported by Connector/Python are accepted. Unrecognized options cause a ValueError to be raised.

For other option groups, Connector/Python ignores unrecognized options.

It is not an error for a named option group not to exist.

Connector/Python treats option values in option files as strings and evaluates them using eval(). This enables specification of option values more complex than simple scalars.

Installations of Connector/Python from version 2.1.1 on support a use_pure argument to mysql.connector.connect() that indicates whether to use the pure Python interface to MySQL or the C Extension that uses the MySQL C client library:

export DYLD_LIBRARY_PATH=/usr/local/mysql/lib   (for sh)
setenv DYLD_LIBRARY_PATH /usr/local/mysql/lib   (for tcsh)

If you need to check whether your Connector/Python installation is aware of the C Extension, test the HAVE_CEXT value. There are different approaches for this. Suppose that your usual arguments for mysql.connector.connect() are specified in a dictionary:

config = {
  'user': 'scott',
  'password': 'password',
  'host': '127.0.0.1',
  'database': 'employees',
}

The following example illustrates one way to add use_pure to the connection arguments:

import mysql.connector

if mysql.connector.__version_info__ > (2, 1) and mysql.connector.HAVE_CEXT:
  config['use_pure'] = False

If use_pure=False and the C Extension is not available, then Connector/Python will automatically fall back to the pure Python implementation.

To use the C Extension directly, import the _mysql_connector module rather than mysql.connector, then use the _mysql_connector.MySQL() class to obtain a MySQL instance. For example:

import _mysql_connector

ccnx = _mysql_connector.MySQL()
ccnx.connect(user='scott', password='password',
             host='127.0.0.1', database='employees')

ccnx.query("SHOW VARIABLES LIKE 'version%'")
row = ccnx.fetch_row()
while row:
  print(row)
  row = ccnx.fetch_row()
ccnx.free_result()

ccnx.close()

For more information, see Chapter 11, Connector/Python C Extension API Reference.

Simple connection pooling is supported that has these characteristics:

Applications that can benefit from connection-pooling capability include:

A connection pool can be created implicitly or explicitly.

To create a connection pool implicitly: Open a connection and specify one or more pool-related arguments (pool_name, pool_size). For example:

dbconfig = {
  "database": "test",
  "user":     "joe"
}

cnx = mysql.connector.connect(pool_name = "mypool",
                              pool_size = 3,
                              **dbconfig)

The pool name is restricted to alphanumeric characters and the special characters ., _, *, $, and #. The pool name must be no more than pooling.CNX_POOL_MAXNAMESIZE characters long (default 64).

The pool size must be greater than 0 and less than or equal to pooling.CNX_POOL_MAXSIZE (default 32).

With either the pool_name or pool_size argument present, Connector/Python creates the new pool. If the pool_name argument is not given, the connect() call automatically generates the name, composed from whichever of the host, port, user, and database connection arguments are given, in that order. If the pool_size argument is not given, the default size is 5 connections.

Subsequent calls to connect() that name the same connection pool return connections from the existing pool. Any pool_size or connection parameter arguments are ignored, so the following connect() calls are equivalent to the original connect() call shown earlier:

cnx = mysql.connector.connect(pool_name = "mypool", pool_size = 3)
cnx = mysql.connector.connect(pool_name = "mypool", **dbconfig)
cnx = mysql.connector.connect(pool_name = "mypool")

Pooled connections obtained by calling connect() with a pool-related argument have a class of PooledMySQLConnection (see Section 10.4, “pooling.PooledMySQLConnection Class”). PooledMySQLConnection pooled connection objects are similar to MySQLConnection unpooled connection objects, with these differences:

To create a connection pool explicitly: Create a MySQLConnectionPool object (see Section 10.3, “pooling.MySQLConnectionPool Class”):

dbconfig = {
  "database": "test",
  "user":     "joe"
}

cnxpool = mysql.connector.pooling.MySQLConnectionPool(pool_name = "mypool",
                                                      pool_size = 3,
                                                      **dbconfig)

To request a connection from the pool, use its get_connection() method:

cnx1 = cnxpool.get_connection()
cnx2 = cnxpool.get_connection()

When you create a connection pool explicitly, it is possible to use the pool object's set_config() method to reconfigure the pool connection parameters:

dbconfig = {
  "database": "performance_schema",
  "user":     "admin",
  "password": "password"
}

cnxpool.set_config(**dbconfig)

Connections requested from the pool after the configuration change use the new parameters. Connections obtained before the change remain unaffected, but when they are closed (returned to the pool) are reopened with the new parameters before being returned by the pool for subsequent connection requests.

Connector/Python includes a mysql.connector.django module that provides a Django back end for MySQL. This back end supports new features found as of MySQL 5.6 such as fractional seconds support for temporal data types.

Django Configuration

Django uses a configuration file named settings.py that contains a variable called DATABASES (see https://docs.djangoproject.com/en/1.5/ref/settings/#std:setting-DATABASES). To configure Django to use Connector/Python as the MySQL back end, the example found in the Django manual can be used as a basis:

DATABASES = {
    'default': {
        'NAME': 'user_data',
        'ENGINE': 'mysql.connector.django',
        'USER': 'mysql_user',
        'PASSWORD': 'password',
        'OPTIONS': {
          'autocommit': True,
        },
    }
}

It is possible to add more connection arguments using OPTIONS.

Support for MySQL Features

Django can launch the MySQL client application mysql. When the Connector/Python back end does this, it arranges for the sql_mode system variable to be set to TRADITIONAL at startup.

Some MySQL features are enabled depending on the server version. For example, support for fractional seconds precision is enabled when connecting to a server from MySQL 5.6.4 or higher. Django's DateTimeField is stored in a MySQL column defined as DATETIME(6), and TimeField is stored as TIME(6). For more information about fractional seconds support, see Fractional Seconds in Time Values.

The mysql.connector module provides top-level methods and properties.

cnx = mysql.connector.connect(user='joe', database='test')
cnx = MySQLConnection(user='joe', database='test')

>>> mysql.connector.apilevel
'2.0'

>>> mysql.connector.paramstyle
'pyformat'

>>> mysql.connector.threadsafety
1

>>> mysql.connector.__version__
'1.1.0'

>>> mysql.connector.__version_info__
(1, 1, 0, 'a', 0)

The MySQLConnection class is used to open and manage a connection to a MySQL server. It also used to send commands and SQL statements and read the results.

cnx = MySQLConnection(**kwargs)

cnx.close()

>>> cursor.execute("INSERT INTO employees (first_name) VALUES (%s)", ('Jane'))
>>> cnx.commit()

cnx.config(**kwargs)

cnx = mysql.connector.connect(user='joe', database='test')
# Connected as 'joe'
cnx.config(user='jane')
cnx.reconnect()
# Now connected as 'jane'

MySQLConnection.connect(**kwargs)

cnx = MySQLConnection(user='joe', database='test')

cursor = cnx.cursor([arg=value[, arg=value]...])

cnx.cmd_change_user(username='', password='', database='', charset=33)

cnx.cmd_init_db(db_name)

cnx.cmd_process_kill(mysql_pid)

>>> cnx.cmd_process_kill(123)
>>> cnx.cmd_query('KILL 123')

cnx.cmd_query(statement)

cnx.cmd_query_iter(statement)

statement = 'SELECT 1; INSERT INTO t1 VALUES (); SELECT 2'
for result in cnx.cmd_query_iter(statement):
  if 'columns' in result:
    columns = result['columns']
    rows = cnx.get_rows()
  else:
    # do something useful with INSERT result

cnx.cmd_refresh(options)

>>> from mysql.connector import RefreshOption
>>> refresh = RefreshOption.LOG | RefreshOption.THREADS
>>> cnx.cmd_refresh(refresh)

cnx.cmd_reset_connection()

cnx.get_rows(count=None)

cnx.isset_client_flag(flag)

cnx.ping(reconnect=False, attempts=1, delay=0)

cnx.reconnect(attempts=1, delay=0)

cnx.reset_session(user_variables = None, session_variables = None)

user_variables = {'var1': '1', 'var2': '10'}
session_variables = {'wait_timeout': 100000, 'sql_mode': 'TRADITIONAL'}
self.cnx.reset_session(user_variables, session_variables)

>>> cursor.execute("INSERT INTO employees (first_name) VALUES (%s)", ('Jane'))
>>> cnx.rollback()

cnx.set_charset_collation(charset=None, collation=None)

>>> cnx = mysql.connector.connect(user='scott')
>>> cnx.set_charset_collation('latin1')

>>> cnx = mysql.connector.connect(user='scott')
>>> cnx.set_charset_collation('latin1', 'latin1_general_ci')

cnx.set_client_flags(flags)

>>> from mysql.connector.constants import ClientFlag
>>> cnx.set_client_flags([ClientFlag.FOUND_ROWS, -ClientFlag.LONG_FLAG])
>>> cnx.reconnect()

cnx.start_transaction(consistent_snapshot=bool,
                      isolation_level=level,
                      readonly=access_mode)

>>> cnx.autocommit
False
>>> cnx.autocommit = True
>>> cnx.autocommit
True

>>> cnx.database = 'test'
>>> cnx.database = 'mysql'
>>> cnx.database
u'mysql'

>>> cnx.get_warnings = True
>>> cursor.execute('SELECT "a"+1')
>>> cursor.fetchall()
[(1.0,)]
>>> cursor.fetchwarnings()
[(u'Warning', 1292, u"Truncated incorrect DOUBLE value: 'a'")]

>>> cnx.start_transaction()
>>> cnx.in_transaction
True
>>> cnx.commit()
>>> cnx.in_transaction
False

>>> cnx.raise_on_warnings = True
>>> cursor.execute('SELECT "a"+1')
>>> cursor.fetchall()
..
mysql.connector.errors.DataError: 1292: Truncated incorrect DOUBLE value: 'a'

>>> cnx.sql_mode = 'TRADITIONAL,NO_ENGINE_SUBSTITUTION'
>>> cnx.sql_mode.split(',')
[u'STRICT_TRANS_TABLES', u'STRICT_ALL_TABLES', u'NO_ZERO_IN_DATE',
u'NO_ZERO_DATE', u'ERROR_FOR_DIVISION_BY_ZERO', u'TRADITIONAL',
u'NO_AUTO_CREATE_USER', u'NO_ENGINE_SUBSTITUTION']

>>> from mysql.connector.constants import SQLMode
>>> cnx.sql_mode = [ SQLMode.NO_ZERO_DATE, SQLMode.REAL_AS_FLOAT]
>>> cnx.sql_mode

u'REAL_AS_FLOAT,NO_ZERO_DATE'

>>> cnx.time_zone = '+00:00'
>>> cursor = cnx.cursor()
>>> cursor.execute('SELECT NOW()') ; cursor.fetchone()
(datetime.datetime(2012, 6, 15, 11, 24, 36),)
>>> cnx.time_zone = '-09:00'
>>> cursor.execute('SELECT NOW()') ; cursor.fetchone()
(datetime.datetime(2012, 6, 15, 2, 24, 44),)
>>> cnx.time_zone
u'-09:00'

This class provides for the instantiation and management of connection pools.

MySQLConnectionPool(pool_name=None,
                    pool_size=5,
                    pool_reset_session=True,
                    **kwargs)

dbconfig = {
  "database": "test",
  "user":     "joe",
}

cnxpool = mysql.connector.pooling.MySQLConnectionPool(pool_name = "mypool",
                                                      pool_size = 3,
                                                      **dbconfig)

cnxpool.add_connection(cnx = None)

cnxpool.add_connection()    # add new connection to pool
cnxpool.add_connection(cnx) # add existing connection to pool

cnxpool.get_connection()

cnx = cnxpool.get_connection()

cnxpool.set_config(**kwargs)

dbconfig = {
  "database": "performance_schema",
  "user":     "admin",
  "password": "password",
}

cnxpool.set_config(**dbconfig)

cnxpool.pool_name

name = cnxpool.pool_name

This class is used by MySQLConnectionPool to return a pooled connection instance. It is also the class used for connections obtained with calls to the connect() method that name a connection pool (see Section 9.1, “Connector/Python Connection Pooling”).

PooledMySQLConnection pooled connection objects are similar to MySQLConnection unpooled connection objects, with these differences:

PooledMySQLConnection(cnxpool, cnx)

pcnx = mysql.connector.pooling.PooledMySQLConnection(cnxpool, cnx)

cnx.close()

cnx.pool_name

cnx = cnxpool.get_connection()
name = cnx.pool_name

The MySQLCursor class instantiates objects that can execute operations such as SQL statements. Cursor objects interact with the MySQL server using a MySQLConnection object.

To create a cursor, use the cursor() method of a connection object:

import mysql.connector

cnx = mysql.connector.connect(database='world')
cursor = cnx.cursor()

Several related classes inherit from MySQLCursor. To create a cursor of one of these types, pass the appropriate arguments to cursor():

import mysql.connector

cnx = mysql.connector.connect(database='world')
cursor = cnx.cursor()

import mysql.connector
from mysql.connector.cursor import MySQLCursor

cnx = mysql.connector.connect(database='world')
cursor = MySQLCursor(cnx)

result_args = cursor.callproc(proc_name, args=())

CREATE PROCEDURE multiply(IN pFac1 INT, IN pFac2 INT, OUT pProd INT)
BEGIN
  SET pProd := pFac1 * pFac2;
END;

>>> args = (5, 6, 0) # 0 is to hold value of the OUT parameter pProd
>>> cursor.callproc('multiply', args)
('5', '6', 30L)

CREATE PROCEDURE sp1(IN pStr1 VARCHAR(20), IN pStr2 VARCHAR(20),
                     OUT pConCat VARCHAR(100))
BEGIN
  SET pConCat := CONCAT(pStr1, pStr2);
END;

args = ('ham', 'eggs', (0, 'CHAR'))
result_args = cursor.callproc('sp1', args)
print(result_args[2])

cursor.close()

cursor.execute(operation, params=None, multi=False)
iterator = cursor.execute(operation, params=None, multi=True)

insert_stmt = (
  "INSERT INTO employees (emp_no, first_name, last_name, hire_date) "
  "VALUES (%s, %s, %s, %s)"
)
data = (2, 'Jane', 'Doe', datetime.date(2012, 3, 23))
cursor.execute(insert_stmt, data)

select_stmt = "SELECT * FROM employees WHERE emp_no = %(emp_no)s"
cursor.execute(select_stmt, { 'emp_no': 2 })

operation = 'SELECT 1; INSERT INTO t1 VALUES (); SELECT 2'
for result in cursor.execute(operation, multi=True):
  if result.with_rows:
    print("Rows produced by statement '{}':".format(
      result.statement))
    print(result.fetchall())
  else:
    print("Number of rows affected by statement '{}': {}".format(
      result.statement, result.rowcount))

cursor.executemany(operation, seq_of_params)

data = [
  ('Jane', date(2005, 2, 12)),
  ('Joe', date(2006, 5, 23)),
  ('John', date(2010, 10, 3)),
]
stmt = "INSERT INTO employees (first_name, hire_date) VALUES (%s, %s)"
cursor.executemany(stmt, data)

INSERT INTO employees (first_name, hire_date)
VALUES ('Jane', '2005-02-12'), ('Joe', '2006-05-23'), ('John', '2010-10-03')

rows = cursor.fetchall()

>>> cursor.execute("SELECT * FROM employees ORDER BY emp_no")
>>> head_rows = cursor.fetchmany(size=2)
>>> remaining_rows = cursor.fetchall()

rows = cursor.fetchmany(size=1)

row = cursor.fetchone()

# Using a while loop
cursor.execute("SELECT * FROM employees")
row = cursor.fetchone()
while row is not None:
  print(row)
  row = cursor.fetchone()

# Using the cursor as iterator
cursor.execute("SELECT * FROM employees")
for row in cursor:
  print(row)

tuples = cursor.fetchwarnings()

>>> cnx.get_warnings = True
>>> cursor.execute("SELECT 'a'+1")
>>> cursor.fetchall()
[(1.0,)]
>>> cursor.fetchwarnings()
[(u'Warning', 1292, u"Truncated incorrect DOUBLE value: 'a'")]

iterator = cursor.stored_results()

>>> cursor.callproc('myproc')
()
>>> for result in cursor.stored_results():
...     print result.fetchall()
...
[(1,)]
[(2,)]

sequence = cursor.column_names

cursor.execute("SELECT last_name, first_name, hire_date "
               "FROM employees WHERE emp_no = %s", (123,))
row = dict(zip(cursor.column_names, cursor.fetchone()))
print("{last_name}, {first_name}: {hire_date}".format(row))

tuples = cursor.description

(column_name,
 type,
 None,
 None,
 None,
 None,
 null_ok,
 column_flags)

import mysql.connector
from mysql.connector import FieldType

...

cursor.execute("SELECT emp_no, last_name, hire_date "
               "FROM employees WHERE emp_no = %s", (123,))
for i in range(len(cursor.description)):
  print("Column {}:".format(i+1))
  desc = cursor.description[i]
  print("  column_name = {}".format(desc[0]))
  print("  type = {} ({})".format(desc[1], FieldType.get_info(desc[1])))
  print("  null_ok = {}".format(desc[6]))
  print("  column_flags = {}".format(desc[7]))

Column 1:
  column_name = emp_no
  type = 3 (LONG)
  null_ok = 0
  column_flags = 20483
Column 2:
  column_name = last_name
  type = 253 (VAR_STRING)
  null_ok = 0
  column_flags = 4097
Column 3:
  column_name = hire_date
  type = 10 (DATE)
  null_ok = 0
  column_flags = 4225

>>> from mysql.connector import FieldFlag
>>> FieldFlag.desc

id = cursor.lastrowid

count = cursor.rowcount

str = cursor.statement

boolean = cursor.with_rows

import mysql.connector

cnx = mysql.connector.connect(user='scott', database='test')
cursor = cnx.cursor()
operation = 'SELECT 1; UPDATE t1 SET c1 = 2; SELECT 2'
for result in cursor.execute(operation, multi=True):
  if result.with_rows:
    result.fetchall()
  else:
    print("Number of affected rows: {}".format(result.rowcount))

The cursor classes described in the following sections inherit from the MySQLCursor class, which is described in Section 10.5, “cursor.MySQLCursor Class”.

import mysql.connector

cnx = mysql.connector.connect()

# Only this particular cursor will buffer results
cursor = cnx.cursor(buffered=True)

# All cursors created from cnx2 will be buffered by default
cnx2 = mysql.connector.connect(buffered=True)

import mysql.connector

cnx = mysql.connector.connect()

# Only this particular cursor will be raw
cursor = cnx.cursor(raw=True)

# All cursors created from cnx2 will be raw by default
cnx2 = mysql.connector.connect(raw=True)

import mysql.connector

cnx = mysql.connector.connect()

# Only this particular cursor will be raw and buffered
cursor = cnx.cursor(raw=True, buffered=True)

# All cursors created from cnx2 will be raw and buffered by default
cnx2 = mysql.connector.connect(raw=True, buffered=True)

cnx = mysql.connector.connect(database='world')
cursor = cnx.cursor(dictionary=True)
cursor.execute("SELECT * FROM country WHERE Continent = 'Europe'")

print("Countries in Europe:")
for row in cursor:
    print("* {Name}".format(Name=row['Name']

Countries in Europe:
* Albania
* Andorra
* Austria
* Belgium
* Bulgaria
...

cursor.execute("SELECT Name, Population FROM country WHERE Continent = 'Europe'")

print("Countries in Europe with population:")
for row in cursor:
    print("* {Name}: {Population}".format(**row))

cursor = cnx.cursor(dictionary=True, buffered=True)

cnx = mysql.connector.connect(database='world')
cursor = cnx.cursor(named_tuple=True)
cursor.execute("SELECT * FROM country WHERE Continent = 'Europe'")

print("Countries in Europe with population:")
for row in cursor:
    print("* {Name}: {Population}".format(
        Name=row.Name,
        Population=row.Population
    ))

cursor = cnx.cursor(named_tuple=True, buffered=True)

cursor = cnx.cursor(prepared=True)
stmt = "SELECT fullname FROM employees WHERE id = %s" # (1)
cursor.execute(stmt, (5,))                            # (2)
# ... fetch data ...
cursor.execute(stmt, (10,))                           # (3)
# ... fetch data ...

from io import IOBase

...

cur = cnx.cursor(prepared=True)
cur.execute("SELECT (%s)", (io.BytesIO(bytes("A", "latin1")), ))

This class provides constants defining MySQL client flags that can be used when the connection is established to configure the session. The ClientFlag class is available when importing mysql.connector.

>>> import mysql.connector
>>> mysql.connector.ClientFlag.FOUND_ROWS
2

See Section 10.2.32, “MySQLConnection.set_client_flags() Method” and the connection argument client_flag.

The ClientFlag class cannot be instantiated.

This class provides all supported MySQL field or data types. They can be useful when dealing with raw data or defining your own converters. The field type is stored with every cursor in the description for each column.

The following example shows how to print the name of the data type for each column in a result set.

from __future__ import print_function
import mysql.connector
from mysql.connector import FieldType

cnx = mysql.connector.connect(user='scott', database='test')
cursor = cnx.cursor()

cursor.execute(
  "SELECT DATE(NOW()) AS `c1`, TIME(NOW()) AS `c2`, "
  "NOW() AS `c3`, 'a string' AS `c4`, 42 AS `c5`")
rows = cursor.fetchall()

for desc in cursor.description:
  colname = desc[0]
  coltype = desc[1]
  print("Column {} has type {}".format(
    colname, FieldType.get_info(coltype)))

cursor.close()
cnx.close()

The FieldType class cannot be instantiated.

This class provides all known MySQL Server SQL Modes. It is mostly used when setting the SQL modes at connection time using the connection's sql_mode property. See Section 10.2.47, “MySQLConnection.sql_mode Property”.

The SQLMode class cannot be instantiated.

This class provides all known MySQL characters sets and their default collations. For examples, see Section 10.2.31, “MySQLConnection.set_charset_collation() Method”.

The CharacterSet class cannot be instantiated.

This class performs various flush operations.

The mysql.connector.errors module defines exception classes for errors and warnings raised by MySQL Connector/Python. Most classes defined in this module are available when you import mysql.connector.

The exception classes defined in this module mostly follow the Python Database API Specification v2.0 (PEP 249). For some MySQL client or server errors it is not always clear which exception to raise. It is good to discuss whether an error should be reclassified by opening a bug report.

MySQL Server errors are mapped with Python exception based on their SQLSTATE value (see Server Error Message Reference). The following table shows the SQLSTATE classes and the exception Connector/Python raises. It is, however, possible to redefine which exception is raised for each server error. The default exception is DatabaseError.

>>> from mysql.connector import errorcode
>>> errorcode.ER_BAD_TABLE_ERROR
1051

import mysql.connector

try:
  cnx = mysql.connector.connect(user='scott', database='employees')
  cursor = cnx.cursor()
  cursor.execute("SELECT * FORM employees")   # Syntax error in query
  cnx.close()
except mysql.connector.Error as err:
  print("Something went wrong: {}".format(err))

>>> from mysql.connector.errors import Error
>>> str(Error())
'Unknown error'

>>> str(Error("Oops! There was an error."))
'Oops! There was an error.'

>>> str(Error(errno=2006))
'2006: MySQL server has gone away'

>>> str(Error(errno=2002, values=('/tmp/mysql.sock', 2)))
"2002: Can't connect to local MySQL server through socket '/tmp/mysql.sock' (2)"

>>> str(Error(errno=1146, sqlstate='42S02', msg="Table 'test.spam' doesn't exist"))
"1146 (42S02): Table 'test.spam' doesn't exist"

import mysql.connector
from mysql.connector import errorcode

cnx = mysql.connector.connect(user='scott', database='test')
cursor = cnx.cursor()
try:
  cursor.execute("DROP TABLE spam")
except mysql.connector.Error as err:
  if err.errno == errorcode.ER_BAD_TABLE_ERROR:
    print("Creating table spam")
  else:
    raise

try:
  conn = mysql.connector.connect(database = "baddb")
except mysql.connector.Error as e:
  print "Error code:", e.errno        # error number
  print "SQLSTATE value:", e.sqlstate # SQLSTATE value
  print "Error message:", e.msg       # error message
  print "Error:", e                   # errno, sqlstate, msg values
  s = str(e)
  print "Error:", s                   # errno, sqlstate, msg values

cursor.execute("CREATE TABLE t1 (id int, PRIMARY KEY (id))")
try:
  cursor.execute("INSERT INTO t1 (id) VALUES (1)")
  cursor.execute("INSERT INTO t1 (id) VALUES (1)")
except mysql.connector.IntegrityError as err:
  print("Error: {}".format(err))

try:
  cursor.execute("CREATE DESK t1 (id int, PRIMARY KEY (id))")
except mysql.connector.ProgrammingError as err:
  if err.errno == errorcode.ER_SYNTAX_ERROR:
    print("Check your syntax!")
  else:
    print("Error: {}".format(err))

errors.custom_error_exception(error=None, exception=None)

import mysql.connector
from mysql.connector import errorcode

# Server error 1028 should raise a DatabaseError
mysql.connector.custom_error_exception(1028, mysql.connector.DatabaseError)

# Or using a dictionary:
mysql.connector.custom_error_exception({
  1028: mysql.connector.DatabaseError,
  1029: mysql.connector.OperationalError,
})

# To reset, pass an empty dictionary:
mysql.connector.custom_error_exception({})

The _mysql_connector module provides classes.

Syntax:

ccnx = _mysql_connector.MySQL(args)

The MySQL class is used to open and manage a connection to a MySQL server (referred to elsewhere in this reference as “the MySQL instance”). It is also used to send commands and SQL statements and read results.

The MySQL class wraps most functions found in the MySQL C Client API and adds some additional convenient functionality.

import _mysql_connector

ccnx = _mysql_connector.MySQL()
ccnx.connect(user='scott', password='password',
             host='127.0.0.1', database='employees')
ccnx.close()

Permitted arguments for the MySQL class are auth_plugin, buffered, charset_name, connection_timeout, raw, use_unicode. Those arguments correspond to the arguments of the same names for MySQLConnection.connect() as described at Section 7.1, “Connector/Python Connection Arguments”, except that charset_name corresponds to charset.

Syntax:

count = ccnx.affected_rows()

Returns the number of rows changed, inserted, or deleted by the most recent UPDATE, INSERT, or DELETE statement.

Syntax:

ccnx.autocommit(bool)

Sets the autocommit mode.

Raises a ValueError exception if mode is not True or False.

Syntax:

is_buffered = ccnx.buffered()     # getter
ccnx.buffered(bool)               # setter

With no argument, returns True or False to indicate whether the MySQL instance buffers (stores) the results.

With a boolean argument, sets the MySQL instance buffering mode.

For the setter syntax, raises a TypeError exception if the value is not True or False.

Syntax:

ccnx.change_user(user='user_name,
                 password='password_val',
                 database='db_name')

Changes the user and sets a new default database. Permitted arguments are user, password, and database.

Syntax:

charset = ccnx.character_set_name()

Returns the name of the default character set for the current MySQL session.

Some MySQL character sets have no equivalent names in Python. When this is the case, a name usable by Python is returned. For example, the 'utf8mb4' MySQL character set name is returned as 'utf8'.

Syntax:

ccnx.close()

Closes the MySQL connection.

Syntax:

ccnx.commit()

Commits the current transaction.

Syntax:

ccnx.connect(args)

Connects to a MySQL server.

import _mysql_connector

ccnx = _mysql_connector.MySQL()
ccnx.connect(user='scott', password='password',
             host='127.0.0.1', database='employees')
ccnx.close()

connect() supports the following arguments: host, user, password, database, port, unix_socket, client_flags, ssl_ca, ssl_cert, ssl_key, ssl_verify_cert, compress. See Section 7.1, “Connector/Python Connection Arguments”.

If ccnx is already connected, connect() discards any pending result set and closes the connection before reopening it.

Raises a TypeError exception if any argument is of an invalid type.

Syntax:

is_connected = ccnx.connected()

Returns True or False to indicate whether the MySQL instance is connected.

Syntax:

ccnx.consume_result()

Consumes the stored result set, if there is one, for this MySQL instance, by fetching all rows. If the statement that was executed returned multiple result sets, this method loops over and consumes all of them.

Syntax:

converted_obj = ccnx.convert_to_mysql(obj))

Converts a Python object to a MySQL value based on the Python type of the object. The converted object is escaped and quoted.

ccnx.query('SELECT CURRENT_USER(), 1 + 3, NOW()')
row = ccnx.fetch_row()
for col in row:
  print(ccnx.convert_to_mysql(col))
ccnx.consume_result()

Raises a MySQLInterfaceError exception if the Python object cannot be converted.

Syntax:

str = ccnx.escape_string(str_to_escape)

Uses the mysql_escape_string() C API function to create an SQL string that you can use in an SQL statement.

Raises a TypeError exception if the value does not have a Unicode, bytes, or (for Python 2) string type. Raises a MySQLError exception if the string could not be escaped.

Syntax:

field_info = ccnx.fetch_fields()

Fetches column information for the active result set. Returns a list of tuples, one tuple per column

Raises a MySQLInterfaceError exception for any MySQL error returned by the MySQL server.

ccnx.query('SELECT CURRENT_USER(), 1 + 3, NOW()')
field_info = ccnx.fetch_fields()
for fi in field_info:
  print(fi)
ccnx.consume_result()

Syntax:

row = ccnx.fetch_row()

Fetches the next row from the active result set. The row is returned as a tuple that contains the values converted to Python objects, unless raw was set.

ccnx.query('SELECT CURRENT_USER(), 1 + 3, NOW()')
row = ccnx.fetch_row()
print(row)
ccnx.free_result()

Raises a MySQLInterfaceError exception for any MySQL error returned by the MySQL server.

Syntax:

count = ccnx.field_count()

Returns the number of columns in the active result set.

Syntax:

ccnx.free_result()

Frees the stored result set, if there is one, for this MySQL instance. If the statement that was executed returned multiple result sets, this method loops over and consumes all of them.

Syntax:

info = ccnx.get_character_set_info()

Returns information about the default character set for the current MySQL session. The returned dictionary has the keys number, name, csname, comment, dir, mbminlen, and mbmaxlen.

Syntax:

info = ccnx.get_client_info()

Returns the MySQL client library version as a string.

Syntax:

info = ccnx.get_client_version()

Returns the MySQL client library version as a tuple.

Syntax:

info = ccnx.get_host_info()

Returns a description of the type of connection in use as a string.

Syntax:

info = ccnx.get_proto_info()

Returns the protocol version used by the current session.

Syntax:

info = ccnx.get_server_info()

Returns the MySQL server version as a string.

Syntax:

info = ccnx.get_server_version()

Returns the MySQL server version as a tuple.

Syntax:

info = ccnx.get_ssl_cipher()

Returns the SSL cipher used for the current session, or None if SSL is not in use.

Syntax:

str = ccnx.hex_string(string_to_hexify)

Encodes a value in hexadecimal format and wraps it within X''. For example, "ham" becomes X'68616D'.

Syntax:

insert_id = ccnx.insert_id()

Returns the AUTO_INCREMENT value generated by the most recent executed statement, or 0 if there is no such value.

Syntax:

more = ccnx.more_results()

Returns True or False to indicate whether any more result sets exist.

Syntax:

ccnx.next_result()

Initiates the next result set for a statement string that produced multiple result sets.

Raises a MySQLInterfaceError exception for any MySQL error returned by the MySQL server.

Syntax:

count = ccnx.num_fields()

Returns the number of columns in the active result set.

Syntax:

count = ccnx.num_rows()

Returns the number of rows in the active result set.

Raises a MySQLError exception if there is no result set.

Syntax:

alive = ccnx.ping()

Returns True or False to indicate whether the connection to the MySQL server is working.

Syntax:

ccnx.query(args)

Executes an SQL statement. The permitted arguments are statement, buffered, raw, and raw_as_string.

ccnx.query('DROP TABLE IF EXISTS t')
ccnx.query('CREATE TABLE t (i INT NOT NULL AUTO_INCREMENT PRIMARY KEY)')
ccnx.query('INSERT INTO t (i) VALUES (NULL),(NULL),(NULL)')
ccnx.query('SELECT LAST_INSERT_ID()')
row = ccnx.fetch_row()
print('LAST_INSERT_ID(): ', row)
ccnx.consume_result()

buffered and raw, if not provided, take their values from the MySQL instance. raw_as_string is a special argument for Python v2 and returns str instead of bytearray (compatible with Connector/Python v1.x).

To check whether the query returns rows, check the have_result_set property of the MySQL instance.

query() returns True if the query executes, and raises an exception otherwise. It raises a TypeError exception if any argument has an invalid type, and a MySQLInterfaceError exception for any MySQL error returned by the MySQL server.

Syntax:

is_raw = ccnx.raw()     # getter
ccnx.raw(bool)          # setter

With no argument, returns True or False to indicate whether the MySQL instance return the rows as is (without conversion to Python objects).

With a boolean argument, sets the MySQL instance raw mode.

Syntax:

ccnx.refresh(flags)

Flushes or resets the tables and caches indicated by the argument. The only argument currently permitted is an integer.

Raises a TypeError exception if the first argument is not an integer.

Syntax:

ccnx.rollback()

Rolls back the current transaction.

Raises a MySQLInterfaceError exception on errors.

Syntax:

ccnx.select_db(db_name)

Sets the default (current) database for the current session.

Raises a MySQLInterfaceError exception for any MySQL error returned by the MySQL server.

Syntax:

ccnx.set_character_set(charset_name)

Sets the default character set for the current session. The only argument permitted is a string that contains the character set name.

Raises a TypeError exception if the argument is not a PyString_type.

Syntax:

ccnx.shutdown(flags)

Shuts down the MySQL server. The only argument currently permitted is an integer that describes the shutdown type.

Raises a TypeError exception if the first argument is not an integer. Raises a MySQLErrorInterface exception if an error is retured by the MySQL server.

Syntax:

info = ccnx.stat()

Returns the server status as a string.

Raises a MySQLErrorInterface exception if an error is retured by the MySQL server.

Syntax:

thread_id = ccnx.thread_id()

Returns the current thread or connection ID.

Syntax:

is_unicode = ccnx.use_unicode()      # getter
ccnx.use_unicode(bool)               # setter

With no argument, returns True or False to indicate whether the MySQL instance returns nonbinary strings as Unicode.

With a boolean argument, sets whether the MySQL instance returns nonbinary strings as Unicode.

Syntax:

count = ccnx.warning_count()

Returns the number of errors, warnings, and notes produced by the previous SQL statement.

Syntax:

has_rows = ccnx.have_result_set

After execution of the query() method, this property indicates whether the query returns rows.