.. _api-mysql:

connection.MySQLConnection
==========================

.. py:module:: mysql.connector.connection
	:synopsis: Database interface for MySQL implementing, but not limited to,
		DB-API v2.0.

.. py:class:: MySQLConnection

   A MySQL object representing a connection to the MySQL server.
   
   Best practice is to use the module 'connect()' function like in the
   following example:
   
   >>> import mysql.connector
   >>> cnx = mysql.connector.connect(host='localhost',database='test')
   >>> cnx.close()

Attributes and Properties
-------------------------

.. py:attribute:: MySQLConnection.charset

  Set and retrieve the character set used for the current MySQL client
  connection.
  Setting the character will set the default collation for the character set
  you are changing too. If you want to change the collation, use the the
  :py:attr:`collation` property.
  
  >>> cnx.charset
  u'utf8'
  >>> cnx.charset = 'latin1'
  >>> cnx.charset
  u'latin1'

.. py:attribute:: MySQLConnection.collation

  Set the collation for the current MySQL client connection. Setting the
  collation will not touch the character set setting, however, setting
  the character set using :py:attr:`charset` will reset the collation to
  the default.
  
  For example, when connecting to MySQL, ``utf8`` is the default character
  set:
  
  >>> cnx = mysql.connector.connect(host='localhost',database='test')
  >>> cnx.collation
  u'utf8_general_ci'
  
  You can then set the collation to whatever you like, but when you set the
  character set, it will be set back to the default:
  
  >>> cnx.collation = 'utf8_unicode_ci'
  >>> cnx.collation
  u'utf8_unicode_ci'
  >>> cnx.collation = 'latin1_german2_ci'
  >>> cnx.collation
  u'latin1_german2_ci'
  >>> cnx.charset = 'utf8'
  >>> cnx.collation
  u'utf8_general_ci'

.. py:attribute:: MySQLConnection.database

   Set and retrieve the current or default database.
   
   >>> cnx = mysql.connector.connect(host='localhost',database='test')
   >>> cnx.database
   u'test'
   >>> cnx.database = 'mysql'
   Traceback (most recent call last):
   ..
   mysql.connector.errors.OperationalError: 1044: Access denied for user ''@'localhost' to database 'mysql'

Methods
-------

