front page

brainboxdotcc · Jul 15, 2024 · 5302caf · 5302caf
1 parent 053e232
commit 5302caf
Show file tree

Hide file tree

Showing 60 changed files with 407 additions and 133 deletions.
diff --git a/Doxyfile b/Doxyfile
@@ -749,7 +749,7 @@ WARN_LOGFILE	   =
 # spaces.
 # Note: If this tag is empty the current directory is searched.
 
-INPUT		  = database.h config.h
+INPUT		  = database.h config.h README.md
 
 # This tag can be used to specify the character encoding of the source files
 # that doxygen parses. Internally doxygen uses the UTF-8 encoding. Doxygen uses

diff --git a/docs/annotated.html b/docs/annotated.html
@@ -97,7 +97,7 @@
 <!-- start footer part -->
 <div id="nav-path" class="navpath"><!-- id is needed for treeview function! -->
   <ul>
-    <li class="footer">Generated on Mon Jul 15 2024 12:46:34 for DPP-MySQL by <a href="https://www.doxygen.org/index.html"><img class="footer" src="doxygen.svg" width="104" height="31" alt="doxygen"/></a> 1.9.1 </li>
+    <li class="footer">Generated on Mon Jul 15 2024 12:49:59 for DPP-MySQL by <a href="https://www.doxygen.org/index.html"><img class="footer" src="doxygen.svg" width="104" height="31" alt="doxygen"/></a> 1.9.1 </li>
   </ul>
 </div>
 </body>

diff --git a/docs/classes.html b/docs/classes.html
@@ -97,7 +97,7 @@
 <!-- start footer part -->
 <div id="nav-path" class="navpath"><!-- id is needed for treeview function! -->
   <ul>
-    <li class="footer">Generated on Mon Jul 15 2024 12:46:34 for DPP-MySQL by <a href="https://www.doxygen.org/index.html"><img class="footer" src="doxygen.svg" width="104" height="31" alt="doxygen"/></a> 1.9.1 </li>
+    <li class="footer">Generated on Mon Jul 15 2024 12:49:59 for DPP-MySQL by <a href="https://www.doxygen.org/index.html"><img class="footer" src="doxygen.svg" width="104" height="31" alt="doxygen"/></a> 1.9.1 </li>
   </ul>
 </div>
 </body>

diff --git a/docs/deprecated.html b/docs/deprecated.html
@@ -98,7 +98,7 @@
 <!-- start footer part -->
 <div id="nav-path" class="navpath"><!-- id is needed for treeview function! -->
   <ul>
-    <li class="footer">Generated on Mon Jul 15 2024 12:46:34 for DPP-MySQL by <a href="https://www.doxygen.org/index.html"><img class="footer" src="doxygen.svg" width="104" height="31" alt="doxygen"/></a> 1.9.1 </li>
+    <li class="footer">Generated on Mon Jul 15 2024 12:49:59 for DPP-MySQL by <a href="https://www.doxygen.org/index.html"><img class="footer" src="doxygen.svg" width="104" height="31" alt="doxygen"/></a> 1.9.1 </li>
   </ul>
 </div>
 </body>

diff --git a/docs/functions.html b/docs/functions.html
@@ -125,7 +125,7 @@
 <!-- start footer part -->
 <div id="nav-path" class="navpath"><!-- id is needed for treeview function! -->
   <ul>
-    <li class="footer">Generated on Mon Jul 15 2024 12:46:34 for DPP-MySQL by <a href="https://www.doxygen.org/index.html"><img class="footer" src="doxygen.svg" width="104" height="31" alt="doxygen"/></a> 1.9.1 </li>
+    <li class="footer">Generated on Mon Jul 15 2024 12:49:59 for DPP-MySQL by <a href="https://www.doxygen.org/index.html"><img class="footer" src="doxygen.svg" width="104" height="31" alt="doxygen"/></a> 1.9.1 </li>
   </ul>
 </div>
 </body>

diff --git a/docs/functions_func.html b/docs/functions_func.html
@@ -116,7 +116,7 @@
 <!-- start footer part -->
 <div id="nav-path" class="navpath"><!-- id is needed for treeview function! -->
   <ul>
