444 lines
16 KiB
HTML
444 lines
16 KiB
HTML
<!DOCTYPE html>
|
|
<html lang="en">
|
|
<head>
|
|
<meta charset="utf-8" />
|
|
<meta http-equiv="X-UA-Compatible" content="IE=edge">
|
|
<meta name="viewport" content="width=device-width, initial-scale=1.0">
|
|
<meta name="generator" content="Crystal Docs 1.5.1">
|
|
<meta name="crystal_docs.project_version" content="0.13.1">
|
|
<meta name="crystal_docs.project_name" content="db">
|
|
|
|
|
|
|
|
<link href="css/style.css" rel="stylesheet" type="text/css" />
|
|
<script type="text/javascript" src="js/doc.js"></script>
|
|
|
|
<meta name="repository-name" content="db">
|
|
<title>db 0.13.1</title>
|
|
<script type="text/javascript">
|
|
CrystalDocs.base_path = "";
|
|
</script>
|
|
</head>
|
|
<body>
|
|
|
|
<svg class="hidden">
|
|
<symbol id="octicon-link" viewBox="0 0 16 16">
|
|
<path fill="currentColor" fill-rule="evenodd" d="M4 9h1v1H4c-1.5 0-3-1.69-3-3.5S2.55 3 4 3h4c1.45 0 3 1.69 3 3.5 0 1.41-.91 2.72-2 3.25V8.59c.58-.45 1-1.27 1-2.09C10 5.22 8.98 4 8 4H4c-.98 0-2 1.22-2 2.5S3 9 4 9zm9-3h-1v1h1c1 0 2 1.22 2 2.5S13.98 12 13 12H9c-.98 0-2-1.22-2-2.5 0-.83.42-1.64 1-2.09V6.25c-1.09.53-2 1.84-2 3.25C6 11.31 7.55 13 9 13h4c1.45 0 3-1.69 3-3.5S14.5 6 13 6z"></path>
|
|
</symbol>
|
|
</svg>
|
|
<input type="checkbox" id="sidebar-btn">
|
|
<label for="sidebar-btn" id="sidebar-btn-label">
|
|
<svg class="open" xmlns="http://www.w3.org/2000/svg" height="2em" width="2em" viewBox="0 0 512 512"><title>Open Sidebar</title><path fill="currentColor" d="M80 96v64h352V96H80zm0 112v64h352v-64H80zm0 112v64h352v-64H80z"></path></svg>
|
|
<svg class="close" xmlns="http://www.w3.org/2000/svg" width="2em" height="2em" viewBox="0 0 512 512"><title>Close Sidebar</title><path fill="currentColor" d="m118.6 73.4-45.2 45.2L210.7 256 73.4 393.4l45.2 45.2L256 301.3l137.4 137.3 45.2-45.2L301.3 256l137.3-137.4-45.2-45.2L256 210.7Z"></path></svg>
|
|
</label>
|
|
<div class="sidebar">
|
|
<div class="sidebar-header">
|
|
<div class="search-box">
|
|
<input type="search" class="search-input" placeholder="Search..." spellcheck="false" aria-label="Search">
|
|
</div>
|
|
|
|
<div class="project-summary">
|
|
<h1 class="project-name">
|
|
<a href="index.html">
|
|
db
|
|
</a>
|
|
</h1>
|
|
|
|
<span class="project-version">
|
|
0.13.1
|
|
</span>
|
|
</div>
|
|
</div>
|
|
|
|
<div class="search-results hidden">
|
|
<ul class="search-list"></ul>
|
|
</div>
|
|
|
|
<div class="types-list">
|
|
<ul>
|
|
|
|
<li class="parent " data-id="db/DB" data-name="db">
|
|
<a href="DB.html">DB</a>
|
|
|
|
<ul>
|
|
|
|
<li class=" " data-id="db/DB/Any" data-name="db::any">
|
|
<a href="DB/Any.html">Any</a>
|
|
|
|
</li>
|
|
|
|
<li class=" " data-id="db/DB/BeginTransaction" data-name="db::begintransaction">
|
|
<a href="DB/BeginTransaction.html">BeginTransaction</a>
|
|
|
|
</li>
|
|
|
|
<li class=" " data-id="db/DB/ColumnTypeMismatchError" data-name="db::columntypemismatcherror">
|
|
<a href="DB/ColumnTypeMismatchError.html">ColumnTypeMismatchError</a>
|
|
|
|
</li>
|
|
|
|
<li class="parent " data-id="db/DB/Connection" data-name="db::connection">
|
|
<a href="DB/Connection.html">Connection</a>
|
|
|
|
<ul>
|
|
|
|
<li class=" " data-id="db/DB/Connection/Options" data-name="db::connection::options">
|
|
<a href="DB/Connection/Options.html">Options</a>
|
|
|
|
</li>
|
|
|
|
</ul>
|
|
|
|
|
|
</li>
|
|
|
|
<li class=" " data-id="db/DB/ConnectionBuilder" data-name="db::connectionbuilder">
|
|
<a href="DB/ConnectionBuilder.html">ConnectionBuilder</a>
|
|
|
|
</li>
|
|
|
|
<li class=" " data-id="db/DB/ConnectionContext" data-name="db::connectioncontext">
|
|
<a href="DB/ConnectionContext.html">ConnectionContext</a>
|
|
|
|
</li>
|
|
|
|
<li class=" " data-id="db/DB/ConnectionLost" data-name="db::connectionlost">
|
|
<a href="DB/ConnectionLost.html">ConnectionLost</a>
|
|
|
|
</li>
|
|
|
|
<li class=" " data-id="db/DB/ConnectionRefused" data-name="db::connectionrefused">
|
|
<a href="DB/ConnectionRefused.html">ConnectionRefused</a>
|
|
|
|
</li>
|
|
|
|
<li class=" " data-id="db/DB/Database" data-name="db::database">
|
|
<a href="DB/Database.html">Database</a>
|
|
|
|
</li>
|
|
|
|
<li class=" " data-id="db/DB/Disposable" data-name="db::disposable">
|
|
<a href="DB/Disposable.html">Disposable</a>
|
|
|
|
</li>
|
|
|
|
<li class=" " data-id="db/DB/Driver" data-name="db::driver">
|
|
<a href="DB/Driver.html">Driver</a>
|
|
|
|
</li>
|
|
|
|
<li class="parent " data-id="db/DB/DriverSpecs" data-name="db::driverspecs(dbanytype)">
|
|
<a href="DB/DriverSpecs.html">DriverSpecs</a>
|
|
|
|
<ul>
|
|
|
|
<li class=" " data-id="db/DB/DriverSpecs/ColumnDef" data-name="db::driverspecs::columndef">
|
|
<a href="DB/DriverSpecs/ColumnDef.html">ColumnDef</a>
|
|
|
|
</li>
|
|
|
|
</ul>
|
|
|
|
|
|
</li>
|
|
|
|
<li class=" " data-id="db/DB/Error" data-name="db::error">
|
|
<a href="DB/Error.html">Error</a>
|
|
|
|
</li>
|
|
|
|
<li class=" " data-id="db/DB/ExecResult" data-name="db::execresult">
|
|
<a href="DB/ExecResult.html">ExecResult</a>
|
|
|
|
</li>
|
|
|
|
<li class=" " data-id="db/DB/Field" data-name="db::field">
|
|
<a href="DB/Field.html">Field</a>
|
|
|
|
</li>
|
|
|
|
<li class=" " data-id="db/DB/Mappable" data-name="db::mappable">
|
|
<a href="DB/Mappable.html">Mappable</a>
|
|
|
|
</li>
|
|
|
|
<li class=" " data-id="db/DB/MappingException" data-name="db::mappingexception">
|
|
<a href="DB/MappingException.html">MappingException</a>
|
|
|
|
</li>
|
|
|
|
<li class=" " data-id="db/DB/MetadataValueConverter" data-name="db::metadatavalueconverter">
|
|
<a href="DB/MetadataValueConverter.html">MetadataValueConverter</a>
|
|
|
|
</li>
|
|
|
|
<li class=" " data-id="db/DB/NoResultsError" data-name="db::noresultserror">
|
|
<a href="DB/NoResultsError.html">NoResultsError</a>
|
|
|
|
</li>
|
|
|
|
<li class="parent " data-id="db/DB/Pool" data-name="db::pool(t)">
|
|
<a href="DB/Pool.html">Pool</a>
|
|
|
|
<ul>
|
|
|
|
<li class=" " data-id="db/DB/Pool/Options" data-name="db::pool::options">
|
|
<a href="DB/Pool/Options.html">Options</a>
|
|
|
|
</li>
|
|
|
|
<li class=" " data-id="db/DB/Pool/Stats" data-name="db::pool::stats">
|
|
<a href="DB/Pool/Stats.html">Stats</a>
|
|
|
|
</li>
|
|
|
|
</ul>
|
|
|
|
|
|
</li>
|
|
|
|
<li class=" " data-id="db/DB/PoolPreparedStatement" data-name="db::poolpreparedstatement">
|
|
<a href="DB/PoolPreparedStatement.html">PoolPreparedStatement</a>
|
|
|
|
</li>
|
|
|
|
<li class=" " data-id="db/DB/PoolResourceLost" data-name="db::poolresourcelost(t)">
|
|
<a href="DB/PoolResourceLost.html">PoolResourceLost</a>
|
|
|
|
</li>
|
|
|
|
<li class=" " data-id="db/DB/PoolResourceRefused" data-name="db::poolresourcerefused">
|
|
<a href="DB/PoolResourceRefused.html">PoolResourceRefused</a>
|
|
|
|
</li>
|
|
|
|
<li class=" " data-id="db/DB/PoolRetryAttemptsExceeded" data-name="db::poolretryattemptsexceeded">
|
|
<a href="DB/PoolRetryAttemptsExceeded.html">PoolRetryAttemptsExceeded</a>
|
|
|
|
</li>
|
|
|
|
<li class=" " data-id="db/DB/PoolStatement" data-name="db::poolstatement">
|
|
<a href="DB/PoolStatement.html">PoolStatement</a>
|
|
|
|
</li>
|
|
|
|
<li class=" " data-id="db/DB/PoolTimeout" data-name="db::pooltimeout">
|
|
<a href="DB/PoolTimeout.html">PoolTimeout</a>
|
|
|
|
</li>
|
|
|
|
<li class=" " data-id="db/DB/PoolUnpreparedStatement" data-name="db::poolunpreparedstatement">
|
|
<a href="DB/PoolUnpreparedStatement.html">PoolUnpreparedStatement</a>
|
|
|
|
</li>
|
|
|
|
<li class=" " data-id="db/DB/QueryMethods" data-name="db::querymethods(stmt)">
|
|
<a href="DB/QueryMethods.html">QueryMethods</a>
|
|
|
|
</li>
|
|
|
|
<li class=" " data-id="db/DB/ResultSet" data-name="db::resultset">
|
|
<a href="DB/ResultSet.html">ResultSet</a>
|
|
|
|
</li>
|
|
|
|
<li class=" " data-id="db/DB/Rollback" data-name="db::rollback">
|
|
<a href="DB/Rollback.html">Rollback</a>
|
|
|
|
</li>
|
|
|
|
<li class=" " data-id="db/DB/SavePointTransaction" data-name="db::savepointtransaction">
|
|
<a href="DB/SavePointTransaction.html">SavePointTransaction</a>
|
|
|
|
</li>
|
|
|
|
<li class="parent " data-id="db/DB/Serializable" data-name="db::serializable">
|
|
<a href="DB/Serializable.html">Serializable</a>
|
|
|
|
<ul>
|
|
|
|
<li class=" " data-id="db/DB/Serializable/NonStrict" data-name="db::serializable::nonstrict">
|
|
<a href="DB/Serializable/NonStrict.html">NonStrict</a>
|
|
|
|
</li>
|
|
|
|
</ul>
|
|
|
|
|
|
</li>
|
|
|
|
<li class="parent " data-id="db/DB/SessionMethods" data-name="db::sessionmethods(session, stmt)">
|
|
<a href="DB/SessionMethods.html">SessionMethods</a>
|
|
|
|
<ul>
|
|
|
|
<li class=" " data-id="db/DB/SessionMethods/PreparedQuery" data-name="db::sessionmethods::preparedquery(session, stmt)">
|
|
<a href="DB/SessionMethods/PreparedQuery.html">PreparedQuery</a>
|
|
|
|
</li>
|
|
|
|
<li class=" " data-id="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="db/DB/Statement" data-name="db::statement">
|
|
<a href="DB/Statement.html">Statement</a>
|
|
|
|
</li>
|
|
|
|
<li class=" " data-id="db/DB/StatementMethods" data-name="db::statementmethods">
|
|
<a href="DB/StatementMethods.html">StatementMethods</a>
|
|
|
|
</li>
|
|
|
|
<li class=" " data-id="db/DB/StringKeyCache" data-name="db::stringkeycache(t)">
|
|
<a href="DB/StringKeyCache.html">StringKeyCache</a>
|
|
|
|
</li>
|
|
|
|
<li class=" " data-id="db/DB/TopLevelTransaction" data-name="db::topleveltransaction">
|
|
<a href="DB/TopLevelTransaction.html">TopLevelTransaction</a>
|
|
|
|
</li>
|
|
|
|
<li class=" " data-id="db/DB/Transaction" data-name="db::transaction">
|
|
<a href="DB/Transaction.html">Transaction</a>
|
|
|
|
</li>
|
|
|
|
</ul>
|
|
|
|
|
|
</li>
|
|
|
|
<li class=" " data-id="db/Enum" data-name="enum">
|
|
<a href="Enum.html">Enum</a>
|
|
|
|
</li>
|
|
|
|
</ul>
|
|
|
|
</div>
|
|
</div>
|
|
|
|
|
|
<div class="main-content">
|
|
<p><a href="https://github.com/crystal-lang/crystal-db/actions?query=workflow:CI+event:push+branch:master"><img src="https://github.com/crystal-lang/crystal-db/workflows/CI/badge.svg" alt="Build Status" /></a></p>
|
|
<h1><a id="crystal-db" class="anchor" href="#crystal-db">
|
|
<svg class="octicon-link" aria-hidden="true">
|
|
<use href="#octicon-link"/>
|
|
</svg>
|
|
</a>crystal-db</h1>
|
|
<p>Common db api for crystal. You will need to have a specific driver to access a database.</p>
|
|
<ul>
|
|
<li><a href="https://github.com/crystal-lang/crystal-sqlite3">SQLite</a></li>
|
|
<li><a href="https://github.com/crystal-lang/crystal-mysql">MySQL</a></li>
|
|
<li><a href="https://github.com/will/crystal-pg">PostgreSQL</a></li>
|
|
<li><a href="https://github.com/naqvis/crystal-odbc">ODBC</a></li>
|
|
<li><a href="https://github.com/kaukas/crystal-cassandra">Cassandra</a></li>
|
|
<li><a href="https://github.com/amauryt/crystal-duckdb">DuckDB</a></li>
|
|
<li><a href="https://github.com/wonderix/crystal-tds">Microsoft SQL Server</a></li>
|
|
</ul>
|
|
<h2><a id="installation" class="anchor" href="#installation">
|
|
<svg class="octicon-link" aria-hidden="true">
|
|
<use href="#octicon-link"/>
|
|
</svg>
|
|
</a>Installation</h2>
|
|
<p>If you are creating a shard that will work with <em>any</em> driver, then add <code>crystal-db</code> as a dependency in <code>shard.yml</code>:</p>
|
|
<pre><code class="language-yaml">dependencies:
|
|
db:
|
|
github: crystal-lang/crystal-db</code></pre>
|
|
<p>If you are creating an application that will work with <em>some specific</em> driver(s), then add them in <code>shard.yml</code>:</p>
|
|
<pre><code class="language-yaml">dependencies:
|
|
sqlite3:
|
|
github: crystal-lang/crystal-sqlite3</code></pre>
|
|
<p><code>crystal-db</code> itself will be a nested dependency if drivers are included.</p>
|
|
<p>Note: Multiple drivers can be included in the same application.</p>
|
|
<h2><a id="documentation" class="anchor" href="#documentation">
|
|
<svg class="octicon-link" aria-hidden="true">
|
|
<use href="#octicon-link"/>
|
|
</svg>
|
|
</a>Documentation</h2>
|
|
<ul>
|
|
<li><a href="https://crystal-lang.github.io/crystal-db/api/latest/">Latest API</a></li>
|
|
<li><a href="https://crystal-lang.org/docs/database/">Crystal book</a></li>
|
|
</ul>
|
|
<h2><a id="usage" class="anchor" href="#usage">
|
|
<svg class="octicon-link" aria-hidden="true">
|
|
<use href="#octicon-link"/>
|
|
</svg>
|
|
</a>Usage</h2>
|
|
<p>This shard only provides an abstract database API. In order to use it, a specific driver for the intended database has to be required as well:</p>
|
|
<p>The following example uses SQLite where <code>?</code> indicates the arguments. If PostgreSQL is used <code>$1</code>, <code>$2</code>, etc. should be used. <code>crystal-db</code> does not interpret the statements.</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>
|
|
<span class="c"># When using the pg driver, use $1, $2, etc. instead of ?</span>
|
|
db.exec <span class="s">"create table contacts (name text, 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: 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>rs.column_name(<span class="n">0</span>)<span class="i">}</span><span class="s"> (</span><span class="i">#{</span>rs.column_name(<span class="n">1</span>)<span class="i">}</span><span class="s">)"</span>
|
|
<span class="c"># => name (age)</span>
|
|
rs.each <span class="k">do</span>
|
|
puts <span class="s">"</span><span class="i">#{</span>rs.read(<span class="t">String</span>)<span class="i">}</span><span class="s"> (</span><span class="i">#{</span>rs.read(<span class="t">Int32</span>)<span class="i">}</span><span class="s">)"</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><a id="roadmap" class="anchor" href="#roadmap">
|
|
<svg class="octicon-link" aria-hidden="true">
|
|
<use href="#octicon-link"/>
|
|
</svg>
|
|
</a>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">#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">#27</a></li>
|
|
<li>[x] Connection pool.</li>
|
|
<li>[x] Logging</li>
|
|
<li>[ ] Direct access to <code>IO</code> to avoid memory allocation for blobs.</li>
|
|
</ul>
|
|
<h2><a id="contributing" class="anchor" href="#contributing">
|
|
<svg class="octicon-link" aria-hidden="true">
|
|
<use href="#octicon-link"/>
|
|
</svg>
|
|
</a>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><a id="contributors" class="anchor" href="#contributors">
|
|
<svg class="octicon-link" aria-hidden="true">
|
|
<use href="#octicon-link"/>
|
|
</svg>
|
|
</a>Contributors</h2>
|
|
<ul>
|
|
<li><a href="https://github.com/bcardiff">bcardiff</a> Brian J. Cardiff - creator, maintainer</li>
|
|
</ul>
|
|
</div>
|
|
</body>
|
|
</html>
|