Chapter 7 Connector/Python Connection Establishment

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 found in 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 v4.1 and later. 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.) This option is available as of Connector/Python 1.1.2.

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 1.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': 'asecret', 
    '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.

Connection pooling is supported as of Connector/Python 1.1.1. 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. This argument is available as of Connector/Python 1.1.2. Before 1.1.2, setting a custom converter class is possible only after instantiating a new connection object.

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.

MySQL Fabric Support

To request a MySQL Fabric connection, provide a fabric argument that specifies to contact Fabric. For details, see Requesting a Fabric Connection.

Server Failover

As of Connector/Python 1.2.1, 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.

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 connection argument determines which. The default is True (use the pure Python implementation). Setting use_pure to False causes the connection to use the C Extension if your Connector/Python installation includes it.

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

As of version 2.0.0, Connector/Python provides the capability of reading options from option files. (For general information about option files, 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:

shell> 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 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, so 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, so 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.