-    <li class="footer">Generated on Mon Jul 15 2024 12:46:34 for DPP-MySQL by <a href="https://www.doxygen.org/index.html"><img class="footer" src="doxygen.svg" width="104" height="31" alt="doxygen"/></a> 1.9.1 </li>
+    <li class="footer">Generated on Mon Jul 15 2024 12:49:59 for DPP-MySQL by <a href="https://www.doxygen.org/index.html"><img class="footer" src="doxygen.svg" width="104" height="31" alt="doxygen"/></a> 1.9.1 </li>
   </ul>
 </div>
 </body>

diff --git a/docs/functions_vars.html b/docs/functions_vars.html
@@ -98,7 +98,7 @@
 <!-- start footer part -->
 <div id="nav-path" class="navpath"><!-- id is needed for treeview function! -->
   <ul>
-    <li class="footer">Generated on Mon Jul 15 2024 12:46:35 for DPP-MySQL by <a href="https://www.doxygen.org/index.html"><img class="footer" src="doxygen.svg" width="104" height="31" alt="doxygen"/></a> 1.9.1 </li>
+    <li class="footer">Generated on Mon Jul 15 2024 12:49:59 for DPP-MySQL by <a href="https://www.doxygen.org/index.html"><img class="footer" src="doxygen.svg" width="104" height="31" alt="doxygen"/></a> 1.9.1 </li>
   </ul>
 </div>
 </body>

diff --git a/docs/graph_legend.html b/docs/graph_legend.html
@@ -151,7 +151,7 @@
 <!-- start footer part -->
 <div id="nav-path" class="navpath"><!-- id is needed for treeview function! -->
   <ul>
-    <li class="footer">Generated on Mon Jul 15 2024 12:46:34 for DPP-MySQL by <a href="https://www.doxygen.org/index.html"><img class="footer" src="doxygen.svg" width="104" height="31" alt="doxygen"/></a> 1.9.1 </li>
+    <li class="footer">Generated on Mon Jul 15 2024 12:49:59 for DPP-MySQL by <a href="https://www.doxygen.org/index.html"><img class="footer" src="doxygen.svg" width="104" height="31" alt="doxygen"/></a> 1.9.1 </li>
   </ul>
 </div>
 </body>

diff --git a/docs/index.html b/docs/index.html
@@ -5,7 +5,7 @@
 <meta http-equiv="X-UA-Compatible" content="IE=9"/>
 <meta name="generator" content="Doxygen 1.9.1"/>
 <meta name="viewport" content="width=device-width, initial-scale=1"/>
-<title>DPP-MySQL: Main Page</title>
+<title>DPP-MySQL: A simple asynchronous MySQL wrapper for D++ bots</title>
 <link href="tabs.css" rel="stylesheet" type="text/css"/>
 <script type="text/javascript" src="jquery.js"></script>
 <script type="text/javascript" src="dynsections.js"></script>
@@ -81,17 +81,110 @@
 </iframe>
 </div>
 
-<div class="header">
+<div class="PageDoc"><div class="header">
   <div class="headertitle">
-<div class="title">DPP-MySQL Documentation</div>  </div>
+<div class="title">A simple asynchronous MySQL wrapper for D++ bots </div>  </div>
 </div><!--header-->
 <div class="contents">
