VladPolskiy/mariadb-connector-python
1
0
Fork 0
mirror of https://github.com/mariadb-corporation/mariadb-connector-python.git synced 2025-08-02 13:56:54 +00:00
Code Issues Packages Projects Releases Wiki Activity
Files
16a3882cb0b8dc9ff5fc7abcab485468f3b54c5c
mariadb-connector-python/docs/connection.html
Georg Richter 588bc01cc0 Implementation for CONPY-100: 
Add option binary for cursor. When set to true cursor will always try
to use the client/server binary protocol, even when no parameter were
passed to execute.
2020-08-12 16:05:29 +02:00

449 lines
25 KiB
HTML
Raw Blame History

This file contains ambiguous Unicode characters

This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

<!DOCTYPE html>
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<meta charset="utf-8" />
<title>The connection class &#8212; MariaDB Connector/Python 1.0.0 documentation</title>
<link rel="stylesheet" href="_static/classic.css" type="text/css" />
<link rel="stylesheet" href="_static/pygments.css" type="text/css" />
<script id="documentation_options" data-url_root="./" src="_static/documentation_options.js"></script>
<script src="_static/jquery.js"></script>
<script src="_static/underscore.js"></script>
<script src="_static/doctools.js"></script>
<script src="_static/language_data.js"></script>
<link rel="index" title="Index" href="genindex.html" />
<link rel="search" title="Search" href="search.html" />
<link rel="next" title="The cursor class" href="cursor.html" />
<link rel="prev" title="The mariadb module" href="module.html" />
</head><body>
<div class="related" role="navigation" aria-label="related navigation">
<h3>Navigation</h3>
<ul>
<li class="right" style="margin-right: 10px">
<a href="genindex.html" title="General Index"
accesskey="I">index</a></li>
<li class="right" >
<a href="py-modindex.html" title="Python Module Index"
>modules</a> |</li>
<li class="right" >
<a href="cursor.html" title="The cursor class"
accesskey="N">next</a> |</li>
<li class="right" >
<a href="module.html" title="The mariadb module"
accesskey="P">previous</a> |</li>
<li class="nav-item nav-item-0"><a href="index.html">MariaDB Connector/Python 1.0.0 documentation</a> &#187;</li>
</ul>
</div>
<div class="document">
<div class="documentwrapper">
<div class="bodywrapper">
<div class="body" role="main">
<div class="section" id="the-connection-class">
<h1>The connection class<a class="headerlink" href="#the-connection-class" title="Permalink to this headline"></a></h1>
<dl class="class">
<dt id="mariadb.connection">
<em class="property">class </em><code class="sig-prename descclassname">mariadb.</code><code class="sig-name descname">connection</code><a class="headerlink" href="#mariadb.connection" title="Permalink to this definition"></a></dt>
<dd><p>Handles the connection to a MariaDB or MySQL database server. It encapsulates a database session.</p>
<p>Connections are created using the method <a class="reference internal" href="module.html#mariadb.connect" title="mariadb.connect"><code class="xref py py-func docutils literal notranslate"><span class="pre">connect()</span></code></a>.</p>
</dd></dl>
<div class="section" id="connection-constructors">
<h2>Connection constructors<a class="headerlink" href="#connection-constructors" title="Permalink to this headline"></a></h2>
<dl class="method">
<dt id="cursor">
<code class="sig-name descname">cursor</code><span class="sig-paren">(</span><em class="sig-param">**kwargs</em><span class="sig-paren">)</span><a class="headerlink" href="#cursor" title="Permalink to this definition"></a></dt>
<dd><p>Returns a new cursor object using the current connection.</p>
<p>By default the result will be unbuffered, which means before executing another statement with the same connection the entire result set must be fetched.</p>
<p>fetch methods of the cursor class by default return result set values as a tuple, unless named_tuple or dictionary was specified. The latter one exists for compatibility reasons and should be avoided due to possible inconsistency in case two or more fields in a result set have the same name.</p>
<p>If cursor_type is set to mariadb.CURSOR_TYPE_READ_ONLY, a cursor is opened for the statement invoked with cursors execute() method.</p>
<p>Supported keywords:</p>
<ul class="simple">
<li><p><strong>named_tuple</strong> (bool): When set to <cite>True</cite> results from fetch methods will be returned as named tuple.</p></li>
<li><p><strong>cursor_type</strong> (type): When set to <cite>CURSOR_TYPE_READ_ONLY</cite>, server side cursor will be used.</p></li>
<li><p><strong>prefetch_size</strong> (integer): The number of rows prefetched. This option will be ignored, if <em>cursor_type</em> is not <cite>CURSOR_TYPE_READ_ONLY</cite></p></li>
<li><p><strong>buffered</strong> (bool): When set to <cite>True</cite> the entire result set from a SELECT/SHOW statement will be stored in client memory</p></li>
<li><p><strong>prepared</strong> (bool): When set to <cite>True</cite> cursor will remain in prepared state after the first <code class="xref py py-func docutils literal notranslate"><span class="pre">execute()</span></code> method was called. Further calls to <em>execute()</em> method will ignore the sql statement.</p></li>
</ul>
</dd></dl>
<div class="versionadded">
<p><span class="versionmodified added">New in version 1.0.1: </span>- <strong>binary</strong> (bool): When set to <cite>True</cite> cursor will be executed using the MariaDB client/server binary protocol.</p>
<dl class="field-list simple">
<dt class="field-odd">return</dt>
<dd class="field-odd"><p>Returns a cursor object or raises an exception if an error occured.</p>
</dd>
</dl>
</div>
<dl class="method">
<dt id="xid">
<code class="sig-name descname">xid</code><span class="sig-paren">(</span><em class="sig-param">format_id</em>, <em class="sig-param">global_transaction_id</em>, <em class="sig-param">branch_qualifier</em><span class="sig-paren">)</span><a class="headerlink" href="#xid" title="Permalink to this definition"></a></dt>
<dd><p>Returns a transaction ID object suitable for passing to the tpc methods of this connection</p>
<dl class="field-list simple">
<dt class="field-odd">Parameters</dt>
<dd class="field-odd"><ul class="simple">
<li><p><strong>format_id</strong> (<em>integer</em>) – Format id. If not set default value <cite>0</cite> will be used.</p></li>
<li><p><strong>global_transaction_id</strong> – Global transaction qualifier, which must be unique. The maximum length of the global transaction id is limited to 64 characters.</p></li>
<li><p><strong>branch_qualifier</strong> (<em>string</em>) – Branch qualifier which represents a local transaction identifier. The maximum length of the branch qualifier is limited to 64 characters.</p></li>
</ul>
</dd>
</dl>
</dd></dl>
</div>
<div class="section" id="connection-methods">
<h2>Connection methods<a class="headerlink" href="#connection-methods" title="Permalink to this headline"></a></h2>
<dl class="method">
<dt id="commit">
<code class="sig-name descname">commit</code><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#commit" title="Permalink to this definition"></a></dt>
<dd><p>Commit any pending transaction to the database.</p>
</dd></dl>
<div class="admonition note">
<p class="admonition-title">Note</p>
<p>This method has no effect, when autocommit was set to True, or the storage engine in use doesn’t support transactions.</p>
</div>
<dl class="method">
<dt id="change_user">
<code class="sig-name descname">change_user</code><span class="sig-paren">(</span><em class="sig-param">user</em>, <em class="sig-param">password</em>, <em class="sig-param">database</em><span class="sig-paren">)</span><a class="headerlink" href="#change_user" title="Permalink to this definition"></a></dt>
<dd><p>Changes the <em>user</em> and default <em>database</em> of the current connection.
In order to successfully change users a valid username and password
parameters must be provided and that user must have sufficient
permissions to access the desired database.</p>
<dl class="field-list simple">
<dt class="field-odd">Parameters</dt>
<dd class="field-odd"><ul class="simple">
<li><p><strong>user</strong> (<em>string</em>) – The user name for server authentication</p></li>
<li><p><strong>password</strong> (<em>string</em>) – The passoword of the user</p></li>
<li><p><strong>database</strong> (<em>string</em>) – The default database</p></li>
</ul>
</dd>
</dl>
<p>If for any reason authorization fails an exception will be raised and the current user authentication will remain.</p>
</dd></dl>
<dl class="method">
<dt id="close">
<code class="sig-name descname">close</code><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#close" title="Permalink to this definition"></a></dt>
<dd><p>Close the connection now (rather than whenever .__del__() is called).</p>
<p>The connection will be unusable from this point forward; an Error
(or subclass) exception will be raised if any operation is attempted
with the connection. The same applies to all cursor objects trying to
use the connection. If the connection was obtained by <em>ConnectionPool</em>,
the connection will not be closed but returned to the pool.</p>
</dd></dl>
<dl class="method">
<dt id="escape_string">
<code class="sig-name descname">escape_string</code><span class="sig-paren">(</span><em class="sig-param">escape_str</em><span class="sig-paren">)</span><a class="headerlink" href="#escape_string" title="Permalink to this definition"></a></dt>
<dd><p>This function is used to create a legal SQL string that you can use in
an SQL statement. The given string is encoded and returned as an escaped string.</p>
<dl class="field-list simple">
<dt class="field-odd">Parameters</dt>
<dd class="field-odd"><p><strong>escape_str</strong> (<em>string</em>) – The string that is to be escaped.</p>
</dd>
<dt class="field-even">Returns</dt>
<dd class="field-even"><p>the escaped string or NULL on error.</p>
</dd>
</dl>
</dd></dl>
<dl class="method">
<dt id="kill">
<code class="sig-name descname">kill</code><span class="sig-paren">(</span><em class="sig-param">thread_id</em><span class="sig-paren">)</span><a class="headerlink" href="#kill" title="Permalink to this definition"></a></dt>
<dd><p>This function is used to ask the server to terminate a database connection, specified
by the <em>thread_id</em> parameter.</p>
<dl class="field-list simple">
<dt class="field-odd">Parameters</dt>
<dd class="field-odd"><p><strong>thread_id</strong> (<em>integer</em>) – An id which represents a database connection.</p>
</dd>
</dl>
</dd></dl>
<div class="admonition note">
<p class="admonition-title">Note</p>
<p>A thread_id from other connections can be determined by executing the SQL statement <code class="docutils literal notranslate"><span class="pre">SHOW</span> <span class="pre">PROCESSLIST</span></code>
The thread_id of the current connection the current connection is stored in <a class="reference internal" href="#connection_id" title="connection_id"><code class="xref py py-data docutils literal notranslate"><span class="pre">connection_id</span></code></a> attribute.</p>
</div>
<dl class="method">
<dt id="ping">
<code class="sig-name descname">ping</code><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#ping" title="Permalink to this definition"></a></dt>
<dd><p>Checks if the connection to the database server is still available.</p>
</dd></dl>
<div class="admonition note">
<p class="admonition-title">Note</p>
<p>If <a class="reference internal" href="#auto_reconnect" title="auto_reconnect"><code class="xref py py-data docutils literal notranslate"><span class="pre">auto_reconnect</span></code></a> was set to True, an attempt will be made to reconnect to the database server in case the connection was lost</p>
<p>If the connection is not available an InterfaceError will be raised.</p>
</div>
<dl class="method">
<dt id="reconnect">
<code class="sig-name descname">reconnect</code><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#reconnect" title="Permalink to this definition"></a></dt>
<dd><p>Tries to reconnect to a server in case the connection died due to timeout
or other errors. It uses the same credentials which were specified in
<code class="xref py py-func docutils literal notranslate"><span class="pre">module.connect()</span></code> method.</p>
</dd></dl>
<dl class="method">
<dt id="reset">
<code class="sig-name descname">reset</code><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#reset" title="Permalink to this definition"></a></dt>
<dd><p>Tries to reconnect to a server in case the connection died due to timeout
or other errors. It uses the same credentials which were specified in
connect() method.</p>
</dd></dl>
<dl class="method">
<dt id="rollback">
<code class="sig-name descname">rollback</code><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#rollback" title="Permalink to this definition"></a></dt>
<dd><blockquote>
<div><p>Causes the database to roll back to the start of any pending transaction</p>
<p>Closing a connection without committing the changes first will cause an
implicit rollback to be performed.</p>
</div></blockquote>
<div class="admonition note">
<p class="admonition-title">Note</p>
<p>rollback() will not work as expected if autocommit mode was set to True or the storage engine does not support transactions.</p>
</div>
</dd></dl>
<dl class="method">
<dt id="tpc_begin">
<code class="sig-name descname">tpc_begin</code><span class="sig-paren">(</span><span class="optional">[</span><em class="sig-param">xid</em><span class="optional">]</span><span class="sig-paren">)</span><a class="headerlink" href="#tpc_begin" title="Permalink to this definition"></a></dt>
<dd><p>Begins a TPC transaction with the given transaction ID xid, which
was created by xid() method.</p>
<p>This method should be called outside of a transaction
(i.e. nothing may have executed since the last .commit()
or .rollback()).</p>
<p>Furthermore, it is an error to call commit() or rollback() within
the TPC transaction. A ProgrammingError is raised, if the application
calls commit() or rollback() during an active TPC transaction.</p>
<dl class="field-list simple">
<dt class="field-odd">Parameters</dt>
<dd class="field-odd"><p><strong>xid</strong> (<em>Dictionary</em>) – A transaction id which was previously created by <a class="reference internal" href="#xid" title="xid"><code class="xref py py-func docutils literal notranslate"><span class="pre">xid()</span></code></a> method.</p>
</dd>
</dl>
</dd></dl>
<dl class="method">
<dt id="tpc_commit">
<code class="sig-name descname">tpc_commit</code><span class="sig-paren">(</span><span class="optional">[</span><em class="sig-param">xid</em><span class="optional">]</span><span class="sig-paren">)</span><a class="headerlink" href="#tpc_commit" title="Permalink to this definition"></a></dt>
<dd><p>When called with no arguments, tpc_commit() commits a TPC transaction
previously prepared with tpc_prepare().</p>
<p>If tpc_commit() is called prior to tpc_prepare(), a single phase commit
is performed. A transaction manager may choose to do this if only a
single resource is participating in the global transaction.</p>
<p>When called with a transaction ID xid, the database commits the given
transaction. If an invalid transaction ID is provided, a ProgrammingError
will be raised. This form should be called outside of a transaction, and
is intended for use in recovery.</p>
</dd></dl>
<dl class="method">
<dt id="tpc_prepare">
<code class="sig-name descname">tpc_prepare</code><span class="sig-paren">(</span><span class="optional">[</span><em class="sig-param">xid</em><span class="optional">]</span><span class="sig-paren">)</span><a class="headerlink" href="#tpc_prepare" title="Permalink to this definition"></a></dt>
<dd><p>Performs the first phase of a transaction started with tpc_begin().</p>
<p>A ProgrammingError will be raised if this method outside of a TPC
transaction.</p>
<p>After calling tpc_prepare(), no statements can be executed until
<a class="reference internal" href="#tpc_commit" title="tpc_commit"><code class="xref py py-func docutils literal notranslate"><span class="pre">tpc_commit()</span></code></a> or <a class="reference internal" href="#tpc_rollback" title="tpc_rollback"><code class="xref py py-func docutils literal notranslate"><span class="pre">tpc_rollback()</span></code></a> have been called.</p>
</dd></dl>
<dl class="method">
<dt id="tpc_recover">
<code class="sig-name descname">tpc_recover</code><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#tpc_recover" title="Permalink to this definition"></a></dt>
<dd><p>Returns a list of pending transaction IDs suitable for use with
tpc_commit(xid) or tpc_rollback(xid).</p>
</dd></dl>
<dl class="method">
<dt id="tpc_rollback">
<code class="sig-name descname">tpc_rollback</code><span class="sig-paren">(</span><span class="optional">[</span><em class="sig-param">xid</em><span class="optional">]</span><span class="sig-paren">)</span><a class="headerlink" href="#tpc_rollback" title="Permalink to this definition"></a></dt>
<dd><p>When called with no arguments, tpc_rollback() rolls back a TPC
transaction. It may be called before or after <a class="reference internal" href="#tpc_prepare" title="tpc_prepare"><code class="xref py py-func docutils literal notranslate"><span class="pre">tpc_prepare()</span></code></a>.</p>
<p>When called with a transaction ID xid, it rolls back the given
transaction.</p>
</dd></dl>
</div>
<div class="section" id="connection-attributes">
<h2>Connection attributes<a class="headerlink" href="#connection-attributes" title="Permalink to this headline"></a></h2>
<dl class="data">
<dt id="auto_reconnect">
<code class="sig-name descname">auto_reconnect</code><a class="headerlink" href="#auto_reconnect" title="Permalink to this definition"></a></dt>
<dd><p>Enable or disable automatic reconnection to the server if the connection
is found to have been lost.</p>
<p>When enabled, client tries to reconnect to a database server in case
the connection to a database server died due to timeout or other errors.</p>
</dd></dl>
<dl class="data">
<dt id="autocommit">
<code class="sig-name descname">autocommit</code><a class="headerlink" href="#autocommit" title="Permalink to this definition"></a></dt>
<dd><p>Toggles autocommit mode on or off for the current database connection.</p>
<p>Autocommit mode only affects operations on transactional table types.
Be aware that <a class="reference internal" href="#rollback" title="rollback"><code class="xref py py-func docutils literal notranslate"><span class="pre">rollback()</span></code></a> will not work, if autocommit mode was switched on.</p>
<p>By default autocommit mode is set to False.</p>
</dd></dl>
<dl class="data">
<dt id="character_set">
<code class="sig-name descname">character_set</code><a class="headerlink" href="#character_set" title="Permalink to this definition"></a></dt>
<dd><p>Returns the character set used for the connection</p>
</dd></dl>
<dl class="data">
<dt id="collation">
<code class="sig-name descname">collation</code><a class="headerlink" href="#collation" title="Permalink to this definition"></a></dt>
<dd><p>Returns character set collation used for the connection</p>
</dd></dl>
<dl class="data">
<dt id="connection_id">
<code class="sig-name descname">connection_id</code><a class="headerlink" href="#connection_id" title="Permalink to this definition"></a></dt>
<dd><p>Returns the (thread) id for the current connection.</p>
<p>If <a class="reference internal" href="#auto_reconnect" title="auto_reconnect"><code class="xref py py-data docutils literal notranslate"><span class="pre">auto_reconnect</span></code></a> was set to True, the id might change if the client reconnects to the database server</p>
</dd></dl>
<dl class="data">
<dt id="database">
<code class="sig-name descname">database</code><a class="headerlink" href="#database" title="Permalink to this definition"></a></dt>
<dd><p>Returns or sets the default database for the current connection</p>
<p>If the used datbase will not change, the preffered way is to specify
the default database when establishing the connection.</p>
</dd></dl>
<dl class="data">
<dt id="server_info">
<code class="sig-name descname">server_info</code><a class="headerlink" href="#server_info" title="Permalink to this definition"></a></dt>
<dd><p>Returns the alphanumeric version of connected database. Tthe numeric version
can be obtained via server_version() property.</p>
</dd></dl>
<dl class="data">
<dt id="server_name">
<code class="sig-name descname">server_name</code><a class="headerlink" href="#server_name" title="Permalink to this definition"></a></dt>
<dd><p>Returns name or IP address of database server</p>
</dd></dl>
<dl class="data">
<dt id="server_port">
<code class="sig-name descname">server_port</code><a class="headerlink" href="#server_port" title="Permalink to this definition"></a></dt>
<dd><p>Returns the database server TCP/IP port</p>
</dd></dl>
<dl class="data">
<dt id="server_version">
<code class="sig-name descname">server_version</code><a class="headerlink" href="#server_version" title="Permalink to this definition"></a></dt>
<dd><p>Returns numeric version of connected database server. The form of the version
number is VERSION_MAJOR * 10000 + VERSION_MINOR * 100 + VERSION_PATCH</p>
</dd></dl>
<dl class="data">
<dt id="tls_cipher">
<code class="sig-name descname">tls_cipher</code><a class="headerlink" href="#tls_cipher" title="Permalink to this definition"></a></dt>
<dd><p>Returns TLS cipher suite in use by connection</p>
</dd></dl>
<dl class="data">
<dt id="tls_version">
<code class="sig-name descname">tls_version</code><a class="headerlink" href="#tls_version" title="Permalink to this definition"></a></dt>
<dd><p>Returns TLS protocol version used by connection</p>
</dd></dl>
<dl class="data">
<dt id="unix_socket">
<code class="sig-name descname">unix_socket</code><a class="headerlink" href="#unix_socket" title="Permalink to this definition"></a></dt>
<dd><p>Returns Unix socket name</p>
</dd></dl>
<dl class="data">
<dt id="user">
<code class="sig-name descname">user</code><a class="headerlink" href="#user" title="Permalink to this definition"></a></dt>
<dd><p>Returns user name for the current connection</p>
</dd></dl>
<dl class="data">
<dt id="warnings">
<code class="sig-name descname">warnings</code><a class="headerlink" href="#warnings" title="Permalink to this definition"></a></dt>
<dd><p>Returns the number of warnings from the last executed statement, or zero
if there are no warnings.</p>
</dd></dl>
<div class="admonition note">
<p class="admonition-title">Note</p>
<p>If the sql mode <code class="docutils literal notranslate"><span class="pre">TRADITIONAL</span></code> is enabled an error instead of a warning will be returned. To retrieve warnings the SQL statement <code class="docutils literal notranslate"><span class="pre">SHOW</span> <span class="pre">WARNINGS</span></code> has to be used.</p>
</div>
</div>
</div>
</div>
</div>
</div>
<div class="sphinxsidebar" role="navigation" aria-label="main navigation">
<div class="sphinxsidebarwrapper">
<h3><a href="index.html">Table of Contents</a></h3>
<ul>
<li><a class="reference internal" href="#">The connection class</a><ul>
<li><a class="reference internal" href="#connection-constructors">Connection constructors</a></li>
<li><a class="reference internal" href="#connection-methods">Connection methods</a></li>
<li><a class="reference internal" href="#connection-attributes">Connection attributes</a></li>
</ul>
</li>
</ul>
<h4>Previous topic</h4>
<p class="topless"><a href="module.html"
title="previous chapter">The mariadb module</a></p>
<h4>Next topic</h4>
<p class="topless"><a href="cursor.html"
title="next chapter">The cursor class</a></p>
<div role="note" aria-label="source link">
<h3>This Page</h3>
<ul class="this-page-menu">
<li><a href="_sources/connection.rst.txt"
rel="nofollow">Show Source</a></li>
</ul>
</div>
<div id="searchbox" style="display: none" role="search">
<h3 id="searchlabel">Quick search</h3>
<div class="searchformwrapper">
<form class="search" action="search.html" method="get">
<input type="text" name="q" aria-labelledby="searchlabel" />
<input type="submit" value="Go" />
</form>
</div>
</div>
<script>$('#searchbox').show(0);</script>
</div>
</div>
<div class="clearer"></div>
</div>
<div class="related" role="navigation" aria-label="related navigation">
<h3>Navigation</h3>
<ul>
<li class="right" style="margin-right: 10px">
<a href="genindex.html" title="General Index"
>index</a></li>
<li class="right" >
<a href="py-modindex.html" title="Python Module Index"
>modules</a> |</li>
<li class="right" >
<a href="cursor.html" title="The cursor class"
>next</a> |</li>
<li class="right" >
<a href="module.html" title="The mariadb module"
>previous</a> |</li>
<li class="nav-item nav-item-0"><a href="index.html">MariaDB Connector/Python 1.0.0 documentation</a> &#187;</li>
</ul>
</div>
<div class="footer" role="contentinfo">
&#169; Copyright 2019,2020 MariaDB Corporation and Georg Richter.
Created using <a href="http://sphinx-doc.org/">Sphinx</a> 2.4.3.
</div>
</body>
</html>
Reference in New Issue View Git Blame Copy Permalink