PageRenderTime 103ms CodeModel.GetById 28ms RepoModel.GetById 0ms app.codeStats 1ms

/resources/lib/mysql-connector-python/docs/mysql-connector-python.html

https://github.com/wtmmac/mythbox
HTML | 2302 lines | 2295 code | 7 blank | 0 comment | 0 complexity | b7e5095c4d72b94bace63b59d34bdc5a MD5 | raw file
Possible License(s): Unlicense, AGPL-1.0, BSD-2-Clause, GPL-2.0, MIT, Apache-2.0 
    

  1. <html lang="en"><head><meta http-equiv="Content-Type" content="text/html; charset=utf-8"><title>MySQL Connector/Python</title><link rel="stylesheet" type="text/css" href="mysql-html.css"><meta name="generator" content="DocBook XSL Stylesheets V1.77.1">
    2. 

  2. <script language="javascript" type="text/javascript">
    3. 

  3.   function addOnload(theFunc)
    4. 

  4.   {
    5. 

  5.     var previous = window.onload;
    6. 

  6.     if (typeof window.onload != 'function')
    7. 

  7.     {
    8. 

  8.       window.onload = theFunc;
    9. 

  9.     }
    10. 

  10.     else
    11. 

  11.     {
    12. 

  12.       window.onload = function()
    13. 

  13.       {
    14. 

  14.         previous();
    15. 

  15.         theFunc();
    16. 

  16.       }
    17. 

  17.     }
    18. 

  18.   }
    19. 

  19. 

  20.   addOnload(function()
    21. 

  21.   {
    22. 

  22.     var base = new Date(1355755772*1000);
    23. 

  23.     var now = new Date();
    24. 

  24.     var diff = ((now-base)/1000)/(24*3600);
    25. 

  25. 

  26.     if (diff > 90) {
    27. 

  27.       var nodes = document.getElementsByClassName('titlepage');
    28. 

  28.       nodes[0].innerHTML = '<p style="border: 5px #ff0000 solid; padding: 5px; margin 5px">' +
    29. 

  29.         'This copy of the manual is more than 90 days old. We encourage you to download a ' +
    30. 

  30.         'new version from <a href="http://dev.mysql.com">dev.mysql.com/doc</a>.</p>' + nodes[0].innerHTML;
    31. 

  31.     }
    32. 

  32.   });
    33. 

  33. </script>
    34. 

  34. <noscript></noscript>
    35. 

  35. </head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div lang="en" class="book"><div class="titlepage"><div><div><h1 class="title"><a name="connectors"></a>MySQL Connector/Python</h1></div><div><div class="abstract"><p class="title"><b>Abstract</b></p><p>
    36. 

  36.         This manual describes how to install, configure, and develop
    37. 

  37.         database applications using MySQL Connector/Python, a
    38. 

  38.         self-contained Python driver for communicating with MySQL
    39. 

  39.         servers.
    40. 

  40.       </p><p>
    41. 

  41.         Document generated on:
    42. 

  42. 

  43.         2012-12-17
    44. 

  44. 

  45. 

  46. 

  47.         (revision: 33584)
    48. 

  48.       </p></div></div></div><hr></div><div class="toc"><p><b>Table of Contents</b></p><dl><dt><span class="preface"><a href="#preface">Preface and Legal Notices</a></span></dt><dt><span class="chapter"><a href="#connector-python">1. MySQL Connector/Python</a></span></dt><dt><span class="chapter"><a href="#connector-python-versions">2. Connector/Python Versions</a></span></dt><dt><span class="chapter"><a href="#connector-python-install">3. Connector/Python Installation</a></span></dt><dd><dl><dt><span class="section"><a href="#connector-python-installation-src-unix">3.1. Installing Connector/Python Source Distribution on Linux, UNIX, or OS X</a></span></dt><dt><span class="section"><a href="#connector-python-installation-src-windows">3.2. Installing Connector/Python Source Distribution on Microsoft Windows</a></span></dt><dt><span class="section"><a href="#connector-python-verification">3.3. Verifying Your Connector/Python Installation</a></span></dt></dl></dd><dt><span class="chapter"><a href="#connector-python-examples">4. Connector/Python Coding Examples</a></span></dt><dd><dl><dt><span class="section"><a href="#myconnpy_example_connecting">4.1. Connecting to MySQL Using Connector/Python</a></span></dt><dt><span class="section"><a href="#myconnpy_example_ddl">4.2. Creating Tables Using Connector/Python</a></span></dt><dt><span class="section"><a href="#myconnpy_example_cursor_transaction">4.3. Inserting Data Using Connector/Python</a></span></dt><dt><span class="section"><a href="#myconnpy_example_cursor_select">4.4. Querying Data Using Connector/Python</a></span></dt></dl></dd><dt><span class="chapter"><a href="#connector-python-tutorials">5. Connector/Python Tutorials</a></span></dt><dd><dl><dt><span class="section"><a href="#myconnpy_tutorial_CursorBuffered_GiveRaise">5.1. Tutorial: Raise employee's salary using a buffering cursor</a></span></dt></dl></dd><dt><span class="chapter"><a href="#connector-python-connectargs">6. Connector/Python Connection Arguments</a></span></dt><dt><span class="chapter"><a href="#connector-python-reference">7. Connector/Python API Reference</a></span></dt><dd><dl><dt><span class="section"><a href="#connector-python-apiref-errors">7.1. Errors and Exceptions</a></span></dt><dd><dl><dt><span class="section"><a href="#connector-python-apiref-errorcode">7.1.1. Module <code class="literal">errorcode</code></a></span></dt><dt><span class="section"><a href="#connector-python-apiref-errors-error">7.1.2. Exception <code class="literal">errors.Error</code></a></span></dt><dt><span class="section"><a href="#connector-python-apiref-errors-warning">7.1.3. Exception <code class="literal">errors.Warning</code></a></span></dt><dt><span class="section"><a href="#connector-python-apiref-errors-interfaceerror">7.1.4. Exception <code class="literal">errors.InterfaceError</code></a></span></dt><dt><span class="section"><a href="#connector-python-apiref-errors-databaseerror">7.1.5. Exception <code class="literal">errors.DatabaseError</code></a></span></dt><dt><span class="section"><a href="#connector-python-apiref-errors-internalerror">7.1.6. Exception <code class="literal">errors.InternalError</code></a></span></dt><dt><span class="section"><a href="#connector-python-apiref-errors-operationalerror">7.1.7. Exception <code class="literal">errors.OperationalError</code></a></span></dt><dt><span class="section"><a href="#connector-python-apiref-errors-programmingerror">7.1.8. Exception <code class="literal">errors.ProgrammingError</code></a></span></dt><dt><span class="section"><a href="#connector-python-apiref-errors-integrityerror">7.1.9. Exception <code class="literal">errors.IntegrityError</code></a></span></dt><dt><span class="section"><a href="#connector-python-apiref-errors-dataerror">7.1.10. Exception <code class="literal">errors.DataError</code></a></span></dt><dt><span class="section"><a href="#connector-python-apiref-errors-notsupportederror">7.1.11. Exception <code class="literal">errors.NotSupportedError</code></a></span></dt><dt><span class="section"><a href="#connector-python-apiref-errors-custom-error-exception">7.1.12. Function <code class="literal">errors.custom_error_exception(error=None,
    49. 

  49.         exception=None)</code></a></span></dt></dl></dd><dt><span class="section"><a href="#connector-python-apiref-MySQLConnection">7.2. Class <code class="literal">connection.MySQLConnection</code></a></span></dt><dd><dl><dt><span class="section"><a href="#myconnpy_MySQLConnection">7.2.1. Constructor <code class="literal">connection.MySQLConnection(**kwargs)</code></a></span></dt><dt><span class="section"><a href="#myconnpy_MySQLConnection_close">7.2.2. Method <code class="literal">MySQLConnection.close()</code></a></span></dt><dt><span class="section"><a href="#myconnpy_MySQLConnection_config">7.2.3. Method <code class="literal">MySQLConnection.config(**kwargs)</code></a></span></dt><dt><span class="section"><a href="#myconnpy_MySQLConnection_connect">7.2.4. Method <code class="literal">MySQLConnection.connect(**kwargs)</code></a></span></dt><dt><span class="section"><a href="#myconnpy_MySQLConnection_commit">7.2.5. Method <code class="literal">MySQLConnection.commit()</code></a></span></dt><dt><span class="section"><a href="#myconnpy_MySQLConnection_cursor">7.2.6. Method <code class="literal">MySQLConnection.cursor(buffered=None, raw=None,
    50. 

  50.         cursor_class=None)</code></a></span></dt><dt><span class="section"><a href="#myconnpy_MySQLConnection_cmd_change_user">7.2.7. Method <code class="literal">MySQLConnection.cmd_change_user(username='',
    51. 

  51.         password='', database='', charset=33)</code></a></span></dt><dt><span class="section"><a href="#myconnpy_MySQLConnection_cmd_debug">7.2.8. Method <code class="literal">MySQLConnection.cmd_debug()</code></a></span></dt><dt><span class="section"><a href="#myconnpy_MySQLConnection_cmd_init_db">7.2.9. Method <code class="literal">MySQLConnection.cmd_init_db(database)</code></a></span></dt><dt><span class="section"><a href="#myconnpy_MySQLConnection_cmd_ping">7.2.10. Method <code class="literal">MySQLConnection.cmd_ping()</code></a></span></dt><dt><span class="section"><a href="#myconnpy_MySQLConnection_cmd_process_info">7.2.11. Method <code class="literal">MySQLConnection.cmd_process_info()</code></a></span></dt><dt><span class="section"><a href="#myconnpy_MySQLConnection_cmd_process_kill">7.2.12. Method <code class="literal">MySQLConnection.cmd_process_kill(mysql_pid)</code></a></span></dt><dt><span class="section"><a href="#myconnpy_MySQLConnection_cmd_quit">7.2.13. Method <code class="literal">MySQLConnection.cmd_quit()</code></a></span></dt><dt><span class="section"><a href="#myconnpy_MySQLConnection_cmd_query">7.2.14. Method <code class="literal">MySQLConnection.cmd_query(statement)</code></a></span></dt><dt><span class="section"><a href="#myconnpy_MySQLConnection_cmd_query_iter">7.2.15. Method <code class="literal">MySQLConnection.cmd_query_iter(statement)</code></a></span></dt><dt><span class="section"><a href="#myconnpy_MySQLConnection_cmd_refresh">7.2.16. Method <code class="literal">MySQLConnection.cmd_refresh(options)</code></a></span></dt><dt><span class="section"><a href="#myconnpy_MySQLConnection_cmd_shutdown">7.2.17. Method <code class="literal">MySQLConnection.cmd_shutdown()</code></a></span></dt><dt><span class="section"><a href="#myconnpy_MySQLConnection_cmd_statistics">7.2.18. Method <code class="literal">MySQLConnection.cmd_statistics()</code></a></span></dt><dt><span class="section"><a href="#myconnpy_MySQLConnection_disconnect">7.2.19. Method <code class="literal">MySQLConnection.disconnect()</code></a></span></dt><dt><span class="section"><a href="#myconnpy_MySQLConnection_get_rows">7.2.20. Method <code class="literal">MySQLConnection.get_rows(count=None)</code></a></span></dt><dt><span class="section"><a href="#myconnpy_MySQLConnection_get_row">7.2.21. Method <code class="literal">MySQLConnection.get_row()</code></a></span></dt><dt><span class="section"><a href="#myconnpy_MySQLConnection_get_server_info">7.2.22. Method <code class="literal">MySQLConnection.get_server_info()</code></a></span></dt><dt><span class="section"><a href="#myconnpy_MySQLConnection_get_server_version">7.2.23. Method <code class="literal">MySQLConnection.get_server_version()</code></a></span></dt><dt><span class="section"><a href="#myconnpy_MySQLConnection_is_connected">7.2.24. Method <code class="literal">MySQLConnection.is_connected()</code></a></span></dt><dt><span class="section"><a href="#myconnpy_MySQLConnection_isset_client_flag">7.2.25. Method <code class="literal">MySQLConnection.isset_client_flag(flag)</code></a></span></dt><dt><span class="section"><a href="#myconnpy_MySQLConnection_ping">7.2.26. Method <code class="literal">MySQLConnection.ping(attempts=1, delay=0)</code></a></span></dt><dt><span class="section"><a href="#myconnpy_MySQLConnectoin_reconnect">7.2.27. Method <code class="literal">MySQLConnection.reconnect(attempts=1, delay=0)</code></a></span></dt><dt><span class="section"><a href="#myconnpy_MySQLConnection_rollback">7.2.28. Method <code class="literal">MySQLConnection.rollback()</code></a></span></dt><dt><span class="section"><a href="#myconnpy_MySQLConnection_set_charset_collation">7.2.29. Method <code class="literal">MySQLConnection.set_charset_collation(charset=None,
    52. 

  52.         collation=None)</code></a></span></dt><dt><span class="section"><a href="#myconnpy_MySQLConnection_set_client_flags">7.2.30. Method <code class="literal">MySQLConnection.set_client_flags(flags)</code></a></span></dt><dt><span class="section"><a href="#myconnpy_MySQLConnection_autocommit">7.2.31. Property <code class="literal">MySQLConnection.autocommit</code></a></span></dt><dt><span class="section"><a href="#myconnpy_MySQLConnection_charset_name">7.2.32. Property <code class="literal">MySQLConnection.charset_name</code></a></span></dt><dt><span class="section"><a href="#myconnpy_MySQLConnection_collation_name">7.2.33. Property <code class="literal">MySQLConnection.collation_name</code></a></span></dt><dt><span class="section"><a href="#myconnpy_MySQLConnection_connection_id">7.2.34. Property <code class="literal">MySQLConnection.connection_id</code></a></span></dt><dt><span class="section"><a href="#myconnpy_MySQLConnection_database">7.2.35. Property <code class="literal">MySQLConnection.database</code></a></span></dt><dt><span class="section"><a href="#myconnpy_MySQLConnection_get_warnings">7.2.36. Property <code class="literal">MySQLConnection.get_warnings</code></a></span></dt><dt><span class="section"><a href="#myconnpy_MySQLConnection_raise_on_warnings">7.2.37. Property <code class="literal">MySQLConnection.raise_on_warnings</code></a></span></dt><dt><span class="section"><a href="#myconnpy_MySQLConnection_server_host">7.2.38. Property <code class="literal">MySQLConnection.server_host</code></a></span></dt><dt><span class="section"><a href="#myconnpy_MySQLConnection_server_port">7.2.39. Property <code class="literal">MySQLConnection.server_port</code></a></span></dt><dt><span class="section"><a href="#myconnpy_MySQLConnection_sql_mode">7.2.40. Property <code class="literal">MySQLConnection.sql_mode</code></a></span></dt><dt><span class="section"><a href="#myconnpy_MySQLConnection_time_zone">7.2.41. Property <code class="literal">MySQLConnection.time_zone</code></a></span></dt><dt><span class="section"><a href="#myconnpy_MySQLConnection_unix_socket">7.2.42. Property <code class="literal">MySQLConnection.unix_socket</code></a></span></dt><dt><span class="section"><a href="#myconnpy_MySQLConnection_user">7.2.43. Property <code class="literal">MySQLConnection.user</code></a></span></dt></dl></dd><dt><span class="section"><a href="#connector-python-apiref-MySQLCursor">7.3. Class <code class="literal">cursor.MySQLCursor</code></a></span></dt><dd><dl><dt><span class="section"><a href="#myconnpy_MySQLCursor">7.3.1. Constructor <code class="literal">cursor.MySQLCursor</code></a></span></dt><dt><span class="section"><a href="#myconnpy_MySQLCursor_callproc">7.3.2. Method <code class="literal">MySQLCursor.callproc(procname, args=())</code></a></span></dt><dt><span class="section"><a href="#myconnpy_MySQLCursor_close">7.3.3. Method <code class="literal">MySQLCursor.close()</code></a></span></dt><dt><span class="section"><a href="#myconnpy_MySQLCursor_execute">7.3.4. Method <code class="literal">MySQLCursor.execute(operation, params=None,
    53. 

  53.         multi=False)</code></a></span></dt><dt><span class="section"><a href="#myconnpy_MySQLCursor_executemany">7.3.5. Method <code class="literal">MySQLCursor.executemany(operation, seq_params)</code></a></span></dt><dt><span class="section"><a href="#myconnpy_MySQLCursor_fetchall">7.3.6. Method <code class="literal">MySQLCursor.fetchall()</code></a></span></dt><dt><span class="section"><a href="#myconnpy_MySQLCursor_fetchmany">7.3.7. Method <code class="literal">MySQLCursor.fetchmany(size=1)</code></a></span></dt><dt><span class="section"><a href="#myconnpy_MySQLCursor_fetchone">7.3.8. Method <code class="literal">MySQLCursor.fetchone()</code></a></span></dt><dt><span class="section"><a href="#myconnpy_MySQLCursor_fetchwarnings">7.3.9. Method <code class="literal">MySQLCursor.fetchwarnings()</code></a></span></dt><dt><span class="section"><a href="#myconnpy_MySQLCursor_stored_results">7.3.10. Method <code class="literal">MySQLCursor.stored_results()</code></a></span></dt><dt><span class="section"><a href="#myconnpy_MySQLCursor_column_names">7.3.11. Property <code class="literal">MySQLCursor.column_names</code></a></span></dt><dt><span class="section"><a href="#myconnpy_MySQLCursor_statement">7.3.12. Property <code class="literal">MySQLCursor.statement</code></a></span></dt><dt><span class="section"><a href="#myconnpy_MySQLCursor_with_rows">7.3.13. Property <code class="literal">MySQLCursor.with_rows</code></a></span></dt></dl></dd><dt><span class="section"><a href="#connector-python-apiref-MySQLCursorBuffered">7.4. Class <code class="literal">cursor.MySQLCursorBuffered</code></a></span></dt><dt><span class="section"><a href="#connector-python-apiref-ClientFlag">7.5. Class <code class="literal">constants.ClientFlag</code></a></span></dt><dt><span class="section"><a href="#connector-python-apiref-FieldType">7.6. Class <code class="literal">constants.FieldType</code></a></span></dt><dt><span class="section"><a href="#connector-python-apiref-SQLMode">7.7. Class <code class="literal">constants.SQLMode</code></a></span></dt><dt><span class="section"><a href="#connector-python-apiref-CharacterSet">7.8. Class <code class="literal">constants.CharacterSet</code></a></span></dt><dt><span class="section"><a href="#connector-python-apiref-RefreshOption">7.9. Class <code class="literal">constants.RefreshOption</code></a></span></dt></dl></dd><dt><span class="chapter"><a href="#cpython-news">8. MySQL Connector/Python Change History</a></span></dt><dd><dl><dt><span class="section"><a href="#cpython-news-1-0-8">8.1. Changes in MySQL Connector/Python 1.0.8 (Not yet released, Generally Available)</a></span></dt><dt><span class="section"><a href="#cpython-news-1-0-7">8.2. Changes in MySQL Connector/Python 1.0.7 (29 September 2012, Generally Available)</a></span></dt><dt><span class="section"><a href="#cpython-news-1-0-6">8.3. Changes in MySQL Connector/Python 1.0.6 (30 August 2012, beta)</a></span></dt><dt><span class="section"><a href="#cpython-news-1-0-5">8.4. Changes in MySQL Connector/Python 1.0.5 (17 July 2012, beta)</a></span></dt><dt><span class="section"><a href="#cpython-news-1-0-4">8.5. Changes in MySQL Connector/Python 1.0.4 (07 July 2012, alpha)</a></span></dt><dt><span class="section"><a href="#cpython-news-1-0-3">8.6. Changes in MySQL Connector/Python 1.0.3 (08 June 2012, alpha)</a></span></dt><dt><span class="section"><a href="#cpython-news-1-0-2">8.7. Changes in MySQL Connector/Python 1.0.2 (19 May 2012, alpha)</a></span></dt><dt><span class="section"><a href="#cpython-news-1-0-1">8.8. Changes in MySQL Connector/Python 1.0.1 (26 April 2012, alpha)</a></span></dt><dt><span class="section"><a href="#cpython-news-1-0-0">8.9. Changes in MySQL Connector/Python 1.0.0 (22 April 2012, alpha)</a></span></dt></dl></dd></dl></div><div class="preface"><div class="titlepage"><div><div><h1 class="title"><a name="preface"></a>Preface and Legal Notices</h1></div></div></div><p>
    54. 

  54.       This manual describes how to install, configure, and develop
    55. 

  55.       database applications using MySQL Connector/Python, the a
    56. 

  56.       self-contained Python driver for communicating with MySQL servers.
    57. 

  57.     </p><h2><a name="legalnotice"></a>Legal Notices</h2><p>
    58. 

  58.     Copyright © 2012, Oracle and/or its affiliates. All rights
    59. 

  59.     reserved.
    60. 

  60.   </p><p>
    61. 

  61.     This software and related documentation are provided under a license
    62. 

  62.     agreement containing restrictions on use and disclosure and are
    63. 

  63.     protected by intellectual property laws. Except as expressly
    64. 

  64.     permitted in your license agreement or allowed by law, you may not
    65. 

  65.     use, copy, reproduce, translate, broadcast, modify, license,
    66. 

  66.     transmit, distribute, exhibit, perform, publish, or display any
    67. 

  67.     part, in any form, or by any means. Reverse engineering,
    68. 

  68.     disassembly, or decompilation of this software, unless required by
    69. 

  69.     law for interoperability, is prohibited.
    70. 

  70.   </p><p>
    71. 

  71.     The information contained herein is subject to change without notice
    72. 

  72.     and is not warranted to be error-free. If you find any errors,
    73. 

  73.     please report them to us in writing.
    74. 

  74.   </p><p>
    75. 

  75.     If this software or related documentation is delivered to the U.S.
    76. 

  76.     Government or anyone licensing it on behalf of the U.S. Government,
    77. 

  77.     the following notice is applicable:
    78. 

  78.   </p><p>
    79. 

  79.     U.S. GOVERNMENT RIGHTS Programs, software, databases, and related
    80. 

  80.     documentation and technical data delivered to U.S. Government
    81. 

  81.     customers are "commercial computer software" or "commercial
    82. 

  82.     technical data" pursuant to the applicable Federal Acquisition
    83. 

  83.     Regulation and agency-specific supplemental regulations. As such,
    84. 

  84.     the use, duplication, disclosure, modification, and adaptation shall
    85. 

  85.     be subject to the restrictions and license terms set forth in the
    86. 

  86.     applicable Government contract, and, to the extent applicable by the
    87. 

  87.     terms of the Government contract, the additional rights set forth in
    88. 

  88.     FAR 52.227-19, Commercial Computer Software License (December 2007).
    89. 

  89.     Oracle USA, Inc., 500 Oracle Parkway, Redwood City, CA 94065.
    90. 

  90.   </p><p>
    91. 

  91.     This software is developed for general use in a variety of
    92. 

  92.     information management applications. It is not developed or intended
    93. 

  93.     for use in any inherently dangerous applications, including
    94. 

  94.     applications which may create a risk of personal injury. If you use
    95. 

  95.     this software in dangerous applications, then you shall be
    96. 

  96.     responsible to take all appropriate fail-safe, backup, redundancy,
    97. 

  97.     and other measures to ensure the safe use of this software. Oracle
    98. 

  98.     Corporation and its affiliates disclaim any liability for any
    99. 

  99.     damages caused by use of this software in dangerous applications.
    100. 

  100.   </p><p>
    101. 

  101.     Oracle is a registered trademark of Oracle Corporation and/or its
    102. 

  102.     affiliates. MySQL is a trademark of Oracle Corporation and/or its
    103. 

  103.     affiliates, and shall not be used without Oracle's express written
    104. 

  104.     authorization. Other names may be trademarks of their respective
    105. 

  105.     owners.
    106. 

  106.   </p><p>
    107. 

  107.     This software and documentation may provide access to or information
    108. 

  108.     on content, products, and services from third parties. Oracle
    109. 

  109.     Corporation and its affiliates are not responsible for and expressly
    110. 

  110.     disclaim all warranties of any kind with respect to third-party
    111. 

  111.     content, products, and services. Oracle Corporation and its
    112. 

  112.     affiliates will not be responsible for any loss, costs, or damages
    113. 

  113.     incurred due to your access to or use of third-party content,
    114. 

  114.     products, or services.
    115. 

  115.   </p><p>
    116. 

  116.     This documentation is in prerelease status and is intended for
    117. 

  117.     demonstration and preliminary use only. It may not be specific to
    118. 

  118.     the hardware on which you are using the software. Oracle Corporation
    119. 

  119.     and its affiliates are not responsible for and expressly disclaim
    120. 

  120.     all warranties of any kind with respect to this documentation and
    121. 

  121.     will not be responsible for any loss, costs, or damages incurred due
    122. 

  122.     to the use of this documentation.
    123. 

  123.   </p><p>
    124. 

  124.     The information contained in this document is for informational
    125. 

  125.     sharing purposes only and should be considered in your capacity as a
    126. 

  126.     customer advisory board member or pursuant to your beta trial
    127. 

  127.     agreement only. It is not a commitment to deliver any material,
    128. 

  128.     code, or functionality, and should not be relied upon in making
    129. 

  129.     purchasing decisions. The development, release, and timing of any
    130. 

  130.     features or functionality described in this document remains at the
    131. 

  131.     sole discretion of Oracle.
    132. 

  132.   </p><p>
    133. 

  133.     This document in any form, software or printed matter, contains
    134. 

  134.     proprietary information that is the exclusive property of Oracle.
    135. 

  135.     Your access to and use of this material is subject to the terms and
    136. 

  136.     conditions of your Oracle Software License and Service Agreement,
    137. 

  137.     which has been executed and with which you agree to comply. This
    138. 

  138.     document and information contained herein may not be disclosed,
    139. 

  139.     copied, reproduced, or distributed to anyone outside Oracle without
    140. 

  140.     prior written consent of Oracle or as specifically provided below.
    141. 

  141.     This document is not part of your license agreement nor can it be
    142. 

  142.     incorporated into any contractual agreement with Oracle or its
    143. 

  143.     subsidiaries or affiliates.
    144. 

  144.   </p><p>
    145. 

  145.     This documentation is NOT distributed under a GPL license. Use of
    146. 

  146.     this documentation is subject to the following terms:
    147. 

  147.   </p><p>
    148. 

  148.     You may create a printed copy of this documentation solely for your
    149. 

  149.     own personal use. Conversion to other formats is allowed as long as
    150. 

  150.     the actual content is not altered or edited in any way. You shall
    151. 

  151.     not publish or distribute this documentation in any form or on any
    152. 

  152.     media, except if you distribute the documentation in a manner
    153. 

  153.     similar to how Oracle disseminates it (that is, electronically for
    154. 

  154.     download on a Web site with the software) or on a CD-ROM or similar
    155. 

  155.     medium, provided however that the documentation is disseminated
    156. 

  156.     together with the software on the same medium. Any other use, such
    157. 

  157.     as any dissemination of printed copies or use of this documentation,
    158. 

  158.     in whole or in part, in another publication, requires the prior
    159. 

  159.     written consent from an authorized representative of Oracle. Oracle
    160. 

  160.     and/or its affiliates reserve any and all rights to this
    161. 

  161.     documentation not expressly granted above.
    162. 

  162.   </p><p>
    163. 

  163.     For more information on the terms of this license, or for details on
    164. 

  164.     how the MySQL documentation is built and produced, please visit
    165. 

  165.     <a class="ulink" href="http://dev.mysql.com/contact/" target="_top">MySQL Contact &amp;
    166. 

  166.     Questions</a>.
    167. 

  167.   </p><p>
    168. 

  168.     For additional licensing information, including licenses for
    169. 

  169.     third-party libraries used by MySQL products, see
    170. 

  170.     <a class="xref" href="#preface" title="Preface and Legal Notices">Preface and Legal Notices</a>.
    171. 

  171.   </p><p>
    172. 

  172.     For help with using MySQL, please visit either the
    173. 

  173.     <a class="ulink" href="http://forums.mysql.com" target="_top">MySQL Forums</a> or
    174. 

  174.     <a class="ulink" href="http://lists.mysql.com" target="_top">MySQL Mailing Lists</a>
    175. 

  175.     where you can discuss your issues with other MySQL users.
    176. 

  176.   </p><p>
    177. 

  177.     For additional documentation on MySQL products, including
    178. 

  178.     translations of the documentation into other languages, and
    179. 

  179.     downloadable versions in variety of formats, including HTML and PDF
    180. 

  180.     formats, see the <a class="ulink" href="http://dev.mysql.com/doc" target="_top">MySQL
    181. 

  181.     Documentation Library</a>.
    182. 

  182.   </p></div><div class="chapter"><div class="titlepage"><div><div><h1 class="title"><a name="connector-python"></a>Chapter 1. MySQL Connector/Python</h1></div></div></div><a class="indexterm" name="id498227"></a><a class="indexterm" name="id498233"></a><a class="indexterm" name="id498240"></a><p>
    183. 

  183.     MySQL Connector/Python allows Python programs to access MySQL
    184. 

  184.     databases, using an API that is compliant with the
    185. 

  185.     <a class="ulink" href="http://www.python.org/dev/peps/pep-0249/" target="_top">Python DB API
    186. 

  186.     version 2.0</a>. It is written in pure Python and does not have
    187. 

  187.     any dependencies except for the
    188. 

  188.     <a class="ulink" href="http://docs.python.org/library/" target="_top">Python Standard
    189. 

  189.     Library</a>.
    190. 

  190.   </p><p>
    191. 

  191.     MySQL Connector/Python includes support for:
    192. 

  192.   </p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
    193. 

  193.         Almost all features provided by MySQL Server up to and including
    194. 

  194.         MySQL Server version 5.5.
    195. 

  195.       </p></li><li class="listitem"><p>
    196. 

  196.         Converting parameter values back and forth between Python and
    197. 

  197.         MySQL data types, for example Python <code class="literal">datetime</code>
    198. 

  198.         and MySQL <code class="literal">DATETIME</code>. You can turn automatic
    199. 

  199.         conversion on for convenience, or off for optimal performance.
    200. 

  200.       </p></li><li class="listitem"><p>
    201. 

  201.         All MySQL extensions to standard SQL syntax.
    202. 

  202.       </p></li><li class="listitem"><p>
    203. 

  203.         Protocol compression, which enables compressing the data stream
    204. 

  204.         between the client and server.
    205. 

  205.       </p></li><li class="listitem"><p>
    206. 

  206.         Connections using TCP/IP sockets and on Unix using Unix sockets.
    207. 

  207.       </p></li><li class="listitem"><p>
    208. 

  208.         Secure TCP/IP connections using SSL.
    209. 

  209.       </p></li><li class="listitem"><p>
    210. 

  210.         Self-contained driver. Connector/Python does not require the
    211. 

  211.         MySQL client library or any Python modules outside the standard
    212. 

  212.         library.
    213. 

  213.       </p></li></ul></div><p>
    214. 

  214.     MySQL Connector/Python supports from Python version 2.4 through 2.7,
    215. 

  215.     and Python 3.1 and later. Note that Connector/Python does not
    216. 

  216.     support the old MySQL Server authentication methods, which means
    217. 

  217.     that MySQL versions prior to 4.1 will not work.
    218. 

  218.   </p></div><div class="chapter"><div class="titlepage"><div><div><h1 class="title"><a name="connector-python-versions"></a>Chapter 2. Connector/Python Versions</h1></div></div></div><p>
    219. 

  219.     MySQL Connector/Python v1.0.x series went going through a series of
    220. 

  220.     beta releases, leading to the first generally available (GA) version
    221. 

  221.     1.0.7. Any development releases prior to general availability are
    222. 

  222.     not supported now that the GA version is released.
    223. 

  223.   </p><p>
    224. 

  224.     The following table summarizes the available Connector/Python
    225. 

  225.     versions:
    226. 

  226.   </p><div class="table"><a name="id498371"></a><p class="title"><b>Table 2.1. Connector/Python Version Reference</b></p><div class="table-contents"><table summary=" For each Connector/Python version, this table lists the
    227. 

  227.       corresponding MySQL Server versions that it works with, the
    228. 

  228.       corresponding versions of Python that it works with, and whether
    229. 

  229.       it is pre-release, generally available (supported), or obsolete.
    230. 

  230.       MySQL server and Python versions within brackets are known to work
    231. 

  231.       with Connector/Python, but are not officially supported. Bugs
    232. 

  232.       might not get fixed for those versions. " border="1"><colgroup><col><col><col><col></colgroup><thead><tr><th scope="col">Connector/Python Version</th><th scope="col">MySQL Server Versions</th><th scope="col">Python Versions</th><th scope="col">Support Status for Connector</th></tr></thead><tbody><tr><td scope="row">1.0</td><td>5.6, 5.5 (5.1, 5.0, 4.1)</td><td>2.7, 2.6 (2.5, 2.4); 3.1 and later</td><td>Recommended version</td></tr></tbody></table></div></div><br class="table-break"><div xmlns="http://www.w3.org/1999/xhtml" class="note" style="margin-left: 0.5in; margin-right: 0.5in;"><div class="admon-title">Note</div><p xmlns="">
    233. 

  233.       MySQL server and Python versions within brackets are known to work
    234. 

  234.       with Connector/Python, but are not officially supported. Bugs
    235. 

  235.       might not get fixed for those versions.
    236. 

  236.     </p></div></div><div class="chapter"><div class="titlepage"><div><div><h1 class="title"><a name="connector-python-install"></a>Chapter 3. Connector/Python Installation</h1></div></div></div><div class="toc"><p><b>Table of Contents</b></p><dl><dt><span class="section"><a href="#connector-python-installation-src-unix">3.1. Installing Connector/Python Source Distribution on Linux, UNIX, or OS X</a></span></dt><dt><span class="section"><a href="#connector-python-installation-src-windows">3.2. Installing Connector/Python Source Distribution on Microsoft Windows</a></span></dt><dt><span class="section"><a href="#connector-python-verification">3.3. Verifying Your Connector/Python Installation</a></span></dt></dl></div><p>
    237. 

  237.     Connector/Python runs on any platform where Python is installed.
    238. 

  238.     Python comes pre-installed on almost any Linux distribution or
    239. 

  239.     UNIX-like system such as Apple Mac OS X and FreeBSD. On Microsoft
    240. 

  240.     Windows systems, you can install Python using the installer found on
    241. 

  241.     the <a class="ulink" href="http://python.org/download/" target="_top">Python Download
    242. 

  242.     website</a>.
    243. 

  243.   </p><p>
    244. 

  244.     Connector/Python is a pure Python implementation of the MySQL
    245. 

  245.     Client/Server protocol, meaning it does not require any other MySQL
    246. 

  246.     client libraries or other components. It also has no third-party
    247. 

  247.     dependencies. If you need SSL support, verify that your Python
    248. 

  248.     installation has been compiled using the
    249. 

  249.     <a class="ulink" href="http://www.openssl.org/" target="_top">OpenSSL</a> libraries.
    250. 

  250.   </p><p>
    251. 

  251.     The installation of Connector/Python is similar on every platform
    252. 

  252.     and follows the standard
    253. 

  253.     <a class="ulink" href="http://docs.python.org/install/index.html#install-index" target="_top">Python
    254. 

  254.     Distribution Utilities</a> or
    255. 

  255.     <a class="ulink" href="http://docs.python.org/distutils/" target="_top">Distutils</a>.
    256. 

  256.     Some platforms have specific packaging, for example RPM, and, when
    257. 

  257.     made available, the installation of these will be covered in this
    258. 

  258.     manual.
    259. 

  259.   </p><p>
    260. 

  260.     Python terminology regarding distributions:
    261. 

  261.   </p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
    262. 

  262.         <span class="bold"><strong>Source Distribution</strong></span> is a
    263. 

  263.         distribution that contains only source files and is generally
    264. 

  264.         platform independent.
    265. 

  265.       </p></li><li class="listitem"><p>
    266. 

  266.         <span class="bold"><strong>Built Distribution</strong></span> can be
    267. 

  267.         regarded as a binary package. It contains both sources and
    268. 

  268.         platform-independent bytecode.
    269. 

  269.       </p></li></ul></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="connector-python-installation-src-unix"></a>3.1. Installing Connector/Python Source Distribution on Linux, UNIX, or OS X</h2></div></div></div><p>
    270. 

  270.       On UNIX-like systems such as Linux distributions, Solaris, Apple
    271. 

  271.       Mac OS X, and FreeBSD, you can download Connector/Python as a
    272. 

  272.       <code class="literal">tar</code> archive from
    273. 

  273.       <a class="ulink" href="http://dev.mysql.com/downloads/connector/python/" target="_top">http://dev.mysql.com/downloads/connector/python/</a>.
    274. 

  274.     </p><p>
    275. 

  275.       To install Connector/Python from the <code class="literal">.tar.gz</code>
    276. 

  276.       file, download the latest version and follow these steps:
    277. 

  277.     </p><pre class="programlisting">shell&gt; <strong class="userinput"><code>gunzip mysql-connector-python-1.0.6b1.tar.gz</code></strong>
    278. 

  278. shell&gt; <strong class="userinput"><code>tar xf mysql-connector-python-1.0.6b1.tar</code></strong>
    279. 

  279. shell&gt; <strong class="userinput"><code>cd mysql-connector-python-1.0.6b1</code></strong>
    280. 

  280. shell&gt; <strong class="userinput"><code>sudo python setup.py install</code></strong>
    281. 

  281. </pre><p>
    282. 

  282.       On UNIX-like systems, Connector/Python gets installed in the
    283. 

  283.       default location
    284. 

  284.       <code class="filename">/<em class="replaceable"><code>prefix</code></em>/lib/python<em class="replaceable"><code>X.Y</code></em>/site-packages/</code>,
    285. 

  285.       where <em class="replaceable"><code>prefix</code></em> is the location where
    286. 

  286.       Python was installed and <em class="replaceable"><code>X.Y</code></em> is the
    287. 

  287.       version of Python. See
    288. 

  288.       <a class="ulink" href="http://docs.python.org/install/index.html#how-installation-works" target="_top">How
    289. 

  289.       installation works</a> in the Python manual.
    290. 

  290.     </p><p>
    291. 

  291.       If you are not sure where Connector/Python was installed, do the
    292. 

  292.       following to retrieve the location:
    293. 

  293.     </p><pre class="programlisting">shell&gt; python
    294. 

  294. &gt;&gt;&gt; from distutils.sysconfig import get_python_lib
    295. 

  295. &gt;&gt;&gt; print get_python_lib()            # Python v2.x
    296. 

  296. /Library/Python/2.7/site-packages
    297. 

  297. &gt;&gt;&gt; print(get_python_lib())           # Python v3.x
    298. 

  298. /Library/Frameworks/Python.framework/Versions/3.1/lib/python3.1/site-packages</pre><div xmlns="http://www.w3.org/1999/xhtml" class="note" style="margin-left: 0.5in; margin-right: 0.5in;"><div class="admon-title">Note</div><p xmlns="">
    299. 

  299.         The above example shows the default installation location on Mac
    300. 

  300.         OS X 10.7.
    301. 

  301.       </p></div></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="connector-python-installation-src-windows"></a>3.2. Installing Connector/Python Source Distribution on Microsoft Windows</h2></div></div></div><p>
    302. 

  302.       On Microsoft Windows systems, you can download Connector/Python as
    303. 

  303.       a <code class="literal">zip</code> archive from
    304. 

  304.       <a class="ulink" href="http://dev.mysql.com/downloads/connector/python/" target="_top">http://dev.mysql.com/downloads/connector/python/</a>.
    305. 

  305.     </p><p>
    306. 

  306.       Make sure that the Python executable is available in the Windows
    307. 

  307.       <code class="literal">%PATH%</code> setting. For more information about
    308. 

  308.       installation and configuration of Python on Windows, see the
    309. 

  309.       section
    310. 

  310.       <a class="ulink" href="http://docs.python.org/using/windows.html" target="_top">Using
    311. 

  311.       Python on Windows</a> in the Python documentation.
    312. 

  312.     </p><p>
    313. 

  313.       To install Connector/Python from the <code class="literal">.zip</code> file,
    314. 

  314.       download the latest version and follow these steps:
    315. 

  315.     </p><div class="orderedlist"><ol class="orderedlist" type="1"><li class="listitem"><p>
    316. 

  316.           Unpack the downloaded <code class="literal">zip</code> archive into a
    317. 

  317.           directory of your choice. For example, into the folder
    318. 

  318.           <code class="filename">C:\mysql-connector\</code>. Use the appropriate
    319. 

  319.           unzip command for your system, for example,
    320. 

  320.           <code class="literal">unzip</code>, <code class="literal">pkunzip</code>, and so
    321. 

  321.           on.
    322. 

  322.         </p></li><li class="listitem"><p>
    323. 

  323.           Start a console window (or a DOS window) and change to the
    324. 

  324.           folder where you unpacked the Connector/Python
    325. 

  325.           <code class="literal">zip</code> archive.
    326. 

  326.         </p><pre class="programlisting">shell&gt; <strong class="userinput"><code>cd C:\mysql-connector\</code></strong>
    327. 

  327. </pre></li><li class="listitem"><p>
    328. 

  328.           Once inside the Connector/Python folder, do the following:
    329. 

  329.         </p><pre class="programlisting">shell&gt; <strong class="userinput"><code>python setup.py install</code></strong>
    330. 

  330. </pre></li></ol></div><p>
    331. 

  331.       On Windows, Connector/Python gets installed in the default
    332. 

  332.       location
    333. 

  333.       <code class="filename">C:\Python<em class="replaceable"><code>X.Y</code></em>\Lib\site-packages\</code>
    334. 

  334.       where <em class="replaceable"><code>X.Y</code></em> is the Python version you
    335. 

  335.       used to install the connector.
    336. 

  336.     </p><p>
    337. 

  337.       If you are not sure where Connector/Python ended up, do the
    338. 

  338.       following to retrieve the location where packages get installed:
    339. 

  339.     </p><pre class="programlisting">shell&gt; python
    340. 

  340. &gt;&gt;&gt; from distutils.sysconfig import get_python_lib
    341. 

  341. &gt;&gt;&gt; print get_python_lib()            # Python v2.x
    342. 

  342. &gt;&gt;&gt; print(get_python_lib())           # Python v3.x</pre></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="connector-python-verification"></a>3.3. Verifying Your Connector/Python Installation</h2></div></div></div><p>
    343. 

  343.       To test that your Connector/Python installation is working and is
    344. 

  344.       able to connect to a MySQL database server, you can run a very
    345. 

  345.       simple program where you substitute the login credentials and host
    346. 

  346.       information of the MySQL server. See
    347. 

  347.       <a class="xref" href="#myconnpy_example_connecting" title="4.1. Connecting to MySQL Using Connector/Python">Section 4.1, “Connecting to MySQL Using Connector/Python”</a> for an example.
    348. 

  348.     </p></div></div><div class="chapter"><div class="titlepage"><div><div><h1 class="title"><a name="connector-python-examples"></a>Chapter 4. Connector/Python Coding Examples</h1></div></div></div><div class="toc"><p><b>Table of Contents</b></p><dl><dt><span class="section"><a href="#myconnpy_example_connecting">4.1. Connecting to MySQL Using Connector/Python</a></span></dt><dt><span class="section"><a href="#myconnpy_example_ddl">4.2. Creating Tables Using Connector/Python</a></span></dt><dt><span class="section"><a href="#myconnpy_example_cursor_transaction">4.3. Inserting Data Using Connector/Python</a></span></dt><dt><span class="section"><a href="#myconnpy_example_cursor_select">4.4. Querying Data Using Connector/Python</a></span></dt></dl></div><p>
    349. 

  349.     These coding examples illustrate how to develop Python applications
    350. 

  350.     and scripts which connect to a MySQL Server using MySQL
    351. 

  351.     Connector/Python.
    352. 

  352.   </p><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="myconnpy_example_connecting"></a>4.1. Connecting to MySQL Using Connector/Python</h2></div></div></div><p>
    353. 

  353.       The <code class="literal">connect()</code> constructor is used for creating
    354. 

  354.       a connection to the MySQL server and returns a
    355. 

  355.       <code class="literal">MySQLConnection</code> object.
    356. 

  356.     </p><p>
    357. 

  357.       The following example shows how to connect to the MySQL server:
    358. 

  358.     </p><pre class="programlisting">import mysql.connector
    359. 

  359. cnx = mysql.connector.connect(user='scott', password='tiger',
    360. 

  360.                               host='127.0.0.1',
    361. 

  361.                               database='employees')
    362. 

  362. cnx.close()</pre><p>
    363. 

  363.       See <a class="xref" href="#connector-python-connectargs" title="Chapter 6. Connector/Python Connection Arguments">Chapter 6, <i>Connector/Python Connection Arguments</i></a> for all
    364. 

  364.       possible connection arguments.
    365. 

  365.     </p><p>
    366. 

  366.       It is also possible to create connection objects using the
    367. 

  367.       <a class="link" href="#connector-python-apiref-MySQLConnection" title="7.2. Class connection.MySQLConnection">connection.MySQLConnection()</a>
    368. 

  368.       class. Both methods, using the <code class="literal">connect()</code>
    369. 

  369.       constructor, or the class directly, are valid and functionally
    370. 

  370.       equal, but using <code class="literal">connector()</code> is preferred and
    371. 

  371.       will be used in most examples in this manual.
    372. 

  372.     </p><p>
    373. 

  373.       To handle connection errors, use the <code class="literal">try</code>
    374. 

  374.       statement and catch all errors using the
    375. 

  375.       <a class="link" href="#connector-python-apiref-errors-error" title="7.1.2. Exception errors.Error">errors.Error</a>
    376. 

  376.       exception:
    377. 

  377.     </p><pre class="programlisting">import mysql.connector
    378. 

  378. from mysql.connector import errorcode
    379. 

  379. try:
    380. 

  380.   cnx = mysql.connector.connect(user='scott',
    381. 

  381.                                 database='testt')
    382. 

  382. except mysql.connector.Error as err:
    383. 

  383.   if err.errno == errorcode.ER_ACCESS_DENIED_ERROR:
    384. 

  384.     print("Something is wrong your username or password")
    385. 

  385.   elif err.errno == errorcode.ER_BAD_DB_ERROR:
    386. 

  386.     print("Database does not exists")
    387. 

  387.   else:
    388. 

  388.     print(err)
    389. 

  389. else:
    390. 

  390.   cnx.close()</pre><p>
    391. 

  391.       If you have lots of connection arguments, it's best to keep them
    392. 

  392.       in a dictionary and use the <code class="literal">**</code>-operator. Here
    393. 

  393.       is an example:
    394. 

  394.     </p><pre class="programlisting">import mysql.connector
    395. 

  395. config = {
    396. 

  396.   'user': 'scott',
    397. 

  397.   'password': 'tiger',
    398. 

  398.   'host': '127.0.0.1',
    399. 

  399.   'database': 'employees',
    400. 

  400.   'raise_on_warnings': True,
    401. 

  401. }
    402. 

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

  403. cnx.close()</pre></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="myconnpy_example_ddl"></a>4.2. Creating Tables Using Connector/Python</h2></div></div></div><p>
    404. 

  404.       All <a class="ulink" href="http://dev.mysql.com/doc/refman/5.5/en/glossary.html#glos_ddl" target="_top">DDL</a> (Data Definition Language)
    405. 

  405.       statements are executed using a handle structure known as a
    406. 

  406.       cursor. The following examples show how to create the tables of
    407. 

  407.       the <code class="literal">employees</code> database. You will need them for
    408. 

  408.       the other examples.
    409. 

  409.     </p><p>
    410. 

  410.       In a MySQL server, tables are very long-lived objects, and are
    411. 

  411.       often accessed by multiple applications written in different
    412. 

  412.       languages. You might typically work with tables that are already
    413. 

  413.       set up, rather than creating them within your own application.
    414. 

  414.       Avoid setting up and dropping tables over and over again, as that
    415. 

  415.       is an expensive operation. The exception is
    416. 

  416.       <a class="ulink" href="http://dev.mysql.com/doc/refman/5.5/en/glossary.html#glos_temporary_table" target="_top">temporary tables</a>,
    417. 

  417.       which can be created and dropped quickly within an application.
    418. 

  418.     </p><pre class="programlisting">from __future__ import print_function
    419. 

  419. import mysql.connector
    420. 

  420. from mysql.connector import errorcode
    421. 

  421. DB_NAME = 'employees'
    422. 

  422. TABLES = {}
    423. 

  423. TABLES['employees'] = (
    424. 

  424.     "CREATE TABLE `employees` ("
    425. 

  425.     "  `emp_no` int(11) NOT NULL AUTO_INCREMENT,"
    426. 

  426.     "  `birth_date` date NOT NULL,"
    427. 

  427.     "  `first_name` varchar(14) NOT NULL,"
    428. 

  428.     "  `last_name` varchar(16) NOT NULL,"
    429. 

  429.     "  `gender` enum('M','F') NOT NULL,"
    430. 

  430.     "  `hire_date` date NOT NULL,"
    431. 

  431.     "  PRIMARY KEY (`emp_no`)"
    432. 

  432.     ") ENGINE=InnoDB")
    433. 

  433. TABLES['departments'] = (
    434. 

  434.     "CREATE TABLE `departments` ("
    435. 

  435.     "  `dept_no` char(4) NOT NULL,"
    436. 

  436.     "  `dept_name` varchar(40) NOT NULL,"
    437. 

  437.     "  PRIMARY KEY (`dept_no`), UNIQUE KEY `dept_name` (`dept_name`)"
    438. 

  438.     ") ENGINE=InnoDB")
    439. 

  439. TABLES['salaries'] = (
    440. 

  440.     "CREATE TABLE `salaries` ("
    441. 

  441.     "  `emp_no` int(11) NOT NULL,"
    442. 

  442.     "  `salary` int(11) NOT NULL,"
    443. 

  443.     "  `from_date` date NOT NULL,"
    444. 

  444.     "  `to_date` date NOT NULL,"
    445. 

  445.     "  PRIMARY KEY (`emp_no`,`from_date`), KEY `emp_no` (`emp_no`),"
    446. 

  446.     "  CONSTRAINT `salaries_ibfk_1` FOREIGN KEY (`emp_no`) "
    447. 

  447.     "     REFERENCES `employees` (`emp_no`) ON DELETE CASCADE"
    448. 

  448.     ") ENGINE=InnoDB")
    449. 

  449. TABLES['dept_emp'] = (
    450. 

  450.     "CREATE TABLE `dept_emp` ("
    451. 

  451.     "  `emp_no` int(11) NOT NULL,"
    452. 

  452.     "  `dept_no` char(4) NOT NULL,"
    453. 

  453.     "  `from_date` date NOT NULL,"
    454. 

  454.     "  `to_date` date NOT NULL,"
    455. 

  455.     "  PRIMARY KEY (`emp_no`,`dept_no`), KEY `emp_no` (`emp_no`),"
    456. 

  456.     "  KEY `dept_no` (`dept_no`),"
    457. 

  457.     "  CONSTRAINT `dept_emp_ibfk_1` FOREIGN KEY (`emp_no`) "
    458. 

  458.     "     REFERENCES `employees` (`emp_no`) ON DELETE CASCADE,"
    459. 

  459.     "  CONSTRAINT `dept_emp_ibfk_2` FOREIGN KEY (`dept_no`) "
    460. 

  460.     "     REFERENCES `departments` (`dept_no`) ON DELETE CASCADE"
    461. 

  461.     ") ENGINE=InnoDB")
    462. 

  462. TABLES['dept_manager'] = (
    463. 

  463.     "  CREATE TABLE `dept_manager` ("
    464. 

  464.     "  `dept_no` char(4) NOT NULL,"
    465. 

  465.     "  `emp_no` int(11) NOT NULL,"
    466. 

  466.     "  `from_date` date NOT NULL,"
    467. 

  467.     "  `to_date` date NOT NULL,"
    468. 

  468.     "  PRIMARY KEY (`emp_no`,`dept_no`),"
    469. 

  469.     "  KEY `emp_no` (`emp_no`),"
    470. 

  470.     "  KEY `dept_no` (`dept_no`),"
    471. 

  471.     "  CONSTRAINT `dept_manager_ibfk_1` FOREIGN KEY (`emp_no`) "
    472. 

  472.     "     REFERENCES `employees` (`emp_no`) ON DELETE CASCADE,"
    473. 

  473.     "  CONSTRAINT `dept_manager_ibfk_2` FOREIGN KEY (`dept_no`) "
    474. 

  474.     "     REFERENCES `departments` (`dept_no`) ON DELETE CASCADE"
    475. 

  475.     ") ENGINE=InnoDB")
    476. 

  476. TABLES['titles'] = (
    477. 

  477.     "CREATE TABLE `titles` ("
    478. 

  478.     "  `emp_no` int(11) NOT NULL,"
    479. 

  479.     "  `title` varchar(50) NOT NULL,"
    480. 

  480.     "  `from_date` date NOT NULL,"
    481. 

  481.     "  `to_date` date DEFAULT NULL,"
    482. 

  482.     "  PRIMARY KEY (`emp_no`,`title`,`from_date`), KEY `emp_no` (`emp_no`),"
    483. 

  483.     "  CONSTRAINT `titles_ibfk_1` FOREIGN KEY (`emp_no`)"
    484. 

  484.     "     REFERENCES `employees` (`emp_no`) ON DELETE CASCADE"
    485. 

  485.     ") ENGINE=InnoDB")</pre><p>
    486. 

  486.       The above code shows how we are storing the
    487. 

  487.       <code class="literal">CREATE</code> statements in a Python dictionary called
    488. 

  488.       <code class="literal">TABLES</code>. We also define the database in a global
    489. 

  489.       variable called <code class="literal">DB_NAME</code>, which allows you to
    490. 

  490.       easily use a different schema.
    491. 

  491.     </p><pre class="programlisting">cnx = mysql.connector.connect(user='scott')
    492. 

  492. cursor = cnx.cursor()</pre><p>
    493. 

  493.       A single MySQL server can contain multiple
    494. 

  494.       <a class="ulink" href="http://dev.mysql.com/doc/refman/5.5/en/glossary.html#glos_database" target="_top">databases</a>. Typically, you
    495. 

  495.       specify the database to switch to when connecting to the MySQL
    496. 

  496.       server. This example does not connect to the database upon
    497. 

  497.       connection, so that it can make sure the database exists, and
    498. 

  498.       create it if not.
    499. 

  499.     </p><pre class="programlisting">def create_database(cursor):
    500. 

  500.     try:
    501. 

  501.         cursor.execute(
    502. 

  502.             "CREATE DATABASE {} DEFAULT CHARACTER SET 'utf8'".format(DB_NAME))
    503. 

  503.     except mysql.connector.Error as err:
    504. 

  504.         print("Failed creating database: {}".format(err))
    505. 

  505.         exit(1)
    506. 

  506. try:
    507. 

  507.     cnx.database = DB_NAME    
    508. 

  508. except mysql.connector.Error as err:
    509. 

  509.     if err.errno == errorcode.ER_BAD_DB_ERROR:
    510. 

  510.         create_database(cursor)
    511. 

  511.         cnx.database = DB_NAME
    512. 

  512.     else:
    513. 

  513.         print(err)
    514. 

  514.         exit(1)</pre><p>
    515. 

  515.       We first try to change to a particular database using the
    516. 

  516.       <code class="literal">database</code> property of the connection object
    517. 

  517.       <code class="literal">cnx</code>. If there is an error, we examine the error
    518. 

  518.       number to check if the database does not exist. If so, we call the
    519. 

  519.       <code class="literal">create_database</code> function to create it for us.
    520. 

  520.     </p><p>
    521. 

  521.       On any other error, the application exits and displays the error
    522. 

  522.       message.
    523. 

  523.     </p><pre class="programlisting">for name, ddl in TABLES.iteritems():
    524. 

  524.     try:
    525. 

  525.         print("Creating table {}: ".format(name), end='')
    526. 

  526.         cursor.execute(ddl)
    527. 

  527.     except mysql.connector.Error as err:
    528. 

  528.         if err.errno == errorcode.ER_TABLE_EXISTS_ERROR:
    529. 

  529.             print("already exists.")
    530. 

  530.         else:
    531. 

  531.             print(err.errmsg)
    532. 

  532.     else:
    533. 

  533.         print("OK")
    534. 

  534. cursor.close()
    535. 

  535. cnx.close()</pre><p>
    536. 

  536.       After we succesfully created or changed to the target database, we
    537. 

  537.       create the tables by iterating over the items of the
    538. 

  538.       <code class="literal">TABLES</code> dictionary.
    539. 

  539.     </p><p>
    540. 

  540.       We handle the error when the table already exists by simply
    541. 

  541.       notifying the user that it was already there. Other errors are
    542. 

  542.       printed, but we simply continue creating tables. (We show how to
    543. 

  543.       handle the <span class="quote">“<span class="quote">table already exists</span>”</span> condition for
    544. 

  544.       illustration purposes. In a real application, we would typically
    545. 

  545.       avoid the error condition entirely by using the <code class="literal">IF NOT
    546. 

  546.       EXISTS</code> clause of the <a class="ulink" href="http://dev.mysql.com/doc/refman/5.5/en/create-table.html" target="_top"><code class="literal">CREATE
    547. 

  547.       TABLE</code></a> statement.)
    548. 

  548.     </p><p>
    549. 

  549.       The output would be something like this:
    550. 

  550.     </p><pre class="programlisting">Creating table employees: already exists.
    551. 

  551. Creating table salaries: already exists.
    552. 

  552. Creating table titles: OK
    553. 

  553. Creating table departments: already exists.
    554. 

  554. Creating table dept_manager: already exists.
    555. 

  555. Creating table dept_emp: already exists.</pre><p>
    556. 

  556.       To populate the employees tables, use the dump files of the
    557. 

  557.       <a class="ulink" href="http://dev.mysql.com/doc/employee/en/index.html" target="_top">Employee
    558. 

  558.       Sample Database</a>. Note that you only need the data dump
    559. 

  559.       files that you will find in an archive named like
    560. 

  560.       <code class="literal">employees_db-dump-files-1.0.5.tar.bz2</code>. After
    561. 

  561.       downloading the dump files, do the following from the command
    562. 

  562.       line, adding connection options to the <span class="command"><strong>mysql</strong></span>
    563. 

  563.       commands if necessary:
    564. 

  564.     </p><pre class="programlisting">shell&gt; tar xzf employees_db-dump-files-1.0.5.tar.bz2
    565. 

  565. shell&gt; cd employees_db
    566. 

  566. shell&gt; mysql employees &lt; load_employees.dump
    567. 

  567. shell&gt; mysql employees &lt; load_titles.dump
    568. 

  568. shell&gt; mysql employees &lt; load_departments.dump
    569. 

  569. shell&gt; mysql employees &lt; load_salaries.dump
    570. 

  570. shell&gt; mysql employees &lt; load_dept_emp.dump
    571. 

  571. shell&gt; mysql employees &lt; load_dept_manager.dump</pre></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="myconnpy_example_cursor_transaction"></a>4.3. Inserting Data Using Connector/Python</h2></div></div></div><p>
    572. 

  572.       Inserting or updating data is also done using the handler
    573. 

  573.       structure known as a cursor. When you use a transactional storage
    574. 

  574.       engine such as <code class="literal">InnoDB</code> (which is the default in
    575. 

  575.       MySQL 5.5 and later), you must
    576. 

  576.       <a class="ulink" href="http://dev.mysql.com/doc/refman/5.5/en/glossary.html#glos_commit" target="_top">commit</a> the data after a
    577. 

  577.       sequence of <a class="ulink" href="http://dev.mysql.com/doc/refman/5.5/en/insert.html" target="_top"><code class="literal">INSERT</code></a>,
    578. 

  578.       <a class="ulink" href="http://dev.mysql.com/doc/refman/5.5/en/delete.html" target="_top"><code class="literal">DELETE</code></a>, and
    579. 

  579.       <a class="ulink" href="http://dev.mysql.com/doc/refman/5.5/en/update.html" target="_top"><code class="literal">UPDATE</code></a> statements.
    580. 

  580.     </p><p>
    581. 

  581.       In this example we show how to insert new data. The second
    582. 

  582.       <a class="ulink" href="http://dev.mysql.com/doc/refman/5.5/en/insert.html" target="_top"><code class="literal">INSERT</code></a> depends on the value of the
    583. 

  583.       newly created <a class="ulink" href="http://dev.mysql.com/doc/refman/5.5/en/glossary.html#glos_primary_key" target="_top">primary key</a>
    584. 

  584.       of the first. We are also demonstrating how to use extended
    585. 

  585.       formats. The task is to add a new employee starting to work
    586. 

  586.       tomorrow with a salary set to 50000.
    587. 

  587.     </p><div xmlns="http://www.w3.org/1999/xhtml" class="note" style="margin-left: 0.5in; margin-right: 0.5in;"><div class="admon-title">Note</div><p xmlns="">
    588. 

  588.         The following example uses tables created in the example
    589. 

  589.         <a class="xref" href="#myconnpy_example_ddl" title="4.2. Creating Tables Using Connector/Python">Section 4.2, “Creating Tables Using Connector/Python”</a>. The
    590. 

  590.         <code class="literal">AUTO_INCREMENT</code> column option for the primary
    591. 

  591.         key of the <code class="literal">employees</code> table is important to
    592. 

  592.         ensure reliable, easily searchable data.
    593. 

  593.       </p></div><pre class="programlisting">from __future__ import print_function
    594. 

  594. from datetime import date, datetime, timedelta
    595. 

  595. import mysql.connector
    596. 

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

  597. cursor = cnx.cursor()
    598. 

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

  599. add_employee = ("INSERT INTO employees "
    600. 

  600.                "(first_name, last_name, hire_date, gender, birth_date) "
    601. 

  601.                "VALUES (%s, %s, %s, %s, %s)")
    602. 

  602. add_salary = ("INSERT INTO salaries "
    603. 

  603.               "(emp_no, salary, from_date, to_date) "
    604. 

  604.               "VALUES (%(emp_no)s, %(salary)s, %(from_date)s, %(to_date)s)")
    605. 

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

  606. # Insert new employee
    607. 

  607. cursor.execute(add_employee, data_employee)
    608. 

  608. emp_no = cursor.lastrowid
    609. 

  609. # Insert salary information
    610. 

  610. data_salary = {
    611. 

  611.   'emp_no': emp_no,
    612. 

  612.   'salary': 50000,
    613. 

  613.   'from_date': tomorrow,
    614. 

  614.   'to_date': date(9999, 1, 1),
    615. 

  615. }
    616. 

  616. cursor.execute(add_salary, data_salary)
    617. 

  617. # Make sure data is committed to the database
    618. 

  618. cnx.commit()
    619. 

  619. cursor.close()
    620. 

  620. cnx.close()</pre><p>
    621. 

  621.       We first open a connection to the MySQL server and store the
    622. 

  622.       <a class="link" href="#connector-python-apiref-MySQLConnection" title="7.2. Class connection.MySQLConnection">connection
    623. 

  623.       object</a> in the variable <code class="literal">cnx</code>. We then
    624. 

  624.       create a new cursor, by default a
    625. 

  625.       <a class="link" href="#connector-python-apiref-MySQLCursor" title="7.3. Class cursor.MySQLCursor">MySQLCursor</a>
    626. 

  626.       object, using the connection's
    627. 

  627.       <a class="link" href="#myconnpy_MySQLConnection_cursor" title="7.2.6. Method MySQLConnection.cursor(buffered=None, raw=None, cursor_class=None)"><code class="literal">cursor()</code></a>
    628. 

  628.       method.
    629. 

  629.     </p><p>
    630. 

  630.       We could calculate tomorrow by calling a database function, but
    631. 

  631.       for clarity we do it in Python using the
    632. 

  632.       <code class="literal">datetime</code> module.
    633. 

  633.     </p><p>
    634. 

  634.       Both <code class="literal">INSERT</code> statements are stored in the
    635. 

  635.       variables called <code class="literal">add_employee</code> and
    636. 

  636.       <code class="literal">add_salary</code>. Note that the second
    637. 

  637.       <code class="literal">INSERT</code> statement uses extended Python format
    638. 

  638.       codes.
    639. 

  639.     </p><p>
    640. 

  640.       The information of the new employee is stored in the tuple
    641. 

  641.       <code class="literal">data_employee</code>. The query to insert the new
    642. 

  642.       employee is executed and we retrieve the newly inserted value for
    643. 

  643.       the column <code class="literal">emp_no</code> using the
    644. 

  644.       <code class="literal">lastrowid</code> property of the cursor object.
    645. 

  645.     </p><p>
    646. 

  646.       Next, we insert the new salary for the new employee. We are using
    647. 

  647.       the <code class="literal">emp_no</code> variable in the directory holding
    648. 

  648.       the data. This directory is passed to the
    649. 

  649.       <code class="literal">execute()</code> method of the cursor object.
    650. 

  650.     </p><p>
    651. 

  651.       Since by default Connector/Python turns
    652. 

  652.       <a class="ulink" href="http://dev.mysql.com/doc/refman/5.5/en/glossary.html#glos_autocommit" target="_top">autocommit</a> off, and MySQL
    653. 

  653.       5.5 and later uses transactional <code class="literal">InnoDB</code> tables
    654. 

  654.       by default, it is necessary to commit your changes using the
    655. 

  655.       connection's <code class="literal">commit()</code> method. You could also
    656. 

  656.       <a class="ulink" href="http://dev.mysql.com/doc/refman/5.5/en/glossary.html#glos_rollback" target="_top">roll back</a> using the
    657. 

  657.       <code class="literal">rollback()</code> method.
    658. 

  658.     </p></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="myconnpy_example_cursor_select"></a>4.4. Querying Data Using Connector/Python</h2></div></div></div><p>
    659. 

  659.       The following example shows how to
    660. 

  660.       <a class="ulink" href="http://dev.mysql.com/doc/refman/5.5/en/glossary.html#glos_query" target="_top">query</a> data using a cursor
    661. 

  661.       created using the connection's
    662. 

  662.       <a class="link" href="#myconnpy_MySQLConnection_cursor" title="7.2.6. Method MySQLConnection.cursor(buffered=None, raw=None, cursor_class=None)"><code class="literal">cursor()</code></a>
    663. 

  663.       method. The data returned is formatted and printed on the console.
    664. 

  664.     </p><p>
    665. 

  665.       The task is to select all employees hired in the year 1999 and
    666. 

  666.       print their names with their hire date to the console.
    667. 

  667.     </p><pre class="programlisting">import datetime
    668. 

  668. import mysql.connector
    669. 

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

  670. cursor = cnx.cursor()
    671. 

  671. query = ("SELECT first_name, last_name, hire_date FROM employees "
    672. 

  672.          "WHERE hire_date BETWEEN %s AND %s")
    673. 

  673. hire_start = datetime.date(1999, 1, 1)
    674. 

  674. hire_end = datetime.date(1999, 12, 31)
    675. 

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

  676. for (first_name, last_name, hire_date) in cursor:
    677. 

  677.   print("{}, {} was hired on {:%d %b %Y}".format(
    678. 

  678.     last_name, first_name, hire_date))
    679. 

  679. cursor.close()
    680. 

  680. cnx.close()</pre><p>
    681. 

  681.       We first open a connection to the MySQL server and store the
    682. 

  682.       <a class="link" href="#connector-python-apiref-MySQLConnection" title="7.2. Class connection.MySQLConnection">connection
    683. 

  683.       object</a> in the variable <code class="literal">cnx</code>. We then
    684. 

  684.       create a new cursor, by default a
    685. 

  685.       <a class="link" href="#connector-python-apiref-MySQLCursor" title="7.3. Class cursor.MySQLCursor">MySQLCursor</a>
    686. 

  686.       object, using the connection's
    687. 

  687.       <a class="link" href="#myconnpy_MySQLConnection_cursor" title="7.2.6. Method MySQLConnection.cursor(buffered=None, raw=None, cursor_class=None)"><code class="literal">cursor()</code></a>
    688. 

  688.       method.
    689. 

  689.     </p><p>
    690. 

  690.       In the preceding example, we store the <code class="literal">SELECT</code>
    691. 

  691.       statement in the variable <code class="literal">query</code>. Note that we
    692. 

  692.       are using unquoted <code class="literal">%s</code>-markers where dates
    693. 

  693.       should have been. Connector/Python converts
    694. 

  694.       <code class="literal">hire_start</code> and <code class="literal">hire_end</code> from
    695. 

  695.       Python types to a data type that MySQL understands and adds the
    696. 

  696.       required quotes. In this case, it replaces the first
    697. 

  697.       <code class="literal">%s</code> with <code class="literal">'1999-01-01'</code>, and
    698. 

  698.       the second with <code class="literal">'1999-12-31'</code>.
    699. 

  699.     </p><p>
    700. 

  700.       We then execute the operation stored in the
    701. 

  701.       <code class="literal">query</code> variable using the
    702. 

  702.       <a class="link" href="#myconnpy_MySQLCursor_execute" title="7.3.4. Method MySQLCursor.execute(operation, params=None, multi=False)"><code class="literal">execute()</code></a>
    703. 

  703.       method. The data used to replace the <code class="literal">%s</code>-markers
    704. 

  704.       in the query is passed as a tuple: <code class="literal">(hire_start,
    705. 

  705.       hire_end)</code>.
    706. 

  706.     </p><p>
    707. 

  707.       After executing the query, the MySQL server is ready to send the
    708. 

  708.       data. The result set could be zero rows, one row, or 100 million
    709. 

  709.       rows. Depending on the expected volume, you can use different
    710. 

  710.       techniques to process this result set. In this example, we use the
    711. 

  711.       <code class="literal">cursor</code> object as an iterator. The first column
    712. 

  712.       in the row will be stored in the variable
    713. 

  713.       <code class="literal">first_name</code>, the second in
    714. 

  714.       <code class="literal">last_name</code>, and the third in
    715. 

  715.       <code class="literal">hire_date</code>.
    716. 

  716.     </p><p>
    717. 

  717.       We print the result, formatting the output using Python's built-in
    718. 

  718.       <code class="literal">format()</code> function. Note that
    719. 

  719.       <code class="literal">hire_date</code> was converted automatically by
    720. 

  720.       Connector/Python to a Python <code class="literal">datetime.date</code>
    721. 

  721.       object. This means that we can easily format the date in a more
    722. 

  722.       human-readable form.
    723. 

  723.     </p><p>
    724. 

  724.       The output should be something like this:
    725. 

  725.     </p><pre class="programlisting">..
    726. 

  726. Wilharm, LiMin was hired on 16 Dec 1999
    727. 

  727. Wielonsky, Lalit was hired on 16 Dec 1999
    728. 

  728. Kamble, Dannz was hired on 18 Dec 1999
    729. 

  729. DuBourdieux, Zhongwei was hired on 19 Dec 1999
    730. 

  730. Fujisawa, Rosita was hired on 20 Dec 1999
    731. 

  731. ..</pre></div></div><div class="chapter"><div class="titlepage"><div><div><h1 class="title"><a name="connector-python-tutorials"></a>Chapter 5. Connector/Python Tutorials</h1></div></div></div><div class="toc"><p><b>Table of Contents</b></p><dl><dt><span class="section"><a href="#myconnpy_tutorial_CursorBuffered_GiveRaise">5.1. Tutorial: Raise employee's salary using a buffering cursor</a></span></dt></dl></div><p>
    732. 

  732.     These tutorials illustrate how to develop Python applications and
    733. 

  733.     scripts that connect to a MySQL database server using MySQL
    734. 

  734.     Connector/Python.
    735. 

  735.   </p><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="myconnpy_tutorial_CursorBuffered_GiveRaise"></a>5.1. Tutorial: Raise employee's salary using a buffering cursor</h2></div></div></div><p>
    736. 

  736.       The following example script will give a long-overdue raise
    737. 

  737.       effective tomorrow to all employees who joined in the year 2000
    738. 

  738.       and are still with the company.
    739. 

  739.     </p><p>
    740. 

  740.       We are using buffered cursors to iterate through the selected
    741. 

  741.       employees. This way we do not have to fetch the rows in a new
    742. 

  742.       variables, but can instead use the cursor as an iterator.
    743. 

  743.     </p><p>
    744. 

  744.       Note that the script is an example; there are other ways of doing
    745. 

  745.       this simple task.
    746. 

  746.     </p><pre class="programlisting">from __future__ import print_function
    747. 

  747. from decimal import Decimal
    748. 

  748. from datetime import datetime, date, timedelta
    749. 

  749. import mysql.connector
    750. 

  750. # Connect with the MySQL Server
    751. 

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

  752. # Get two buffered cursors
    753. 

  753. curA = cnx.cursor(buffered=True)
    754. 

  754. curB = cnx.cursor(buffered=True)
    755. 

  755. # Query to get employees who joined in a period defined by two dates
    756. 

  756. query = (
    757. 

  757.   "SELECT s.emp_no, salary, from_date, to_date FROM employees AS e "
    758. 

  758.   "LEFT JOIN salaries AS s USING (emp_no) "
    759. 

  759.   "WHERE to_date = DATE('9999-01-01')"
    760. 

  760.   "AND e.hire_date BETWEEN DATE(%s) AND DATE(%s)")
    761. 

  761. # UPDATE and INSERT statements for the old and new salary
    762. 

  762. update_old_salary = (
    763. 

  763.   "UPDATE salaries SET to_date = %s "
    764. 

  764.   "WHERE emp_no = %s AND from_date = %s")
    765. 

  765. insert_new_salary = (
    766. 

  766.   "INSERT INTO salaries (emp_no, from_date, to_date, salary) "
    767. 

  767.   "VALUES (%s, %s, %s, %s)")
    768. 

  768. # Select the employes getting a raise
    769. 

  769. curA.execute(query, (date(2000, 1, 1), date(2001, 1, 1)))
    770. 

  770. # Iterate through the result of curA
    771. 

  771. for (emp_no, salary, from_date, to_date) in curA:
    772. 

  772.   # Update the old and insert the new salary
    773. 

  773.   new_salary = int(round(salary * Decimal('1.15')))
    774. 

  774.   curB.execute(update_old_salary, (tomorrow, emp_no, from_date))
    775. 

  775.   curB.execute(insert_new_salary,
    776. 

  776.                (emp_no, tomorrow, date(9999, 1, 1,), new_salary))
    777. 

  777.   # Commit the changes
    778. 

  778.   cnx.commit()
    779. 

  779. cnx.close()</pre></div></div><div class="chapter"><div class="titlepage"><div><div><h1 class="title"><a name="connector-python-connectargs"></a>Chapter 6. Connector/Python Connection Arguments</h1></div></div></div><p>
    780. 

  780.     The following lists the arguments which can be used to initiate a
    781. 

  781.     connection with the MySQL server using either:
    782. 

  782.   </p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
    783. 

  783.         Function <code class="literal">mysql.connector.connect()</code>
    784. 

  784.       </p></li><li class="listitem"><p>
    785. 

  785.         Class <code class="literal">mysql.connector.MySQLConnection()</code>
    786. 

  786.       </p></li></ul></div><div class="table"><a name="id499609"></a><p class="title"><b>Table 6.1. Connection Arguments for Connector/Python</b></p><div class="table-contents"><table summary="Connection Arguments for Connector/Python" border="1"><colgroup><col><col><col></colgroup><thead><tr><th scope="col">Argument Name</th><th scope="col">Default</th><th scope="col">Description</th></tr></thead><tbody><tr><td scope="row"><code class="literal">user</code> (<code class="literal">username</code>*)</td><td> </td><td>The username used to authenticate with the MySQL Server.</td></tr><tr><td scope="row"><code class="literal">password</code> (<code class="literal">passwd</code>*)</td><td> </td><td>The password to authenticate the user with the MySQL Server.</td></tr><tr><td scope="row"><code class="literal">database</code> (<code class="literal">db</code>*)</td><td> </td><td>Database name to use when connecting with the MySQL Server.</td></tr><tr><td scope="row"><code class="literal">host</code></td><td>127.0.0.1</td><td>Hostname or IP address of the MySQL Server.</td></tr><tr><td scope="row"><code class="literal">port</code></td><td>3306</td><td>TCP/IP port of the MySQL Server. Must be an integer.</td></tr><tr><td scope="row"><code class="literal">unix_socket</code></td><td> </td><td>The location of the Unix socket file.</td></tr><tr><td scope="row"><code class="literal">use_unicode</code></td><td>True</td><td>Whether to use Unicode or not.</td></tr><tr><td scope="row"><code class="literal">charset</code></td><td>utf8</td><td>Which MySQL character set to use.</td></tr><tr><td scope="row"><code class="literal">collation</code></td><td>utf8_general_ci</td><td>Which MySQL collation to use.</td></tr><tr><td scope="row"><code class="literal">autocommit</code></td><td>False</td><td>Whether to <a class="ulink" href="http://dev.mysql.com/doc/refman/5.5/en/glossary.html#glos_autocommit" target="_top">autocommit</a>
    787. 

  787.             transactions.</td></tr><tr><td scope="row"><code class="literal">time_zone</code></td><td> </td><td>Set the <code class="literal">time_zone</code> session variable at connection.</td></tr><tr><td scope="row"><code class="literal">sql_mode</code></td><td> </td><td>Set the <code class="literal">sql_mode</code> session variable at connection.</td></tr><tr><td scope="row"><code class="literal">get_warnings</code></td><td>False</td><td>Whether to fetch warnings.</td></tr><tr><td scope="row"><code class="literal">raise_on_warnings</code></td><td>False</td><td>Whether to raise an exception on warnings.</td></tr><tr><td scope="row"><code class="literal">connection_timeout</code>
    788. 

  788.             (<code class="literal">connect_timeout</code>*)</td><td> </td><td>Timeout for the TCP and Unix socket connections.</td></tr><tr><td scope="row"><code class="literal">client_flags</code></td><td> </td><td>MySQL client flags.</td></tr><tr><td scope="row"><code class="literal">buffered</code></td><td>False</td><td>Whether cursor object fetches the result immediately after executing
    789. 

  789.             query.</td></tr><tr><td scope="row"><code class="literal">raw</code></td><td>False</td><td>Whether MySQL results are returned as-is, rather than converted to
    790. 

  790.             Python types.</td></tr><tr><td scope="row"><code class="literal">ssl_ca</code></td><td> </td><td>File containing the SSL certificate authority.</td></tr><tr><td scope="row"><code class="literal">ssl_cert</code></td><td> </td><td>File containing the SSL certificate file.</td></tr><tr><td scope="row"><code class="literal">ssl_key</code></td><td> </td><td>File containing the SSL key.</td></tr><tr><td scope="row"><code class="literal">dsn</code></td><td> </td><td>Not supported (raises <code class="literal">NotSupportedError</code> when used).</td></tr></tbody></table></div></div><br class="table-break"><p>
    791. 

  791.     * Synonymous argument name, available only for compatibility with
    792. 

  792.     other Python MySQL drivers. Oracle recommends not to use these
    793. 

  793.     alternative names.
    794. 

  794.   </p><p>
    795. 

  795.     Authentication with MySQL will use <code class="literal">username</code> and
    796. 

  796.     <code class="literal">password</code>. Note that MySQL Connector/Python does
    797. 

  797.     not support the old, insecure password protocols of MySQL versions
    798. 

  798.     prior to 4.1.
    799. 

  799.   </p><p>
    800. 

  800.     When the <code class="literal">database</code> parameter is given, the current
    801. 

  801.     database is set to the given value. To later change the database,
    802. 

  802.     execute the MySQL <code class="literal">USE</code> command or set the
    803. 

  803.     <code class="literal">database</code> property of the
    804. 

  804.     <code class="literal">MySQLConnection</code> instance.
    805. 

  805.   </p><p>
    806. 

  806.     By default, Connector/Python tries to connect to a MySQL server
    807. 

  807.     running on <code class="literal">localhost</code> using TCP/IP. The
    808. 

  808.     <code class="literal">host</code> argument defaults to IP address 127.0.0.1
    809. 

  809.     and <code class="literal">port</code> to 3306. Unix sockets are supported by
    810. 

  810.     setting <code class="literal">unix_socket</code>. Named pipes on the Windows
    811. 

  811.     platform are not supported.
    812. 

  812.   </p><p>
    813. 

  813.     Strings coming from MySQL are by default returned as Python Unicode
    814. 

  814.     literals. To change this behavior, set
    815. 

  815.     <code class="literal">use_unicode</code> to <code class="literal">False</code>. You can
    816. 

  816.     change the character setting for the client connection through the
    817. 

  817.     <code class="literal">charset</code> argument. To change the character set
    818. 

  818.     after connecting to MySQL, set the <code class="literal">charset</code>
    819. 

  819.     property of the <code class="literal">MySQLConnection</code> instance. This
    820. 

  820.     technique is preferred over using the MySQL <code class="literal">SET
    821. 

  821.     NAMES</code> statement directly. Similar to the
    822. 

  822.     <code class="literal">charset</code> property, you can set the
    823. 

  823.     <code class="literal">collation</code> for the current MySQL session.
    824. 

  824.   </p><p>
    825. 

  825.     Transactions are not automatically committed; call the
    826. 

  826.     <code class="literal">commit()</code> method of the
    827. 

  827.     <code class="literal">MySQLConnection</code> instance within your application
    828. 

  828.     after doing a set of related insert, update, and delete operations.
    829. 

  829.     For data consistency and high throughput for write operations, it is
    830. 

  830.     best to leave the <code class="literal">autocommit</code> configuration option
    831. 

  831.     turned off when using <code class="literal">InnoDB</code> or other
    832. 

  832.     transactional tables.
    833. 

  833.   </p><p>
    834. 

  834.     The time zone can be set per connection using the
    835. 

  835.     <code class="literal">time_zone</code> argument. This is useful if the MySQL
    836. 

  836.     server is set, for example, to UTC and <code class="literal">TIMESTAMP</code>
    837. 

  837.     values should be returned by MySQL converted to the
    838. 

  838.     <code class="literal">PST</code> time zone.
    839. 

  839.   </p><p>
    840. 

  840.     MySQL supports so called SQL Modes. which will change the behavior
    841. 

  841.     of the server globally or per connection. For example, to have
    842. 

  842.     warnings raised as errors, set <code class="literal">sql_mode</code> to
    843. 

  843.     <code class="literal">TRADITIONAL</code>. For more information, see
    844. 

  844.     <a class="ulink" href="http://dev.mysql.com/doc/refman/5.5/en/server-sql-mode.html" target="_top">Server SQL Modes</a>.
    845. 

  845.   </p><p>
    846. 

  846.     Warnings generated by queries are fetched automatically when
    847. 

  847.     <code class="literal">get_warnings</code> is set to <code class="literal">True</code>.
    848. 

  848.     You can also immediately raise an exception by setting
    849. 

  849.     <code class="literal">raise_on_warnings</code> to <code class="literal">True</code>.
    850. 

  850.     Consider using the MySQL
    851. 

  851.     <a class="ulink" href="http://dev.mysql.com/doc/refman/5.5/en/server-sql-mode.html" target="_top">sql_mode</a> setting for turning
    852. 

  852.     warnings into errors.
    853. 

  853.   </p><p>
    854. 

  854.     To set a timeout value for connections, use
    855. 

  855.     <code class="literal">connection_timeout</code>.
    856. 

  856.   </p><p>
    857. 

  857.     MySQL uses <a class="ulink" href="http://dev.mysql.com/doc/refman/5.5/en/mysql-real-connect.html" target="_top">client flags</a> to
    858. 

  858.     enable or disable features. Using the
    859. 

  859.     <code class="literal">client_flags</code> argument, you have control of what
    860. 

  860.     is set. To find out what flags are available, use the following:
    861. 

  861.   </p><pre class="programlisting">from mysql.connector.constants import ClientFlag
    862. 

  862. print '\n'.join(ClientFlag.get_full_info())</pre><p>
    863. 

  863.     If <code class="literal">client_flags</code> is not specified (that is, it is
    864. 

  864.     zero), defaults are used for MySQL v4.1 and later. If you specify an
    865. 

  865.     integer greater than <code class="literal">0</code>, make sure all flags are
    866. 

  866.     set. A better way to set and unset flags is to use a list. For
    867. 

  867.     example, to set <code class="literal">FOUND_ROWS</code>, but disable the
    868. 

  868.     default <code class="literal">LONG_FLAG</code>:
    869. 

  869.   </p><pre class="programlisting">flags = [ClientFlag.FOUND_ROWS, -ClientFlag.LONG_FLAG]
    870. 

  870. mysql.connector.connect(client_flags=flags)</pre><p>
    871. 

  871.     By default, MySQL Connector/Python does not buffer or pre-fetch
    872. 

  872.     results. This means that after a query is executed, your program is
    873. 

  873.     responsible of fetching the data. This avoids using excessive memory
    874. 

  874.     when queries return large result sets. If you know that the result
    875. 

  875.     set is small enough to handle all at once, fetching the results
    876. 

  876.     immediately by setting <code class="literal">buffered</code> to
    877. 

  877.     <code class="literal">True</code>. It is also possible to set this per cursor
    878. 

  878.     (see cursor manual).
    879. 

  879.   </p><p>
    880. 

  880.     MySQL types will be converted automatically to Python types. For
    881. 

  881.     example, a <code class="literal">DATETIME</code> column becomes a
    882. 

  882.     <a class="ulink" href="http://docs.python.org/library/datetime.html#datetime.datetime" target="_top">datetime.datetime</a>
    883. 

  883.     object. When conversion should be done differently, for example to
    884. 

  884.     get better performance, set <code class="literal">raw</code> to
    885. 

  885.     <code class="literal">True</code>.
    886. 

  886.   </p><p>
    887. 

  887.     Using SSL connections is possible when your
    888. 

  888.     <a class="ulink" href="http://docs.python.org/library/ssl.html" target="_top">Python
    889. 

  889.     installation supports SSL</a>, that is, when it is compiled
    890. 

  890.     against the OpenSSL libraries. When you provide the arguments
    891. 

  891.     <code class="literal">ssl_ca</code>, <code class="literal">ssl_key</code> and
    892. 

  892.     <code class="literal">ssl_cert</code>, the connection switches to SSL. You can
    893. 

  893.     use this in combination with the <code class="literal">compressed</code>
    894. 

  894.     argument set to <code class="literal">True</code>.
    895. 

  895.   </p><p>
    896. 

  896.     <code class="literal">passwd</code>, <code class="literal">db</code> and
    897. 

  897.     <code class="literal">connect_timeout</code> are valid for compatibility with
    898. 

  898.     other MySQL interfaces and are respectively the same as
    899. 

  899.     <code class="literal">password</code>, <code class="literal">database</code> and
    900. 

  900.     <code class="literal">connection_timeout</code>. The latter take precedence.
    901. 

  901.     Data source name syntax or <code class="literal">dsn</code> is not used; if
    902. 

  902.     specified, it raises a <code class="literal">NotSupportedError</code>
    903. 

  903.     exception.
    904. 

  904.   </p></div><div class="chapter"><div class="titlepage"><div><div><h1 class="title"><a name="connector-python-reference"></a>Chapter 7. Connector/Python API Reference</h1></div></div></div><div class="toc"><p><b>Table of Contents</b></p><dl><dt><span class="section"><a href="#connector-python-apiref-errors">7.1. Errors and Exceptions</a></span></dt><dd><dl><dt><span class="section"><a href="#connector-python-apiref-errorcode">7.1.1. Module <code class="literal">errorcode</code></a></span></dt><dt><span class="section"><a href="#connector-python-apiref-errors-error">7.1.2. Exception <code class="literal">errors.Error</code></a></span></dt><dt><span class="section"><a href="#connector-python-apiref-errors-warning">7.1.3. Exception <code class="literal">errors.Warning</code></a></span></dt><dt><span class="section"><a href="#connector-python-apiref-errors-interfaceerror">7.1.4. Exception <code class="literal">errors.InterfaceError</code></a></span></dt><dt><span class="section"><a href="#connector-python-apiref-errors-databaseerror">7.1.5. Exception <code class="literal">errors.DatabaseError</code></a></span></dt><dt><span class="section"><a href="#connector-python-apiref-errors-internalerror">7.1.6. Exception <code class="literal">errors.InternalError</code></a></span></dt><dt><span class="section"><a href="#connector-python-apiref-errors-operationalerror">7.1.7. Exception <code class="literal">errors.OperationalError</code></a></span></dt><dt><span class="section"><a href="#connector-python-apiref-errors-programmingerror">7.1.8. Exception <code class="literal">errors.ProgrammingError</code></a></span></dt><dt><span class="section"><a href="#connector-python-apiref-errors-integrityerror">7.1.9. Exception <code class="literal">errors.IntegrityError</code></a></span></dt><dt><span class="section"><a href="#connector-python-apiref-errors-dataerror">7.1.10. Exception <code class="literal">errors.DataError</code></a></span></dt><dt><span class="section"><a href="#connector-python-apiref-errors-notsupportederror">7.1.11. Exception <code class="literal">errors.NotSupportedError</code></a></span></dt><dt><span class="section"><a href="#connector-python-apiref-errors-custom-error-exception">7.1.12. Function <code class="literal">errors.custom_error_exception(error=None,
    905. 

  905.         exception=None)</code></a></span></dt></dl></dd><dt><span class="section"><a href="#connector-python-apiref-MySQLConnection">7.2. Class <code class="literal">connection.MySQLConnection</code></a></span></dt><dd><dl><dt><span class="section"><a href="#myconnpy_MySQLConnection">7.2.1. Constructor <code class="literal">connection.MySQLConnection(**kwargs)</code></a></span></dt><dt><span class="section"><a href="#myconnpy_MySQLConnection_close">7.2.2. Method <code class="literal">MySQLConnection.close()</code></a></span></dt><dt><span class="section"><a href="#myconnpy_MySQLConnection_config">7.2.3. Method <code class="literal">MySQLConnection.config(**kwargs)</code></a></span></dt><dt><span class="section"><a href="#myconnpy_MySQLConnection_connect">7.2.4. Method <code class="literal">MySQLConnection.connect(**kwargs)</code></a></span></dt><dt><span class="section"><a href="#myconnpy_MySQLConnection_commit">7.2.5. Method <code class="literal">MySQLConnection.commit()</code></a></span></dt><dt><span class="section"><a href="#myconnpy_MySQLConnection_cursor">7.2.6. Method <code class="literal">MySQLConnection.cursor(buffered=None, raw=None,
    906. 

  906.         cursor_class=None)</code></a></span></dt><dt><span class="section"><a href="#myconnpy_MySQLConnection_cmd_change_user">7.2.7. Method <code class="literal">MySQLConnection.cmd_change_user(username='',
    907. 

  907.         password='', database='', charset=33)</code></a></span></dt><dt><span class="section"><a href="#myconnpy_MySQLConnection_cmd_debug">7.2.8. Method <code class="literal">MySQLConnection.cmd_debug()</code></a></span></dt><dt><span class="section"><a href="#myconnpy_MySQLConnection_cmd_init_db">7.2.9. Method <code class="literal">MySQLConnection.cmd_init_db(database)</code></a></span></dt><dt><span class="section"><a href="#myconnpy_MySQLConnection_cmd_ping">7.2.10. Method <code class="literal">MySQLConnection.cmd_ping()</code></a></span></dt><dt><span class="section"><a href="#myconnpy_MySQLConnection_cmd_process_info">7.2.11. Method <code class="literal">MySQLConnection.cmd_process_info()</code></a></span></dt><dt><span class="section"><a href="#myconnpy_MySQLConnection_cmd_process_kill">7.2.12. Method <code class="literal">MySQLConnection.cmd_process_kill(mysql_pid)</code></a></span></dt><dt><span class="section"><a href="#myconnpy_MySQLConnection_cmd_quit">7.2.13. Method <code class="literal">MySQLConnection.cmd_quit()</code></a></span></dt><dt><span class="section"><a href="#myconnpy_MySQLConnection_cmd_query">7.2.14. Method <code class="literal">MySQLConnection.cmd_query(statement)</code></a></span></dt><dt><span class="section"><a href="#myconnpy_MySQLConnection_cmd_query_iter">7.2.15. Method <code class="literal">MySQLConnection.cmd_query_iter(statement)</code></a></span></dt><dt><span class="section"><a href="#myconnpy_MySQLConnection_cmd_refresh">7.2.16. Method <code class="literal">MySQLConnection.cmd_refresh(options)</code></a></span></dt><dt><span class="section"><a href="#myconnpy_MySQLConnection_cmd_shutdown">7.2.17. Method <code class="literal">MySQLConnection.cmd_shutdown()</code></a></span></dt><dt><span class="section"><a href="#myconnpy_MySQLConnection_cmd_statistics">7.2.18. Method <code class="literal">MySQLConnection.cmd_statistics()</code></a></span></dt><dt><span class="section"><a href="#myconnpy_MySQLConnection_disconnect">7.2.19. Method <code class="literal">MySQLConnection.disconnect()</code></a></span></dt><dt><span class="section"><a href="#myconnpy_MySQLConnection_get_rows">7.2.20. Method <code class="literal">MySQLConnection.get_rows(count=None)</code></a></span></dt><dt><span class="section"><a href="#myconnpy_MySQLConnection_get_row">7.2.21. Method <code class="literal">MySQLConnection.get_row()</code></a></span></dt><dt><span class="section"><a href="#myconnpy_MySQLConnection_get_server_info">7.2.22. Method <code class="literal">MySQLConnection.get_server_info()</code></a></span></dt><dt><span class="section"><a href="#myconnpy_MySQLConnection_get_server_version">7.2.23. Method <code class="literal">MySQLConnection.get_server_version()</code></a></span></dt><dt><span class="section"><a href="#myconnpy_MySQLConnection_is_connected">7.2.24. Method <code class="literal">MySQLConnection.is_connected()</code></a></span></dt><dt><span class="section"><a href="#myconnpy_MySQLConnection_isset_client_flag">7.2.25. Method <code class="literal">MySQLConnection.isset_client_flag(flag)</code></a></span></dt><dt><span class="section"><a href="#myconnpy_MySQLConnection_ping">7.2.26. Method <code class="literal">MySQLConnection.ping(attempts=1, delay=0)</code></a></span></dt><dt><span class="section"><a href="#myconnpy_MySQLConnectoin_reconnect">7.2.27. Method <code class="literal">MySQLConnection.reconnect(attempts=1, delay=0)</code></a></span></dt><dt><span class="section"><a href="#myconnpy_MySQLConnection_rollback">7.2.28. Method <code class="literal">MySQLConnection.rollback()</code></a></span></dt><dt><span class="section"><a href="#myconnpy_MySQLConnection_set_charset_collation">7.2.29. Method <code class="literal">MySQLConnection.set_charset_collation(charset=None,
    908. 

  908.         collation=None)</code></a></span></dt><dt><span class="section"><a href="#myconnpy_MySQLConnection_set_client_flags">7.2.30. Method <code class="literal">MySQLConnection.set_client_flags(flags)</code></a></span></dt><dt><span class="section"><a href="#myconnpy_MySQLConnection_autocommit">7.2.31. Property <code class="literal">MySQLConnection.autocommit</code></a></span></dt><dt><span class="section"><a href="#myconnpy_MySQLConnection_charset_name">7.2.32. Property <code class="literal">MySQLConnection.charset_name</code></a></span></dt><dt><span class="section"><a href="#myconnpy_MySQLConnection_collation_name">7.2.33. Property <code class="literal">MySQLConnection.collation_name</code></a></span></dt><dt><span class="section"><a href="#myconnpy_MySQLConnection_connection_id">7.2.34. Property <code class="literal">MySQLConnection.connection_id</code></a></span></dt><dt><span class="section"><a href="#myconnpy_MySQLConnection_database">7.2.35. Property <code class="literal">MySQLConnection.database</code></a></span></dt><dt><span class="section"><a href="#myconnpy_MySQLConnection_get_warnings">7.2.36. Property <code class="literal">MySQLConnection.get_warnings</code></a></span></dt><dt><span class="section"><a href="#myconnpy_MySQLConnection_raise_on_warnings">7.2.37. Property <code class="literal">MySQLConnection.raise_on_warnings</code></a></span></dt><dt><span class="section"><a href="#myconnpy_MySQLConnection_server_host">7.2.38. Property <code class="literal">MySQLConnection.server_host</code></a></span></dt><dt><span class="section"><a href="#myconnpy_MySQLConnection_server_port">7.2.39. Property <code class="literal">MySQLConnection.server_port</code></a></span></dt><dt><span class="section"><a href="#myconnpy_MySQLConnection_sql_mode">7.2.40. Property <code class="literal">MySQLConnection.sql_mode</code></a></span></dt><dt><span class="section"><a href="#myconnpy_MySQLConnection_time_zone">7.2.41. Property <code class="literal">MySQLConnection.time_zone</code></a></span></dt><dt><span class="section"><a href="#myconnpy_MySQLConnection_unix_socket">7.2.42. Property <code class="literal">MySQLConnection.unix_socket</code></a></span></dt><dt><span class="section"><a href="#myconnpy_MySQLConnection_user">7.2.43. Property <code class="literal">MySQLConnection.user</code></a></span></dt></dl></dd><dt><span class="section"><a href="#connector-python-apiref-MySQLCursor">7.3. Class <code class="literal">cursor.MySQLCursor</code></a></span></dt><dd><dl><dt><span class="section"><a href="#myconnpy_MySQLCursor">7.3.1. Constructor <code class="literal">cursor.MySQLCursor</code></a></span></dt><dt><span class="section"><a href="#myconnpy_MySQLCursor_callproc">7.3.2. Method <code class="literal">MySQLCursor.callproc(procname, args=())</code></a></span></dt><dt><span class="section"><a href="#myconnpy_MySQLCursor_close">7.3.3. Method <code class="literal">MySQLCursor.close()</code></a></span></dt><dt><span class="section"><a href="#myconnpy_MySQLCursor_execute">7.3.4. Method <code class="literal">MySQLCursor.execute(operation, params=None,
    909. 

  909.         multi=False)</code></a></span></dt><dt><span class="section"><a href="#myconnpy_MySQLCursor_executemany">7.3.5. Method <code class="literal">MySQLCursor.executemany(operation, seq_params)</code></a></span></dt><dt><span class="section"><a href="#myconnpy_MySQLCursor_fetchall">7.3.6. Method <code class="literal">MySQLCursor.fetchall()</code></a></span></dt><dt><span class="section"><a href="#myconnpy_MySQLCursor_fetchmany">7.3.7. Method <code class="literal">MySQLCursor.fetchmany(size=1)</code></a></span></dt><dt><span class="section"><a href="#myconnpy_MySQLCursor_fetchone">7.3.8. Method <code class="literal">MySQLCursor.fetchone()</code></a></span></dt><dt><span class="section"><a href="#myconnpy_MySQLCursor_fetchwarnings">7.3.9. Method <code class="literal">MySQLCursor.fetchwarnings()</code></a></span></dt><dt><span class="section"><a href="#myconnpy_MySQLCursor_stored_results">7.3.10. Method <code class="literal">MySQLCursor.stored_results()</code></a></span></dt><dt><span class="section"><a href="#myconnpy_MySQLCursor_column_names">7.3.11. Property <code class="literal">MySQLCursor.column_names</code></a></span></dt><dt><span class="section"><a href="#myconnpy_MySQLCursor_statement">7.3.12. Property <code class="literal">MySQLCursor.statement</code></a></span></dt><dt><span class="section"><a href="#myconnpy_MySQLCursor_with_rows">7.3.13. Property <code class="literal">MySQLCursor.with_rows</code></a></span></dt></dl></dd><dt><span class="section"><a href="#connector-python-apiref-MySQLCursorBuffered">7.4. Class <code class="literal">cursor.MySQLCursorBuffered</code></a></span></dt><dt><span class="section"><a href="#connector-python-apiref-ClientFlag">7.5. Class <code class="literal">constants.ClientFlag</code></a></span></dt><dt><span class="section"><a href="#connector-python-apiref-FieldType">7.6. Class <code class="literal">constants.FieldType</code></a></span></dt><dt><span class="section"><a href="#connector-python-apiref-SQLMode">7.7. Class <code class="literal">constants.SQLMode</code></a></span></dt><dt><span class="section"><a href="#connector-python-apiref-CharacterSet">7.8. Class <code class="literal">constants.CharacterSet</code></a></span></dt><dt><span class="section"><a href="#connector-python-apiref-RefreshOption">7.9. Class <code class="literal">constants.RefreshOption</code></a></span></dt></dl></div><p>
    910. 

  910.     This section contains the public API reference of Connector/Python.
    911. 

  911.     Although valid for both Python 2 and Python 3, examples should be
    912. 

  912.     considered working for Python 2.7, and Python 3.1 and greater.
    913. 

  913.   </p><p>
    914. 

  914.     The following overview shows the <code class="literal">mysql.connector</code>
    915. 

  915.     package with its modules. Currently, only the most useful modules,
    916. 

  916.     classes and functions for end users are documented.
    917. 

  917.   </p><pre class="programlisting">mysql.connector
    918. 

  918.   errorcode
    919. 

  919.   errors
    920. 

  920.   connection
    921. 

  921.   constants
    922. 

  922.   conversion
    923. 

  923.   cursor
    924. 

  924.   dbapi
    925. 

  925.   locales
    926. 

  926.     eng
    927. 

  927.       client_error
    928. 

  928.   protocol
    929. 

  929.   utils</pre><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="connector-python-apiref-errors"></a>7.1. Errors and Exceptions</h2></div></div></div><div class="toc"><dl><dt><span class="section"><a href="#connector-python-apiref-errorcode">7.1.1. Module <code class="literal">errorcode</code></a></span></dt><dt><span class="section"><a href="#connector-python-apiref-errors-error">7.1.2. Exception <code class="literal">errors.Error</code></a></span></dt><dt><span class="section"><a href="#connector-python-apiref-errors-warning">7.1.3. Exception <code class="literal">errors.Warning</code></a></span></dt><dt><span class="section"><a href="#connector-python-apiref-errors-interfaceerror">7.1.4. Exception <code class="literal">errors.InterfaceError</code></a></span></dt><dt><span class="section"><a href="#connector-python-apiref-errors-databaseerror">7.1.5. Exception <code class="literal">errors.DatabaseError</code></a></span></dt><dt><span class="section"><a href="#connector-python-apiref-errors-internalerror">7.1.6. Exception <code class="literal">errors.InternalError</code></a></span></dt><dt><span class="section"><a href="#connector-python-apiref-errors-operationalerror">7.1.7. Exception <code class="literal">errors.OperationalError</code></a></span></dt><dt><span class="section"><a href="#connector-python-apiref-errors-programmingerror">7.1.8. Exception <code class="literal">errors.ProgrammingError</code></a></span></dt><dt><span class="section"><a href="#connector-python-apiref-errors-integrityerror">7.1.9. Exception <code class="literal">errors.IntegrityError</code></a></span></dt><dt><span class="section"><a href="#connector-python-apiref-errors-dataerror">7.1.10. Exception <code class="literal">errors.DataError</code></a></span></dt><dt><span class="section"><a href="#connector-python-apiref-errors-notsupportederror">7.1.11. Exception <code class="literal">errors.NotSupportedError</code></a></span></dt><dt><span class="section"><a href="#connector-python-apiref-errors-custom-error-exception">7.1.12. Function <code class="literal">errors.custom_error_exception(error=None,
    930. 

  930.         exception=None)</code></a></span></dt></dl></div><p>
    931. 

  931.       The <code class="literal">mysql.connector.errors</code> module defines
    932. 

  932.       exception classes for errors and warnings raised by MySQL
    933. 

  933.       Connector/Python. Most classes defined in this module are
    934. 

  934.       available when you import <code class="literal">mysql.connector</code>.
    935. 

  935.     </p><p>
    936. 

  936.       The exception classes defined in this module follow mostly the
    937. 

  937.       Python Database Specification v2.0 (PEP-249). For some MySQL
    938. 

  938.       client or server errors it is not always clear which exception to
    939. 

  939.       raise. It is good to discuss whether an error should be
    940. 

  940.       reclassified by opening a bug report.
    941. 

  941.     </p><p>
    942. 

  942.       MySQL Server errors are mapped with Python exception based on
    943. 

  943.       their SQLState (see <a class="ulink" href="http://dev.mysql.com/doc/refman/5.5/en/error-messages-server.html" target="_top">Server Error Codes and Messages</a>). The
    944. 

  944.       following list shows the <code class="literal">SQLState</code> classes and
    945. 

  945.       the exception Connector/Python will raise. It is, however,
    946. 

  946.       possible to redefine which exception is raised for each server
    947. 

  947.       error. Note that the default exception is
    948. 

  948.       <code class="literal">DatabaseError</code>.
    949. 

  949.     </p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
    950. 

  950.           <code class="literal">02</code>: DataError
    951. 

  951.         </p></li><li class="listitem"><p>
    952. 

  952.           <code class="literal">07</code>: DatabaseError
    953. 

  953.         </p></li><li class="listitem"><p>
    954. 

  954.           <code class="literal">08</code>: OperationalError
    955. 

  955.         </p></li><li class="listitem"><p>
    956. 

  956.           <code class="literal">0A</code>: NotSupportedError
    957. 

  957.         </p></li><li class="listitem"><p>
    958. 

  958.           <code class="literal">21</code>: DataError
    959. 

  959.         </p></li><li class="listitem"><p>
    960. 

  960.           <code class="literal">22</code>: DataError
    961. 

  961.         </p></li><li class="listitem"><p>
    962. 

  962.           <code class="literal">23</code>: IntegrityError
    963. 

  963.         </p></li><li class="listitem"><p>
    964. 

  964.           <code class="literal">24</code>: ProgrammingError
    965. 

  965.         </p></li><li class="listitem"><p>
    966. 

  966.           <code class="literal">25</code>: ProgrammingError
    967. 

  967.         </p></li><li class="listitem"><p>
    968. 

  968.           <code class="literal">26</code>: ProgrammingError
    969. 

  969.         </p></li><li class="listitem"><p>
    970. 

  970.           <code class="literal">27</code>: ProgrammingError
    971. 

  971.         </p></li><li class="listitem"><p>
    972. 

  972.           <code class="literal">28</code>: ProgrammingError
    973. 

  973.         </p></li><li class="listitem"><p>
    974. 

  974.           <code class="literal">2A</code>: ProgrammingError
    975. 

  975.         </p></li><li class="listitem"><p>
    976. 

  976.           <code class="literal">2B</code>: DatabaseError
    977. 

  977.         </p></li><li class="listitem"><p>
    978. 

  978.           <code class="literal">2C</code>: ProgrammingError
    979. 

  979.         </p></li><li class="listitem"><p>
    980. 

  980.           <code class="literal">2D</code>: DatabaseError
    981. 

  981.         </p></li><li class="listitem"><p>
    982. 

  982.           <code class="literal">2E</code>: DatabaseError
    983. 

  983.         </p></li><li class="listitem"><p>
    984. 

  984.           <code class="literal">33</code>: DatabaseError
    985. 

  985.         </p></li><li class="listitem"><p>
    986. 

  986.           <code class="literal">34</code>: ProgrammingError
    987. 

  987.         </p></li><li class="listitem"><p>
    988. 

  988.           <code class="literal">35</code>: ProgrammingError
    989. 

  989.         </p></li><li class="listitem"><p>
    990. 

  990.           <code class="literal">37</code>: ProgrammingError
    991. 

  991.         </p></li><li class="listitem"><p>
    992. 

  992.           <code class="literal">3C</code>: ProgrammingError
    993. 

  993.         </p></li><li class="listitem"><p>
    994. 

  994.           <code class="literal">3D</code>: ProgrammingError
    995. 

  995.         </p></li><li class="listitem"><p>
    996. 

  996.           <code class="literal">3F</code>: ProgrammingError
    997. 

  997.         </p></li><li class="listitem"><p>
    998. 

  998.           <code class="literal">40</code>: InternalError
    999. 

  999.         </p></li><li class="listitem"><p>
    1000. 

  1000.           <code class="literal">42</code>: ProgrammingError
    1001. 

  1001.         </p></li><li class="listitem"><p>
    1002. 

  1002.           <code class="literal">44</code>: InternalError
    1003. 

  1003.         </p></li><li class="listitem"><p>
    1004. 

  1004.           <code class="literal">HZ</code>: OperationalError
    1005. 

  1005.         </p></li><li class="listitem"><p>
    1006. 

  1006.           <code class="literal">XA</code>: IntegrityError
    1007. 

  1007.         </p></li><li class="listitem"><p>
    1008. 

  1008.           <code class="literal">0K</code>: OperationalError
    1009. 

  1009.         </p></li><li class="listitem"><p>
    1010. 

  1010.           <code class="literal">HY</code>: DatabaseError
    1011. 

  1011.         </p></li></ul></div><div class="section"><div class="titlepage"><div><div><h3 class="title"><a name="connector-python-apiref-errorcode"></a>7.1.1. Module <code class="literal">errorcode</code></h3></div></div></div><p>
    1012. 

  1012.         This module contains both MySQL server and client error codes
    1013. 

  1013.         defined as module attributes with the error number as value.
    1014. 

  1014.         Using error codes instead of error numbers could make reading
    1015. 

  1015.         the source code a bit easier.
    1016. 

  1016.       </p><pre class="programlisting">
    1017. 

  1017. &gt;&gt;&gt; from mysql.connector import errorcode
    1018. 

  1018. &gt;&gt;&gt; errorcode.ER_BAD_TABLE_ERROR
    1019. 

  1019. 1051
    1020. 

  1020. </pre><p>
    1021. 

  1021.         See <a class="ulink" href="http://dev.mysql.com/doc/refman/5.5/en/error-messages-server.html" target="_top">Server Error Codes and Messages</a> and
    1022. 

  1022.         <a class="ulink" href="http://dev.mysql.com/doc/refman/5.5/en/error-messages-client.html" target="_top">Client Error Codes and Messages</a>.
    1023. 

  1023.       </p></div><div class="section"><div class="titlepage"><div><div><h3 class="title"><a name="connector-python-apiref-errors-error"></a>7.1.2. Exception <code class="literal">errors.Error</code></h3></div></div></div><p>
    1024. 

  1024.         This exception is the base class for all other exceptions in the
    1025. 

  1025.         <code class="literal">errors</code> module. It can be used to catch all
    1026. 

  1026.         errors in a single <code class="literal">except</code> statement.
    1027. 

  1027.       </p><p>
    1028. 

  1028.         The following example shows how we could catch syntax errors:
    1029. 

  1029.       </p><pre class="programlisting">import mysql.connector
    1030. 

  1030. try:
    1031. 

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

  1032.   cursor = cnx.cursor()
    1033. 

  1033.   cursor.execute("SELECT * FORM employees")   # Syntax error in query
    1034. 

  1034.   cnx.close()
    1035. 

  1035. except mysql.connector.Error as err:
    1036. 

  1036.   print("Something went wrong: {}".format(err))</pre><p>
    1037. 

  1037.         Initializing the exception supports a few optional arguments,
    1038. 

  1038.         namely <code class="literal">msg</code>, <code class="literal">errno</code>,
    1039. 

  1039.         <code class="literal">values</code> and <code class="literal">sqlstate</code>. All
    1040. 

  1040.         of them are optional and default to <code class="literal">None</code>.
    1041. 

  1041.         <code class="literal">errors.Error</code> isinternally used by
    1042. 

  1042.         Connector/Python to raise MySQL client and server errors and
    1043. 

  1043.         should not be used by your application to raise exceptions.
    1044. 

  1044.       </p><p>
    1045. 

  1045.         The following examples show the result when using no or a
    1046. 

  1046.         combination of the arguments:
    1047. 

  1047.       </p><pre class="programlisting">
    1048. 

  1048. &gt;&gt;&gt; from mysql.connector.errors import Error
    1049. 

  1049. &gt;&gt;&gt; str(Error())
    1050. 

  1050. 'Unknown error'
    1051. 

  1051. &gt;&gt;&gt; str(Error("Oops! There was an error."))
    1052. 

  1052. 'Oops! There was an error.'
    1053. 

  1053. &gt;&gt;&gt; str(Error(errno=2006))
    1054. 

  1054. '2006: MySQL server has gone away'
    1055. 

  1055. &gt;&gt;&gt; str(Error(errno=2002, values=('/tmp/mysql.sock', 2)))
    1056. 

  1056. "2002: Can't connect to local MySQL server through socket '/tmp/mysql.sock' (2)"
    1057. 

  1057. &gt;&gt;&gt; str(Error(errno=1146, sqlstate='42S02', msg="Table 'test.spam' doesn't exist"))
    1058. 

  1058. "1146 (42S02): Table 'test.spam' doesn't exist"
    1059. 

  1059. </pre><p>
    1060. 

  1060.         The example which uses error number 1146 is used when
    1061. 

  1061.         Connector/Python receives an error packet from the MySQL Server.
    1062. 

  1062.         The information is parsed and passed to the
    1063. 

  1063.         <code class="literal">Error</code> exception as shown.
    1064. 

  1064.       </p><p>
    1065. 

  1065.         Each exception subclassing from <code class="literal">Error</code> can be
    1066. 

  1066.         initialized using the above mentioned arguments. Additionally,
    1067. 

  1067.         each instance has the attributes <code class="literal">errno</code>,
    1068. 

  1068.         <code class="literal">msg</code> and <code class="literal">sqlstate</code> which can
    1069. 

  1069.         be used in your code.
    1070. 

  1070.       </p><p>
    1071. 

  1071.         The following example shows how to handle errors when dropping a
    1072. 

  1072.         table which does not exists (when you do not want to use the
    1073. 

  1073.         <code class="literal">IF EXISTS</code> clause):
    1074. 

  1074.       </p><pre class="programlisting">import mysql.connector
    1075. 

  1075. from mysql.connector import errorcode
    1076. 

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

  1077. try:
    1078. 

  1078.   cur.execute("DROP TABLE spam")
    1079. 

  1079. except mysql.connector.Error as err:
    1080. 

  1080.   if err.errno == errorcode.ER_BAD_TABLE_ERROR:
    1081. 

  1081.     print("Creating table spam")
    1082. 

  1082.   else:
    1083. 

  1083.     raise</pre><p>
    1084. 

  1084.         <code class="literal">errors.Error</code> is a subclass of the Python
    1085. 

  1085.         <code class="literal">StandardError</code>.
    1086. 

  1086.       </p></div><div class="section"><div class="titlepage"><div><div><h3 class="title"><a name="connector-python-apiref-errors-warning"></a>7.1.3. Exception <code class="literal">errors.Warning</code></h3></div></div></div><p>
    1087. 

  1087.         This exception is used for reporting important warnings,
    1088. 

  1088.         however, Connector/Python does not use it. It is included to be
    1089. 

  1089.         compliant with the Python Database Specification v2.0 (PEP-249).
    1090. 

  1090.       </p><p>
    1091. 

  1091.         Consider using either more strict
    1092. 

  1092.         <a class="ulink" href="http://dev.mysql.com/doc/refman/5.5/en/server-sql-mode.html" target="_top">Server SQL Modes</a> or the
    1093. 

  1093.         <a class="link" href="#connector-python-connectargs" title="Chapter 6. Connector/Python Connection Arguments">raise_on_warnings</a>
    1094. 

  1094.         connection argument to make Connector/Python raise errors when
    1095. 

  1095.         your queries produce warnings.
    1096. 

  1096.       </p><p>
    1097. 

  1097.         <code class="literal">errors.Warning</code> is a subclass of the Python
    1098. 

  1098.         <code class="literal">StandardError</code>.
    1099. 

  1099.       </p></div><div class="section"><div class="titlepage"><div><div><h3 class="title"><a name="connector-python-apiref-errors-interfaceerror"></a>7.1.4. Exception <code class="literal">errors.InterfaceError</code></h3></div></div></div><p>
    1100. 

  1100.         This exception is raised for errors originating from
    1101. 

  1101.         Connector/Python itself, not related to the MySQL server.
    1102. 

  1102.       </p><p>
    1103. 

  1103.         <code class="literal">errors.InterfaceError</code> is a subclass of
    1104. 

  1104.         <code class="literal">errors.Error</code>.
    1105. 

  1105.       </p></div><div class="section"><div class="titlepage"><div><div><h3 class="title"><a name="connector-python-apiref-errors-databaseerror"></a>7.1.5. Exception <code class="literal">errors.DatabaseError</code></h3></div></div></div><p>
    1106. 

  1106.         This exception is the default for any MySQL error which does not
    1107. 

  1107.         fit the other exceptions.
    1108. 

  1108.       </p><p>
    1109. 

  1109.         <code class="literal">errors.DatabaseError</code> is a subclass of
    1110. 

  1110.         <code class="literal">errors.Error</code>.
    1111. 

  1111.       </p></div><div class="section"><div class="titlepage"><div><div><h3 class="title"><a name="connector-python-apiref-errors-internalerror"></a>7.1.6. Exception <code class="literal">errors.InternalError</code></h3></div></div></div><p>
    1112. 

  1112.         This exception is raised when the MySQL server encounters an
    1113. 

  1113.         internal error, for example, when a deadlock occurred.
    1114. 

  1114.       </p><p>
    1115. 

  1115.         <code class="literal">errors.InternalError</code> is a subclass of
    1116. 

  1116.         <code class="literal">errors.DatabaseError</code>.
    1117. 

  1117.       </p></div><div class="section"><div class="titlepage"><div><div><h3 class="title"><a name="connector-python-apiref-errors-operationalerror"></a>7.1.7. Exception <code class="literal">errors.OperationalError</code></h3></div></div></div><p>
    1118. 

  1118.         This exception is raised for errors which are related to MySQL's
    1119. 

  1119.         operations. For example, to many connections, a hostname could
    1120. 

  1120.         not be resolved, bad handshake, server is shutting down,
    1121. 

  1121.         communication errors, and so on.
    1122. 

  1122.       </p><p>
    1123. 

  1123.         <code class="literal">errors.OperationalError</code> is a subclass of
    1124. 

  1124.         <code class="literal">errors.DatabaseError</code>.
    1125. 

  1125.       </p></div><div class="section"><div class="titlepage"><div><div><h3 class="title"><a name="connector-python-apiref-errors-programmingerror"></a>7.1.8. Exception <code class="literal">errors.ProgrammingError</code></h3></div></div></div><p>
    1126. 

  1126.         This exception is raised on programming errors, for example when
    1127. 

  1127.         you have a syntax error in your SQL or a table was not found.
    1128. 

  1128.       </p><p>
    1129. 

  1129.         The following example shows how to handle syntax errors:
    1130. 

  1130.       </p><pre class="programlisting">try:
    1131. 

  1131.   cursor.execute("CREATE DESK t1 (id int, PRIMARY KEY (id))")
    1132. 

  1132. except mysql.connector.ProgrammingError as err:
    1133. 

  1133.   if err.errno == errorcode.ER_SYNTAX_ERROR:
    1134. 

  1134.     print("Check your syntax!")
    1135. 

  1135.   else:
    1136. 

  1136.     print("Error: {}".format(err))</pre><p>
    1137. 

  1137.         <code class="literal">errors.ProgrammingError</code> is a subclass of
    1138. 

  1138.         <code class="literal">errors.DatabaseError</code>.
    1139. 

  1139.       </p></div><div class="section"><div class="titlepage"><div><div><h3 class="title"><a name="connector-python-apiref-errors-integrityerror"></a>7.1.9. Exception <code class="literal">errors.IntegrityError</code></h3></div></div></div><p>
    1140. 

  1140.         This exception is raised when the relational integrity of the
    1141. 

  1141.         data is affected. For example, a duplicate key was inserted or a
    1142. 

  1142.         foreign key constraint would fail.
    1143. 

  1143.       </p><p>
    1144. 

  1144.         The following example shows a duplicate key error raised as
    1145. 

  1145.         IntegrityError:
    1146. 

  1146.       </p><pre class="programlisting">cursor.execute("CREATE TABLE t1 (id int, PRIMARY KEY (id))")
    1147. 

  1147. try:
    1148. 

  1148.   cursor.execute("INSERT INTO t1 (id) VALUES (1)")
    1149. 

  1149.   cursor.execute("INSERT INTO t1 (id) VALUES (1)")
    1150. 

  1150. except mysql.connector.IntegrityError as err:
    1151. 

  1151.   print("Error: {}".format(err))</pre><p>
    1152. 

  1152.         <code class="literal">errors.IntegrityError</code> is a subclass of
    1153. 

  1153.         <code class="literal">errors.DatabaseError</code>.
    1154. 

  1154.       </p></div><div class="section"><div class="titlepage"><div><div><h3 class="title"><a name="connector-python-apiref-errors-dataerror"></a>7.1.10. Exception <code class="literal">errors.DataError</code></h3></div></div></div><p>
    1155. 

  1155.         This exception is raised when there were problems with the data.
    1156. 

  1156.         Examples are a column set to NULL when it can not, out of range
    1157. 

  1157.         values for a column, division by zero, column count does not
    1158. 

  1158.         match value count, and so on.
    1159. 

  1159.       </p><p>
    1160. 

  1160.         <code class="literal">errors.DataError</code> is a subclass of
    1161. 

  1161.         <code class="literal">errors.DatabaseError</code>.
    1162. 

  1162.       </p></div><div class="section"><div class="titlepage"><div><div><h3 class="title"><a name="connector-python-apiref-errors-notsupportederror"></a>7.1.11. Exception <code class="literal">errors.NotSupportedError</code></h3></div></div></div><p>
    1163. 

  1163.         This exception is raised is case some feature was used but not
    1164. 

  1164.         supported by the version of MySQL which returned the error. It
    1165. 

  1165.         is also raised when using functions or statements which are not
    1166. 

  1166.         supported by stored routines.
    1167. 

  1167.       </p><p>
    1168. 

  1168.         <code class="literal">errors.NotSupportedError</code> is a subclass of
    1169. 

  1169.         <code class="literal">errors.DatabaseError</code>.
    1170. 

  1170.       </p></div><div class="section"><div class="titlepage"><div><div><h3 class="title"><a name="connector-python-apiref-errors-custom-error-exception"></a>7.1.12. Function <code class="literal">errors.custom_error_exception(error=None,
    1171. 

  1171.         exception=None)</code></h3></div></div></div><p>
    1172. 

  1172.         This function defines custom exceptions for MySQL server errors
    1173. 

  1173.         and returns current customizations.
    1174. 

  1174.       </p><p>
    1175. 

  1175.         If <code class="literal">error</code> is a MySQL Server error number, then
    1176. 

  1176.         you have to pass also the <code class="literal">exception</code> class.
    1177. 

  1177.         The <code class="literal">error</code> argument can also be a dictionary
    1178. 

  1178.         in which case the key is the server error number, and value the
    1179. 

  1179.         class of the exception to be raised.
    1180. 

  1180.       </p><p>
    1181. 

  1181.         To reset the customizations, simply supply an empty dictionary.
    1182. 

  1182.       </p><pre class="programlisting">import mysql.connector
    1183. 

  1183. from mysql.connector import errorcode
    1184. 

  1184. # Server error 1028 should raise a DatabaseError
    1185. 

  1185. mysql.connector.custom_error_exception(1028, mysql.connector.DatabaseError)
    1186. 

  1186. # Or using a dictionary:
    1187. 

  1187. mysql.connector.custom_error_exception({
    1188. 

  1188.   1028: mysql.connector.DatabaseError,
    1189. 

  1189.   1029: mysql.connector.OperationalError,
    1190. 

  1190. })
    1191. 

  1191. # To reset, pass an empty dictionary:
    1192. 

  1192. mysql.connector.custom_error_exception({})</pre></div></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="connector-python-apiref-MySQLConnection"></a>7.2. Class <code class="literal">connection.MySQLConnection</code></h2></div></div></div><div class="toc"><dl><dt><span class="section"><a href="#myconnpy_MySQLConnection">7.2.1. Constructor <code class="literal">connection.MySQLConnection(**kwargs)</code></a></span></dt><dt><span class="section"><a href="#myconnpy_MySQLConnection_close">7.2.2. Method <code class="literal">MySQLConnection.close()</code></a></span></dt><dt><span class="section"><a href="#myconnpy_MySQLConnection_config">7.2.3. Method <code class="literal">MySQLConnection.config(**kwargs)</code></a></span></dt><dt><span class="section"><a href="#myconnpy_MySQLConnection_connect">7.2.4. Method <code class="literal">MySQLConnection.connect(**kwargs)</code></a></span></dt><dt><span class="section"><a href="#myconnpy_MySQLConnection_commit">7.2.5. Method <code class="literal">MySQLConnection.commit()</code></a></span></dt><dt><span class="section"><a href="#myconnpy_MySQLConnection_cursor">7.2.6. Method <code class="literal">MySQLConnection.cursor(buffered=None, raw=None,
    1193. 

  1193.         cursor_class=None)</code></a></span></dt><dt><span class="section"><a href="#myconnpy_MySQLConnection_cmd_change_user">7.2.7. Method <code class="literal">MySQLConnection.cmd_change_user(username='',
    1194. 

  1194.         password='', database='', charset=33)</code></a></span></dt><dt><span class="section"><a href="#myconnpy_MySQLConnection_cmd_debug">7.2.8. Method <code class="literal">MySQLConnection.cmd_debug()</code></a></span></dt><dt><span class="section"><a href="#myconnpy_MySQLConnection_cmd_init_db">7.2.9. Method <code class="literal">MySQLConnection.cmd_init_db(database)</code></a></span></dt><dt><span class="section"><a href="#myconnpy_MySQLConnection_cmd_ping">7.2.10. Method <code class="literal">MySQLConnection.cmd_ping()</code></a></span></dt><dt><span class="section"><a href="#myconnpy_MySQLConnection_cmd_process_info">7.2.11. Method <code class="literal">MySQLConnection.cmd_process_info()</code></a></span></dt><dt><span class="section"><a href="#myconnpy_MySQLConnection_cmd_process_kill">7.2.12. Method <code class="literal">MySQLConnection.cmd_process_kill(mysql_pid)</code></a></span></dt><dt><span class="section"><a href="#myconnpy_MySQLConnection_cmd_quit">7.2.13. Method <code class="literal">MySQLConnection.cmd_quit()</code></a></span></dt><dt><span class="section"><a href="#myconnpy_MySQLConnection_cmd_query">7.2.14. Method <code class="literal">MySQLConnection.cmd_query(statement)</code></a></span></dt><dt><span class="section"><a href="#myconnpy_MySQLConnection_cmd_query_iter">7.2.15. Method <code class="literal">MySQLConnection.cmd_query_iter(statement)</code></a></span></dt><dt><span class="section"><a href="#myconnpy_MySQLConnection_cmd_refresh">7.2.16. Method <code class="literal">MySQLConnection.cmd_refresh(options)</code></a></span></dt><dt><span class="section"><a href="#myconnpy_MySQLConnection_cmd_shutdown">7.2.17. Method <code class="literal">MySQLConnection.cmd_shutdown()</code></a></span></dt><dt><span class="section"><a href="#myconnpy_MySQLConnection_cmd_statistics">7.2.18. Method <code class="literal">MySQLConnection.cmd_statistics()</code></a></span></dt><dt><span class="section"><a href="#myconnpy_MySQLConnection_disconnect">7.2.19. Method <code class="literal">MySQLConnection.disconnect()</code></a></span></dt><dt><span class="section"><a href="#myconnpy_MySQLConnection_get_rows">7.2.20. Method <code class="literal">MySQLConnection.get_rows(count=None)</code></a></span></dt><dt><span class="section"><a href="#myconnpy_MySQLConnection_get_row">7.2.21. Method <code class="literal">MySQLConnection.get_row()</code></a></span></dt><dt><span class="section"><a href="#myconnpy_MySQLConnection_get_server_info">7.2.22. Method <code class="literal">MySQLConnection.get_server_info()</code></a></span></dt><dt><span class="section"><a href="#myconnpy_MySQLConnection_get_server_version">7.2.23. Method <code class="literal">MySQLConnection.get_server_version()</code></a></span></dt><dt><span class="section"><a href="#myconnpy_MySQLConnection_is_connected">7.2.24. Method <code class="literal">MySQLConnection.is_connected()</code></a></span></dt><dt><span class="section"><a href="#myconnpy_MySQLConnection_isset_client_flag">7.2.25. Method <code class="literal">MySQLConnection.isset_client_flag(flag)</code></a></span></dt><dt><span class="section"><a href="#myconnpy_MySQLConnection_ping">7.2.26. Method <code class="literal">MySQLConnection.ping(attempts=1, delay=0)</code></a></span></dt><dt><span class="section"><a href="#myconnpy_MySQLConnectoin_reconnect">7.2.27. Method <code class="literal">MySQLConnection.reconnect(attempts=1, delay=0)</code></a></span></dt><dt><span class="section"><a href="#myconnpy_MySQLConnection_rollback">7.2.28. Method <code class="literal">MySQLConnection.rollback()</code></a></span></dt><dt><span class="section"><a href="#myconnpy_MySQLConnection_set_charset_collation">7.2.29. Method <code class="literal">MySQLConnection.set_charset_collation(charset=None,
    1195. 

  1195.         collation=None)</code></a></span></dt><dt><span class="section"><a href="#myconnpy_MySQLConnection_set_client_flags">7.2.30. Method <code class="literal">MySQLConnection.set_client_flags(flags)</code></a></span></dt><dt><span class="section"><a href="#myconnpy_MySQLConnection_autocommit">7.2.31. Property <code class="literal">MySQLConnection.autocommit</code></a></span></dt><dt><span class="section"><a href="#myconnpy_MySQLConnection_charset_name">7.2.32. Property <code class="literal">MySQLConnection.charset_name</code></a></span></dt><dt><span class="section"><a href="#myconnpy_MySQLConnection_collation_name">7.2.33. Property <code class="literal">MySQLConnection.collation_name</code></a></span></dt><dt><span class="section"><a href="#myconnpy_MySQLConnection_connection_id">7.2.34. Property <code class="literal">MySQLConnection.connection_id</code></a></span></dt><dt><span class="section"><a href="#myconnpy_MySQLConnection_database">7.2.35. Property <code class="literal">MySQLConnection.database</code></a></span></dt><dt><span class="section"><a href="#myconnpy_MySQLConnection_get_warnings">7.2.36. Property <code class="literal">MySQLConnection.get_warnings</code></a></span></dt><dt><span class="section"><a href="#myconnpy_MySQLConnection_raise_on_warnings">7.2.37. Property <code class="literal">MySQLConnection.raise_on_warnings</code></a></span></dt><dt><span class="section"><a href="#myconnpy_MySQLConnection_server_host">7.2.38. Property <code class="literal">MySQLConnection.server_host</code></a></span></dt><dt><span class="section"><a href="#myconnpy_MySQLConnection_server_port">7.2.39. Property <code class="literal">MySQLConnection.server_port</code></a></span></dt><dt><span class="section"><a href="#myconnpy_MySQLConnection_sql_mode">7.2.40. Property <code class="literal">MySQLConnection.sql_mode</code></a></span></dt><dt><span class="section"><a href="#myconnpy_MySQLConnection_time_zone">7.2.41. Property <code class="literal">MySQLConnection.time_zone</code></a></span></dt><dt><span class="section"><a href="#myconnpy_MySQLConnection_unix_socket">7.2.42. Property <code class="literal">MySQLConnection.unix_socket</code></a></span></dt><dt><span class="section"><a href="#myconnpy_MySQLConnection_user">7.2.43. Property <code class="literal">MySQLConnection.user</code></a></span></dt></dl></div><p>
    1196. 

  1196.       The MySQLConnection class is used to open and manage a connection
    1197. 

  1197.       to a MySQL server. It also used to send commands and SQL queries
    1198. 

  1198.       and read result.
    1199. 

  1199.     </p><div class="section"><div class="titlepage"><div><div><h3 class="title"><a name="myconnpy_MySQLConnection"></a>7.2.1. Constructor <code class="literal">connection.MySQLConnection(**kwargs)</code></h3></div></div></div><p>
    1200. 

  1200.         The MySQLConnection constructor initializes the attributes and
    1201. 

  1201.         when at least one argument is passed, it tries to connect with
    1202. 

  1202.         the MySQL server.
    1203. 

  1203.       </p><p>
    1204. 

  1204.         For a complete list or arguments, see
    1205. 

  1205.         <a class="xref" href="#connector-python-connectargs" title="Chapter 6. Connector/Python Connection Arguments">Chapter 6, <i>Connector/Python Connection Arguments</i></a>.
    1206. 

  1206.       </p></div><div class="section"><div class="titlepage"><div><div><h3 class="title"><a name="myconnpy_MySQLConnection_close"></a>7.2.2. Method <code class="literal">MySQLConnection.close()</code></h3></div></div></div><p>
    1207. 

  1207.         See
    1208. 

  1208.         <a class="link" href="#myconnpy_MySQLConnection_disconnect" title="7.2.19. Method MySQLConnection.disconnect()">disconnect()</a>.
    1209. 

  1209.       </p><p>
    1210. 

  1210.         Returns a tuple.
    1211. 

  1211.       </p></div><div class="section"><div class="titlepage"><div><div><h3 class="title"><a name="myconnpy_MySQLConnection_config"></a>7.2.3. Method <code class="literal">MySQLConnection.config(**kwargs)</code></h3></div></div></div><p>
    1212. 

  1212.         Allows to configure a MySQLConnection instance after it was
    1213. 

  1213.         instantiated. See <a class="xref" href="#connector-python-connectargs" title="Chapter 6. Connector/Python Connection Arguments">Chapter 6, <i>Connector/Python Connection Arguments</i></a>
    1214. 

  1214.         for a complete list of possible arguments.
    1215. 

  1215.       </p><p>
    1216. 

  1216.         You could use the <code class="literal">config()</code> method to change,
    1217. 

  1217.         for example, the username and call
    1218. 

  1218.         <code class="literal">reconnect()</code>.
    1219. 

  1219.       </p><pre class="programlisting">cnx = MySQLConnection(user='joe', database='test')
    1220. 

  1220. # Connected as 'joe'
    1221. 

  1221. cnx.config(user='jane')
    1222. 

  1222. cnx.reconnect()
    1223. 

  1223. # Now connected as 'jane'</pre></div><div class="section"><div class="titlepage"><div><div><h3 class="title"><a name="myconnpy_MySQLConnection_connect"></a>7.2.4. Method <code class="literal">MySQLConnection.connect(**kwargs)</code></h3></div></div></div><p>
    1224. 

  1224.         This method sets up the connection to the MySQL server. If no
    1225. 

  1225.         arguments are given, it uses the already configured or default
    1226. 

  1226.         values. See <a class="xref" href="#connector-python-connectargs" title="Chapter 6. Connector/Python Connection Arguments">Chapter 6, <i>Connector/Python Connection Arguments</i></a> for a
    1227. 

  1227.         complete list of possible arguments.
    1228. 

  1228.       </p></div><div class="section"><div class="titlepage"><div><div><h3 class="title"><a name="myconnpy_MySQLConnection_commit"></a>7.2.5. Method <code class="literal">MySQLConnection.commit()</code></h3></div></div></div><p>
    1229. 

  1229.         This method sends the <code class="literal">COMMIT</code> command to the
    1230. 

  1230.         MySQL server, committing the current transaction. Since by
    1231. 

  1231.         default, Connector/Python does not auto commit, it is important
    1232. 

  1232.         to call this method after every transaction which updates data
    1233. 

  1233.         for tables using transactional storage engines.
    1234. 

  1234.       </p><p>
    1235. 

  1235.         See the
    1236. 

  1236.         <a class="link" href="#myconnpy_MySQLConnection_rollback" title="7.2.28. Method MySQLConnection.rollback()">rollback()</a>
    1237. 

  1237.         method for rolling back transactions.
    1238. 

  1238.       </p><pre class="programlisting">
    1239. 

  1239. &gt;&gt;&gt; cursor.execute("INSERT INTO employees (first_name) VALUES (%s)", ('Jane'))
    1240. 

  1240. &gt;&gt;&gt; cnx.commit()
    1241. 

  1241. </pre></div><div class="section"><div class="titlepage"><div><div><h3 class="title"><a name="myconnpy_MySQLConnection_cursor"></a>7.2.6. Method <code class="literal">MySQLConnection.cursor(buffered=None, raw=None,
    1242. 

  1242.         cursor_class=None)</code></h3></div></div></div><p>
    1243. 

  1243.         This method returns a MySQLCursor() object, or a subclass of it
    1244. 

  1244.         depending the passed arguments.
    1245. 

  1245.       </p><p>
    1246. 

  1246.         When <code class="literal">buffered</code> is True, the cursor will fetch
    1247. 

  1247.         all rows after the operation is executed. This is useful when
    1248. 

  1248.         queries return small result sets. Setting <code class="literal">raw</code>
    1249. 

  1249.         will skip the conversion from MySQL data types to Python types
    1250. 

  1250.         when fetching rows. Raw is usually used when you want to have
    1251. 

  1251.         more performance and/or you want to do the conversion yourself.
    1252. 

  1252.       </p><p>
    1253. 

  1253.         The <code class="literal">cursor_class</code> argument can be used to pass
    1254. 

  1254.         a class to use for instantiating a new cursor. It has to be a
    1255. 

  1255.         subclass of <code class="literal">cursor.CursorBase</code>.
    1256. 

  1256.       </p><p>
    1257. 

  1257.         The returned object depends on the combination of the
    1258. 

  1258.         <code class="literal">buffered</code> and <code class="literal">raw</code>
    1259. 

  1259.         arguments.
    1260. 

  1260.       </p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
    1261. 

  1261.             If not buffered and not raw:
    1262. 

  1262.             <code class="literal">cursor.MySQLCursor</code>
    1263. 

  1263.           </p></li><li class="listitem"><p>
    1264. 

  1264.             If buffered and not raw:
    1265. 

  1265.             <code class="literal">cursor.MySQLCursorBuffered</code>
    1266. 

  1266.           </p></li><li class="listitem"><p>
    1267. 

  1267.             If buffered and raw:
    1268. 

  1268.             <code class="literal">cursor.MySQLCursorBufferedRaw</code>
    1269. 

  1269.           </p></li><li class="listitem"><p>
    1270. 

  1270.             If not buffered and raw:
    1271. 

  1271.             <code class="literal">cursor.MySQLCursorRaw</code>
    1272. 

  1272.           </p></li></ul></div><p>
    1273. 

  1273.         Returns a <code class="literal">CursorBase</code> instance.
    1274. 

  1274.       </p></div><div class="section"><div class="titlepage"><div><div><h3 class="title"><a name="myconnpy_MySQLConnection_cmd_change_user"></a>7.2.7. Method <code class="literal">MySQLConnection.cmd_change_user(username='',
    1275. 

  1275.         password='', database='', charset=33)</code></h3></div></div></div><p>
    1276. 

  1276.         Changes the user using <code class="literal">username</code> and
    1277. 

  1277.         <code class="literal">password</code>. It also causes the specified
    1278. 

  1278.         <code class="literal">database</code> to become the default (current)
    1279. 

  1279.         database. It is also possible to change the character set using
    1280. 

  1280.         the <code class="literal">charset</code> argument.
    1281. 

  1281.       </p><p>
    1282. 

  1282.         Returns a dictionary containing the OK packet information.
    1283. 

  1283.       </p></div><div class="section"><div class="titlepage"><div><div><h3 class="title"><a name="myconnpy_MySQLConnection_cmd_debug"></a>7.2.8. Method <code class="literal">MySQLConnection.cmd_debug()</code></h3></div></div></div><p>
    1284. 

  1284.         Instructs the server to write some debug information to the log.
    1285. 

  1285.         For this to work, the connected user must have the
    1286. 

  1286.         <code class="literal">SUPER</code> privilege.
    1287. 

  1287.       </p><p>
    1288. 

  1288.         Returns a dictionary containing the OK packet information.
    1289. 

  1289.       </p></div><div class="section"><div class="titlepage"><div><div><h3 class="title"><a name="myconnpy_MySQLConnection_cmd_init_db"></a>7.2.9. Method <code class="literal">MySQLConnection.cmd_init_db(database)</code></h3></div></div></div><p>
    1290. 

  1290.         This method makes specified database the default (current)
    1291. 

  1291.         database. In subsequent queries, this database is the default
    1292. 

  1292.         for table references that do not include an explicit database
    1293. 

  1293.         specifier.
    1294. 

  1294.       </p><p>
    1295. 

  1295.         Returns a dictionary containing the OK packet information.
    1296. 

  1296.       </p></div><div class="section"><div class="titlepage"><div><div><h3 class="title"><a name="myconnpy_MySQLConnection_cmd_ping"></a>7.2.10. Method <code class="literal">MySQLConnection.cmd_ping()</code></h3></div></div></div><p>
    1297. 

  1297.         Checks whether the connection to the server is working.
    1298. 

  1298.       </p><p>
    1299. 

  1299.         This method is not to be used directly. Use
    1300. 

  1300.         <a class="link" href="#myconnpy_MySQLConnection_ping" title="7.2.26. Method MySQLConnection.ping(attempts=1, delay=0)">ping()</a>
    1301. 

  1301.         or
    1302. 

  1302.         <a class="link" href="#myconnpy_MySQLConnection_is_connected" title="7.2.24. Method MySQLConnection.is_connected()">is_connected()</a>
    1303. 

  1303.         instead.
    1304. 

  1304.       </p><p>
    1305. 

  1305.         Returns a dictionary containing the OK packet information.
    1306. 

  1306.       </p></div><div class="section"><div class="titlepage"><div><div><h3 class="title"><a name="myconnpy_MySQLConnection_cmd_process_info"></a>7.2.11. Method <code class="literal">MySQLConnection.cmd_process_info()</code></h3></div></div></div><p>
    1307. 

  1307.         This method raises the NotSupportedError exception. Instead, use
    1308. 

  1308.         the <code class="literal">SHOW PROCESSLIST</code> statement or query the
    1309. 

  1309.         tables found in the database
    1310. 

  1310.         <code class="literal">INFORMATION_SCHEMA</code>.
    1311. 

  1311.       </p></div><div class="section"><div class="titlepage"><div><div><h3 class="title"><a name="myconnpy_MySQLConnection_cmd_process_kill"></a>7.2.12. Method <code class="literal">MySQLConnection.cmd_process_kill(mysql_pid)</code></h3></div></div></div><p>
    1312. 

  1312.         Asks the server to kill the thread specified by
    1313. 

  1313.         <code class="literal">mysql_pid</code>. Although still available, it's
    1314. 

  1314.         better to use the SQL <code class="literal">KILL</code> command.
    1315. 

  1315.       </p><p>
    1316. 

  1316.         Returns a dictionary containing the OK packet information.
    1317. 

  1317.       </p><p>
    1318. 

  1318.         The following two lines do the same:
    1319. 

  1319.       </p><pre class="programlisting">
    1320. 

  1320. &gt;&gt;&gt; cnx.cmd_process_kill(123)
    1321. 

  1321. &gt;&gt;&gt; cnx.cmd_query('KILL 123')
    1322. 

  1322. </pre></div><div class="section"><div class="titlepage"><div><div><h3 class="title"><a name="myconnpy_MySQLConnection_cmd_quit"></a>7.2.13. Method <code class="literal">MySQLConnection.cmd_quit()</code></h3></div></div></div><p>
    1323. 

  1323.         This method sends the <code class="literal">QUIT</code> command to the
    1324. 

  1324.         MySQL server, closing the current connection. Since there is no
    1325. 

  1325.         response from the MySQL, the packet that was sent is returned.
    1326. 

  1326.       </p></div><div class="section"><div class="titlepage"><div><div><h3 class="title"><a name="myconnpy_MySQLConnection_cmd_query"></a>7.2.14. Method <code class="literal">MySQLConnection.cmd_query(statement)</code></h3></div></div></div><p>
    1327. 

  1327.         This method sends the given <code class="literal">statement</code> to the
    1328. 

  1328.         MySQL server and returns a result. If you need to send multiple
    1329. 

  1329.         statements, you have to use the
    1330. 

  1330.         <a class="link" href="#myconnpy_MySQLConnection_cmd_query_iter" title="7.2.15. Method MySQLConnection.cmd_query_iter(statement)">cmd_query_iter()</a>
    1331. 

  1331.         method.
    1332. 

  1332.       </p><p>
    1333. 

  1333.         The returned dictionary contains information depending on what
    1334. 

  1334.         kind of query was executed. If the query is a
    1335. 

  1335.         <a class="ulink" href="http://dev.mysql.com/doc/refman/5.5/en/select.html" target="_top"><code class="literal">SELECT</code></a> statement, the result
    1336. 

  1336.         contains information about columns. Other statements return a
    1337. 

  1337.         dictionary containing OK or EOF packet information.
    1338. 

  1338.       </p><p>
    1339. 

  1339.         Errors received from the MySQL server are raised as exceptions.
    1340. 

  1340.         An <code class="literal">InterfaceError</code> is raised when multiple
    1341. 

  1341.         results are found.
    1342. 

  1342.       </p><p>
    1343. 

  1343.         Returns a dictionary.
    1344. 

  1344.       </p></div><div class="section"><div class="titlepage"><div><div><h3 class="title"><a name="myconnpy_MySQLConnection_cmd_query_iter"></a>7.2.15. Method <code class="literal">MySQLConnection.cmd_query_iter(statement)</code></h3></div></div></div><p>
    1345. 

  1345.         Similar to the
    1346. 

  1346.         <a class="link" href="#myconnpy_MySQLConnection_cmd_query" title="7.2.14. Method MySQLConnection.cmd_query(statement)">cmd_query()</a>
    1347. 

  1347.         method, but returns a generator object to iterate through
    1348. 

  1348.         results. Use <code class="literal">cmd_query_iter()</code> when sending
    1349. 

  1349.         multiple statements, and separate the statements with
    1350. 

  1350.         semicolons.
    1351. 

  1351.       </p><p>
    1352. 

  1352.         The following example shows how to iterate through the results
    1353. 

  1353.         after sending multiple statements:
    1354. 

  1354.       </p><pre class="programlisting">statement = 'SELECT 1; INSERT INTO t1 VALUES (); SELECT 2'
    1355. 

  1355. for result in cnx.cmd_query(statement, iterate=True):
    1356. 

  1356.   if 'columns' in result:
    1357. 

  1357.     columns = result['columns']
    1358. 

  1358.     rows = cnx.get_rows()
    1359. 

  1359.   else:
    1360. 

  1360.     # do something useful with INSERT result</pre><p>
    1361. 

  1361.         Returns a generator object.
    1362. 

  1362.       </p></div><div class="section"><div class="titlepage"><div><div><h3 class="title"><a name="myconnpy_MySQLConnection_cmd_refresh"></a>7.2.16. Method <code class="literal">MySQLConnection.cmd_refresh(options)</code></h3></div></div></div><p>
    1363. 

  1363.         This method flushes tables or caches, or resets replication
    1364. 

  1364.         server information. The connected user must have the
    1365. 

  1365.         <code class="literal">RELOAD</code> privilege.
    1366. 

  1366.       </p><p>
    1367. 

  1367.         The <code class="literal">options</code> argument should be a bitwise
    1368. 

  1368.         value using constants from the class
    1369. 

  1369.         <code class="literal">constants.RefreshOption</code>.
    1370. 

  1370.       </p><p>
    1371. 

  1371.         See <a class="xref" href="#connector-python-apiref-RefreshOption" title="7.9. Class constants.RefreshOption">Section 7.9, “Class <code class="literal">constants.RefreshOption</code>”</a> for
    1372. 

  1372.         a list of options.
    1373. 

  1373.       </p><p>
    1374. 

  1374.         Example:
    1375. 

  1375.       </p><pre class="programlisting">
    1376. 

  1376. &gt;&gt;&gt; from mysql.connector import RefreshOption
    1377. 

  1377. &gt;&gt;&gt; refresh = RefreshOption.LOG | RefreshOption.THREADS
    1378. 

  1378. &gt;&gt;&gt; cnx.cmd_refresh(refresh)
    1379. 

  1379. </pre></div><div class="section"><div class="titlepage"><div><div><h3 class="title"><a name="myconnpy_MySQLConnection_cmd_shutdown"></a>7.2.17. Method <code class="literal">MySQLConnection.cmd_shutdown()</code></h3></div></div></div><p>
    1380. 

  1380.         Asks the database server to shut down. The connected user must
    1381. 

  1381.         have the <code class="literal">SHUTDOWN</code> privilege.
    1382. 

  1382.       </p><p>
    1383. 

  1383.         Returns a dictionary containing the OK packet information.
    1384. 

  1384.       </p></div><div class="section"><div class="titlepage"><div><div><h3 class="title"><a name="myconnpy_MySQLConnection_cmd_statistics"></a>7.2.18. Method <code class="literal">MySQLConnection.cmd_statistics()</code></h3></div></div></div><p>
    1385. 

  1385.         Returns a dictionary containing information about the MySQL
    1386. 

  1386.         server including uptime in seconds and the number of running
    1387. 

  1387.         threads, questions, reloads, and open tables.
    1388. 

  1388.       </p></div><div class="section"><div class="titlepage"><div><div><h3 class="title"><a name="myconnpy_MySQLConnection_disconnect"></a>7.2.19. Method <code class="literal">MySQLConnection.disconnect()</code></h3></div></div></div><p>
    1389. 

  1389.         This method tries to send the <code class="literal">QUIT</code> command
    1390. 

  1390.         and close the socket. It does not raise any exceptions.
    1391. 

  1391.       </p><p>
    1392. 

  1392.         <code class="literal">MySQLConnection.close()</code> is a synonymous
    1393. 

  1393.         method name and more commonly used.
    1394. 

  1394.       </p></div><div class="section"><div class="titlepage"><div><div><h3 class="title"><a name="myconnpy_MySQLConnection_get_rows"></a>7.2.20. Method <code class="literal">MySQLConnection.get_rows(count=None)</code></h3></div></div></div><p>
    1395. 

  1395.         This method retrieves all or remaining rows of a query result
    1396. 

  1396.         set, returning a tuple containing the rows as sequence and the
    1397. 

  1397.         EOF packet information. The count argument can be used to get a
    1398. 

  1398.         given amount of rows. If count is not specified or is
    1399. 

  1399.         <code class="literal">None</code>, all rows are retrieved.
    1400. 

  1400.       </p><p>
    1401. 

  1401.         The tuple returned by <code class="literal">get_rows()</code> consists of:
    1402. 

  1402.       </p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
    1403. 

  1403.             A list of tuples containing the row data as byte objects, or
    1404. 

  1404.             an empty list when no rows are available.
    1405. 

  1405.           </p></li><li class="listitem"><p>
    1406. 

  1406.             EOF packet information as a dictionary containing
    1407. 

  1407.             <code class="literal">status_flag</code> and
    1408. 

  1408.             <code class="literal">warning_count</code>.
    1409. 

  1409.           </p></li></ul></div><p>
    1410. 

  1410.         An <code class="literal">InterfaceError</code> is raised when all rows
    1411. 

  1411.         have been retrieved.
    1412. 

  1412.       </p><p>
    1413. 

  1413.         The <code class="literal">get_rows()</code> method is used by
    1414. 

  1414.         <a class="link" href="#connector-python-apiref-MySQLCursor" title="7.3. Class cursor.MySQLCursor">MySQLCursor</a>
    1415. 

  1415.         to fetch rows.
    1416. 

  1416.       </p><p>
    1417. 

  1417.         Returns a tuple.
    1418. 

  1418.       </p></div><div class="section"><div class="titlepage"><div><div><h3 class="title"><a name="myconnpy_MySQLConnection_get_row"></a>7.2.21. Method <code class="literal">MySQLConnection.get_row()</code></h3></div></div></div><p>
    1419. 

  1419.         This method retrieves the next row of a query result set,
    1420. 

  1420.         returning a tuple.
    1421. 

  1421.       </p><p>
    1422. 

  1422.         The tuple returned by <code class="literal">get_row()</code> consists of:
    1423. 

  1423.       </p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
    1424. 

  1424.             The row as a tuple containing byte objects, or
    1425. 

  1425.             <code class="literal">None</code> when no more rows are available.
    1426. 

  1426.           </p></li><li class="listitem"><p>
    1427. 

  1427.             EOF packet information as a dictionary containing
    1428. 

  1428.             <code class="literal">status_flag</code> and
    1429. 

  1429.             <code class="literal">warning_count</code>, or <code class="literal">None</code>
    1430. 

  1430.             when the row returned is not the last row.
    1431. 

  1431.           </p></li></ul></div><p>
    1432. 

  1432.         The <code class="literal">get_row()</code> method is used by
    1433. 

  1433.         <a class="link" href="#connector-python-apiref-MySQLCursor" title="7.3. Class cursor.MySQLCursor">MySQLCursor</a>
    1434. 

  1434.         to fetch rows.
    1435. 

  1435.       </p></div><div class="section"><div class="titlepage"><div><div><h3 class="title"><a name="myconnpy_MySQLConnection_get_server_info"></a>7.2.22. Method <code class="literal">MySQLConnection.get_server_info()</code></h3></div></div></div><p>
    1436. 

  1436.         This method returns the MySQL server information verbatim, for
    1437. 

  1437.         example <code class="literal">'5.5.24-log'</code>, or
    1438. 

  1438.         <code class="literal">None</code> when not connected.
    1439. 

  1439.       </p><p>
    1440. 

  1440.         Returns a string or <code class="literal">None</code>.
    1441. 

  1441.       </p></div><div class="section"><div class="titlepage"><div><div><h3 class="title"><a name="myconnpy_MySQLConnection_get_server_version"></a>7.2.23. Method <code class="literal">MySQLConnection.get_server_version()</code></h3></div></div></div><p>
    1442. 

  1442.         This method returns the MySQL server version as a tuple, or
    1443. 

  1443.         <code class="literal">None</code> when not connected.
    1444. 

  1444.       </p><p>
    1445. 

  1445.         Returns a tuple or <code class="literal">None</code>.
    1446. 

  1446.       </p></div><div class="section"><div class="titlepage"><div><div><h3 class="title"><a name="myconnpy_MySQLConnection_is_connected"></a>7.2.24. Method <code class="literal">MySQLConnection.is_connected()</code></h3></div></div></div><p>
    1447. 

  1447.         Reports whether the connection to MySQL Server is available.
    1448. 

  1448.       </p><p>
    1449. 

  1449.         This method checks whether the connection to MySQL is available
    1450. 

  1450.         using the
    1451. 

  1451.         <a class="link" href="#myconnpy_MySQLConnection_ping" title="7.2.26. Method MySQLConnection.ping(attempts=1, delay=0)">ping()</a>
    1452. 

  1452.         method, but unlike <code class="literal">ping()</code>,
    1453. 

  1453.         <code class="literal">is_connected()</code> returns
    1454. 

  1454.         <code class="literal">True</code> when the connection is available,
    1455. 

  1455.         <code class="literal">False</code> otherwise.
    1456. 

  1456.       </p><p>
    1457. 

  1457.         Returns <code class="literal">True</code> or <code class="literal">False</code>.
    1458. 

  1458.       </p></div><div class="section"><div class="titlepage"><div><div><h3 class="title"><a name="myconnpy_MySQLConnection_isset_client_flag"></a>7.2.25. Method <code class="literal">MySQLConnection.isset_client_flag(flag)</code></h3></div></div></div><p>
    1459. 

  1459.         This method returns <code class="literal">True</code> if the client flag
    1460. 

  1460.         was set, <code class="literal">False</code> otherwise.
    1461. 

  1461.       </p><p>
    1462. 

  1462.         Returns <code class="literal">True</code> or <code class="literal">False</code>.
    1463. 

  1463.       </p></div><div class="section"><div class="titlepage"><div><div><h3 class="title"><a name="myconnpy_MySQLConnection_ping"></a>7.2.26. Method <code class="literal">MySQLConnection.ping(attempts=1, delay=0)</code></h3></div></div></div><p>
    1464. 

  1464.         Check whether the connection to the MySQL server is still
    1465. 

  1465.         available.
    1466. 

  1466.       </p><p>
    1467. 

  1467.         When <code class="literal">reconnect</code> is set to
    1468. 

  1468.         <code class="literal">True</code>, one or more attempts are made to try to
    1469. 

  1469.         reconnect to the MySQL server using the
    1470. 

  1470.         <code class="literal">reconnect()</code> method. Use the
    1471. 

  1471.         <code class="literal">delay</code> argument (seconds) if you want to wait
    1472. 

  1472.         between each retry.
    1473. 

  1473.       </p><p>
    1474. 

  1474.         When the connection is not available, an
    1475. 

  1475.         <code class="literal">InterfaceError</code> is raised. Use the
    1476. 

  1476.         <a class="link" href="#myconnpy_MySQLConnection_is_connected" title="7.2.24. Method MySQLConnection.is_connected()">is_connected()</a>
    1477. 

  1477.         method to check the connection without raising an error.
    1478. 

  1478.       </p><p>
    1479. 

  1479.         Raises <code class="literal">InterfaceError</code> on errors.
    1480. 

  1480.       </p></div><div class="section"><div class="titlepage"><div><div><h3 class="title"><a name="myconnpy_MySQLConnectoin_reconnect"></a>7.2.27. Method <code class="literal">MySQLConnection.reconnect(attempts=1, delay=0)</code></h3></div></div></div><p>
    1481. 

  1481.         Attempt to reconnect with the MySQL server.
    1482. 

  1482.       </p><p>
    1483. 

  1483.         The argument <code class="literal">attempts</code> specifies the number of
    1484. 

  1484.         times a reconnect is tried. The <code class="literal">delay</code>
    1485. 

  1485.         argument is the number of seconds to wait between each retry.
    1486. 

  1486.       </p><p>
    1487. 

  1487.         You might set the number of attempts higher and use a longer
    1488. 

  1488.         delay when you expect the MySQL server to be down for
    1489. 

  1489.         maintenance, or when you expect the network to be temporarily
    1490. 

  1490.         unavailable.
    1491. 

  1491.       </p></div><div class="section"><div class="titlepage"><div><div><h3 class="title"><a name="myconnpy_MySQLConnection_rollback"></a>7.2.28. Method <code class="literal">MySQLConnection.rollback()</code></h3></div></div></div><p>
    1492. 

  1492.         This method sends the <code class="literal">ROLLBACK</code> command to the
    1493. 

  1493.         MySQL server, undoing all data changes from the current
    1494. 

  1494.         <code class="literal">transaction</code>. Since by default,
    1495. 

  1495.         Connector/Python does not auto commit, it is possible to cancel
    1496. 

  1496.         transactions when using transactional storage engines such as
    1497. 

  1497.         <code class="literal">InnoDB</code>.
    1498. 

  1498.       </p><p>
    1499. 

  1499.         See the
    1500. 

  1500.         <a class="link" href="#myconnpy_MySQLConnection_commit" title="7.2.5. Method MySQLConnection.commit()">commit()</a>
    1501. 

  1501.         method for <a class="ulink" href="http://dev.mysql.com/doc/refman/5.5/en/glossary.html#glos_commit" target="_top">committing</a>
    1502. 

  1502.         transactions.
    1503. 

  1503.       </p><pre class="programlisting">
    1504. 

  1504. &gt;&gt;&gt; cursor.execute("INSERT INTO employees (first_name) VALUES (%s)", ('Jane'))
    1505. 

  1505. &gt;&gt;&gt; cnx.rollback()
    1506. 

  1506. </pre></div><div class="section"><div class="titlepage"><div><div><h3 class="title"><a name="myconnpy_MySQLConnection_set_charset_collation"></a>7.2.29. Method <code class="literal">MySQLConnection.set_charset_collation(charset=None,
    1507. 

  1507.         collation=None)</code></h3></div></div></div><p>
    1508. 

  1508.         This method sets the character set and collation to be used for
    1509. 

  1509.         the current connection. The <code class="literal">charset</code> argument
    1510. 

  1510.         can be either the name of a character set, or the numerical
    1511. 

  1511.         equivalent as defined in
    1512. 

  1512.         <code class="literal">constants.CharacterSet</code>.
    1513. 

  1513.       </p><p>
    1514. 

  1514.         When <code class="literal">collation</code> is <code class="literal">None</code>,
    1515. 

  1515.         the default will be looked up and used.
    1516. 

  1516.       </p><p>
    1517. 

  1517.         The <code class="literal">charset</code> argument then be either:
    1518. 

  1518.       </p><p>
    1519. 

  1519.         In the following example, we set the character set to
    1520. 

  1520.         <code class="literal">latin1</code> and the collation will be set to the
    1521. 

  1521.         default <code class="literal">latin1_swedish_ci</code>:
    1522. 

  1522.       </p><pre class="programlisting">
    1523. 

  1523. &gt;&gt;&gt; cnx = mysql.connector.connect(user='scott')
    1524. 

  1524. &gt;&gt;&gt; cnx.set_charset('latin1')
    1525. 

  1525. </pre><p>
    1526. 

  1526.         Specify a specific collation as follows:
    1527. 

  1527.       </p><pre class="programlisting">
    1528. 

  1528. &gt;&gt;&gt; cnx = mysql.connector.connect(user='scott')
    1529. 

  1529. &gt;&gt;&gt; cnx.set_charset('latin1', 'latin1_general_ci')
    1530. 

  1530. </pre></div><div class="section"><div class="titlepage"><div><div><h3 class="title"><a name="myconnpy_MySQLConnection_set_client_flags"></a>7.2.30. Method <code class="literal">MySQLConnection.set_client_flags(flags)</code></h3></div></div></div><p>
    1531. 

  1531.         This method sets the client flags which are used when connecting
    1532. 

  1532.         with the MySQL server and returns the new value. The
    1533. 

  1533.         <code class="literal">flags</code> argument can be either an integer or a
    1534. 

  1534.         sequence of valid client flag values (see
    1535. 

  1535.         <a class="xref" href="#connector-python-apiref-ClientFlag" title="7.5. Class constants.ClientFlag">Section 7.5, “Class <code class="literal">constants.ClientFlag</code>”</a>).
    1536. 

  1536.       </p><p>
    1537. 

  1537.         If <code class="literal">flags</code> is a sequence, each item in the
    1538. 

  1538.         sequence will set the flag when the value is positive or unset
    1539. 

  1539.         it when negative. For example, to unset
    1540. 

  1540.         <code class="literal">LONG_FLAG</code> and set the
    1541. 

  1541.         <code class="literal">FOUND_ROWS</code> flags:
    1542. 

  1542.       </p><pre class="programlisting">
    1543. 

  1543. &gt;&gt;&gt; from mysql.connector.constants import ClientFlag
    1544. 

  1544. &gt;&gt;&gt; cnx.set_client_flags([ClientFlag.FOUND_ROWS, -ClientFlag.LONG_FLAG])
    1545. 

  1545. &gt;&gt;&gt; cnx.reconnect()
    1546. 

  1546. </pre><p>
    1547. 

  1547.         Note that client flags are only set or used when connecting with
    1548. 

  1548.         the MySQL server. It is therefor necessary to reconnect after
    1549. 

  1549.         making changes.
    1550. 

  1550.       </p><p>
    1551. 

  1551.         Returns an integer.
    1552. 

  1552.       </p></div><div class="section"><div class="titlepage"><div><div><h3 class="title"><a name="myconnpy_MySQLConnection_autocommit"></a>7.2.31. Property <code class="literal">MySQLConnection.autocommit</code></h3></div></div></div><p>
    1553. 

  1553.         This property is used to toggle the auto commit feature of MySQL
    1554. 

  1554.         and retrieve the current state. When the value evaluates to
    1555. 

  1555.         True, auto commit will be turned, otherwise it is turned off.
    1556. 

  1556.       </p><p>
    1557. 

  1557.         Note that auto commit is disabled by default when connecting
    1558. 

  1558.         through Connector/Python. This can be toggled using the
    1559. 

  1559.         <a class="link" href="#connector-python-connectargs" title="Chapter 6. Connector/Python Connection Arguments">connection
    1560. 

  1560.         parameter</a> <code class="literal">autocommit</code>.
    1561. 

  1561.       </p><p>
    1562. 

  1562.         When the auto commit is turned off, you have to
    1563. 

  1563.         <a class="link" href="#myconnpy_MySQLConnection_commit" title="7.2.5. Method MySQLConnection.commit()">commit</a>
    1564. 

  1564.         transactions when using transactional storage engines such as
    1565. 

  1565.         InnoDB or NDBCluster.
    1566. 

  1566.       </p><pre class="programlisting">
    1567. 

  1567. &gt;&gt;&gt; cnx.autocommit
    1568. 

  1568. False
    1569. 

  1569. &gt;&gt;&gt; cnx.autocommit = True
    1570. 

  1570. &gt;&gt;&gt; cnx.autocommit
    1571. 

  1571. True
    1572. 

  1572. </pre><p>
    1573. 

  1573.         Returns True or False.
    1574. 

  1574.       </p></div><div class="section"><div class="titlepage"><div><div><h3 class="title"><a name="myconnpy_MySQLConnection_charset_name"></a>7.2.32. Property <code class="literal">MySQLConnection.charset_name</code></h3></div></div></div><p>
    1575. 

  1575.         This property returns which character set is used for the
    1576. 

  1576.         connection whether it is connected or not.
    1577. 

  1577.       </p><p>
    1578. 

  1578.         Returns a string.
    1579. 

  1579.       </p></div><div class="section"><div class="titlepage"><div><div><h3 class="title"><a name="myconnpy_MySQLConnection_collation_name"></a>7.2.33. Property <code class="literal">MySQLConnection.collation_name</code></h3></div></div></div><p>
    1580. 

  1580.         This property returns which collation is used for the connection
    1581. 

  1581.         whether it is connected or not.
    1582. 

  1582.       </p><p>
    1583. 

  1583.         Returns a string.
    1584. 

  1584.       </p></div><div class="section"><div class="titlepage"><div><div><h3 class="title"><a name="myconnpy_MySQLConnection_connection_id"></a>7.2.34. Property <code class="literal">MySQLConnection.connection_id</code></h3></div></div></div><p>
    1585. 

  1585.         This property returns the connection ID (thread ID or session
    1586. 

  1586.         ID) for the current connection or None when not connected.
    1587. 

  1587.       </p><p>
    1588. 

  1588.         Returns a integer or None.
    1589. 

  1589.       </p></div><div class="section"><div class="titlepage"><div><div><h3 class="title"><a name="myconnpy_MySQLConnection_database"></a>7.2.35. Property <code class="literal">MySQLConnection.database</code></h3></div></div></div><p>
    1590. 

  1590.         This property is used to set current (active) database executing
    1591. 

  1591.         the <code class="literal">USE</code> command. The property can also be
    1592. 

  1592.         used to retrieve the current database name.
    1593. 

  1593.       </p><pre class="programlisting">
    1594. 

  1594. &gt;&gt;&gt; cnx.database = 'test'
    1595. 

  1595. &gt;&gt;&gt; cnx.database = 'mysql'
    1596. 

  1596. &gt;&gt;&gt; cnx.database
    1597. 

  1597. u'mysql'
    1598. 

  1598. </pre><p>
    1599. 

  1599.         Returns a string.
    1600. 

  1600.       </p></div><div class="section"><div class="titlepage"><div><div><h3 class="title"><a name="myconnpy_MySQLConnection_get_warnings"></a>7.2.36. Property <code class="literal">MySQLConnection.get_warnings</code></h3></div></div></div><p>
    1601. 

  1601.         This property is used to toggle whether warnings should be
    1602. 

  1602.         fetched automatically or not. It accepts True or False
    1603. 

  1603.         (default).
    1604. 

  1604.       </p><p>
    1605. 

  1605.         Fetching warnings automatically could be useful when debugging
    1606. 

  1606.         queries. Cursors will make warnings available through the method
    1607. 

  1607.         <a class="link" href="#myconnpy_MySQLCursor_fetchwarnings" title="7.3.9. Method MySQLCursor.fetchwarnings()">MySQLCursor.fetchwarnings()</a>.
    1608. 

  1608.       </p><pre class="programlisting">
    1609. 

  1609. &gt;&gt;&gt; cnx.get_warnings = True
    1610. 

  1610. &gt;&gt;&gt; cursor.execute('SELECT "a"+1')
    1611. 

  1611. &gt;&gt;&gt; cursor.fetchall()
    1612. 

  1612. [(1.0,)]
    1613. 

  1613. &gt;&gt;&gt; cursor.fetchwarnings()
    1614. 

  1614. [(u'Warning', 1292, u"Truncated incorrect DOUBLE value: 'a'")]
    1615. 

  1615. </pre><p>
    1616. 

  1616.         Returns True or False.
    1617. 

  1617.       </p></div><div class="section"><div class="titlepage"><div><div><h3 class="title"><a name="myconnpy_MySQLConnection_raise_on_warnings"></a>7.2.37. Property <code class="literal">MySQLConnection.raise_on_warnings</code></h3></div></div></div><p>
    1618. 

  1618.         This property is used to toggle whether warnings should raise
    1619. 

  1619.         exceptions or not. It accepts True or False (default).
    1620. 

  1620.       </p><p>
    1621. 

  1621.         Toggling <code class="literal">raise_on_warnings</code> will also toggle
    1622. 

  1622.         <code class="literal">get_warnings</code> since warnings need to be
    1623. 

  1623.         fetched so they can be raised as exceptions.
    1624. 

  1624.       </p><p>
    1625. 

  1625.         Note that you might always want to check setting SQL Mode if you
    1626. 

  1626.         would like to have the MySQL server directly report warnings as
    1627. 

  1627.         errors. It is also good to use transactional engines so
    1628. 

  1628.         transactions can be rolled back when catching the exception.
    1629. 

  1629.       </p><p>
    1630. 

  1630.         Result sets needs to be fetched completely before any exception
    1631. 

  1631.         can be raised. The following example shows the execution of a
    1632. 

  1632.         query which produces a warning
    1633. 

  1633.       </p><pre class="programlisting">
    1634. 

  1634. &gt;&gt;&gt; cnx.raise_on_warnings = True
    1635. 

  1635. &gt;&gt;&gt; cursor.execute('SELECT "a"+1')
    1636. 

  1636. &gt;&gt;&gt; cursor.fetchall()
    1637. 

  1637. ..
    1638. 

  1638. mysql.connector.errors.DataError: 1292: Truncated incorrect DOUBLE value: 'a'
    1639. 

  1639. </pre><p>
    1640. 

  1640.         Returns True or False.
    1641. 

  1641.       </p></div><div class="section"><div class="titlepage"><div><div><h3 class="title"><a name="myconnpy_MySQLConnection_server_host"></a>7.2.38. Property <code class="literal">MySQLConnection.server_host</code></h3></div></div></div><p>
    1642. 

  1642.         This read-only property returns the hostname or IP address used
    1643. 

  1643.         for connecting with the MySQL server.
    1644. 

  1644.       </p><p>
    1645. 

  1645.         Returns a string.
    1646. 

  1646.       </p></div><div class="section"><div class="titlepage"><div><div><h3 class="title"><a name="myconnpy_MySQLConnection_server_port"></a>7.2.39. Property <code class="literal">MySQLConnection.server_port</code></h3></div></div></div><p>
    1647. 

  1647.         This read-only property returns the TCP/IP port used for
    1648. 

  1648.         connecting with the MySQL server.
    1649. 

  1649.       </p><p>
    1650. 

  1650.         Returns a integer.
    1651. 

  1651.       </p></div><div class="section"><div class="titlepage"><div><div><h3 class="title"><a name="myconnpy_MySQLConnection_sql_mode"></a>7.2.40. Property <code class="literal">MySQLConnection.sql_mode</code></h3></div></div></div><p>
    1652. 

  1652.         This property is used to retrieve and set the SQL Modes for the
    1653. 

  1653.         current. The value should be list of different modes separated
    1654. 

  1654.         by comma (","), or a sequence of modes, preferably using the
    1655. 

  1655.         constants.SQLMode class.
    1656. 

  1656.       </p><p>
    1657. 

  1657.         To unset all modes, pass an empty string or an empty sequence.
    1658. 

  1658.       </p><pre class="programlisting">
    1659. 

  1659. &gt;&gt;&gt; cnx.sql_mode = 'TRADITIONAL,NO_ENGINE_SUBSTITUTION'
    1660. 

  1660. &gt;&gt;&gt; cnx.sql_mode.split(',')
    1661. 

  1661. [u'STRICT_TRANS_TABLES', u'STRICT_ALL_TABLES', u'NO_ZERO_IN_DATE',
    1662. 

  1662. u'NO_ZERO_DATE', u'ERROR_FOR_DIVISION_BY_ZERO', u'TRADITIONAL', 
    1663. 

  1663. u'NO_AUTO_CREATE_USER', u'NO_ENGINE_SUBSTITUTION']
    1664. 

  1664. &gt;&gt;&gt; from mysql.connector.constants import SQLMode
    1665. 

  1665. &gt;&gt;&gt; cnx.sql_mode = [ SQLMode.NO_ZERO_DATE, SQLMode.REAL_AS_FLOAT]
    1666. 

  1666. &gt;&gt;&gt; cnx.sql_mode
    1667. 

  1667. 

  1668. u'REAL_AS_FLOAT,NO_ZERO_DATE'</pre><p>
    1669. 

  1669.         Returns a string.
    1670. 

  1670.       </p></div><div class="section"><div class="titlepage"><div><div><h3 class="title"><a name="myconnpy_MySQLConnection_time_zone"></a>7.2.41. Property <code class="literal">MySQLConnection.time_zone</code></h3></div></div></div><p>
    1671. 

  1671.         This property is used to set the time zone session variable for
    1672. 

  1672.         the current connection and retrieve it.
    1673. 

  1673.       </p><pre class="programlisting">
    1674. 

  1674. &gt;&gt;&gt; cnx.time_zone = '+00:00'
    1675. 

  1675. &gt;&gt;&gt; cur.execute('SELECT NOW()') ; cur.fetchone()
    1676. 

  1676. (datetime.datetime(2012, 6, 15, 11, 24, 36),)
    1677. 

  1677. &gt;&gt;&gt; cnx.time_zone = '-09:00'
    1678. 

  1678. &gt;&gt;&gt; cur.execute('SELECT NOW()') ; cur.fetchone()
    1679. 

  1679. (datetime.datetime(2012, 6, 15, 2, 24, 44),)
    1680. 

  1680. &gt;&gt;&gt; cnx.time_zone
    1681. 

  1681. u'-09:00'
    1682. 

  1682. </pre><p>
    1683. 

  1683.         Returns a string.
    1684. 

  1684.       </p></div><div class="section"><div class="titlepage"><div><div><h3 class="title"><a name="myconnpy_MySQLConnection_unix_socket"></a>7.2.42. Property <code class="literal">MySQLConnection.unix_socket</code></h3></div></div></div><p>
    1685. 

  1685.         This read-only property returns the UNIX socket user for
    1686. 

  1686.         connecting with the MySQL server.
    1687. 

  1687.       </p><p>
    1688. 

  1688.         Returns a string.
    1689. 

  1689.       </p></div><div class="section"><div class="titlepage"><div><div><h3 class="title"><a name="myconnpy_MySQLConnection_user"></a>7.2.43. Property <code class="literal">MySQLConnection.user</code></h3></div></div></div><p>
    1690. 

  1690.         This read-only property returns the username used for connecting
    1691. 

  1691.         with the MySQL server.
    1692. 

  1692.       </p><p>
    1693. 

  1693.         Returns a string.
    1694. 

  1694.       </p></div></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="connector-python-apiref-MySQLCursor"></a>7.3. Class <code class="literal">cursor.MySQLCursor</code></h2></div></div></div><div class="toc"><dl><dt><span class="section"><a href="#myconnpy_MySQLCursor">7.3.1. Constructor <code class="literal">cursor.MySQLCursor</code></a></span></dt><dt><span class="section"><a href="#myconnpy_MySQLCursor_callproc">7.3.2. Method <code class="literal">MySQLCursor.callproc(procname, args=())</code></a></span></dt><dt><span class="section"><a href="#myconnpy_MySQLCursor_close">7.3.3. Method <code class="literal">MySQLCursor.close()</code></a></span></dt><dt><span class="section"><a href="#myconnpy_MySQLCursor_execute">7.3.4. Method <code class="literal">MySQLCursor.execute(operation, params=None,
    1695. 

  1695.         multi=False)</code></a></span></dt><dt><span class="section"><a href="#myconnpy_MySQLCursor_executemany">7.3.5. Method <code class="literal">MySQLCursor.executemany(operation, seq_params)</code></a></span></dt><dt><span class="section"><a href="#myconnpy_MySQLCursor_fetchall">7.3.6. Method <code class="literal">MySQLCursor.fetchall()</code></a></span></dt><dt><span class="section"><a href="#myconnpy_MySQLCursor_fetchmany">7.3.7. Method <code class="literal">MySQLCursor.fetchmany(size=1)</code></a></span></dt><dt><span class="section"><a href="#myconnpy_MySQLCursor_fetchone">7.3.8. Method <code class="literal">MySQLCursor.fetchone()</code></a></span></dt><dt><span class="section"><a href="#myconnpy_MySQLCursor_fetchwarnings">7.3.9. Method <code class="literal">MySQLCursor.fetchwarnings()</code></a></span></dt><dt><span class="section"><a href="#myconnpy_MySQLCursor_stored_results">7.3.10. Method <code class="literal">MySQLCursor.stored_results()</code></a></span></dt><dt><span class="section"><a href="#myconnpy_MySQLCursor_column_names">7.3.11. Property <code class="literal">MySQLCursor.column_names</code></a></span></dt><dt><span class="section"><a href="#myconnpy_MySQLCursor_statement">7.3.12. Property <code class="literal">MySQLCursor.statement</code></a></span></dt><dt><span class="section"><a href="#myconnpy_MySQLCursor_with_rows">7.3.13. Property <code class="literal">MySQLCursor.with_rows</code></a></span></dt></dl></div><p>
    1696. 

  1696.       The MySQLCursor class is used to instantiate object which can
    1697. 

  1697.       execute operation such as SQL queries. They interact with the
    1698. 

  1698.       MySQL server using a MySQLConnection object.
    1699. 

  1699.     </p><div class="section"><div class="titlepage"><div><div><h3 class="title"><a name="myconnpy_MySQLCursor"></a>7.3.1. Constructor <code class="literal">cursor.MySQLCursor</code></h3></div></div></div><p>
    1700. 

  1700.         The constructor initializes the instance with the optional
    1701. 

  1701.         <code class="literal">connection</code>, which should be an instance of
    1702. 

  1702.         <a class="link" href="#connector-python-apiref-MySQLConnection" title="7.2. Class connection.MySQLConnection">MySQLConnection</a>.
    1703. 

  1703.       </p><p>
    1704. 

  1704.         In most cases, the MySQLConnection method
    1705. 

  1705.         <a class="link" href="#myconnpy_MySQLConnection_cursor" title="7.2.6. Method MySQLConnection.cursor(buffered=None, raw=None, cursor_class=None)"><code class="literal">cursor()</code></a>
    1706. 

  1706.         is used to instantiate a MySQLCursor object.
    1707. 

  1707.       </p></div><div class="section"><div class="titlepage"><div><div><h3 class="title"><a name="myconnpy_MySQLCursor_callproc"></a>7.3.2. Method <code class="literal">MySQLCursor.callproc(procname, args=())</code></h3></div></div></div><p>
    1708. 

  1708.         This method calls a stored procedure with the given name. The
    1709. 

  1709.         <code class="literal">args</code> sequence of parameters must contain one
    1710. 

  1710.         entry for each argument that the routine expects. The result is
    1711. 

  1711.         returned as modified copy of the input sequence. Input
    1712. 

  1712.         parameters are left untouched, output and input/output
    1713. 

  1713.         parameters replaced with possibly new values.
    1714. 

  1714.       </p><p>
    1715. 

  1715.         Result set provided by the stored procedure are automatically
    1716. 

  1716.         fetched and stored as
    1717. 

  1717.         <a class="link" href="#connector-python-apiref-MySQLCursorBuffered" title="7.4. Class cursor.MySQLCursorBuffered">MySQLBufferedCursor</a>
    1718. 

  1718.         instances. See
    1719. 

  1719.         <a class="link" href="#myconnpy_MySQLCursor_stored_results" title="7.3.10. Method MySQLCursor.stored_results()">stored_results()</a>
    1720. 

  1720.         for more information.
    1721. 

  1721.       </p><p>
    1722. 

  1722.         The following example shows how to execute a stored procedure
    1723. 

  1723.         which takes two parameters, multiplies the values and returns
    1724. 

  1724.         the product:
    1725. 

  1725.       </p><pre class="programlisting">
    1726. 

  1726. # Definition of the multiply stored procedure:
    1727. 

  1727. # CREATE PROCEDURE multiply(IN pFac1 INT, IN pFac2 INT, OUT pProd INT)
    1728. 

  1728. # BEGIN
    1729. 

  1729. #  SET pProd := pFac1 * pFac2;
    1730. 

  1730. # END
    1731. 

  1731. &gt;&gt;&gt; args = (5, 5, 0) # 0 is to hold value of the OUT parameter pProd
    1732. 

  1732. &gt;&gt;&gt; cursor.callproc('multiply', args)
    1733. 

  1733. ('5', '5', 25L)
    1734. 

  1734. </pre></div><div class="section"><div class="titlepage"><div><div><h3 class="title"><a name="myconnpy_MySQLCursor_close"></a>7.3.3. Method <code class="literal">MySQLCursor.close()</code></h3></div></div></div><p>
    1735. 

  1735.         This method will close the MySQL cursor, resetting all results
    1736. 

  1736.         and removing the connection.
    1737. 

  1737.       </p><p>
    1738. 

  1738.         Use <code class="literal">close()</code> every time you are done using the
    1739. 

  1739.         cursor.
    1740. 

  1740.       </p></div><div class="section"><div class="titlepage"><div><div><h3 class="title"><a name="myconnpy_MySQLCursor_execute"></a>7.3.4. Method <code class="literal">MySQLCursor.execute(operation, params=None,
    1741. 

  1741.         multi=False)</code></h3></div></div></div><p>
    1742. 

  1742.         This method prepare the given database
    1743. 

  1743.         <code class="literal">operation</code> (query or command). The parameters
    1744. 

  1744.         found in the tuple or dictionary <code class="literal">params</code> will
    1745. 

  1745.         be bound to the variables in the operation. Variables are
    1746. 

  1746.         specified using %s markers or named markers %(name)s.
    1747. 

  1747.       </p><p>
    1748. 

  1748.         For example, insert information about a new employee and
    1749. 

  1749.         selecting again the data of this person:
    1750. 

  1750.       </p><pre class="programlisting">insert = (
    1751. 

  1751. "INSERT INTO employees (emp_no, first_name, last_name, hire_date) "
    1752. 

  1752. "VALUES (%s, %s, %s, %s)")
    1753. 

  1753. data = (2, 'Jane', 'Doe', datetime.date(2012, 3, 23))
    1754. 

  1754. cursor.execute(insert, data)
    1755. 

  1755. select = "SELECT * FROM employees WHERE emp_no = %(emp_no)s"
    1756. 

  1756. cursor.execute(select, { 'emp_no': 2 })</pre><p>
    1757. 

  1757.         Note that the data is converted from Python object to something
    1758. 

  1758.         MySQL understand. In the above example, the datetime.date()
    1759. 

  1759.         instance is converted to '2012-03-23' in the above example.
    1760. 

  1760.       </p><p>
    1761. 

  1761.         When <code class="literal">multi</code> is set to True,
    1762. 

  1762.         <code class="literal">execute()</code> will be able to execute multiple
    1763. 

  1763.         statements. It will return an iterator which makes it possible
    1764. 

  1764.         to go through all results for each statement. Note that using
    1765. 

  1765.         parameters is not working well in this case, and it's usually a
    1766. 

  1766.         good idea to execute each statement on its own.
    1767. 

  1767.       </p><p>
    1768. 

  1768.         In the following example we select and insert data in one
    1769. 

  1769.         operation and display the result:
    1770. 

  1770.       </p><pre class="programlisting">operation = 'SELECT 1; INSERT INTO t1 VALUES (); SELECT 2'
    1771. 

  1771. for result in cursor.execute(operation):
    1772. 

  1772.   if result.with_rows:
    1773. 

  1773.     print("Statement '{}' has following rows:".format(
    1774. 

  1774.       result.statement))
    1775. 

  1775.     print(result.fetchall())
    1776. 

  1776.   else:
    1777. 

  1777.     print("Affected row(s) by query '{}' was {}".format(
    1778. 

  1778.       result.statement, result.rowcount))</pre><p>
    1779. 

  1779.         If the connection was configured to fetch warnings, warnings
    1780. 

  1780.         generated by the operation will be available through the method
    1781. 

  1781.         <a class="link" href="#myconnpy_MySQLCursor_fetchwarnings" title="7.3.9. Method MySQLCursor.fetchwarnings()">MySQLCursor.fetchwarnings()</a>.
    1782. 

  1782.       </p><p>
    1783. 

  1783.         Returns an iterator when multi is True.
    1784. 

  1784.       </p></div><div class="section"><div class="titlepage"><div><div><h3 class="title"><a name="myconnpy_MySQLCursor_executemany"></a>7.3.5. Method <code class="literal">MySQLCursor.executemany(operation, seq_params)</code></h3></div></div></div><p>
    1785. 

  1785.         This method prepares a database operation (query or command) and
    1786. 

  1786.         then execute it against all parameter sequences or mappings
    1787. 

  1787.         found in the sequence <code class="literal">seq_of_params</code>.
    1788. 

  1788.       </p><p>
    1789. 

  1789.         The <code class="literal">executemany()</code> is simply iterating through
    1790. 

  1790.         the sequence of parameters calling the
    1791. 

  1791.         <code class="literal">execute()</code> method. Inserting data, however, is
    1792. 

  1792.         optimized by batching them using the multiple rows syntax.
    1793. 

  1793.       </p><p>
    1794. 

  1794.         In the following example we are inserting 3 records:
    1795. 

  1795.       </p><pre class="programlisting">data = [
    1796. 

  1796.   ('Jane', date(2005, 2, 12)),
    1797. 

  1797.   ('Joe', date(2006, 5, 23)),
    1798. 

  1798.   ('John', date(2010, 10, 3)),
    1799. 

  1799. ]
    1800. 

  1800. stmt = "INSERT INTO employees (first_name, hire_date) VALUES (%s, %s)"
    1801. 

  1801. cursor.executemany(stmt, data)</pre><p>
    1802. 

  1802.         In the above example, the INSERT statement sent to MySQL would
    1803. 

  1803.         be as follows: <code class="literal">INSERT INTO employees (first_name,
    1804. 

  1804.         hire_date) VALUES ('Jane', '2005-02-12'), ('Joe', '2006-05-23'),
    1805. 

  1805.         ('John', '2010-10-03')</code>.
    1806. 

  1806.       </p><p>
    1807. 

  1807.         Note that it is not possible to execute multiple statements
    1808. 

  1808.         using the <code class="literal">executemany()</code> method. Doing so will
    1809. 

  1809.         raise an <code class="literal">InternalError</code> exception.
    1810. 

  1810.       </p></div><div class="section"><div class="titlepage"><div><div><h3 class="title"><a name="myconnpy_MySQLCursor_fetchall"></a>7.3.6. Method <code class="literal">MySQLCursor.fetchall()</code></h3></div></div></div><p>
    1811. 

  1811.         The method fetches all or remaining rows of a query result set,
    1812. 

  1812.         returning a list of tuples. An empty list is returned when no
    1813. 

  1813.         rows are (anymore) available.
    1814. 

  1814.       </p><p>
    1815. 

  1815.         The following examples shows how to retrieve the first 2 rows of
    1816. 

  1816.         a result set, and then retrieve the remaining rows:
    1817. 

  1817.       </p><pre class="programlisting">
    1818. 

  1818. &gt;&gt;&gt; cursor.execute("SELECT * FROM employees ORDER BY emp_no")
    1819. 

  1819. &gt;&gt;&gt; head_rows = cursor.fetchmany(size=2)
    1820. 

  1820. &gt;&gt;&gt; remaining_rows = cursor.fetchall()
    1821. 

  1821. </pre><p>
    1822. 

  1822.         Note that you have to fetch all rows before being able to
    1823. 

  1823.         execute new queries using the same connection.
    1824. 

  1824.       </p><p>
    1825. 

  1825.         Returns a list of tuples or empty list when no rows available.
    1826. 

  1826.       </p></div><div class="section"><div class="titlepage"><div><div><h3 class="title"><a name="myconnpy_MySQLCursor_fetchmany"></a>7.3.7. Method <code class="literal">MySQLCursor.fetchmany(size=1)</code></h3></div></div></div><p>
    1827. 

  1827.         This method fetches the next set of rows of a query results,
    1828. 

  1828.         returning a list of tuples. An empty list is returned when no
    1829. 

  1829.         more rows are available.
    1830. 

  1830.       </p><p>
    1831. 

  1831.         The number of rows returned can be specified using the size
    1832. 

  1832.         argument, which defaults to one. Fewer rows might be returned,
    1833. 

  1833.         when there are not more rows available than specified by the
    1834. 

  1834.         argument.
    1835. 

  1835.       </p><p>
    1836. 

  1836.         Note that you have to fetch all rows before being able to
    1837. 

  1837.         execute new queries using the same connection.
    1838. 

  1838.       </p><p>
    1839. 

  1839.         Returns a list of tuples or empty list when no rows available.
    1840. 

  1840.       </p></div><div class="section"><div class="titlepage"><div><div><h3 class="title"><a name="myconnpy_MySQLCursor_fetchone"></a>7.3.8. Method <code class="literal">MySQLCursor.fetchone()</code></h3></div></div></div><p>
    1841. 

  1841.         This method retrieves the next row of a query result set,
    1842. 

  1842.         returning a single sequence, or None when no more data is
    1843. 

  1843.         available.The returned tuple consists of data returned by the
    1844. 

  1844.         MySQL server converted to Python objects.
    1845. 

  1845.       </p><p>
    1846. 

  1846.         The <code class="literal">fetchone()</code> method is used by
    1847. 

  1847.         <a class="link" href="#myconnpy_MySQLCursor_fetchmany" title="7.3.7. Method MySQLCursor.fetchmany(size=1)">fetchmany()</a>
    1848. 

  1848.         and
    1849. 

  1849.         <a class="link" href="#myconnpy_MySQLCursor_fetchall" title="7.3.6. Method MySQLCursor.fetchall()">fetchall()</a>.
    1850. 

  1850.         It is also used when using the MySQLCursor instance as an
    1851. 

  1851.         iterator.
    1852. 

  1852.       </p><p>
    1853. 

  1853.         The following examples show how to iterate through the result of
    1854. 

  1854.         a query using <code class="literal">fetchone()</code>:
    1855. 

  1855.       </p><pre class="programlisting"># Using a while-loop
    1856. 

  1856. cursor.execute("SELECT * FROM employees")
    1857. 

  1857. row = cursor.fetchone()
    1858. 

  1858. while row is not None:
    1859. 

  1859.   print(row)
    1860. 

  1860.   row = cursor.fetchone()
    1861. 

  1861. # Using the cursor as iterator 
    1862. 

  1862. cursor.execute("SELECT * FROM employees")
    1863. 

  1863. for row in cursor:
    1864. 

  1864.   print(row)</pre><p>
    1865. 

  1865.         Note that you have to fetch all rows before being able to
    1866. 

  1866.         execute new queries using the same connection.
    1867. 

  1867.       </p><p>
    1868. 

  1868.         Returns a tuple or None.
    1869. 

  1869.       </p></div><div class="section"><div class="titlepage"><div><div><h3 class="title"><a name="myconnpy_MySQLCursor_fetchwarnings"></a>7.3.9. Method <code class="literal">MySQLCursor.fetchwarnings()</code></h3></div></div></div><p>
    1870. 

  1870.         This method returns a list of tuples containing warnings
    1871. 

  1871.         generated by previously executed statement. Use the connection's
    1872. 

  1872.         <code class="literal">get_warnings</code> property to toggle whether
    1873. 

  1873.         warnings has to be fetched.
    1874. 

  1874.       </p><p>
    1875. 

  1875.         The following example shows a SELECT statement which generated a
    1876. 

  1876.         warning:
    1877. 

  1877.       </p><pre class="programlisting">
    1878. 

  1878. &gt;&gt;&gt; cnx.get_warnings = True
    1879. 

  1879. &gt;&gt;&gt; cursor.execute('SELECT "a"+1')
    1880. 

  1880. &gt;&gt;&gt; cursor.fetchall()
    1881. 

  1881. [(1.0,)]
    1882. 

  1882. &gt;&gt;&gt; cursor.fetchwarnings()
    1883. 

  1883. [(u'Warning', 1292, u"Truncated incorrect DOUBLE value: 'a'")]
    1884. 

  1884. </pre><p>
    1885. 

  1885.         It is also possible to raise errors when warnings are found. See
    1886. 

  1886.         the MySQLConnection property
    1887. 

  1887.         <a class="link" href="#myconnpy_MySQLConnection_raise_on_warnings" title="7.2.37. Property MySQLConnection.raise_on_warnings">raise_on_warnings</a>.
    1888. 

  1888.       </p><p>
    1889. 

  1889.         Returns a list of tuples.
    1890. 

  1890.       </p></div><div class="section"><div class="titlepage"><div><div><h3 class="title"><a name="myconnpy_MySQLCursor_stored_results"></a>7.3.10. Method <code class="literal">MySQLCursor.stored_results()</code></h3></div></div></div><p>
    1891. 

  1891.         This method returns an list iterator object which can be used to
    1892. 

  1892.         go through result sets provided by stored procedures after
    1893. 

  1893.         calling them using the
    1894. 

  1894.         <a class="link" href="#myconnpy_MySQLCursor_callproc" title="7.3.2. Method MySQLCursor.callproc(procname, args=())">callproc()</a>
    1895. 

  1895.         method.
    1896. 

  1896.       </p><p>
    1897. 

  1897.         In the following example we execute a stored procedure which
    1898. 

  1898.         will provide two result sets. We use
    1899. 

  1899.         <code class="literal">stored_results()</code> to retrieve them:
    1900. 

  1900.       </p><pre class="programlisting">
    1901. 

  1901. &gt;&gt;&gt; cursor.callproc('sp1')
    1902. 

  1902. ()
    1903. 

  1903. &gt;&gt;&gt; for result in cursor.stored_results():
    1904. 

  1904. ...     print result.fetchall()
    1905. 

  1905. ... 
    1906. 

  1906. [(1,)]
    1907. 

  1907. [(2,)]
    1908. 

  1908. </pre><p>
    1909. 

  1909.         Note that the result sets stay available until you executed
    1910. 

  1910.         another operation or call another stored procedure.
    1911. 

  1911.       </p><p>
    1912. 

  1912.         Returns a listiterator.
    1913. 

  1913.       </p></div><div class="section"><div class="titlepage"><div><div><h3 class="title"><a name="myconnpy_MySQLCursor_column_names"></a>7.3.11. Property <code class="literal">MySQLCursor.column_names</code></h3></div></div></div><p>
    1914. 

  1914.         This read-only property returns the column names of a result set
    1915. 

  1915.         as sequence of (unicode) strings.
    1916. 

  1916.       </p><p>
    1917. 

  1917.         The following example shows how you can create a dictionary out
    1918. 

  1918.         of a tuple containing data with keys using
    1919. 

  1919.         <code class="literal">column_names</code>:
    1920. 

  1920.       </p><pre class="programlisting">cursor.execute("SELECT last_name, first_name, hire_date "
    1921. 

  1921.   "FROM employees WHERE emp_no = %s", (123,))
    1922. 

  1922. row = dict(zip(cursor.column_names, cursor.fetchone())
    1923. 

  1923. print("{last_name}, {first_name}: {hire_date}".format(row))</pre><p>
    1924. 

  1924.         Returns a tuple.
    1925. 

  1925.       </p></div><div class="section"><div class="titlepage"><div><div><h3 class="title"><a name="myconnpy_MySQLCursor_statement"></a>7.3.12. Property <code class="literal">MySQLCursor.statement</code></h3></div></div></div><p>
    1926. 

  1926.         This read-only property returns the last executed statement. In
    1927. 

  1927.         case multiple statements where executed, it will show the actual
    1928. 

  1928.         statement.
    1929. 

  1929.       </p><p>
    1930. 

  1930.         The <code class="literal">statement</code> property might be useful for
    1931. 

  1931.         debugging and showing what was send to the MySQL server.
    1932. 

  1932.       </p><p>
    1933. 

  1933.         Returns a string.
    1934. 

  1934.       </p></div><div class="section"><div class="titlepage"><div><div><h3 class="title"><a name="myconnpy_MySQLCursor_with_rows"></a>7.3.13. Property <code class="literal">MySQLCursor.with_rows</code></h3></div></div></div><p>
    1935. 

  1935.         This read-only property will return True when the result of the
    1936. 

  1936.         executed operation provides rows.
    1937. 

  1937.       </p><p>
    1938. 

  1938.         The <code class="literal">with_rows</code> property is useful when
    1939. 

  1939.         executing multiple statements and you need to fetch rows. In the
    1940. 

  1940.         following example we only report the affected rows by the
    1941. 

  1941.         <code class="literal">UPDATE</code> statement:
    1942. 

  1942.       </p><pre class="programlisting">import mysql.connector
    1943. 

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

  1944. cursor = cnx.cursor()
    1945. 

  1945. operation = 'SELECT 1; UPDATE t1 SET c1 = 2; SELECT 2'
    1946. 

  1946. for result in cursor.execute(operation, multi=True):
    1947. 

  1947.   if result.with_rows:
    1948. 

  1948.     result.fetchall()
    1949. 

  1949.   else:
    1950. 

  1950.     print("Updated row(s): {}".format(result.rowcount))</pre></div></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="connector-python-apiref-MySQLCursorBuffered"></a>7.4. Class <code class="literal">cursor.MySQLCursorBuffered</code></h2></div></div></div><p>
    1951. 

  1951.       This class is inheriting from cursor.MySQLCursor and if needed
    1952. 

  1952.       automatically retrieves rows after an operation has been executed.
    1953. 

  1953.     </p><p>
    1954. 

  1954.       MySQLCursorBuffered can be useful in situations where two queries,
    1955. 

  1955.       with small result sets, need to be combined or computed with each
    1956. 

  1956.       other.
    1957. 

  1957.     </p><p>
    1958. 

  1958.       You can either use the <code class="literal">buffered</code> argument when
    1959. 

  1959.       using the connection's
    1960. 

  1960.       <a class="link" href="#myconnpy_MySQLConnection_cursor" title="7.2.6. Method MySQLConnection.cursor(buffered=None, raw=None, cursor_class=None)">
    1961. 

  1961.       <code class="literal">cursor()</code></a> method, or you can use the
    1962. 

  1962.       <code class="literal">buffered</code>
    1963. 

  1963.       <a class="link" href="#connector-python-connectargs" title="Chapter 6. Connector/Python Connection Arguments">connection
    1964. 

  1964.       option</a> to make all created cursors by default buffering.
    1965. 

  1965.     </p><pre class="programlisting">import mysql.connector
    1966. 

  1966. cnx = mysql.connector.connect()
    1967. 

  1967. # Only this particular cursor will be buffering results
    1968. 

  1968. cursor.cursor(buffered=True)
    1969. 

  1969. # All cursors by default buffering
    1970. 

  1970. cnx = mysql.connector.connect(buffered=True)</pre><p>
    1971. 

  1971.       See <a class="xref" href="#myconnpy_tutorial_CursorBuffered_GiveRaise" title="5.1. Tutorial: Raise employee's salary using a buffering cursor">Section 5.1, “Tutorial: Raise employee's salary using a buffering cursor”</a>
    1972. 

  1972.       for a practical use case.
    1973. 

  1973.     </p></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="connector-python-apiref-ClientFlag"></a>7.5. Class <code class="literal">constants.ClientFlag</code></h2></div></div></div><p>
    1974. 

  1974.       This class provides constants defining MySQL client flags which
    1975. 

  1975.       can be used upon connection to configure the session. The
    1976. 

  1976.       ClientFlag class is available when importing mysql.connector.
    1977. 

  1977.     </p><pre class="programlisting">
    1978. 

  1978. &gt;&gt;&gt; import mysql.connector
    1979. 

  1979. &gt;&gt;&gt; mysql.connector.ClientFlag.FOUND_ROWS
    1980. 

  1980. 2
    1981. 

  1981. </pre><p>
    1982. 

  1982.       See <a class="xref" href="#myconnpy_MySQLConnection_set_client_flags" title="7.2.30. Method MySQLConnection.set_client_flags(flags)">Section 7.2.30, “Method <code class="literal">MySQLConnection.set_client_flags(flags)</code>”</a>
    1983. 

  1983.       and the <a class="link" href="#connector-python-connectargs" title="Chapter 6. Connector/Python Connection Arguments">connection
    1984. 

  1984.       argument</a> <code class="literal">client_flag</code>.
    1985. 

  1985.     </p><p>
    1986. 

  1986.       Note that the ClientFlag class can not be instantiated.
    1987. 

  1987.     </p></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="connector-python-apiref-FieldType"></a>7.6. Class <code class="literal">constants.FieldType</code></h2></div></div></div><p>
    1988. 

  1988.       This class provides all supported MySQL field or data types. They
    1989. 

  1989.       can be useful when dealing with raw data or defining your own
    1990. 

  1990.       converters. The field type is stored with every cursor in the
    1991. 

  1991.       description for each column.
    1992. 

  1992.     </p><p>
    1993. 

  1993.       The following example shows how you can print the name of the data
    1994. 

  1994.       types for each of the columns in the result set.
    1995. 

  1995.     </p><pre class="programlisting">from __future__ import print_function
    1996. 

  1996. import mysql.connector
    1997. 

  1997. from mysql.connector import FieldType
    1998. 

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

  1999. cursor = cnx.cursor()
    2000. 

  2000. cursor.execute(
    2001. 

  2001.   "SELECT DATE(NOW()) AS `c1`, TIME(NOW()) AS `c2`, "
    2002. 

  2002.   "NOW() AS `c3`, 'a string' AS `c4`, 42 AS `c5`")
    2003. 

  2003. rows = cursor.fetchall()
    2004. 

  2004. for desc in cursor.description:
    2005. 

  2005.   colname = desc[0]
    2006. 

  2006.   coltype = desc[1]
    2007. 

  2007.   print("Column {} has type {}".format(
    2008. 

  2008.     colname, FieldType.get_info(coltype)))
    2009. 

  2009. cursor.close()
    2010. 

  2010. cnx.close()</pre><p>
    2011. 

  2011.       Note that the FieldType class can not be instantiated.
    2012. 

  2012.     </p></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="connector-python-apiref-SQLMode"></a>7.7. Class <code class="literal">constants.SQLMode</code></h2></div></div></div><p>
    2013. 

  2013.       This class provides all known MySQL
    2014. 

  2014.       <a class="ulink" href="http://dev.mysql.com/doc/refman/5.5/en/server-sql-mode.html" target="_top">Server SQL Modes</a>. It is
    2015. 

  2015.       mostly used when setting the SQL modes at connection time using
    2016. 

  2016.       the connection's property <code class="literal">sql_mode</code>. See
    2017. 

  2017.       <a class="xref" href="#myconnpy_MySQLConnection_sql_mode" title="7.2.40. Property MySQLConnection.sql_mode">Section 7.2.40, “Property <code class="literal">MySQLConnection.sql_mode</code>”</a>.
    2018. 

  2018.     </p><p>
    2019. 

  2019.       Note that the SQLMode class can not be instantiated.
    2020. 

  2020.     </p></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="connector-python-apiref-CharacterSet"></a>7.8. Class <code class="literal">constants.CharacterSet</code></h2></div></div></div><p>
    2021. 

  2021.       This class provides all known MySQL characters sets and their
    2022. 

  2022.       default collations. See
    2023. 

  2023.       <a class="xref" href="#myconnpy_MySQLConnection_set_charset_collation" title="7.2.29. Method MySQLConnection.set_charset_collation(charset=None, collation=None)">Section 7.2.29, “Method <code class="literal">MySQLConnection.set_charset_collation(charset=None,
    2024. 

  2024.         collation=None)</code>”</a>
    2025. 

  2025.       for examples.
    2026. 

  2026.     </p><p>
    2027. 

  2027.       Note that the CharacterSet class can not be instantiated.
    2028. 

  2028.     </p></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="connector-python-apiref-RefreshOption"></a>7.9. Class <code class="literal">constants.RefreshOption</code></h2></div></div></div><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
    2029. 

  2029.           <code class="literal">RefreshOption.GRANT</code>
    2030. 

  2030.         </p><p>
    2031. 

  2031.           Refresh the grant tables, like
    2032. 

  2032.           <a class="ulink" href="http://dev.mysql.com/doc/refman/5.5/en/flush.html" target="_top"><code class="literal">FLUSH
    2033. 

  2033.           PRIVILEGES</code></a>.
    2034. 

  2034.         </p></li><li class="listitem"><p>
    2035. 

  2035.           <code class="literal">RefreshOption.LOG</code>
    2036. 

  2036.         </p><p>
    2037. 

  2037.           Flush the logs, like
    2038. 

  2038.           <a class="ulink" href="http://dev.mysql.com/doc/refman/5.5/en/flush.html" target="_top"><code class="literal">FLUSH LOGS</code></a>.
    2039. 

  2039.         </p></li><li class="listitem"><p>
    2040. 

  2040.           <code class="literal">RefreshOption.TABLES</code>
    2041. 

  2041.         </p><p>
    2042. 

  2042.           Flush the table cache, like
    2043. 

  2043.           <a class="ulink" href="http://dev.mysql.com/doc/refman/5.5/en/flush.html" target="_top"><code class="literal">FLUSH TABLES</code></a>.
    2044. 

  2044.         </p></li><li class="listitem"><p>
    2045. 

  2045.           <code class="literal">RefreshOption.HOSTS</code>
    2046. 

  2046.         </p><p>
    2047. 

  2047.           Flush the host cache, like
    2048. 

  2048.           <a class="ulink" href="http://dev.mysql.com/doc/refman/5.5/en/flush.html" target="_top"><code class="literal">FLUSH HOSTS</code></a>.
    2049. 

  2049.         </p></li><li class="listitem"><p>
    2050. 

  2050.           <code class="literal">RefreshOption.STATUS</code>
    2051. 

  2051.         </p><p>
    2052. 

  2052.           Reset status variables, like <code class="literal">FLUSH STATUS</code>.
    2053. 

  2053.         </p></li><li class="listitem"><p>
    2054. 

  2054.           <code class="literal">RefreshOption.THREADS</code>
    2055. 

  2055.         </p><p>
    2056. 

  2056.           Flush the thread cache.
    2057. 

  2057.         </p></li><li class="listitem"><p>
    2058. 

  2058.           <code class="literal">RefreshOption.SLAVE</code>
    2059. 

  2059.         </p><p>
    2060. 

  2060.           On a slave replication server, reset the master server
    2061. 

  2061.           information and restart the slave, like
    2062. 

  2062.           <a class="ulink" href="http://dev.mysql.com/doc/refman/5.5/en/reset-slave.html" target="_top"><code class="literal">RESET SLAVE</code></a>.
    2063. 

  2063.         </p></li><li class="listitem"><p>
    2064. 

  2064.           <code class="literal">RefreshOption.MASTER</code>
    2065. 

  2065.         </p><p>
    2066. 

  2066.           On a master replication server, remove the binary log files
    2067. 

  2067.           listed in the binary log index and truncate the index file,
    2068. 

  2068.           like <a class="ulink" href="http://dev.mysql.com/doc/refman/5.5/en/reset-master.html" target="_top"><code class="literal">RESET MASTER</code></a>.
    2069. 

  2069.         </p></li></ul></div></div></div><div class="chapter"><div class="titlepage"><div><div><h1 class="title"><a name="cpython-news"></a>Chapter 8. MySQL Connector/Python Change History</h1></div></div></div><div class="toc"><p><b>Table of Contents</b></p><dl><dt><span class="section"><a href="#cpython-news-1-0-8">8.1. Changes in MySQL Connector/Python 1.0.8 (Not yet released, Generally Available)</a></span></dt><dt><span class="section"><a href="#cpython-news-1-0-7">8.2. Changes in MySQL Connector/Python 1.0.7 (29 September 2012, Generally Available)</a></span></dt><dt><span class="section"><a href="#cpython-news-1-0-6">8.3. Changes in MySQL Connector/Python 1.0.6 (30 August 2012, beta)</a></span></dt><dt><span class="section"><a href="#cpython-news-1-0-5">8.4. Changes in MySQL Connector/Python 1.0.5 (17 July 2012, beta)</a></span></dt><dt><span class="section"><a href="#cpython-news-1-0-4">8.5. Changes in MySQL Connector/Python 1.0.4 (07 July 2012, alpha)</a></span></dt><dt><span class="section"><a href="#cpython-news-1-0-3">8.6. Changes in MySQL Connector/Python 1.0.3 (08 June 2012, alpha)</a></span></dt><dt><span class="section"><a href="#cpython-news-1-0-2">8.7. Changes in MySQL Connector/Python 1.0.2 (19 May 2012, alpha)</a></span></dt><dt><span class="section"><a href="#cpython-news-1-0-1">8.8. Changes in MySQL Connector/Python 1.0.1 (26 April 2012, alpha)</a></span></dt><dt><span class="section"><a href="#cpython-news-1-0-0">8.9. Changes in MySQL Connector/Python 1.0.0 (22 April 2012, alpha)</a></span></dt></dl></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="cpython-news-1-0-8"></a>8.1. Changes in MySQL Connector/Python 1.0.8 (Not yet released, Generally Available)</h2></div></div></div><p class="release-level">
    2070. 

  2070.         Fixes bugs since the initial 1.0.7 GA release.
    2071. 

  2071.       </p><p>Version 1.0.8 has no changelog entries.</p></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="cpython-news-1-0-7"></a>8.2. Changes in MySQL Connector/Python 1.0.7 (29 September 2012, Generally Available)</h2></div></div></div><p class="release-level">
    2072. 

  2072.         GA release. Connector/Python is now production-ready.
    2073. 

  2073.       </p><p><span class="bold"><strong>Functionality Added or Changed</strong></span></p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
    2074. 

  2074.         Client and server errors have been regenerated using the MySQL
    2075. 

  2075.         5.6.6 development release.
    2076. 

  2076.       </p></li></ul></div><p><span class="bold"><strong>Bugs Fixed</strong></span></p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
    2077. 

  2077.         Fixed formatting of client errors changing numeric to string
    2078. 

  2078.         placeholders.
    2079. 

  2079.        (Bug #14548043)</p></li></ul></div></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="cpython-news-1-0-6"></a>8.3. Changes in MySQL Connector/Python 1.0.6 (30 August 2012, beta)</h2></div></div></div><p class="release-level">
    2080. 

  2080.         Second beta release.
    2081. 

  2081.       </p><p><span class="bold"><strong>Functionality Added or Changed</strong></span></p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
    2082. 

  2082.         Changed name and version of distributions to align with other
    2083. 

  2083.         MySQL projects:
    2084. 

  2084.       </p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: circle; "><li class="listitem"><p>
    2085. 

  2085.             The version now includes the suffix 'b' for beta and 'a' for
    2086. 

  2086.             alpha followed by a number. This version is used in the
    2087. 

  2087.             source and built distributions. GA versions will have no
    2088. 

  2088.             suffix.
    2089. 

  2089.           </p></li><li class="listitem"><p>
    2090. 

  2090.             The RPM spec files have been updated to create packages
    2091. 

  2091.             whose names are aligned with RPMs from other MySQL projects.
    2092. 

  2092.           </p></li></ul></div></li><li class="listitem"><p>
    2093. 

  2093.         Changed how MySQL server errors are mapped to Python exceptions.
    2094. 

  2094.         We now use the <code class="literal">SQLState</code> (when available) to
    2095. 

  2095.         raise a better error.
    2096. 

  2096.       </p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: circle; "><li class="listitem"><p>
    2097. 

  2097.             Incompatibility: some server errors are now raised with a
    2098. 

  2098.             different exception.
    2099. 

  2099.           </p></li><li class="listitem"><p>
    2100. 

  2100.             It is possible to override how errors are raised using the
    2101. 

  2101.             <code class="literal">mysql.connector.custom_error_exception()</code>
    2102. 

  2102.             function, defined in the
    2103. 

  2103.             <code class="literal">mysql.connector.errors</code> module. This can
    2104. 

  2104.             be useful for certain frameworks to align with other
    2105. 

  2105.             database drivers.
    2106. 

  2106.           </p></li></ul></div></li></ul></div><p><span class="bold"><strong>Bugs Fixed</strong></span></p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
    2107. 

  2107.         Fixed version-specific code so Connector/Python works with
    2108. 

  2108.         Python 3.3.
    2109. 

  2109.        (Bug #14524942)</p></li><li class="listitem"><p>
    2110. 

  2110.         Fixed <code class="literal">MySQLCursorRaw.fetchall()</code> so it does
    2111. 

  2111.         not raise an exception when results are available.
    2112. 

  2112.        (Bug #14517262, Bug #66465)</p></li><li class="listitem"><p>
    2113. 

  2113.         Fixed installation of <code class="filename">version.py</code> on OS X:
    2114. 

  2114.       </p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: circle; "><li class="listitem"><p>
    2115. 

  2115.             <code class="filename">version.py</code> is now correctly installed
    2116. 

  2116.             on OS X in the <code class="literal">mysql.connector</code> package.
    2117. 

  2117.             Previously, it was installed through
    2118. 

  2118.             <code class="literal">data_files</code>, and
    2119. 

  2119.             <code class="filename">version.py</code> ended up in the system-wide
    2120. 

  2120.             package location of Python, from which it could not be
    2121. 

  2121.             imported.
    2122. 

  2122.           </p></li><li class="listitem"><p>
    2123. 

  2123.             <code class="literal">data_files</code> is not used any longer in
    2124. 

  2124.             <code class="filename">setup.py</code> and is removed. Extra files
    2125. 

  2125.             like <code class="filename">version.py</code> are now copied in the
    2126. 

  2126.             custom <code class="literal">Distutils</code> commands.
    2127. 

  2127.           </p></li></ul></div><p>(Bug #14483142)</p></li><li class="listitem"><p>
    2128. 

  2128.         Timeout for unit tests has been set to 10 seconds. Test cases
    2129. 

  2129.         can individually adjust it to be higher or lower.
    2130. 

  2130.        (Bug #14487502)</p></li><li class="listitem"><p>
    2131. 

  2131.         Fixed test cases in <code class="filename">test_mysql_database.py</code>
    2132. 

  2132.         that failed when using <code class="literal">YEAR(2)</code> with MySQL
    2133. 

  2133.         5.6.6 and greater.
    2134. 

  2134.        (Bug #14460680)</p></li><li class="listitem"><p>
    2135. 

  2135.         Fixed SSL unit testing for source distributions:
    2136. 

  2136.       </p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: circle; "><li class="listitem"><p>
    2137. 

  2137.             The SSL keys and certificates were missing and are now added
    2138. 

  2138.             to the source distribution. Now SSL testing works properly.
    2139. 

  2139.           </p></li><li class="listitem"><p>
    2140. 

  2140.             Additionally for the Windows platform, forward slashes were
    2141. 

  2141.             added to the option file creation so the MySQL server can
    2142. 

  2142.             pick up the needed SSL files.
    2143. 

  2143.           </p></li></ul></div><p>(Bug #14402737)</p></li></ul></div></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="cpython-news-1-0-5"></a>8.4. Changes in MySQL Connector/Python 1.0.5 (17 July 2012, beta)</h2></div></div></div><p>
    2144. 

  2144.         First beta release.
    2145. 

  2145.       </p><p><span class="bold"><strong>Functionality Added or Changed</strong></span></p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
    2146. 

  2146.         Added SQLMode class in the constants module to make it easier to
    2147. 

  2147.         set modes. For example:
    2148. 

  2148.       </p><pre class="programlisting">cnx.sql_mode = [SQLMode.REAL_AS_FLOAT, SQLMode.NO_ZERO_DATE]</pre></li><li class="listitem"><p>
    2149. 

  2149.         Added descriptive error codes for both client and server errors
    2150. 

  2150.         in the module <code class="literal">errorcode</code>. A new sub-package
    2151. 

  2151.         <code class="literal">locales</code> has been added, which currently only
    2152. 

  2152.         supports English client error messages.
    2153. 

  2153.       </p><p>
    2154. 

  2154.         For example, <code class="literal">errorcode.CR_CONNECTION_ERROR</code> is
    2155. 

  2155.         2002.
    2156. 

  2156.       </p></li></ul></div></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="cpython-news-1-0-4"></a>8.5. Changes in MySQL Connector/Python 1.0.4 (07 July 2012, alpha)</h2></div></div></div><p>
    2157. 

  2157.         Internal alpha release.
    2158. 

  2158.       </p><p><span class="bold"><strong>Bugs Fixed</strong></span></p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p><span class="bold"><strong>Incompatible Change</strong></span>: 
    2159. 

  2159.         The <code class="literal">MySQLConnection</code> methods
    2160. 

  2160.         <code class="literal">unset_client_flag()</code> and
    2161. 

  2161.         <code class="literal">set_client_flag()</code> have been removed. Use
    2162. 

  2162.         the<code class="literal">set_client_flags()</code> method instead using a
    2163. 

  2163.         sequence.
    2164. 

  2164.        (Bug #14259996)</p></li><li class="listitem"><p><span class="bold"><strong>Incompatible Change</strong></span>: 
    2165. 

  2165.         The method <code class="literal">MySQLConnection.set_charset()</code> has
    2166. 

  2166.         been removed and replaced by
    2167. 

  2167.         <code class="literal">MySQLConnection.set_charset_collation()</code> to
    2168. 

  2168.         simplify setting and retrieving character set and collation
    2169. 

  2169.         information. The <code class="literal">MySQLConnection</code> properties
    2170. 

  2170.         <code class="literal">collation</code> and <code class="literal">charset</code> are
    2171. 

  2171.         now read-only.
    2172. 

  2172.        (Bug #14260052)</p></li><li class="listitem"><p><span class="bold"><strong>Incompatible Change</strong></span>: 
    2173. 

  2173.         Fixed <code class="literal">MySQLConnection.cmd_query()</code> to raise an
    2174. 

  2174.         error when the operation has multiple statements. We introduced
    2175. 

  2175.         a new method <code class="literal">MySQLConnection.cmd_query_iter()</code>
    2176. 

  2176.         which needs to be used when multiple statements send to the
    2177. 

  2177.         MySQL server. It returns a generator object to iterate through
    2178. 

  2178.         results.
    2179. 

  2179.       </p><p>
    2180. 

  2180.         When executing single statements,
    2181. 

  2181.         <code class="literal">MySQLCursor.execute()</code> will always return
    2182. 

  2182.         <code class="literal">None</code>. You can use the
    2183. 

  2183.         <code class="literal">MySQLCursor</code> property
    2184. 

  2184.         <code class="literal">with_rows</code> to check whether a result could
    2185. 

  2185.         have rows or not.
    2186. 

  2186.       </p><p>
    2187. 

  2187.         <code class="literal">MySQLCursor.execute()</code> returns a generator
    2188. 

  2188.         object with which you can iterate over results when executing
    2189. 

  2189.         multiple statements.
    2190. 

  2190.       </p><p>
    2191. 

  2191.         The <code class="literal">MySQLCursor.next_resultset()</code> became
    2192. 

  2192.         obsolete and was removed and the
    2193. 

  2193.         <code class="literal">MySQLCursor.next_proc_result()</code> method has
    2194. 

  2194.         been renamed to <code class="literal">MySQLCursor.proc_results()</code>,
    2195. 

  2195.         which returns a generator object. The
    2196. 

  2196.         <code class="literal">MySQLCursor.with_rows</code> property can be used to
    2197. 

  2197.         check if a result could return rows. The
    2198. 

  2198.         <code class="filename">multiple_resultset.py</code> example script shows
    2199. 

  2199.         how to go through results produced by sending multiple
    2200. 

  2200.         statements.
    2201. 

  2201.        (Bug #14208326)</p></li><li class="listitem"><p>
    2202. 

  2202.         Fixed <code class="literal">MySQLCursor.executemany()</code> when
    2203. 

  2203.         <code class="literal">INSERT</code> statements use the <code class="literal">ON
    2204. 

  2204.         DUPLICATE KEY</code> clause with a function such as
    2205. 

  2205.         <code class="literal">VALUES()</code>.
    2206. 

  2206.        (Bug #14259954)</p></li><li class="listitem"><p>
    2207. 

  2207.         Fixed unit testing on the Microsoft Windows platform.
    2208. 

  2208.        (Bug #14236592)</p></li><li class="listitem"><p>
    2209. 

  2209.         Fixed converting a <code class="literal">datetime.time</code> to a MySQL
    2210. 

  2210.         type using Python 2.4 and 2.5. The <code class="literal">strftime()</code>
    2211. 

  2211.         function has no support for the <code class="literal">%f</code> mark in
    2212. 

  2212.         those Python versions.
    2213. 

  2213.        (Bug #14231941)</p></li><li class="listitem"><p>
    2214. 

  2214.         Fixed <code class="literal">cursor.CursorBase</code> attributes
    2215. 

  2215.         <code class="literal">description</code>, <code class="literal">lastrowid</code> and
    2216. 

  2216.         <code class="literal">rowcount</code> to be read-only properties.
    2217. 

  2217.        (Bug #14231160)</p></li><li class="listitem"><p>
    2218. 

  2218.         Fixed <code class="literal">MySQLConnection.cmd_query()</code> and other
    2219. 

  2219.         methods so they check first whether there are unread results.
    2220. 

  2220.        (Bug #14184643)</p></li></ul></div></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="cpython-news-1-0-3"></a>8.6. Changes in MySQL Connector/Python 1.0.3 (08 June 2012, alpha)</h2></div></div></div><p>
    2221. 

  2221.         Internal alpha release.
    2222. 

  2222.       </p><p><span class="bold"><strong>Functionality Added or Changed</strong></span></p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
    2223. 

  2223.         Adding new <code class="literal">Distutils</code> commands to create
    2224. 

  2224.         Windows Installers using WiX and RPM packages.
    2225. 

  2225.       </p></li><li class="listitem"><p>
    2226. 

  2226.         Adding support for time values with a fractional part, for MySQL
    2227. 

  2227.         5.6.4 and greater. A new example script
    2228. 

  2228.         <code class="filename">microseconds.py</code> was added to show this
    2229. 

  2229.         functionality.
    2230. 

  2230.       </p></li></ul></div></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="cpython-news-1-0-2"></a>8.7. Changes in MySQL Connector/Python 1.0.2 (19 May 2012, alpha)</h2></div></div></div><p>
    2231. 

  2231.         Internal alpha release.
    2232. 

  2232.       </p><p><span class="bold"><strong>Functionality Added or Changed</strong></span></p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
    2233. 

  2233.         Added more unit tests for modules like
    2234. 

  2234.         <code class="literal">connection</code> and <code class="literal">network</code> as
    2235. 

  2235.         well as testing the SSL functionality.
    2236. 

  2236.       </p></li></ul></div><p><span class="bold"><strong>Bugs Fixed</strong></span></p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
    2237. 

  2237.         Fixing and refactoring the
    2238. 

  2238.         <code class="literal">mysql.connector.errors</code> module.
    2239. 

  2239.        (Bug #14039339)</p></li><li class="listitem"><p>
    2240. 

  2240.         Fixed bootstrapping MySQL 5.6 running unit tests.
    2241. 

  2241.       </p><p>
    2242. 

  2242.         Messages send by the bootstrapped MySQL server to
    2243. 

  2243.         <code class="literal">stdout</code> and <code class="literal">stderr</code> are now
    2244. 

  2244.         discarded.
    2245. 

  2245.        (Bug #14048685)</p></li></ul></div></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="cpython-news-1-0-1"></a>8.8. Changes in MySQL Connector/Python 1.0.1 (26 April 2012, alpha)</h2></div></div></div><p>
    2246. 

  2246.         Internal alpha release.
    2247. 

  2247.       </p><p><span class="bold"><strong>Functionality Added or Changed</strong></span></p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
    2248. 

  2248.         Change the version so it only contain integers. The 'a' or
    2249. 

  2249.         'alpha' suffix will not be present in packages, but it will be
    2250. 

  2250.         mentioned in the <code class="filename">_version.py</code> module since
    2251. 

  2251.         <code class="filename">metasetupinfo.py</code> uses this information to
    2252. 

  2252.         set, for example, the Trove classifiers dynamically.
    2253. 

  2253.       </p></li></ul></div></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="cpython-news-1-0-0"></a>8.9. Changes in MySQL Connector/Python 1.0.0 (22 April 2012, alpha)</h2></div></div></div><p>
    2254. 

  2254.         Internal alpha release.
    2255. 

  2255.       </p><p><span class="bold"><strong>Functionality Added or Changed</strong></span></p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p><span class="bold"><strong>Incompatible Change</strong></span>: 
    2256. 

  2256.         <code class="literal">MySQLConnection.reconnect()</code> can be used to
    2257. 

  2257.         reconnect to the MySQL server. It accepts number of retries and
    2258. 

  2258.         an optional delay between attempts.
    2259. 

  2259.       </p><p>
    2260. 

  2260.         <code class="literal">MySQLConnectiong.ping()</code> is now a method and
    2261. 

  2261.         works the way the MySQL C API <code class="literal">mysql_ping()</code>
    2262. 

  2262.         function works: it raises an error. It can also optionally
    2263. 

  2263.         reconnect.
    2264. 

  2264.       </p><p>
    2265. 

  2265.         <code class="literal">MySQLConnection.is_connected()</code> now returns
    2266. 

  2266.         <code class="literal">True</code> when connection is available,
    2267. 

  2267.         <code class="literal">False</code> otherwise.
    2268. 

  2268.       </p><p>
    2269. 

  2269.         <code class="literal">ping()</code> and <code class="literal">is_connected()</code>
    2270. 

  2270.         are backwards incompatible.
    2271. 

  2271.        (Bug #13392739)</p></li><li class="listitem"><p>
    2272. 

  2272.         Refactored the modules connection and protocol and created a new
    2273. 

  2273.         module <code class="literal">network</code>. The
    2274. 

  2274.         <code class="literal">MySQLProtocol</code> does not keep a reference to
    2275. 

  2275.         the connection object any more and deals only with creating and
    2276. 

  2276.         parsing MySQL packets. Network interaction is now done by the
    2277. 

  2277.         <code class="literal">MySQLConnection</code> objects (with the exception
    2278. 

  2278.         of <code class="literal">MySQLProtocol.read_text_result()</code>).
    2279. 

  2279.       </p></li></ul></div><p><span class="bold"><strong>Bugs Fixed</strong></span></p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
    2280. 

  2280.         Fixed <code class="filename">metasetupinfo.py</code> to use the
    2281. 

  2281.         Connector/Python which is being installed instead of the version
    2282. 

  2282.         already installed.
    2283. 

  2283.        (Bug #13962765)</p></li><li class="listitem"><p>
    2284. 

  2284.         Fixed <code class="literal">MySQLCursor.description</code> so it stores
    2285. 

  2285.         column names as Unicode.
    2286. 

  2286.        (Bug #13792575)</p></li><li class="listitem"><p>
    2287. 

  2287.         Fixed <code class="literal">dbapi.Binary</code> to be a bytes types for
    2288. 

  2288.         Python 3.x.
    2289. 

  2289.        (Bug #13780676)</p></li><li class="listitem"><p>
    2290. 

  2290.         Fixed automatic garbage collection which caused memory usage to
    2291. 

  2291.         grow over time. Note that <code class="literal">MySQLConnection</code>
    2292. 

  2292.         does not keep track of its cursors any longer.
    2293. 

  2293.        (Bug #13435186)</p></li><li class="listitem"><p>
    2294. 

  2294.         Fixed setting time zone for current MySQL session.
    2295. 

  2295.        (Bug #13395083)</p></li><li class="listitem"><p>
    2296. 

  2296.         Fixed setting and retrieving character set and collation.
    2297. 

  2297.        (Bug #13375632)</p></li><li class="listitem"><p>
    2298. 

  2298.         Fixed handling of errors after authentication for Python 3.
    2299. 

  2299.        (Bug #13364285)</p></li></ul></div></div></div></div><div class="copyright-footer">
    2300. 

  2300.     Copyright © 2012, Oracle and/or its affiliates. All rights
    2301. 

  2301.     reserved.
    2302. 

  2302.   <a href="#legalnotice">Legal Notices</a></div></body></html>
    2303. 

  2303.