+<div class="textblock"><p><a class="anchor" id="md_README"></a> Simply take the source files and add them to your D++ bot project. This is a slightly modified version of what is used in my own bots.</p>
+<p>This wrapper supports both synchronous (blocking) API and asynchronous (coroutine) API, alongside callback based async. All queries done through this wrapper use cached prepared statements, this will consume a very small amount of ram for a sometimes drastic increase in performance.</p>
+<p>It is thread safe, however be aware that different threads may run queries that may intrude into other threads transactions. If you need ACID transaction safety, you should only use <code><a class="el" href="namespacedb.html#a7cba5870abb1d49fe0f9fe17dd8ef15f" title="Start an SQL transaction in a coroutine that can be awaited. SQL transactions are atomic in nature,...">db::co_transaction()</a></code> or <code><a class="el" href="namespacedb.html#a2b4f92b15fde6491a19818b96b0d79d9" title="Start an SQL transaction. SQL transactions are atomic in nature, ALL other queries will be forced to ...">db::transaction()</a></code> and ensure all queries within use <code><a class="el" href="namespacedb.html#a8e64d322c430542846327f26e9d00ff6" title="Run a mysql query, with automatic escaping of parameters to prevent SQL injection.">db::query()</a></code>.</p>
+<p>No support is offered for this software at present. Your mileage may vary. I have only ever used this wrapper on Linux.</p>
+<p><b>Detecting and linking the dependencies (libmysqlclient.so etc) is currently your responsibility. No package mangagement or build script is provided.</b></p>
+<h1><a class="anchor" id="autotoc_md1"></a>
+Documentation</h1>
+<p>Doxygen documentation can be found on <a href="https://brainboxdotcc.github.io/dpp-mysql/">github pages</a>. It can be re-generated by running 'doxygen'</p>
+<h1><a class="anchor" id="autotoc_md2"></a>
+Dependencies</h1>
+<ul>
+<li>libmysqlclient-dev</li>
+<li>D++</li>
+<li>fmtlib</li>
+<li>A C++ compiler capable of building D++ bots with coroutine support, if you want to use the asynchronous interface</li>
+</ul>
+<h1><a class="anchor" id="autotoc_md3"></a>
+Documentation</h1>
+<p>All functions in the <code>db</code> namespace have Doxygen comment blocks.</p>
+<h1><a class="anchor" id="autotoc_md4"></a>
+Using the wrapper</h1>
+<h2><a class="anchor" id="autotoc_md5"></a>
+Simple Queries</h2>
+<p>This is an example of using the asynchronous interface:</p>
+<div class="fragment"><div class="line"><span class="preprocessor">#include &lt;dpp/dpp.h&gt;</span></div>
+<div class="line"><span class="preprocessor">#include &quot;database.h&quot;</span></div>
+<div class="line"><span class="preprocessor">#include &quot;config.h&quot;</span></div>
+<div class="line"> </div>
+<div class="line"><span class="keywordtype">int</span> main(<span class="keywordtype">int</span> argc, <span class="keywordtype">char</span> <span class="keyword">const</span> *argv[]) {</div>
+<div class="line">    <a class="code" href="namespaceconfig.html#a3b6fc04da34bbdb59ec978612c865538">config::init</a>(<span class="stringliteral">&quot;config.json&quot;</span>);</div>
+<div class="line">    dpp::cluster bot(<a class="code" href="namespaceconfig.html#abda9d2a5f8aaf27890a20b26c1cd2f10">config::get</a>(<span class="stringliteral">&quot;token&quot;</span>));</div>
+<div class="line"> </div>
+<div class="line">    bot.on_ready([&amp;bot](<span class="keyword">const</span> dpp::ready_t&amp; event) -&gt; dpp::task&lt;void&gt; {</div>
+<div class="line"> </div>
+<div class="line">        <span class="keyword">auto</span> rs = co_await <a class="code" href="namespacedb.html#af873c3dbbe3724ee0e31953ade03f2bd">db::co_query</a>(<span class="stringliteral">&quot;SELECT * FROM bigtable WHERE bar = ?&quot;</span>, { <span class="stringliteral">&quot;baz&quot;</span> });</div>
+<div class="line">        <span class="keywordflow">if</span> (!rs.ok()) {</div>
+<div class="line">            std::cout &lt;&lt; <span class="stringliteral">&quot;SQL error: &quot;</span> &lt;&lt; rs.error &lt;&lt; <span class="stringliteral">&quot;\n&quot;</span>;</div>
+<div class="line">            co_return;</div>
+<div class="line">        }</div>
+<div class="line"> </div>
+<div class="line">        std::cout &lt;&lt; <span class="stringliteral">&quot;Number of rows returned: &quot;</span> &lt;&lt; rs.size() &lt;&lt; <span class="stringliteral">&quot;\n&quot;</span>;</div>
+<div class="line">        <span class="keywordflow">if</span> (!rs.empty()) {</div>
+<div class="line">            std::cout &lt;&lt; <span class="stringliteral">&quot;First row &#39;bar&#39; value: &quot;</span> &lt;&lt; rs[0].at(<span class="stringliteral">&quot;bar&quot;</span>) &lt;&lt; <span class="stringliteral">&quot;\n&quot;</span>;</div>
+<div class="line">        }</div>
+<div class="line"> </div>
+<div class="line">        co_return;</div>
+<div class="line">    });</div>
+<div class="line"> </div>
+<div class="line">    <a class="code" href="namespacedb.html#a8a004a2115b829e9f7258f4f65fcbe0b">db::init</a>(bot);</div>
+<div class="line">    bot.start(dpp::st_wait);</div>
+<div class="line">}</div>
+<div class="ttc" id="anamespaceconfig_html_a3b6fc04da34bbdb59ec978612c865538"><div class="ttname"><a href="namespaceconfig.html#a3b6fc04da34bbdb59ec978612c865538">config::init</a></div><div class="ttdeci">void init(const std::string &amp;config_file)</div><div class="ttdoc">Initialise config file.</div></div>
+<div class="ttc" id="anamespaceconfig_html_abda9d2a5f8aaf27890a20b26c1cd2f10"><div class="ttname"><a href="namespaceconfig.html#abda9d2a5f8aaf27890a20b26c1cd2f10">config::get</a></div><div class="ttdeci">json &amp; get(const std::string &amp;key=&quot;&quot;)</div><div class="ttdoc">Get all config values from a specific key.</div></div>
+<div class="ttc" id="anamespacedb_html_a8a004a2115b829e9f7258f4f65fcbe0b"><div class="ttname"><a href="namespacedb.html#a8a004a2115b829e9f7258f4f65fcbe0b">db::init</a></div><div class="ttdeci">void init(dpp::cluster &amp;bot)</div><div class="ttdoc">Initialise database connection.</div></div>
+<div class="ttc" id="anamespacedb_html_af873c3dbbe3724ee0e31953ade03f2bd"><div class="ttname"><a href="namespacedb.html#af873c3dbbe3724ee0e31953ade03f2bd">db::co_query</a></div><div class="ttdeci">dpp::async&lt; resultset &gt; co_query(const std::string &amp;format, const paramlist &amp;parameters={})</div><div class="ttdoc">Run a mysql query, with automatic escaping of parameters to prevent SQL injection....</div></div>
+</div><!-- fragment --><p>Also create a <code>config.json</code> file. To use unix sockets to connect, set the port value to <code>0</code> and the hostname value to <code>localhost</code>.</p>
+<div class="fragment"><div class="line">{</div>
+<div class="line">    &quot;token&quot;: &quot;discord bot token&quot;,</div>
+<div class="line">    &quot;database&quot;: {</div>
+<div class="line">        &quot;host&quot;: &quot;hostname&quot;,</div>
+<div class="line">        &quot;username&quot;: &quot;database username&quot;,</div>
+<div class="line">        &quot;password&quot;: &quot;database password&quot;,</div>
+<div class="line">        &quot;database&quot;: &quot;schema name&quot;,</div>
+<div class="line">        &quot;port&quot;: 0,</div>
+<div class="line">        &quot;socket&quot;: &quot;/path/to/mysqld.sock&quot;</div>
+<div class="line">    }</div>
+<div class="line">}</div>
+</div><!-- fragment --><h2><a class="anchor" id="autotoc_md6"></a>
+Using Transactions</h2>
+<p>To use transactions, wrap the transaction in the <code><a class="el" href="namespacedb.html#a2b4f92b15fde6491a19818b96b0d79d9" title="Start an SQL transaction. SQL transactions are atomic in nature, ALL other queries will be forced to ...">db::transaction</a></code> function, and use only the <code><a class="el" href="namespacedb.html#a8e64d322c430542846327f26e9d00ff6" title="Run a mysql query, with automatic escaping of parameters to prevent SQL injection.">db::query</a></code> function within it for queries. Return true to commit the transaction, or throw any exception or return false to roll back the transaction.</p>
+<p>Note that during a transaction all other queries will be forced to wait until the transaction is completed. Transactions are asynchronous, so use the callback to be notified when it completes, or use co_transaction as below:</p>
+<div class="fragment"><div class="line"><span class="preprocessor">#include &lt;dpp/dpp.h&gt;</span></div>
+<div class="line"><span class="preprocessor">#include &quot;database.h&quot;</span></div>
+<div class="line"><span class="preprocessor">#include &quot;config.h&quot;</span></div>
+<div class="line"> </div>
+<div class="line"><span class="keywordtype">int</span> main(<span class="keywordtype">int</span> argc, <span class="keywordtype">char</span> <span class="keyword">const</span> *argv[]) {</div>
+<div class="line">    <a class="code" href="namespaceconfig.html#a3b6fc04da34bbdb59ec978612c865538">config::init</a>(<span class="stringliteral">&quot;config.json&quot;</span>);</div>
+<div class="line">    dpp::cluster bot(<a class="code" href="namespaceconfig.html#abda9d2a5f8aaf27890a20b26c1cd2f10">config::get</a>(<span class="stringliteral">&quot;token&quot;</span>));</div>
+<div class="line"> </div>
+<div class="line">    bot.on_ready([&amp;bot](<span class="keyword">const</span> dpp::ready_t&amp; event) -&gt; dpp::task&lt;void&gt; {</div>
+<div class="line">        co_await <a class="code" href="namespacedb.html#a7cba5870abb1d49fe0f9fe17dd8ef15f">db::co_transaction</a>([event]() -&gt; <span class="keywordtype">bool</span> {</div>
+<div class="line">            <span class="keyword">auto</span> rs = <a class="code" href="namespacedb.html#a8e64d322c430542846327f26e9d00ff6">db::query</a>(<span class="stringliteral">&quot;SELECT current FROM data&quot;</span>);</div>
+<div class="line">            <a class="code" href="namespacedb.html#a8e64d322c430542846327f26e9d00ff6">db::query</a>(<span class="stringliteral">&quot;UPDATE data SET previous = ?&quot;</span>, { rs[0].at(<span class="stringliteral">&quot;data&quot;</span>) });</div>
+<div class="line">            <span class="keywordflow">return</span> <span class="keyword">true</span>;</div>
+<div class="line">        });</div>
+<div class="line">    });</div>
+<div class="line"> </div>
+<div class="line">    <a class="code" href="namespacedb.html#a8a004a2115b829e9f7258f4f65fcbe0b">db::init</a>(bot);</div>
+<div class="line">    bot.start(dpp::st_wait);</div>
+<div class="line">}</div>
+<div class="ttc" id="anamespacedb_html_a7cba5870abb1d49fe0f9fe17dd8ef15f"><div class="ttname"><a href="namespacedb.html#a7cba5870abb1d49fe0f9fe17dd8ef15f">db::co_transaction</a></div><div class="ttdeci">dpp::async&lt; resultset &gt; co_transaction(std::function&lt; bool()&gt; closure)</div><div class="ttdoc">Start an SQL transaction in a coroutine that can be awaited. SQL transactions are atomic in nature,...</div></div>
+<div class="ttc" id="anamespacedb_html_a8e64d322c430542846327f26e9d00ff6"><div class="ttname"><a href="namespacedb.html#a8e64d322c430542846327f26e9d00ff6">db::query</a></div><div class="ttdeci">resultset query(const std::string &amp;format, const paramlist &amp;parameters={})</div><div class="ttdoc">Run a mysql query, with automatic escaping of parameters to prevent SQL injection.</div></div>
+</div><!-- fragment --> </div></div><!-- PageDoc -->
 </div><!-- contents -->
 </div><!-- doc-content -->
 <!-- start footer part -->
 <div id="nav-path" class="navpath"><!-- id is needed for treeview function! -->
   <ul>
