mirror of
https://gitea.invidious.io/iv-org/shard-crystal-db.git
synced 2024-08-15 00:53:32 +00:00
734 lines
25 KiB
HTML
734 lines
25 KiB
HTML
|
<!DOCTYPE html>
|
||
|
<html lang="en">
|
||
|
<head>
|
||
|
<meta charset="utf-8" />
|
||
|
<meta http-equiv="X-UA-Compatible" content="IE=edge">
|
||
|
<meta name="generator" content="Crystal Docs 0.34.0">
|
||
|
<meta name="crystal_docs.project_version" content="0.9.0">
|
||
|
<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>
|
||
|
|
||
|
<svg class="hidden">
|
||
|
<symbol id="octicon-link" viewBox="0 0 16 16">
|
||
|
<path 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>
|
||
|
|
||
|
<meta id="repository-name" content="db">
|
||
|
<title>DB - db 0.9.0</title>
|
||
|
<script type="text/javascript">
|
||
|
CrystalDocs.base_path = "";
|
||
|
</script>
|
||
|
</head>
|
||
|
<body>
|
||
|
|
||
|
<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.9.0
|
||
|
</span>
|
||
|
</div>
|
||
|
</div>
|
||
|
|
||
|
<div class="search-results" class="hidden">
|
||
|
<ul class="search-list"></ul>
|
||
|
</div>
|
||
|
|
||
|
<div class="types-list">
|
||
|
<ul>
|
||
|
|
||
|
<li class="parent open current" 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/Connection" data-name="db::connection">
|
||
|
<a href="DB/Connection.html">Connection</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/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/Stats" data-name="db::pool::stats">
|
||
|
<a href="DB/Pool/Stats.html">Stats</a>
|
||
|
|
||
|
</li>
|
||
|
|
||
|
<li class=" " data-id="db/DB/Pool/TimeoutHelper" data-name="db::pool::timeouthelper">
|
||
|
<a href="DB/Pool/TimeoutHelper.html">TimeoutHelper</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/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>
|
||
|
|
||
|
</ul>
|
||
|
|
||
|
</div>
|
||
|
</div>
|
||
|
|
||
|
|
||
|
<div class="main-content">
|
||
|
<h1 class="type-name">
|
||
|
|
||
|
<span class="kind">module</span> DB
|
||
|
|
||
|
</h1>
|
||
|
|
||
|
|
||
|
|
||
|
|
||
|
|
||
|
<h2>
|
||
|
<a id="overview" class="anchor" href="#overview">
|
||
|
<svg class="octicon-link" aria-hidden="true">
|
||
|
<use href="#octicon-link"/>
|
||
|
</svg>
|
||
|
</a>
|
||
|
Overview
|
||
|
</h2>
|
||
|
|
||
|
<p>The DB module is a unified interface for database access.
|
||
|
Individual database systems are supported by specific database driver shards.</p>
|
||
|
|
||
|
<p>Available drivers include:</p>
|
||
|
|
||
|
<ul><li><a href="https://github.com/crystal-lang/crystal-sqlite3" target="_blank">crystal-lang/crystal-sqlite3</a> for SQLite</li><li><a href="https://github.com/crystal-lang/crystal-mysql" target="_blank">crystal-lang/crystal-mysql</a> for MySQL and MariaDB</li><li><a href="https://github.com/will/crystal-pg" target="_blank">will/crystal-pg</a> for PostgreSQL</li><li><a href="https://github.com/kaukas/crystal-cassandra" target="_blank">kaukas/crystal-cassandra</a> for Cassandra</li></ul>
|
||
|
|
||
|
<p>For basic instructions on implementing a new database driver, check <code><a href="DB/Driver.html">Driver</a></code> and the existing drivers.</p>
|
||
|
|
||
|
<p>DB manages a connection pool. The connection pool can be configured by query parameters to the
|
||
|
connection <code>URI</code> as described in <code><a href="DB/Database.html">Database</a></code>.</p>
|
||
|
|
||
|
<h3><a id="usage" class="anchor" href="#usage">
|
||
|
<svg class="octicon-link" aria-hidden="true">
|
||
|
<use href="#octicon-link"/>
|
||
|
</svg>
|
||
|
</a>Usage</h3>
|
||
|
|
||
|
<p>Assuming <code>crystal-sqlite3</code> is included a SQLite3 database can be opened with <code><a href="DB.html#open(uri:URI%7CString)-class-method">#open</a></code>.</p>
|
||
|
|
||
|
<pre><code>db <span class="o">=</span> <span class="t">DB</span>.open <span class="s">"sqlite3:./path/to/db/file.db"</span>
|
||
|
db.close</code></pre>
|
||
|
|
||
|
<p>If a block is given to <code><a href="DB.html#open(uri:URI%7CString)-class-method">#open</a></code> the database is closed automatically</p>
|
||
|
|
||
|
<pre><code><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"># work with db</span>
|
||
|
<span class="k">end</span> <span class="c"># db is closed</span></code></pre>
|
||
|
|
||
|
<p>In the code above <code>db</code> is a <code><a href="DB/Database.html">Database</a></code>. Methods available for querying it are described in <code><a href="DB/QueryMethods.html">QueryMethods</a></code>.</p>
|
||
|
|
||
|
<p>Three kind of statements can be performed:</p>
|
||
|
|
||
|
<ol><li><code>Database#exec</code> waits no response from the database.</li><li><code>Database#scalar</code> reads a single value of the response.</li><li><code>Database#query</code> returns a ResultSet that allows iteration over the rows in the response and column information.</li></ol>
|
||
|
|
||
|
<p>All of the above methods allows parametrised query. Either positional or named arguments.</p>
|
||
|
|
||
|
<p>Check a full working version:</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><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="defined-in" class="anchor" href="#defined-in">
|
||
|
<svg class="octicon-link" aria-hidden="true">
|
||
|
<use href="#octicon-link"/>
|
||
|
</svg>
|
||
|
</a>
|
||
|
Defined in:
|
||
|
</h2>
|
||
|
|
||
|
|
||
|
|
||
|
|
||
|
|
||
|
<h2>
|
||
|
<a id="constant-summary" class="anchor" href="#constant-summary">
|
||
|
<svg class="octicon-link" aria-hidden="true">
|
||
|
<use href="#octicon-link"/>
|
||
|
</svg>
|
||
|
</a>
|
||
|
Constant Summary
|
||
|
</h2>
|
||
|
|
||
|
<dl>
|
||
|
|
||
|
<dt class="entry-const" id="TYPES">
|
||
|
<strong>TYPES</strong> = <code>[<span class="t">Nil</span>, <span class="t">String</span>, <span class="t">Bool</span>, <span class="t">Int32</span>, <span class="t">Int64</span>, <span class="t">Float32</span>, <span class="t">Float64</span>, <span class="t">Time</span>, <span class="t">Bytes</span>]</code>
|
||
|
</dt>
|
||
|
|
||
|
<dd class="entry-const-doc">
|
||
|
<p>Types supported to interface with database driver.
|
||
|
These can be used in any <code><a href="DB/ResultSet.html#read(**types:Class)-instance-method">ResultSet#read</a></code> or any <code>Database#query</code> related
|
||
|
method to be used as query parameters</p>
|
||
|
</dd>
|
||
|
|
||
|
|
||
|
<dt class="entry-const" id="VERSION">
|
||
|
<strong>VERSION</strong> = <code><span class="s">"0.9.0"</span></code>
|
||
|
</dt>
|
||
|
|
||
|
|
||
|
</dl>
|
||
|
|
||
|
|
||
|
|
||
|
|
||
|
|
||
|
<h2>
|
||
|
<a id="class-method-summary" class="anchor" href="#class-method-summary">
|
||
|
<svg class="octicon-link" aria-hidden="true">
|
||
|
<use href="#octicon-link"/>
|
||
|
</svg>
|
||
|
</a>
|
||
|
Class Method Summary
|
||
|
</h2>
|
||
|
<ul class="list-summary">
|
||
|
|
||
|
<li class="entry-summary">
|
||
|
<a href="#connect(uri:URI%7CString)-class-method" class="signature"><strong>.connect</strong>(uri : URI | String)</a>
|
||
|
|
||
|
<div class="summary"><p>Opens a connection using the specified <em>uri</em>.</p></div>
|
||
|
|
||
|
</li>
|
||
|
|
||
|
<li class="entry-summary">
|
||
|
<a href="#connect(uri:URI%7CString,&)-class-method" class="signature"><strong>.connect</strong>(uri : URI | String, &)</a>
|
||
|
|
||
|
<div class="summary"><p>Opens a connection using the specified <em>uri</em>.</p></div>
|
||
|
|
||
|
</li>
|
||
|
|
||
|
<li class="entry-summary">
|
||
|
<a href="#open(uri:URI%7CString)-class-method" class="signature"><strong>.open</strong>(uri : URI | String)</a>
|
||
|
|
||
|
<div class="summary"><p>Creates a <code><a href="DB/Database.html">Database</a></code> pool and opens initial connection(s) as specified in the connection <em>uri</em>.</p></div>
|
||
|
|
||
|
</li>
|
||
|
|
||
|
<li class="entry-summary">
|
||
|
<a href="#open(uri:URI%7CString,&)-class-method" class="signature"><strong>.open</strong>(uri : URI | String, &)</a>
|
||
|
|
||
|
<div class="summary"><p>Same as <code><a href="DB.html#open(uri:URI%7CString)-class-method">#open</a></code> but the database is yielded and closed automatically at the end of the block.</p></div>
|
||
|
|
||
|
</li>
|
||
|
|
||
|
<li class="entry-summary">
|
||
|
<a href="#register_driver(driver_name,driver_class:Driver.class)-class-method" class="signature"><strong>.register_driver</strong>(driver_name, driver_class : <span class="t">Driver</span>.<span class="k">class</span>)</a>
|
||
|
|
||
|
<div class="summary"><p>Registers a driver class for a given <em>driver_name</em>.</p></div>
|
||
|
|
||
|
</li>
|
||
|
|
||
|
</ul>
|
||
|
|
||
|
|
||
|
|
||
|
|
||
|
|
||
|
<h2>
|
||
|
<a id="macro-summary" class="anchor" href="#macro-summary">
|
||
|
<svg class="octicon-link" aria-hidden="true">
|
||
|
<use href="#octicon-link"/>
|
||
|
</svg>
|
||
|
</a>
|
||
|
Macro Summary
|
||
|
</h2>
|
||
|
<ul class="list-summary">
|
||
|
|
||
|
<li class="entry-summary">
|
||
|
<a href="#mapping(properties,strict=true)-macro" class="signature"><strong>mapping</strong>(properties, strict = <span class="n">true</span>)</a>
|
||
|
|
||
|
<div class="summary"><p>The <code><a href="DB.html#mapping(**properties)-macro">DB.mapping</a></code> macro defines how an object is built from a <code><a href="DB/ResultSet.html">ResultSet</a></code>.</p></div>
|
||
|
|
||
|
</li>
|
||
|
|
||
|
<li class="entry-summary">
|
||
|
<a href="#mapping(**properties)-macro" class="signature"><strong>mapping</strong>(**properties)</a>
|
||
|
|
||
|
</li>
|
||
|
|
||
|
</ul>
|
||
|
|
||
|
|
||
|
|
||
|
<div class="methods-inherited">
|
||
|
|
||
|
</div>
|
||
|
|
||
|
|
||
|
|
||
|
|
||
|
<h2>
|
||
|
<a id="class-method-detail" class="anchor" href="#class-method-detail">
|
||
|
<svg class="octicon-link" aria-hidden="true">
|
||
|
<use href="#octicon-link"/>
|
||
|
</svg>
|
||
|
</a>
|
||
|
Class Method Detail
|
||
|
</h2>
|
||
|
|
||
|
<div class="entry-detail" id="connect(uri:URI|String)-class-method">
|
||
|
<div class="signature">
|
||
|
|
||
|
def self.<strong>connect</strong>(uri : URI | String)
|
||
|
|
||
|
<a class="method-permalink" href="#connect(uri:URI%7CString)-class-method">#</a>
|
||
|
</div>
|
||
|
|
||
|
<div class="doc">
|
||
|
|
||
|
<p>Opens a connection using the specified <em>uri</em>.
|
||
|
The scheme of the <em>uri</em> determines the driver to use.
|
||
|
Returned connection must be closed by <code>Connection#close</code>.
|
||
|
If a block is used the connection is yielded and closed automatically.</p>
|
||
|
</div>
|
||
|
|
||
|
<br/>
|
||
|
<div>
|
||
|
|
||
|
</div>
|
||
|
</div>
|
||
|
|
||
|
<div class="entry-detail" id="connect(uri:URI|String,&)-class-method">
|
||
|
<div class="signature">
|
||
|
|
||
|
def self.<strong>connect</strong>(uri : URI | String, &)
|
||
|
|
||
|
<a class="method-permalink" href="#connect(uri:URI%7CString,&)-class-method">#</a>
|
||
|
</div>
|
||
|
|
||
|
<div class="doc">
|
||
|
|
||
|
<p>Opens a connection using the specified <em>uri</em>.
|
||
|
The scheme of the <em>uri</em> determines the driver to use.
|
||
|
Returned connection must be closed by <code>Connection#close</code>.
|
||
|
If a block is used the connection is yielded and closed automatically.</p>
|
||
|
</div>
|
||
|
|
||
|
<br/>
|
||
|
<div>
|
||
|
|
||
|
</div>
|
||
|
</div>
|
||
|
|
||
|
<div class="entry-detail" id="open(uri:URI|String)-class-method">
|
||
|
<div class="signature">
|
||
|
|
||
|
def self.<strong>open</strong>(uri : URI | String)
|
||
|
|
||
|
<a class="method-permalink" href="#open(uri:URI%7CString)-class-method">#</a>
|
||
|
</div>
|
||
|
|
||
|
<div class="doc">
|
||
|
|
||
|
<p>Creates a <code><a href="DB/Database.html">Database</a></code> pool and opens initial connection(s) as specified in the connection <em>uri</em>.
|
||
|
Use <code><a href="DB.html#connect(uri:URI%7CString)-class-method">DB#connect</a></code> to open a single connection.</p>
|
||
|
|
||
|
<p>The scheme of the <em>uri</em> determines the driver to use.
|
||
|
Connection parameters such as hostname, user, database name, etc. are specified according
|
||
|
to each database driver's specific format.</p>
|
||
|
|
||
|
<p>The returned database must be closed by <code><a href="DB/Database.html#close-instance-method">Database#close</a></code>.</p>
|
||
|
</div>
|
||
|
|
||
|
<br/>
|
||
|
<div>
|
||
|
|
||
|
</div>
|
||
|
</div>
|
||
|
|
||
|
<div class="entry-detail" id="open(uri:URI|String,&)-class-method">
|
||
|
<div class="signature">
|
||
|
|
||
|
def self.<strong>open</strong>(uri : URI | String, &)
|
||
|
|
||
|
<a class="method-permalink" href="#open(uri:URI%7CString,&)-class-method">#</a>
|
||
|
</div>
|
||
|
|
||
|
<div class="doc">
|
||
|
|
||
|
<p>Same as <code><a href="DB.html#open(uri:URI%7CString)-class-method">#open</a></code> but the database is yielded and closed automatically at the end of the block.</p>
|
||
|
</div>
|
||
|
|
||
|
<br/>
|
||
|
<div>
|
||
|
|
||
|
</div>
|
||
|
</div>
|
||
|
|
||
|
<div class="entry-detail" id="register_driver(driver_name,driver_class:Driver.class)-class-method">
|
||
|
<div class="signature">
|
||
|
|
||
|
def self.<strong>register_driver</strong>(driver_name, driver_class : <span class="t">Driver</span>.<span class="k">class</span>)
|
||
|
|
||
|
<a class="method-permalink" href="#register_driver(driver_name,driver_class:Driver.class)-class-method">#</a>
|
||
|
</div>
|
||
|
|
||
|
<div class="doc">
|
||
|
|
||
|
<p>Registers a driver class for a given <em>driver_name</em>.
|
||
|
Should be called by drivers implementors only.</p>
|
||
|
</div>
|
||
|
|
||
|
<br/>
|
||
|
<div>
|
||
|
|
||
|
</div>
|
||
|
</div>
|
||
|
|
||
|
|
||
|
|
||
|
|
||
|
|
||
|
|
||
|
<h2>
|
||
|
<a id="macro-detail" class="anchor" href="#macro-detail">
|
||
|
<svg class="octicon-link" aria-hidden="true">
|
||
|
<use href="#octicon-link"/>
|
||
|
</svg>
|
||
|
</a>
|
||
|
Macro Detail
|
||
|
</h2>
|
||
|
|
||
|
<div class="entry-detail" id="mapping(properties,strict=true)-macro">
|
||
|
<div class="signature">
|
||
|
|
||
|
macro <strong>mapping</strong>(properties, strict = <span class="n">true</span>)
|
||
|
|
||
|
<a class="method-permalink" href="#mapping(properties,strict=true)-macro">#</a>
|
||
|
</div>
|
||
|
|
||
|
<div class="doc">
|
||
|
|
||
|
<p>The <code><a href="DB.html#mapping(**properties)-macro">DB.mapping</a></code> macro defines how an object is built from a <code><a href="DB/ResultSet.html">ResultSet</a></code>.</p>
|
||
|
|
||
|
<p>It takes hash literal as argument, in which attributes and types are defined.
|
||
|
Once defined, <code><a href="DB/ResultSet.html#read(type:DB::Mappable.class)-instance-method">ResultSet#read(t)</a></code> populates properties of the class from the
|
||
|
<code><a href="DB/ResultSet.html">ResultSet</a></code>.</p>
|
||
|
|
||
|
<pre><code class="language-crystal"><span class="k">require</span> <span class="s">"db"</span>
|
||
|
|
||
|
<span class="k">class</span> <span class="t">Employee</span>
|
||
|
<span class="t">DB</span>.mapping({
|
||
|
title: <span class="t">String</span>,
|
||
|
name: <span class="t">String</span>,
|
||
|
})
|
||
|
<span class="k">end</span>
|
||
|
|
||
|
employees <span class="o">=</span> <span class="t">Employee</span>.from_rs(db.query(<span class="s">"SELECT title, name FROM employees"</span>))
|
||
|
employees[<span class="n">0</span>].title <span class="c"># => "Manager"</span>
|
||
|
employees[<span class="n">0</span>].name <span class="c"># => "John"</span></code></pre>
|
||
|
|
||
|
<p>Attributes not mapped with <code><a href="DB.html#mapping(**properties)-macro">DB.mapping</a></code> are not defined as properties.
|
||
|
Also, missing attributes raise a <code><a href="DB/MappingException.html">DB::MappingException</a></code>.</p>
|
||
|
|
||
|
<p>You can also define attributes for each property.</p>
|
||
|
|
||
|
<pre><code class="language-crystal"><span class="k">class</span> <span class="t">Employee</span>
|
||
|
<span class="t">DB</span>.mapping({
|
||
|
title: <span class="t">String</span>,
|
||
|
name: {
|
||
|
<span class="k">type</span>: <span class="t">String</span>,
|
||
|
nilable: <span class="n">true</span>,
|
||
|
key: <span class="s">"firstname"</span>,
|
||
|
},
|
||
|
})
|
||
|
<span class="k">end</span></code></pre>
|
||
|
|
||
|
<p>Available attributes:</p>
|
||
|
|
||
|
<ul><li><em>type</em> (required) defines its type. In the example above, <em>title: String</em> is a shortcut to <em>title: {type: String}</em>.</li><li><em>nilable</em> defines if a property can be a <code>Nil</code>.</li><li><strong>default</strong>: value to use if the property is missing in the result set, or if it's <code>null</code> and <code>nilable</code> was not set to <code>true</code>. If the default value creates a new instance of an object (for example <code>[1, 2, 3]</code> or <code>SomeObject.new</code>), a different instance will be used each time a row is parsed.</li><li><em>key</em> defines which column to read from a <code><a href="DB/ResultSet.html">ResultSet</a></code>. It defaults to the name of the property.</li><li><em>converter</em> takes an alternate type for parsing. It requires a <code>#from_rs</code> method in that class, and returns an instance of the given type.</li></ul>
|
||
|
|
||
|
<p>The mapping also automatically defines Crystal properties (getters and setters) for each
|
||
|
of the keys. It doesn't define a constructor accepting those arguments, but you can provide
|
||
|
an overload.</p>
|
||
|
|
||
|
<p>The macro basically defines a constructor accepting a <code><a href="DB/ResultSet.html">ResultSet</a></code> that reads from
|
||
|
it and initializes this type's instance variables.</p>
|
||
|
|
||
|
<p>This macro also declares instance variables of the types given in the mapping.</p>
|
||
|
</div>
|
||
|
|
||
|
<br/>
|
||
|
<div>
|
||
|
|
||
|
</div>
|
||
|
</div>
|
||
|
|
||
|
<div class="entry-detail" id="mapping(**properties)-macro">
|
||
|
<div class="signature">
|
||
|
|
||
|
macro <strong>mapping</strong>(**properties)
|
||
|
|
||
|
<a class="method-permalink" href="#mapping(**properties)-macro">#</a>
|
||
|
</div>
|
||
|
|
||
|
<br/>
|
||
|
<div>
|
||
|
|
||
|
</div>
|
||
|
</div>
|
||
|
|
||
|
|
||
|
|
||
|
</div>
|
||
|
|
||
|
</body>
|
||
|
</html>
|