<!DOCTYPE html> <html> <head> <meta charset="utf-8" /> <meta id="repository-name" content="github.com/crystal-lang/crystal-db"> <link href="css/style.css" rel="stylesheet" type="text/css" /> <script type="text/javascript" src="js/doc.js"></script> <title>README - github.com/crystal-lang/crystal-db</title> </head> <body> <div id="types-list"> <div id="search-box"> <input type="search" id="search-input" placeholder="Search..."> </div> <ul> <li class="current"><a href="index.html">README</a></li> </ul> <ul> <li class="parent " data-id="github.com/crystal-lang/crystal-db/DB" data-name="db"> <a href="DB.html">DB</a> <ul> <li class=" " data-id="github.com/crystal-lang/crystal-db/DB/Any" data-name="db::any"> <a href="DB/Any.html">Any</a> </li> <li class=" " data-id="github.com/crystal-lang/crystal-db/DB/BeginTransaction" data-name="db::begintransaction"> <a href="DB/BeginTransaction.html">BeginTransaction</a> </li> <li class=" " data-id="github.com/crystal-lang/crystal-db/DB/Connection" data-name="db::connection"> <a href="DB/Connection.html">Connection</a> </li> <li class=" " data-id="github.com/crystal-lang/crystal-db/DB/ConnectionLost" data-name="db::connectionlost"> <a href="DB/ConnectionLost.html">ConnectionLost</a> </li> <li class=" " data-id="github.com/crystal-lang/crystal-db/DB/ConnectionRefused" data-name="db::connectionrefused"> <a href="DB/ConnectionRefused.html">ConnectionRefused</a> </li> <li class=" " data-id="github.com/crystal-lang/crystal-db/DB/Database" data-name="db::database"> <a href="DB/Database.html">Database</a> </li> <li class=" " data-id="github.com/crystal-lang/crystal-db/DB/Disposable" data-name="db::disposable"> <a href="DB/Disposable.html">Disposable</a> </li> <li class=" " data-id="github.com/crystal-lang/crystal-db/DB/Driver" data-name="db::driver"> <a href="DB/Driver.html">Driver</a> </li> <li class=" " data-id="github.com/crystal-lang/crystal-db/DB/Error" data-name="db::error"> <a href="DB/Error.html">Error</a> </li> <li class=" " data-id="github.com/crystal-lang/crystal-db/DB/ExecResult" data-name="db::execresult"> <a href="DB/ExecResult.html">ExecResult</a> </li> <li class=" " data-id="github.com/crystal-lang/crystal-db/DB/Mappable" data-name="db::mappable"> <a href="DB/Mappable.html">Mappable</a> </li> <li class=" " data-id="github.com/crystal-lang/crystal-db/DB/MappingException" data-name="db::mappingexception"> <a href="DB/MappingException.html">MappingException</a> </li> <li class="parent " data-id="github.com/crystal-lang/crystal-db/DB/Pool" data-name="db::pool(t)"> <a href="DB/Pool.html">Pool</a> <ul> <li class=" " data-id="github.com/crystal-lang/crystal-db/DB/Pool/TimeoutHelper" data-name="db::pool::timeouthelper"> <a href="DB/Pool/TimeoutHelper.html">TimeoutHelper</a> </li> </ul> </li> <li class=" " data-id="github.com/crystal-lang/crystal-db/DB/PoolPreparedStatement" data-name="db::poolpreparedstatement"> <a href="DB/PoolPreparedStatement.html">PoolPreparedStatement</a> </li> <li class=" " data-id="github.com/crystal-lang/crystal-db/DB/PoolRetryAttemptsExceeded" data-name="db::poolretryattemptsexceeded"> <a href="DB/PoolRetryAttemptsExceeded.html">PoolRetryAttemptsExceeded</a> </li> <li class=" " data-id="github.com/crystal-lang/crystal-db/DB/PoolStatement" data-name="db::poolstatement"> <a href="DB/PoolStatement.html">PoolStatement</a> </li> <li class=" " data-id="github.com/crystal-lang/crystal-db/DB/PoolTimeout" data-name="db::pooltimeout"> <a href="DB/PoolTimeout.html">PoolTimeout</a> </li> <li class=" " data-id="github.com/crystal-lang/crystal-db/DB/PoolUnpreparedStatement" data-name="db::poolunpreparedstatement"> <a href="DB/PoolUnpreparedStatement.html">PoolUnpreparedStatement</a> </li> <li class=" " data-id="github.com/crystal-lang/crystal-db/DB/QueryMethods" data-name="db::querymethods"> <a href="DB/QueryMethods.html">QueryMethods</a> </li> <li class=" " data-id="github.com/crystal-lang/crystal-db/DB/ResultSet" data-name="db::resultset"> <a href="DB/ResultSet.html">ResultSet</a> </li> <li class=" " data-id="github.com/crystal-lang/crystal-db/DB/Rollback" data-name="db::rollback"> <a href="DB/Rollback.html">Rollback</a> </li> <li class=" " data-id="github.com/crystal-lang/crystal-db/DB/SavePointTransaction" data-name="db::savepointtransaction"> <a href="DB/SavePointTransaction.html">SavePointTransaction</a> </li> <li class="parent " data-id="github.com/crystal-lang/crystal-db/DB/SessionMethods" data-name="db::sessionmethods(session, stmt)"> <a href="DB/SessionMethods.html">SessionMethods</a> <ul> <li class=" " data-id="github.com/crystal-lang/crystal-db/DB/SessionMethods/PreparedQuery" data-name="db::sessionmethods::preparedquery(session, stmt)"> <a href="DB/SessionMethods/PreparedQuery.html">PreparedQuery</a> </li> <li class=" " data-id="github.com/crystal-lang/crystal-db/DB/SessionMethods/UnpreparedQuery" data-name="db::sessionmethods::unpreparedquery(session, stmt)"> <a href="DB/SessionMethods/UnpreparedQuery.html">UnpreparedQuery</a> </li> </ul> </li> <li class=" " data-id="github.com/crystal-lang/crystal-db/DB/Statement" data-name="db::statement"> <a href="DB/Statement.html">Statement</a> </li> <li class=" " data-id="github.com/crystal-lang/crystal-db/DB/StatementMethods" data-name="db::statementmethods"> <a href="DB/StatementMethods.html">StatementMethods</a> </li> <li class=" " data-id="github.com/crystal-lang/crystal-db/DB/StringKeyCache" data-name="db::stringkeycache(t)"> <a href="DB/StringKeyCache.html">StringKeyCache</a> </li> <li class=" " data-id="github.com/crystal-lang/crystal-db/DB/TopLevelTransaction" data-name="db::topleveltransaction"> <a href="DB/TopLevelTransaction.html">TopLevelTransaction</a> </li> <li class=" " data-id="github.com/crystal-lang/crystal-db/DB/Transaction" data-name="db::transaction"> <a href="DB/Transaction.html">Transaction</a> </li> </ul> </li> </ul> </div> <div id="main-content"> <p><a href="https://travis-ci.org/crystal-lang/crystal-db" target="_blank"><img src="https://travis-ci.org/crystal-lang/crystal-db.svg?branch=master" alt="Build Status"/></a></p> <h1>crystal-db</h1> <p>Common db api for crystal. You will need to a specific driver to access a database.</p> <ul><li><a href="https://github.com/crystal-lang/crystal-sqlite3" target="_blank">sqlite</a></li><li><a href="https://github.com/crystal-lang/crystal-mysql" target="_blank">mysql</a></li><li><a href="https://github.com/will/crystal-pg" target="_blank">postgres</a></li></ul> <h2>Installation</h2> <p>Add this to your application's <code>shard.yml</code>:</p> <pre><code class='language-yaml'>dependencies: db: github: crystal-lang/crystal-db</code></pre> <h2>Usage</h2> <p>Since this is an abstract db api, it's usage is through a concrete database driver.</p> <pre><code class='language-crystal'><span class="k">require</span> <span class="s">"db"</span> <span class="k">require</span> <span class="s">"sqlite3"</span> <span class="t">DB</span>.open <span class="s">"sqlite3:./file.db"</span> <span class="k">do</span> <span class="o">|</span>db<span class="o">|</span> db.exec <span class="s">"create table contacts (name string, age integer)"</span> db.exec <span class="s">"insert into contacts values (?, ?)"</span>, <span class="s">"John Doe"</span>, <span class="n">30</span> args <span class="o">=</span> <span class="o">[]</span> <span class="k">of</span> <span class="t">DB</span><span class="t">::</span><span class="t">Any</span> args <span class="o"><<</span> <span class="s">"Sarah"</span> args <span class="o"><<</span> <span class="n">33</span> db.exec <span class="s">"insert into contacts values (?, ?)"</span>, args puts <span class="s">"max age:"</span> puts db.scalar <span class="s">"select max(age) from contacts"</span> <span class="c"># => 33</span> puts <span class="s">"contacts:"</span> db.query <span class="s">"select name, age from contacts order by age desc"</span> <span class="k">do</span> <span class="o">|</span>rs<span class="o">|</span> puts <span class="s">"</span><span class="i">#{</span></span>rs.column_name(<span class="n">0</span>)<span class="s"><span class="i">}</span> (</span><span class="i">#{</span></span>rs.column_name(<span class="n">1</span>)<span class="s"><span class="i">}</span>)"</span> <span class="c"># => name (age)</span> rs.each <span class="k">do</span> puts <span class="s">"</span><span class="i">#{</span></span>rs.read(<span class="t">String</span>)<span class="s"><span class="i">}</span> (</span><span class="i">#{</span></span>rs.read(<span class="t">Int32</span>)<span class="s"><span class="i">}</span>)"</span> <span class="c"># => Sarah (33)</span> <span class="c"># => John Doe (30)</span> <span class="k">end</span> <span class="k">end</span> <span class="k">end</span></code></pre> <h2>Roadmap</h2> <p>Issues not yet addressed</p> <ul><li>[x] Support non prepared statements. <a href="https://github.com/crystal-lang/crystal-db/pull/25" target="_blank">#25</a></li><li>[x] Time data type. (implementation details depends on actual drivers)</li><li>[x] Data type extensibility. Allow each driver to extend the data types allowed.</li><li>[x] Transactions & nested transactions. <a href="https://github.com/crystal-lang/crystal-db/pull/27" target="_blank">#27</a></li><li>[x] Connection pool.</li><li>[ ] Direct access to <code>IO</code> to avoid memory allocation for blobs.</li></ul> <h2>Contributing</h2> <ol><li>Fork it ( https://github.com/crystal-lang/crystal-db/fork )</li><li>Create your feature branch (git checkout -b my-new-feature)</li><li>Commit your changes (git commit -am 'Add some feature')</li><li>Push to the branch (git push origin my-new-feature)</li><li>Create a new Pull Request</li></ol> <h2>Contributors</h2> <ul><li><a href="https://github.com/bcardiff" target="_blank">bcardiff</a> Brian J. Cardiff - creator, maintainer</li></ul> </div> </body> </html>