-    <li class="footer">Generated on Mon Jul 15 2024 12:46:34 for DPP-MySQL by <a href="https://www.doxygen.org/index.html"><img class="footer" src="doxygen.svg" width="104" height="31" alt="doxygen"/></a> 1.9.1 </li>
+    <li class="footer">Generated on Mon Jul 15 2024 12:49:59 for DPP-MySQL by <a href="https://www.doxygen.org/index.html"><img class="footer" src="doxygen.svg" width="104" height="31" alt="doxygen"/></a> 1.9.1 </li>
   </ul>
 </div>
 </body>

diff --git a/docs/namespaceconfig.html b/docs/namespaceconfig.html
@@ -185,7 +185,7 @@ <h2 class="memtitle"><span class="permalink"><a href="#a3b6fc04da34bbdb59ec97861
 <div id="nav-path" class="navpath"><!-- id is needed for treeview function! -->
   <ul>
     <li class="navelem"><a class="el" href="namespaceconfig.html">config</a></li>
-    <li class="footer">Generated on Mon Jul 15 2024 12:46:34 for DPP-MySQL by <a href="https://www.doxygen.org/index.html"><img class="footer" src="doxygen.svg" width="104" height="31" alt="doxygen"/></a> 1.9.1 </li>
+    <li class="footer">Generated on Mon Jul 15 2024 12:49:59 for DPP-MySQL by <a href="https://www.doxygen.org/index.html"><img class="footer" src="doxygen.svg" width="104" height="31" alt="doxygen"/></a> 1.9.1 </li>
   </ul>
 </div>
 </body>

