VladPolskiy/mariadb-connector-python
1
0
Fork 0
mirror of https://github.com/mariadb-corporation/mariadb-connector-python.git synced 2025-08-03 19:20:35 +00:00
Code Issues Packages Projects Releases Wiki Activity
Files
63e0b4af80eed9b69e1f52def4b8f8bdd19e4625
mariadb-connector-python/docs/module.html
Georg Richter 63e0b4af80 Changed html scheme for documentation. Adjusted version number in 
documentation.
2020-06-03 13:34:48 +02:00

402 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 mariadb module &#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 connection class" href="connection.html" />
<link rel="prev" title="Installation" href="install.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="connection.html" title="The connection class"
accesskey="N">next</a> |</li>
<li class="right" >
<a href="install.html" title="Installation"
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="module-mariadb">
<span id="the-mariadb-module"></span><span id="module"></span><h1>The mariadb module<a class="headerlink" href="#module-mariadb" title="Permalink to this headline"></a></h1>
<p>The mariadb module supports the standard defined by DB API 2.0 (PEP-249).</p>
<dl class="function">
<dt id="mariadb.connect">
<code class="sig-prename descclassname">mariadb.</code><code class="sig-name descname">connect</code><span class="sig-paren">(</span><em class="sig-param">**kwargs</em><span class="sig-paren">)</span><a class="headerlink" href="#mariadb.connect" title="Permalink to this definition"></a></dt>
<dd><blockquote>
<div><p>Establishes a connection to a database server and returns a new connection
object.</p>
<p>The connection parameters have to be provided as a set of keyword arguments.</p>
</div></blockquote>
<p>The supported connection keywords are:</p>
<ul class="simple">
<li><p><strong>user</strong> (string): The username used to authenticate with the database server, defaults to current user</p></li>
<li><p><strong>pasword</strong> (string): The password of the given user</p></li>
<li><p><strong>host</strong> (string): The host name or IP address of the database server</p></li>
<li><p><strong>database</strong> (string): The database (schema) name to used when connecting with the database server</p></li>
<li><p><strong>unix_socket</strong> (string): The location of the unix socket file to use instead of using an IP port to connect. If socket authentication is enabled, this can also be used in place of a password.</p></li>
<li><p><strong>port</strong> (integer): The port number of the database server. If not specified the default value (=3306) will be used.</p></li>
<li><p><strong>connect_timeout</strong> (integer): The connect timeout in seconds</p></li>
<li><p><strong>read_timeout</strong> (integer): The read timeout in seconds</p></li>
<li><p><strong>write_timeout</strong> (integer): The write timeout in seconds</p></li>
<li><p><strong>local_infile</strong> (bool): Enables or disables the use of LOAD DATA LOCAL INFILE statements.</p></li>
<li><dl class="simple">
<dt><strong>compress</strong> (bool) – Uses the compressed protocol for client server communication. If the</dt><dd><p>server doesn’t support compressed protocol, the default protocol will
be used</p>
</dd>
</dl>
</li>
<li><p><strong>init_command</strong> (string): Specifies one or more commands to execute when connecting and reconnecting to the database server.</p></li>
<li><p><strong>default_file</strong> (string): Read options from the specified option file. If the file is an empty string, default configuration file(s) will be used</p></li>
<li><p><strong>default_group</strong> (string): – Read options from the specified group</p></li>
<li><dl class="simple">
<dt><strong>ssl_key</strong> (string): Defines a path to a private key file to use for TLS. This option</dt><dd><p>requires that you use the absolute path, not a relative path. The specified key must be in PEM format</p>
</dd>
</dl>
</li>
<li><p><strong>ssl_cert</strong> (string): Defines a path to the X509 certificate file to use for TLS. This option requires that you use the absolute path, not a relative path. The X609 certificate must be in PEM format.</p></li>
<li><p><strong>ssl_ca</strong> (string): Defines a path to a PEM file that should contain one or more X509 certificates for trusted Certificate Authorities (CAs) to use for TLS. This option requires that you use the absolute path, not a relative path.</p></li>
<li><p><strong>ssl_capath</strong> (string): Defines a path to a directory that contains one or more PEM files that contains one X509 certificate for a trusted Certificate Authority (CA)</p></li>
<li><p><strong>ssl_cipher</strong> (string): Defines a list of permitted cipher suites to use for TLS</p></li>
<li><p><strong>ssl_crl_path</strong> (string): Defines a path to a PEM file that should contain one or more revoked X509 certificates to use for TLS. This option requires that you use the absolute path, not a relative path.</p></li>
<li><p><strong>ssl_verify_server_cert</strong> (bool): Enables server certificate verification.</p></li>
<li><p><strong>ssl_enforce</strong> (bool): Always use a secure TLS connection</p></li>
</ul>
<dl class="field-list simple">
<dt class="field-odd">Returns</dt>
<dd class="field-odd"><p>Returns a connection or raises an error if the connection between client and server couldn’t be established.</p>
</dd>
<dt class="field-even">Return type</dt>
<dd class="field-even"><p>mariadb.connection object</p>
</dd>
<dt class="field-odd">Example</dt>
<dd class="field-odd"><p></p></dd>
</dl>
<p>The connection parameters have to be provided as a set of keyword arguments:</p>
<div class="highlight-python notranslate"><div class="highlight"><pre><span></span><span class="kn">import</span> <span class="nn">mariadb</span>
<span class="n">connection</span><span class="o">=</span> <span class="n">mariadb</span><span class="o">.</span><span class="n">connect</span><span class="p">(</span><span class="n">user</span><span class="o">=</span><span class="s2">&quot;myuser&quot;</span><span class="p">,</span> <span class="n">host</span><span class="o">=</span><span class="s2">&quot;localhost&quot;</span><span class="p">,</span> <span class="n">database</span><span class="o">=</span><span class="s2">&quot;test&quot;</span><span class="p">,</span> <span class="n">password</span><span class="o">=</span><span class="s2">&quot;secret&quot;</span><span class="p">)</span>
</pre></div>
</div>
</dd></dl>
<dl class="function">
<dt id="mariadb.ConnectionPool">
<code class="sig-prename descclassname">mariadb.</code><code class="sig-name descname">ConnectionPool</code><span class="sig-paren">(</span><em class="sig-param">**kwargs</em><span class="sig-paren">)</span><a class="headerlink" href="#mariadb.ConnectionPool" title="Permalink to this definition"></a></dt>
<dd><p>Creates a connection pool and returns a ConnectionPool object.</p>
<p>The connection parameters have to be provided as a set of keyword arguments:</p>
<div class="highlight-python notranslate"><div class="highlight"><pre><span></span><span class="n">db_conf</span><span class="o">=</span> <span class="p">{</span><span class="n">user</span><span class="o">=</span><span class="s2">&quot;myname&quot;</span><span class="p">,</span> <span class="n">password</span><span class="o">=</span><span class="s2">&quot;secret&quot;</span><span class="p">,</span> <span class="n">database</span><span class="o">=</span><span class="s2">&quot;test&quot;</span><span class="p">,</span> <span class="n">host</span><span class="o">=</span><span class="s2">&quot;localhost&quot;</span><span class="p">};</span>
<span class="n">pool</span><span class="o">=</span> <span class="n">mariadb</span><span class="o">.</span><span class="n">ConnectionPool</span><span class="p">(</span><span class="n">pool_name</span><span class="o">=</span><span class="s2">&quot;pool1&quot;</span><span class="p">,</span> <span class="o">**</span><span class="n">db_conf</span><span class="p">)</span>
</pre></div>
</div>
<p>Beside pool specific parameter all parameters from connect() are supported.
The supported pool parameters are:</p>
<ul class="simple">
<li><p>pool_name – Name of the pool</p></li>
<li><p>pool_size – Size of the pool. If this value is not provided, a default size of 5 pool connections will be used.</p></li>
<li><p>pool_reset – If set to <cite>True</cite> the connection will be resetted after close() method was called.</p></li>
</ul>
</dd></dl>
<dl class="data">
<dt id="mariadb.apilevel">
<code class="sig-prename descclassname">mariadb.</code><code class="sig-name descname">apilevel</code><a class="headerlink" href="#mariadb.apilevel" title="Permalink to this definition"></a></dt>
<dd><p>String constant stating the supported DB API level. The value for <cite>mariadb</cite> is
<code class="docutils literal notranslate"><span class="pre">2.0</span></code>.</p>
</dd></dl>
<dl class="data">
<dt id="mariadb.threadsafety">
<code class="sig-prename descclassname">mariadb.</code><code class="sig-name descname">threadsafety</code><a class="headerlink" href="#mariadb.threadsafety" title="Permalink to this definition"></a></dt>
<dd><p>Integer constant stating the level of thread safety. For <cite>mariadb</cite> the value is 1,
which means threads can share the module but not the connection.</p>
</dd></dl>
<dl class="data">
<dt id="mariadb.paramstyle">
<code class="sig-prename descclassname">mariadb.</code><code class="sig-name descname">paramstyle</code><a class="headerlink" href="#mariadb.paramstyle" title="Permalink to this definition"></a></dt>
<dd><p>String constant stating the type of parameter marker. For <cite>mariadb</cite> the value is
<cite>qmark</cite>. For compatibility reasons <cite>mariadb</cite> also supports the <cite>format</cite> and
<cite>pyformat</cite> paramstyles with the limitation that they can’t be mixed inside a SQL statement.</p>
</dd></dl>
<dl class="data">
<dt id="mariadb.mariadbapi_version">
<code class="sig-prename descclassname">mariadb.</code><code class="sig-name descname">mariadbapi_version</code><a class="headerlink" href="#mariadb.mariadbapi_version" title="Permalink to this definition"></a></dt>
<dd><p>String constant stating the version of the used MariaDB Connector/C library.</p>
</dd></dl>
<div class="section" id="exceptions">
<h2>Exceptions<a class="headerlink" href="#exceptions" title="Permalink to this headline"></a></h2>
<p>Compliant to DB API 2.0 MariaDB Connector/C provides information about errors
through the following exceptions:</p>
<dl class="exception">
<dt id="mariadb.DataError">
<em class="property">exception </em><code class="sig-prename descclassname">mariadb.</code><code class="sig-name descname">DataError</code><a class="headerlink" href="#mariadb.DataError" title="Permalink to this definition"></a></dt>
<dd><p>Exception raised for errors that are due to problems with the processed data like division by zero,
numeric value out of range, etc.</p>
</dd></dl>
<dl class="exception">
<dt id="mariadb.DatabaseError">
<em class="property">exception </em><code class="sig-prename descclassname">mariadb.</code><code class="sig-name descname">DatabaseError</code><a class="headerlink" href="#mariadb.DatabaseError" title="Permalink to this definition"></a></dt>
<dd><p>Exception raised for errors that are related to the database</p>
</dd></dl>
<dl class="exception">
<dt id="mariadb.InterfaceError">
<em class="property">exception </em><code class="sig-prename descclassname">mariadb.</code><code class="sig-name descname">InterfaceError</code><a class="headerlink" href="#mariadb.InterfaceError" title="Permalink to this definition"></a></dt>
<dd><p>Exception raised for errors that are related to the database interface
rather than the database itself.</p>
</dd></dl>
<dl class="exception">
<dt id="mariadb.Warning">
<em class="property">exception </em><code class="sig-prename descclassname">mariadb.</code><code class="sig-name descname">Warning</code><a class="headerlink" href="#mariadb.Warning" title="Permalink to this definition"></a></dt>
<dd><p>Exception raised for important warnings like data truncations while inserting, etc.</p>
</dd></dl>
<dl class="exception">
<dt id="mariadb.PoolError">
<em class="property">exception </em><code class="sig-prename descclassname">mariadb.</code><code class="sig-name descname">PoolError</code><a class="headerlink" href="#mariadb.PoolError" title="Permalink to this definition"></a></dt>
<dd><p>Exception rasied for errors related to ConnectionPool class.</p>
</dd></dl>
<dl class="exception">
<dt id="mariadb.OperationalError">
<em class="property">exception </em><code class="sig-prename descclassname">mariadb.</code><code class="sig-name descname">OperationalError</code><a class="headerlink" href="#mariadb.OperationalError" title="Permalink to this definition"></a></dt>
<dd><p>Exception raised for errors that are related to the database’s operation
and not necessarily under the control of the programmer</p>
</dd></dl>
<dl class="exception">
<dt id="mariadb.IntegrityError">
<em class="property">exception </em><code class="sig-prename descclassname">mariadb.</code><code class="sig-name descname">IntegrityError</code><a class="headerlink" href="#mariadb.IntegrityError" title="Permalink to this definition"></a></dt>
<dd><p>Exception raised when the relational integrity of the database is affected,
e.g. a foreign key check fails.</p>
</dd></dl>
<dl class="exception">
<dt id="mariadb.InternalError">
<em class="property">exception </em><code class="sig-prename descclassname">mariadb.</code><code class="sig-name descname">InternalError</code><a class="headerlink" href="#mariadb.InternalError" title="Permalink to this definition"></a></dt>
<dd><p>Exception raised when the database encounters an internal error,
e.g. the cursor is not valid anymore</p>
</dd></dl>
<dl class="exception">
<dt id="mariadb.ProgrammingError">
<em class="property">exception </em><code class="sig-prename descclassname">mariadb.</code><code class="sig-name descname">ProgrammingError</code><a class="headerlink" href="#mariadb.ProgrammingError" title="Permalink to this definition"></a></dt>
<dd><p>Exception raised for programming errors, e.g. table not found or already
exists, syntax error in the SQL statement</p>
</dd></dl>
<dl class="exception">
<dt id="mariadb.NotSupportedError">
<em class="property">exception </em><code class="sig-prename descclassname">mariadb.</code><code class="sig-name descname">NotSupportedError</code><a class="headerlink" href="#mariadb.NotSupportedError" title="Permalink to this definition"></a></dt>
<dd><p>Exception raised in case a method or database API was used which is not
supported by the database</p>
</dd></dl>
</div>
<div class="section" id="type-objects-and-constructors">
<h2>Type objects and constructors<a class="headerlink" href="#type-objects-and-constructors" title="Permalink to this headline"></a></h2>
<dl class="function">
<dt id="mariadb.Binary">
<code class="sig-prename descclassname">mariadb.</code><code class="sig-name descname">Binary</code><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#mariadb.Binary" title="Permalink to this definition"></a></dt>
<dd><p>This function constructs an object capable of holding a binary (long)
string value</p>
</dd></dl>
<dl class="function">
<dt id="mariadb.Date">
<code class="sig-prename descclassname">mariadb.</code><code class="sig-name descname">Date</code><span class="sig-paren">(</span><em class="sig-param">year</em>, <em class="sig-param">month</em>, <em class="sig-param">day</em><span class="sig-paren">)</span><a class="headerlink" href="#mariadb.Date" title="Permalink to this definition"></a></dt>
<dd><p>This function constructs an object holding a date value</p>
</dd></dl>
<dl class="function">
<dt id="mariadb.DateFromTicks">
<code class="sig-prename descclassname">mariadb.</code><code class="sig-name descname">DateFromTicks</code><span class="sig-paren">(</span><em class="sig-param">ticks</em><span class="sig-paren">)</span><a class="headerlink" href="#mariadb.DateFromTicks" title="Permalink to this definition"></a></dt>
<dd><p>This function constructs an object holding a date value from the given
ticks value (number of seconds since the epoch). For more information
see the documentation of the standard Python time module</p>
</dd></dl>
<dl class="function">
<dt id="mariadb.Time">
<code class="sig-prename descclassname">mariadb.</code><code class="sig-name descname">Time</code><span class="sig-paren">(</span><em class="sig-param">hour</em>, <em class="sig-param">minute</em>, <em class="sig-param">second</em><span class="sig-paren">)</span><a class="headerlink" href="#mariadb.Time" title="Permalink to this definition"></a></dt>
<dd><p>This function constructs an object holding a time value</p>
</dd></dl>
<dl class="function">
<dt id="mariadb.TimeFromTicks">
<code class="sig-prename descclassname">mariadb.</code><code class="sig-name descname">TimeFromTicks</code><span class="sig-paren">(</span><em class="sig-param">ticks</em><span class="sig-paren">)</span><a class="headerlink" href="#mariadb.TimeFromTicks" title="Permalink to this definition"></a></dt>
<dd><p>This function constructs an object holding a time value from the given
ticks value (number of seconds since the epoch). For more information
see the documentation of the standard Python time module</p>
</dd></dl>
<dl class="function">
<dt id="mariadb.Timestamp">
<code class="sig-prename descclassname">mariadb.</code><code class="sig-name descname">Timestamp</code><span class="sig-paren">(</span><em class="sig-param">year</em>, <em class="sig-param">month</em>, <em class="sig-param">day</em>, <em class="sig-param">hour</em>, <em class="sig-param">minute</em>, <em class="sig-param">second</em><span class="sig-paren">)</span><a class="headerlink" href="#mariadb.Timestamp" title="Permalink to this definition"></a></dt>
<dd><p>This function constructs an object holding a time stamp value</p>
</dd></dl>
<dl class="function">
<dt id="mariadb.TimestampFromTicks">
<code class="sig-prename descclassname">mariadb.</code><code class="sig-name descname">TimestampFromTicks</code><span class="sig-paren">(</span><em class="sig-param">ticks</em><span class="sig-paren">)</span><a class="headerlink" href="#mariadb.TimestampFromTicks" title="Permalink to this definition"></a></dt>
<dd><p>This function constructs an object holding a time stamp value from the given
ticks value (number of seconds since the epoch). For more information
see the documentation of the standard Python time module</p>
</dd></dl>
<dl class="data">
<dt id="mariadb.STRING">
<code class="sig-prename descclassname">mariadb.</code><code class="sig-name descname">STRING</code><a class="headerlink" href="#mariadb.STRING" title="Permalink to this definition"></a></dt>
<dd><p>This type object is used to describe columns in a database that are
string-based (e.g. CHAR).</p>
</dd></dl>
<dl class="data">
<dt id="mariadb.BINARY">
<code class="sig-prename descclassname">mariadb.</code><code class="sig-name descname">BINARY</code><a class="headerlink" href="#mariadb.BINARY" title="Permalink to this definition"></a></dt>
<dd><p>This type object is used to describe (long) binary columns in a database
(e.g. LONG, RAW, BLOBs).</p>
</dd></dl>
<dl class="data">
<dt id="mariadb.NUMBER">
<code class="sig-prename descclassname">mariadb.</code><code class="sig-name descname">NUMBER</code><a class="headerlink" href="#mariadb.NUMBER" title="Permalink to this definition"></a></dt>
<dd><p>This type object is used to describe numeric columns in a database.</p>
</dd></dl>
<dl class="data">
<dt id="mariadb.DATETIME">
<code class="sig-prename descclassname">mariadb.</code><code class="sig-name descname">DATETIME</code><a class="headerlink" href="#mariadb.DATETIME" title="Permalink to this definition"></a></dt>
<dd><p>This type object is used to describe date/time columns in a database.</p>
</dd></dl>
<dl class="data">
<dt id="mariadb.ROWID">
<code class="sig-prename descclassname">mariadb.</code><code class="sig-name descname">ROWID</code><a class="headerlink" href="#mariadb.ROWID" title="Permalink to this definition"></a></dt>
<dd><p>This type object is used to describe the “Row ID” column in a database.</p>
</dd></dl>
<dl class="data">
<dt id="mariadb.indicator_default">
<code class="sig-prename descclassname">mariadb.</code><code class="sig-name descname">indicator_default</code><a class="headerlink" href="#mariadb.indicator_default" title="Permalink to this definition"></a></dt>
<dd><p>This indicator object is used to use a default value for insert/update.</p>
</dd></dl>
<dl class="data">
<dt id="mariadb.indicator_ignore">
<code class="sig-prename descclassname">mariadb.</code><code class="sig-name descname">indicator_ignore</code><a class="headerlink" href="#mariadb.indicator_ignore" title="Permalink to this definition"></a></dt>
<dd><p>This indicatior object is used to skip the update of a column.</p>
</dd></dl>
<dl class="data">
<dt id="mariadb.indicator_null">
<code class="sig-prename descclassname">mariadb.</code><code class="sig-name descname">indicator_null</code><a class="headerlink" href="#mariadb.indicator_null" title="Permalink to this definition"></a></dt>
<dd><p>This indicator object is used for NULL values.</p>
</dd></dl>
<dl class="data">
<dt id="mariadb.indicator_row">
<code class="sig-prename descclassname">mariadb.</code><code class="sig-name descname">indicator_row</code><a class="headerlink" href="#mariadb.indicator_row" title="Permalink to this definition"></a></dt>
<dd><p>This indicator object is used for skip the update/insert of the entire row.</p>
</dd></dl>
</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 mariadb module</a><ul>
<li><a class="reference internal" href="#exceptions">Exceptions</a></li>
<li><a class="reference internal" href="#type-objects-and-constructors">Type objects and constructors</a></li>
</ul>
</li>
</ul>
<h4>Previous topic</h4>
<p class="topless"><a href="install.html"
title="previous chapter">Installation</a></p>
<h4>Next topic</h4>
<p class="topless"><a href="connection.html"
title="next chapter">The connection class</a></p>
<div role="note" aria-label="source link">
<h3>This Page</h3>
<ul class="this-page-menu">
<li><a href="_sources/module.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="connection.html" title="The connection class"
>next</a> |</li>
<li class="right" >
<a href="install.html" title="Installation"
>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