Added chapter usage (documentation)

This commit is contained in:
Georg Richter
2020-06-08 12:25:54 +02:00
parent 9a24ee4402
commit ba052adafa
2 changed files with 436 additions and 0 deletions

124
doc/source/usage.rst Normal file
View File

@ -0,0 +1,124 @@
***********
Basic usage
***********
.. sectionauthor:: Georg Richter <georg@mariadb.com>
Connecting
##########
The basic usage of MariaDB Connector/Python is similiar to other database drivers which
implement |DBAPI|.
Below is a simple example of a typical use of MariaDB Connector/Python
.. literalinclude:: ../examples/basic01.py
:language: python
:linenos:
Before MariaDB Connector/Python can be used, the MariaDB Connector/Python module must be
imported (line #2)
Once the mariadb module is loaded, a connection to a database server will be established
using the method :func:`~mariadb.connect` (line #5).
In order to be able to communicate with the database server in the form of SQL statements,
a cursor object must be created first (line #7).
The method name cursor may be a little misleading: unlike a cursor in MariaDB that can only
read and return data, a cursor in Python can be used for all types of SQL statements.
After creating the table mytest, everything is ready to insert some data (line #16): Column values
that are to be inserted in the database are identified by place holders, the data is then passed in
the form of a tuple as a second parameter (line #16).
After creating and populating the table mytest the cursor will be used to retrieve the data (line #20 - line#23).
Passing parameters to SQL statements
####################################
As shown in previous example, passing parameters to SQL statements happens by using placeholders in the statement. By default
MariaDB Connector/Python uses a question mark as a placeholder, for compatibility reason also %s placeholders are supported. Passing
parameters is supported in methods :func:`~execute` and :func:`~executemany` of the cursor class.
Since |MCP| uses binary protocol, escaping strings or binary data like in other database drivers is not required.
.. code-block:: python
:linenos:
# update
sql= "UPDATE books SET price=? WHERE book_name=?"
data= (14.90, "Dream of the Red Chamber")
cursor.execute(sql, data)
# delete
sql= "DELETE FROM books WHERE id=?"
data= (4034,) # Don't forget a comma at the end!
cursor.execute(sql, data)
# insert
sql= "INSERT INTO books (book_name, author_name, price) VALUES (?, ?, ?)"
data= ("The Lord of the Rings", "J.R.R. Tolkien", 18.99)
Often there is a requirement to update, delete or insert multiple records. This could be done be using :func:`~execute` in
a loop, but much more effective is using the :func:`executemany` method, especially when using a MariaDB database server 10.2 and above, which supports a special "bulk" protocol. The executemany() works similiar to execute(), but accepts data as a list of tuples:
.. code-block:: python
:linenos:
# update
sql= "UPDATE books SET price=? WHERE book_name=?"
data= [(14.90, "Dream of the Red Chamber"),
(22.30, "The Master and Margarita"),
(17.10, "And Then There Were None")]
cursor.executemany(sql, data)
# delete
sql= "DELETE FROM books WHERE id=?"
data= [(4034,),(12001,),(230,)]
cursor.executemany(sql, data)
#insert
sql= "INSERT INTO books (book_name, author_name, price) VALUES (?, ?, ?)"
data= [("The Lord of the Rings", "J.R.R. Tolkien", 18.99),
("Le Petit Prince", "Antoine de Saint-Exupéry", 22.40),
("Dream of the Red Chamber", "Cao Xueqin", 16.90),
("The Adventures of Pinocchio", "Carlo Collodi", 17.10)]
cursor.executemany(sql, data)
When using executemany(), there are a few restrictions:
- All tuples must have the same types as in first tuple. E.g. the parameter [(1),(1.0)] or [(1),(None)] are invalid.
- Special values like None or column default value needs to be indicated by an indicator.
Using indicators
****************
In certain situations, for example when inserting default values or NULL, special indicators must be used.
.. code-block:: python
:linenos:
cursor.execute("CREATE TABLE cakes(id int, cake varchar(100), price decimal(10,2) default 1.99)")
sql= "INSERT INTO cakes (id, cake, price) VALUES (?,?)"
data= [(1, "Cherry Cake", 2.10), (2, "Apple Cake", mariadb.indicator_default)]
cursor.executemany(sql, data)
Beside the default indicator which inserts the default value of 1.99, the following indicators are supported:
* indicator_ignore: Ignores the value (only update commands)
* indicator_null: Value is NULL
* indicator_row: Don't update or insert row
.. note::
* Mixing different parameter styles is not supported and will raise an exception
* The Python string operator % must not be used. The :func:`~execute` method accepts a tuple or list as second parameter.
* Placeholders between quotation marks are interpreted as a string.
* Parameters for :func:`~execute` needs to be passed as a tuple. If only one parameter will be passed, tuple needs to contain a comma at the end.
* Parameters for :func:`~executemany` need to be passed as a list of tuples.
Supported Data types
--------------------

312
docs/usage.html Normal file
View File

@ -0,0 +1,312 @@
<!DOCTYPE html>
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<meta charset="utf-8" />
<title>Basic usage &#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 mariadb module" href="module.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="module.html" title="The mariadb module"
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="basic-usage">
<h1>Basic usage<a class="headerlink" href="#basic-usage" title="Permalink to this headline"></a></h1>
<div class="section" id="connecting">
<h2>Connecting<a class="headerlink" href="#connecting" title="Permalink to this headline"></a></h2>
<p>The basic usage of MariaDB Connector/Python is similiar to other database drivers which
implement DB API 2.0 (PEP-249).</p>
<p>Below is a simple example of a typical use of MariaDB Connector/Python</p>
<div class="highlight-python notranslate"><table class="highlighttable"><tr><td class="linenos"><div class="linenodiv"><pre> 1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28</pre></div></td><td class="code"><div class="highlight"><pre><span></span><span class="c1"># Import MariaDB Connector/Python module</span>
<span class="kn">import</span> <span class="nn">mariadb</span>
<span class="c1"># Establish a connection</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">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">cursor</span><span class="o">=</span> <span class="n">connection</span><span class="o">.</span><span class="n">cursor</span><span class="p">()</span>
<span class="c1"># Create a database table</span>
<span class="n">cursor</span><span class="o">.</span><span class="n">execute</span><span class="p">(</span><span class="s2">&quot;DROP TABLE IF EXISTS mytest&quot;</span><span class="p">)</span>
<span class="n">cursor</span><span class="o">.</span><span class="n">execute</span><span class="p">(</span><span class="s2">&quot;CREATE TABLE mytest(id INT UNSIGNED AUTO_INCREMENT PRIMARY KEY,&quot;</span>
<span class="s2">&quot;first_name VARCHAR(100), last_name VARCHAR(100))&quot;</span><span class="p">)</span>
<span class="c1"># Populate table with some data</span>
<span class="n">cursor</span><span class="o">.</span><span class="n">execute</span><span class="p">(</span><span class="s2">&quot;INSERT INTO mytest(first_name, last_name) VALUES (?,?)&quot;</span><span class="p">,</span>
<span class="p">(</span><span class="s2">&quot;Robert&quot;</span><span class="p">,</span> <span class="s2">&quot;Redford&quot;</span><span class="p">))</span>
<span class="c1"># retrieve data</span>
<span class="n">cursor</span><span class="o">.</span><span class="n">execute</span><span class="p">(</span><span class="s2">&quot;SELECT id, first_name, last_name FROM mytest&quot;</span><span class="p">)</span>
<span class="c1"># print content</span>
<span class="n">row</span><span class="o">=</span> <span class="n">cursor</span><span class="o">.</span><span class="n">fetchone</span><span class="p">()</span>
<span class="nb">print</span><span class="p">(</span><span class="o">*</span><span class="n">row</span><span class="p">,</span> <span class="n">sep</span><span class="o">=</span><span class="s1">&#39;</span><span class="se">\t</span><span class="s1">&#39;</span><span class="p">)</span>
<span class="c1"># free resources</span>
<span class="n">cursor</span><span class="o">.</span><span class="n">close</span><span class="p">()</span>
<span class="n">connection</span><span class="o">.</span><span class="n">close</span><span class="p">()</span>
</pre></div>
</td></tr></table></div>
<p>Before MariaDB Connector/Python can be used, the MariaDB Connector/Python module must be
imported (line #2)
Once the mariadb module is loaded, a connection to a database server will be established
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> (line #5).</p>
<p>In order to be able to communicate with the database server in the form of SQL statements,
a cursor object must be created first (line #7).</p>
<p>The method name cursor may be a little misleading: unlike a cursor in MariaDB that can only
read and return data, a cursor in Python can be used for all types of SQL statements.</p>
<p>After creating the table mytest, everything is ready to insert some data (line #16): Column values
that are to be inserted in the database are identified by place holders, the data is then passed in
the form of a tuple as a second parameter (line #16).</p>
<p>After creating and populating the table mytest the cursor will be used to retrieve the data (line #20 - line#23).</p>
</div>
<div class="section" id="passing-parameters-to-sql-statements">
<h2>Passing parameters to SQL statements<a class="headerlink" href="#passing-parameters-to-sql-statements" title="Permalink to this headline"></a></h2>
<p>As shown in previous example, passing parameters to SQL statements happens by using placeholders in the statement. By default
MariaDB Connector/Python uses a question mark as a placeholder, for compatibility reason also %s placeholders are supported. Passing
parameters is supported in methods <a class="reference internal" href="cursor.html#execute" title="execute"><code class="xref py py-func docutils literal notranslate"><span class="pre">execute()</span></code></a> and <a class="reference internal" href="cursor.html#executemany" title="executemany"><code class="xref py py-func docutils literal notranslate"><span class="pre">executemany()</span></code></a> of the cursor class.</p>
<p>Since MariaDB Connector/Python uses binary protocol, escaping strings or binary data like in other database drivers is not required.</p>
<div class="highlight-python notranslate"><table class="highlighttable"><tr><td class="linenos"><div class="linenodiv"><pre> 1
2
3
4
5
6
7
8
9
10
11
12
13
14</pre></div></td><td class="code"><div class="highlight"><pre><span></span><span class="c1"># update</span>
<span class="n">sql</span><span class="o">=</span> <span class="s2">&quot;UPDATE books SET price=? WHERE book_name=?&quot;</span>
<span class="n">data</span><span class="o">=</span> <span class="p">(</span><span class="mf">14.90</span><span class="p">,</span> <span class="s2">&quot;Dream of the Red Chamber&quot;</span><span class="p">)</span>
<span class="n">cursor</span><span class="o">.</span><span class="n">execute</span><span class="p">(</span><span class="n">sql</span><span class="p">,</span> <span class="n">data</span><span class="p">)</span>
<span class="c1"># delete</span>
<span class="n">sql</span><span class="o">=</span> <span class="s2">&quot;DELETE FROM books WHERE id=?&quot;</span>
<span class="n">data</span><span class="o">=</span> <span class="p">(</span><span class="mi">4034</span><span class="p">,)</span> <span class="c1"># Don&#39;t forget a comma at the end!</span>
<span class="n">cursor</span><span class="o">.</span><span class="n">execute</span><span class="p">(</span><span class="n">sql</span><span class="p">,</span> <span class="n">data</span><span class="p">)</span>
<span class="c1"># insert</span>
<span class="n">sql</span><span class="o">=</span> <span class="s2">&quot;INSERT INTO books (book_name, author_name, price) VALUES (?, ?, ?)&quot;</span>
<span class="n">data</span><span class="o">=</span> <span class="p">(</span><span class="s2">&quot;The Lord of the Rings&quot;</span><span class="p">,</span> <span class="s2">&quot;J.R.R. Tolkien&quot;</span><span class="p">,</span> <span class="mf">18.99</span><span class="p">)</span>
</pre></div>
</td></tr></table></div>
<p>Often there is a requirement to update, delete or insert multiple records. This could be done be using <a class="reference internal" href="cursor.html#execute" title="execute"><code class="xref py py-func docutils literal notranslate"><span class="pre">execute()</span></code></a> in
a loop, but much more effective is using the <a class="reference internal" href="cursor.html#executemany" title="executemany"><code class="xref py py-func docutils literal notranslate"><span class="pre">executemany()</span></code></a> method, especially when using a MariaDB database server 10.2 and above, which supports a special “bulk” protocol. The executemany() works similiar to execute(), but accepts data as a list of tuples:</p>
<div class="highlight-python notranslate"><table class="highlighttable"><tr><td class="linenos"><div class="linenodiv"><pre> 1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19</pre></div></td><td class="code"><div class="highlight"><pre><span></span><span class="c1"># update</span>
<span class="n">sql</span><span class="o">=</span> <span class="s2">&quot;UPDATE books SET price=? WHERE book_name=?&quot;</span>
<span class="n">data</span><span class="o">=</span> <span class="p">[(</span><span class="mf">14.90</span><span class="p">,</span> <span class="s2">&quot;Dream of the Red Chamber&quot;</span><span class="p">),</span>
<span class="p">(</span><span class="mf">22.30</span><span class="p">,</span> <span class="s2">&quot;The Master and Margarita&quot;</span><span class="p">),</span>
<span class="p">(</span><span class="mf">17.10</span><span class="p">,</span> <span class="s2">&quot;And Then There Were None&quot;</span><span class="p">)]</span>
<span class="n">cursor</span><span class="o">.</span><span class="n">executemany</span><span class="p">(</span><span class="n">sql</span><span class="p">,</span> <span class="n">data</span><span class="p">)</span>
<span class="c1"># delete</span>
<span class="n">sql</span><span class="o">=</span> <span class="s2">&quot;DELETE FROM books WHERE id=?&quot;</span>
<span class="n">data</span><span class="o">=</span> <span class="p">[(</span><span class="mi">4034</span><span class="p">,),(</span><span class="mi">12001</span><span class="p">,),(</span><span class="mi">230</span><span class="p">,)]</span>
<span class="n">cursor</span><span class="o">.</span><span class="n">executemany</span><span class="p">(</span><span class="n">sql</span><span class="p">,</span> <span class="n">data</span><span class="p">)</span>
<span class="c1">#insert</span>
<span class="n">sql</span><span class="o">=</span> <span class="s2">&quot;INSERT INTO books (book_name, author_name, price) VALUES (?, ?, ?)&quot;</span>
<span class="n">data</span><span class="o">=</span> <span class="p">[(</span><span class="s2">&quot;The Lord of the Rings&quot;</span><span class="p">,</span> <span class="s2">&quot;J.R.R. Tolkien&quot;</span><span class="p">,</span> <span class="mf">18.99</span><span class="p">),</span>
<span class="p">(</span><span class="s2">&quot;Le Petit Prince&quot;</span><span class="p">,</span> <span class="s2">&quot;Antoine de Saint-Exupéry&quot;</span><span class="p">,</span> <span class="mf">22.40</span><span class="p">),</span>
<span class="p">(</span><span class="s2">&quot;Dream of the Red Chamber&quot;</span><span class="p">,</span> <span class="s2">&quot;Cao Xueqin&quot;</span><span class="p">,</span> <span class="mf">16.90</span><span class="p">),</span>
<span class="p">(</span><span class="s2">&quot;The Adventures of Pinocchio&quot;</span><span class="p">,</span> <span class="s2">&quot;Carlo Collodi&quot;</span><span class="p">,</span> <span class="mf">17.10</span><span class="p">)]</span>
<span class="n">cursor</span><span class="o">.</span><span class="n">executemany</span><span class="p">(</span><span class="n">sql</span><span class="p">,</span> <span class="n">data</span><span class="p">)</span>
</pre></div>
</td></tr></table></div>
<p>When using executemany(), there are a few restrictions:
- All tuples must have the same types as in first tuple. E.g. the parameter [(1),(1.0)] or [(1),(None)] are invalid.
- Special values like None or column default value needs to be indicated by an indicator.</p>
<div class="section" id="using-indicators">
<h3>Using indicators<a class="headerlink" href="#using-indicators" title="Permalink to this headline"></a></h3>
<p>In certain situations, for example when inserting default values or NULL, special indicators must be used.</p>
<div class="highlight-python notranslate"><table class="highlighttable"><tr><td class="linenos"><div class="linenodiv"><pre>1
2
3
4
5</pre></div></td><td class="code"><div class="highlight"><pre><span></span><span class="n">cursor</span><span class="o">.</span><span class="n">execute</span><span class="p">(</span><span class="s2">&quot;CREATE TABLE cakes(id int, cake varchar(100), price decimal(10,2) default 1.99)&quot;</span><span class="p">)</span>
<span class="n">sql</span><span class="o">=</span> <span class="s2">&quot;INSERT INTO cakes (id, cake, price) VALUES (?,?)&quot;</span>
<span class="n">data</span><span class="o">=</span> <span class="p">[(</span><span class="mi">1</span><span class="p">,</span> <span class="s2">&quot;Cherry Cake&quot;</span><span class="p">,</span> <span class="mf">2.10</span><span class="p">),</span> <span class="p">(</span><span class="mi">2</span><span class="p">,</span> <span class="s2">&quot;Apple Cake&quot;</span><span class="p">,</span> <span class="n">mariadb</span><span class="o">.</span><span class="n">indicator_default</span><span class="p">)]</span>
<span class="n">cursor</span><span class="o">.</span><span class="n">executemany</span><span class="p">(</span><span class="n">sql</span><span class="p">,</span> <span class="n">data</span><span class="p">)</span>
</pre></div>
</td></tr></table></div>
<dl class="simple">
<dt>Beside the default indicator which inserts the default value of 1.99, the following indicators are supported:</dt><dd><ul class="simple">
<li><p>indicator_ignore: Ignores the value (only update commands)</p></li>
<li><p>indicator_null: Value is NULL</p></li>
<li><p>indicator_row: Dont update or insert row</p></li>
</ul>
</dd>
</dl>
<div class="admonition note">
<p class="admonition-title">Note</p>
<ul class="simple">
<li><p>Mixing different parameter styles is not supported and will raise an exception</p></li>
<li><p>The Python string operator % must not be used. The <a class="reference internal" href="cursor.html#execute" title="execute"><code class="xref py py-func docutils literal notranslate"><span class="pre">execute()</span></code></a> method accepts a tuple or list as second parameter.</p></li>
<li><p>Placeholders between quotation marks are interpreted as a string.</p></li>
<li><p>Parameters for <a class="reference internal" href="cursor.html#execute" title="execute"><code class="xref py py-func docutils literal notranslate"><span class="pre">execute()</span></code></a> needs to be passed as a tuple. If only one parameter will be passed, tuple needs to contain a comma at the end.</p></li>
<li><p>Parameters for <a class="reference internal" href="cursor.html#executemany" title="executemany"><code class="xref py py-func docutils literal notranslate"><span class="pre">executemany()</span></code></a> need to be passed as a list of tuples.</p></li>
</ul>
</div>
<div class="section" id="supported-data-types">
<h4>Supported Data types<a class="headerlink" href="#supported-data-types" title="Permalink to this headline"></a></h4>
</div>
</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="#">Basic usage</a><ul>
<li><a class="reference internal" href="#connecting">Connecting</a></li>
<li><a class="reference internal" href="#passing-parameters-to-sql-statements">Passing parameters to SQL statements</a><ul>
<li><a class="reference internal" href="#using-indicators">Using indicators</a><ul>
<li><a class="reference internal" href="#supported-data-types">Supported Data types</a></li>
</ul>
</li>
</ul>
</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="module.html"
title="next chapter">The mariadb module</a></p>
<div role="note" aria-label="source link">
<h3>This Page</h3>
<ul class="this-page-menu">
<li><a href="_sources/usage.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="module.html" title="The mariadb module"
>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>