diff --git a/docs/namespacedb.html b/docs/namespacedb.html
@@ -674,7 +674,7 @@ <h2 class="memtitle"><span class="permalink"><a href="#a2b4f92b15fde6491a19818b9
 <div id="nav-path" class="navpath"><!-- id is needed for treeview function! -->
   <ul>
     <li class="navelem"><a class="el" href="namespacedb.html">db</a></li>
-    <li class="footer">Generated on Mon Jul 15 2024 12:46:34 for DPP-MySQL by <a href="https://www.doxygen.org/index.html"><img class="footer" src="doxygen.svg" width="104" height="31" alt="doxygen"/></a> 1.9.1 </li>
+    <li class="footer">Generated on Mon Jul 15 2024 12:49:59 for DPP-MySQL by <a href="https://www.doxygen.org/index.html"><img class="footer" src="doxygen.svg" width="104" height="31" alt="doxygen"/></a> 1.9.1 </li>
   </ul>
 </div>
 </body>

diff --git a/docs/namespacemembers.html b/docs/namespacemembers.html
@@ -144,7 +144,7 @@
 <!-- start footer part -->
 <div id="nav-path" class="navpath"><!-- id is needed for treeview function! -->
   <ul>
-    <li class="footer">Generated on Mon Jul 15 2024 12:46:34 for DPP-MySQL by <a href="https://www.doxygen.org/index.html"><img class="footer" src="doxygen.svg" width="104" height="31" alt="doxygen"/></a> 1.9.1 </li>
+    <li class="footer">Generated on Mon Jul 15 2024 12:49:59 for DPP-MySQL by <a href="https://www.doxygen.org/index.html"><img class="footer" src="doxygen.svg" width="104" height="31" alt="doxygen"/></a> 1.9.1 </li>
   </ul>
 </div>
 </body>

diff --git a/docs/namespacemembers_func.html b/docs/namespacemembers_func.html
@@ -132,7 +132,7 @@
 <!-- start footer part -->
 <div id="nav-path" class="navpath"><!-- id is needed for treeview function! -->
   <ul>
-    <li class="footer">Generated on Mon Jul 15 2024 12:46:34 for DPP-MySQL by <a href="https://www.doxygen.org/index.html"><img class="footer" src="doxygen.svg" width="104" height="31" alt="doxygen"/></a> 1.9.1 </li>
+    <li class="footer">Generated on Mon Jul 15 2024 12:49:59 for DPP-MySQL by <a href="https://www.doxygen.org/index.html"><img class="footer" src="doxygen.svg" width="104" height="31" alt="doxygen"/></a> 1.9.1 </li>
   </ul>
 </div>
 </body>