.. py:method:: MySQLConnection.connect([database=None, user='', password='',\
         host='127.0.0.1', port=3306, unix_socket=None,\
         use_unicode=True, charset='utf8', collation=None,\
         autocommit=False,\
         time_zone=None, sql_mode=None,\
         get_warnings=False, raise_on_warnings=False,\
         connection_timeout=None, client_flags=0,\
         buffered=False, raw=False,\
         passwd=None, db=None, connect_timeout=None, dsn=None])

			Connect to a MySQL server. All arguments are optional.

         :param database:
            Database or schema name to use when connecting with MySQL.

         :param user:
            The username used to authenticate with the MySQL Server.
         
         :param password:
            The password to authenticate the user with the MySQL Server.
         
         :param host:
            Hostname or IP address of the MySQL Server.
         
         :param port:
            TCP/IP port of the MySQL Server. Default ``3306``.
         
         :param unix_socket:
            The location of the Unix socket file. Default ``None``.
         
         :param use_unicode:
            Whether to use Unicode or not. Default is ``True``.
         
         :param charset:
            Which character set to use. Default is ``utf8``.
         
         :param collation:
            Which collation to use. Default derived from *charset*.
         
         :param autocommit:
            Auto commit transactions. Default is ``False``.
         
         :param time_zone:
            Set the time_zone session variable at connection. Default
            ``None`` (use server global time_zone).

         :param sql_mode:
            Set the sql_mode session variable at connection. Default ``None``
            (use server global sql_mode).
         
         :param get_warnings:
            Whether to fetch warnings. Default is ``False``.
         
         :param raise_on_warnings:
            Whether to raise an exception on Warnigns. Default is ``False``.
         
         :param connection_timeout:
            Timeout for the TCP and Unix socket connections.
         
         :param client_flags:
            MySQL client flags. When not given, defaults to MySQL 4.1 client
            flags.
         
         :param buffered:
            If ``True``, cursor object will fetch result immediatly. Default
            ``False``.
         
         :param raw:
            If ``True``, MySQL result will not be converted to Python types.
            Default ``False``.
         
         :param passwd:
            Same as *password* (which takes precedence).
         
         :param db:
            Same as *database* (which takes precedence).
         
         :param connect_timeout:
            Same as *connection_timeout* (which takes precedence).
            
         :param dsn:
            Not used (will raise NotSupportedError).
         
         When the *database* parameter is given, the current database will
         be set to the given value. You can later change the database
         using the MySQL ``USE`` command, or by setting the 
         :py:attr:`database` property.
         
         Authentication with MySQL will use *username* and *password*. Note
         that MySQL Connector/Python does not and will not support the
         old, insecure passwords of earlier MySQL protocols.
         
         By default, we will connect with a MySQL sever using TCP/IP running
         locally on port 3306. You can use the *host* and *port* arguments
         to connect to a remote server.
         Unix sockets are supported by setting *unix_socket*. Named pipes
         on the Windows-platform are not supported.
         
         Strings coming from MySQL are returned as unicode. You can change
         this behavior by setting *use_unicode* to ``False``.
         
         You can change the character setting for the client connection
         through the *charset* argument. If you want to change the character
         set after connecting to MySQL, set the :py:attr:`charset` property.
         It is discouraged to use the MySQL ``SET NAMES`` command directly.
         
         Similar to the *charset* argument, you can set the *collation*
         for the current MySQL session.
         
         Transactions are not automatically commited and the application will
         need to call :py:meth:`commit`. If you don't want this, set
         *autocommit* to ``True`` (not recommended).
         
         Time zone can be set per connection setting the *time_zone* argument.
         This is useful if the MySQL server is set to UTC and you'd like
         the MySQL ``TIMESTAMP`` values converted to ``PST``, for example.
         
         MySQL supports so called SQL Modes which will change the behavior
         of the server globally or per connection. If you want, for example,
         warnings raised as errors, you could set *sql_mode* to
         ``TRADIONTAL``. Please check the `MySQL Manual
         <http://http://dev.mysql.com/doc/refman/5.1/en/server-sql-mode.html>`_
         for explanation of all modes.
         
         Warnings generated by queries will be fetched autmatically when
         *get_warnings* is set to ``True``. You can also immediatally raise
         an exception by setting *raise_on_warnings* to ``True``.
         Consider using SQL Modes for turning warnings into errors.
         
         Timeout for connections can be set using *connection_timeout*.
         
         MySQL uses client flags when connecting to enable or disable
         certain features. Using the *client_flags* arguments you have
         controle of what is set. To find out what flags are available,
         you can 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
         will used for MySQL v4.1 and later. If you specify an integer greater
         than ``0``, you need to make sure all flags are set. However, a much
         better way to set and unset flags is to use a list.

         For example, you want to set the FOUND_ROWS-flag:
         
         >>> mysql.connector.connect(client_flags=[ClientFlag.FOUND_ROWS])
         
         If you want to unset one of the defaults, e.g. LONG_FLAG:
         
         >>> mysql.connector.connect(client_flags=[
            ClientFlag.FOUND_ROWS,
            -ClientFlag.LONG_FLAG,
            ])
         
         MySQL Connector/Python does not buffer or pre-fetch results. This
         means the after a query is executed, the programmer is responsible of
         fetching the data. This is useful for queries returning big result
         sets. If fetching results is desired, set *buffered* to ``True``.
         It is possible to set this per cursor (see :py:meth:`cursor`).
         
         MySQL types will be converted automatically to Python types. For
         example, a ``DATETIME`` column becomas a ``datetime.datetime`` 
         object.
         When conversion will be done later, and performance is needed,
         set *raw* to ``True``. This will return what comes from MySQL as
         a string. It is possible to set this per cursor (see
         :py:meth:`cursor`).
         
         *passwd*, *db* and *connect_timeout* are there 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 and will raise
         ``NotSupportedError``. 
         