blob: 28a8f379f4d2105f0e16cb9f86220c54e8490f39 [file] [log] [blame]
<!DOCTYPE HTML>
<html lang="en-US">
<head>
<meta charset="UTF-8">
<title>Go Client Reference</title>
<meta name="viewport" content="width=device-width,initial-scale=1">
<meta name="generator" content="Jekyll v3.7.3">
<link rel="stylesheet" href="//fonts.googleapis.com/css?family=Lato:300,300italic,400,400italic,700,700italic,900">
<link rel="stylesheet" href="/avatica/css/screen.css">
<link rel="icon" type="image/x-icon" href="/avatica/favicon.ico">
<!--[if lt IE 9]>
<script src="/js/html5shiv.min.js"></script>
<script src="/js/respond.min.js"></script>
<![endif]-->
</head>
<body class="wrap">
<header role="banner">
<nav class="mobile-nav show-on-mobiles">
<ul>
<li class="">
<a href="/avatica/">Home</a>
</li>
<li class="">
<a href="/avatica/downloads/">Download</a>
</li>
<li class="">
<a href="/avatica/community/">Community</a>
</li>
<li class="">
<a href="/avatica/develop/">Develop</a>
</li>
<li class="">
<a href="/avatica/news/">News</a>
</li>
<li class="current">
<a href="/avatica/docs/">Docs</a>
</li>
</ul>
</nav>
<div class="grid">
<div class="unit one-third center-on-mobiles">
<h1>
<a href="/avatica/">
<span class="sr-only">Apache Calcite Avatica</span>
<img src="/avatica/img/logo.png" width="226" height="140" alt="Calcite Logo">
</a>
</h1>
</div>
<nav class="main-nav unit two-thirds hide-on-mobiles">
<ul>
<li class="">
<a href="/avatica/">Home</a>
</li>
<li class="">
<a href="/avatica/downloads/">Download</a>
</li>
<li class="">
<a href="/avatica/community/">Community</a>
</li>
<li class="">
<a href="/avatica/develop/">Develop</a>
</li>
<li class="">
<a href="/avatica/news/">News</a>
</li>
<li class="current">
<a href="/avatica/docs/">Docs</a>
</li>
</ul>
</nav>
</div>
</header>
<section class="docs">
<div class="grid">
<div class="docs-nav-mobile unit whole show-on-mobiles">
<select onchange="if (this.value) window.location.href=this.value">
<option value="">Navigate the docs…</option>
<optgroup label="Overview">
</optgroup>
<optgroup label="Avatica Reference">
</optgroup>
<optgroup label="Avatica Go Client Reference">
</optgroup>
<optgroup label="Avatica Meta">
</optgroup>
<optgroup label="Avatica Go Client Meta">
</optgroup>
</select>
</div>
<div class="unit four-fifths">
<article>
<h1>Go Client Reference</h1>
<!--
-->
<p>The Avatica Go client is an Avatica driver for Go’s
<a href="https://golang.org/pkg/database/sql/">database/sql</a>package.</p>
<p>It also works with the Phoenix Query Server from the Apache
Phoenix project, as the Phoenix Query Server uses Avatica under the
hood.</p>
<ul id="markdown-toc">
<li><a href="#getting-started" id="markdown-toc-getting-started">Getting Started</a></li>
<li><a href="#usage" id="markdown-toc-usage">Usage</a></li>
<li><a href="#dsn-data-source-name" id="markdown-toc-dsn-data-source-name">DSN (Data Source Name)</a></li>
<li><a href="#timetime-support" id="markdown-toc-timetime-support">time.Time support</a></li>
<li><a href="#apache-phoenix-error-codes" id="markdown-toc-apache-phoenix-error-codes">Apache Phoenix Error Codes</a></li>
<li><a href="#version-compatibility" id="markdown-toc-version-compatibility">Version Compatibility</a></li>
</ul>
<h2 id="getting-started">Getting Started</h2>
<p>If you are using Go 1.10 and below, install using <a href="https://github.com/golang/dep">dep</a>:</p>
<figure class="highlight"><pre><code class="language-shell" data-lang="shell"><span class="nv">$ </span>dep ensure <span class="nt">-add</span> github.com/apache/calcite-avatica-go</code></pre></figure>
<p>If you are using Go 1.11 and above, install using Go modules:</p>
<figure class="highlight"><pre><code class="language-shell" data-lang="shell"><span class="nv">$ </span>go get github.com/apache/calcite-avatica-go</code></pre></figure>
<h2 id="usage">Usage</h2>
<p>The Avatica Go driver implements Go’s <code class="highlighter-rouge">database/sql/driver</code> interface, so, import Go’s
<code class="highlighter-rouge">database/sql</code> package and the driver:</p>
<figure class="highlight"><pre><code class="language-go" data-lang="go"><span class="k">import</span><span class="x"> </span><span class="s">"database/sql"</span><span class="x">
</span><span class="k">import</span><span class="x"> </span><span class="n">_</span><span class="x"> </span><span class="s">"github.com/apache/calcite-avatica-go/v4"</span><span class="x">
</span><span class="n">db</span><span class="p">,</span><span class="x"> </span><span class="n">err</span><span class="x"> </span><span class="o">:=</span><span class="x"> </span><span class="n">sql</span><span class="o">.</span><span class="n">Open</span><span class="p">(</span><span class="s">"avatica"</span><span class="p">,</span><span class="x"> </span><span class="s">"http://localhost:8765"</span><span class="p">)</span></code></pre></figure>
<p>Then simply use the database connection to query some data, for example:</p>
<figure class="highlight"><pre><code class="language-go" data-lang="go"><span class="n">rows</span><span class="x"> </span><span class="o">:=</span><span class="x"> </span><span class="n">db</span><span class="o">.</span><span class="n">Query</span><span class="p">(</span><span class="s">"SELECT COUNT(*) FROM test"</span><span class="p">)</span></code></pre></figure>
<h2 id="dsn-data-source-name">DSN (Data Source Name)</h2>
<p>The DSN has the following format (optional parts are marked by square brackets):</p>
<figure class="highlight"><pre><code class="language-shell" data-lang="shell">http://address:port[/schema][?parameter1<span class="o">=</span>value&amp;...parameterN<span class="o">=</span>value]</code></pre></figure>
<p>In other words, the scheme (http), address and port are mandatory, but the schema and parameters are optional.</p>
<p><strong><a name="schema" href="#schema">schema</a></strong></p>
<p>The <code class="highlighter-rouge">schema</code> path sets the default schema to use for this connection. For example, if you set it to <code class="highlighter-rouge">myschema</code>,
then executing the query <code class="highlighter-rouge">SELECT * FROM my_table</code> will have the equivalence of <code class="highlighter-rouge">SELECT * FROM myschema.my_table</code>.
If schema is set, you can still work on tables in other schemas by supplying a schema prefix:
<code class="highlighter-rouge">SELECT * FROM myotherschema.my_other_table</code>.</p>
<p>The parameters references the options used by the Java implementation as much as possible.
The following parameters are supported:</p>
<p><strong><a name="authentication" href="#authentication">authentication</a></strong></p>
<p>The authentication type to use when authenticating against Avatica. Valid values are <code class="highlighter-rouge">BASIC</code> for HTTP Basic authentication,
<code class="highlighter-rouge">DIGEST</code> for HTTP Digest authentication, and <code class="highlighter-rouge">SPNEGO</code> for Kerberos with SPNEGO authentication.</p>
<p><strong><a name="avaticaUser" href="#avaticaUser">avaticaUser</a></strong></p>
<p>The user to use when authenticating against Avatica. This parameter is required if <code class="highlighter-rouge">authentication</code> is <code class="highlighter-rouge">BASIC</code> or <code class="highlighter-rouge">DIGEST</code>.</p>
<p><strong><a name="avaticaPassword" href="#avaticaPassword">avaticaPassword</a></strong></p>
<p>The password to use when authenticating against Avatica. This parameter is required if <code class="highlighter-rouge">authentication</code> is <code class="highlighter-rouge">BASIC</code> or <code class="highlighter-rouge">DIGEST</code>.</p>
<p><strong><a name="principal" href="#principal">principal</a></strong></p>
<p>The Kerberos principal to use when authenticating against Avatica. It should be in the form <code class="highlighter-rouge">primary/instance@realm</code>, where
the instance is optional. This parameter is required if <code class="highlighter-rouge">authentication</code> is <code class="highlighter-rouge">SPNEGO</code> and you want the driver to perform the
Kerberos login.</p>
<p><strong><a name="keytab" href="#keytab">keytab</a></strong></p>
<p>The path to the Kerberos keytab to use when authenticating against Avatica. This parameter is required if <code class="highlighter-rouge">authentication</code>
is <code class="highlighter-rouge">SPNEGO</code> and you want the driver to perform the Kerberos login.</p>
<p><strong><a name="krb5Conf" href="#krb5Conf">krb5Conf</a></strong></p>
<p>The path to the Kerberos configuration to use when authenticating against Avatica. This parameter is required if <code class="highlighter-rouge">authentication</code>
is <code class="highlighter-rouge">SPNEGO</code> and you want the driver to perform the Kerberos login.</p>
<p><strong><a name="krb5CredentialsCache" href="#krb5CredentialsCache">krb5CredentialsCache</a></strong></p>
<p>The path to the Kerberos credential cache file to use when authenticating against Avatica. This parameter is required if
<code class="highlighter-rouge">authentication</code> is <code class="highlighter-rouge">SPNEGO</code> and you have logged into Kerberos already and want the driver to use the existing credentials.</p>
<p><strong><a name="location" href="#location">location</a></strong></p>
<p>The <code class="highlighter-rouge">location</code> will be set as the location of unserialized <code class="highlighter-rouge">time.Time</code> values. It must be a valid timezone.
If you want to use the local timezone, use <code class="highlighter-rouge">Local</code>. By default, this is set to <code class="highlighter-rouge">UTC</code>.</p>
<p><strong><a name="maxRowsTotal" href="#maxRowsTotal">maxRowsTotal</a></strong></p>
<p>The <code class="highlighter-rouge">maxRowsTotal</code> parameter sets the maximum number of rows to return for a given query. By default, this is set to
<code class="highlighter-rouge">-1</code>, so that there is no limit on the number of rows returned.</p>
<p><strong><a name="frameMaxSize" href="#frameMaxSize">frameMaxSize</a></strong></p>
<p>The <code class="highlighter-rouge">frameMaxSize</code> parameter sets the maximum number of rows to return in a frame. Depending on the number of rows
returned and subject to the limits of <code class="highlighter-rouge">maxRowsTotal</code>, a query result set can contain rows in multiple frames. These
additional frames are then fetched on a as-needed basis. <code class="highlighter-rouge">frameMaxSize</code> allows you to control the number of rows
in each frame to suit your application’s performance profile. By default this is set to <code class="highlighter-rouge">-1</code>, so that there is no limit
on the number of rows in a frame.</p>
<p><strong><a name="transactionIsolation" href="#transactionIsolation">transactionIsolation</a></strong></p>
<p>Setting <code class="highlighter-rouge">transactionIsolation</code> allows you to set the isolation level for transactions using the connection. The value
should be a positive integer analogous to the transaction levels defined by the JDBC specification. The default value
is <code class="highlighter-rouge">0</code>, which means transactions are not supported. This is to deal with the fact that Calcite/Avatica works with
many types of backends, with some backends having no transaction support. If you are using Apache Phoenix 4.7 onwards,
we recommend setting it to <code class="highlighter-rouge">4</code>, which is the maximum isolation level supported.</p>
<p>The supported values for <code class="highlighter-rouge">transactionIsolation</code> are:</p>
<table>
<thead>
<tr>
<th style="text-align: left">Value</th>
<th style="text-align: left">JDBC Constant</th>
<th style="text-align: left">Description</th>
</tr>
</thead>
<tbody>
<tr>
<td style="text-align: left">0</td>
<td style="text-align: left">none</td>
<td style="text-align: left">Transactions are not supported</td>
</tr>
<tr>
<td style="text-align: left">1</td>
<td style="text-align: left"><code class="highlighter-rouge">TRANSACTION_READ_UNCOMMITTED</code></td>
<td style="text-align: left">Dirty reads, non-repeatable reads and phantom reads may occur.</td>
</tr>
<tr>
<td style="text-align: left">2</td>
<td style="text-align: left"><code class="highlighter-rouge">TRANSACTION_READ_COMMITTED</code></td>
<td style="text-align: left">Dirty reads are prevented, but non-repeatable reads and phantom reads may occur.</td>
</tr>
<tr>
<td style="text-align: left">4</td>
<td style="text-align: left"><code class="highlighter-rouge">TRANSACTION_REPEATABLE_READ</code></td>
<td style="text-align: left">Dirty reads and non-repeatable reads are prevented, but phantom reads may occur.</td>
</tr>
<tr>
<td style="text-align: left">8</td>
<td style="text-align: left"><code class="highlighter-rouge">TRANSACTION_SERIALIZABLE</code></td>
<td style="text-align: left">Dirty reads, non-repeatable reads, and phantom reads are all prevented.</td>
</tr>
</tbody>
</table>
<h2 id="timetime-support">time.Time support</h2>
<p>The following datatypes are automatically converted to and from <code class="highlighter-rouge">time.Time</code>:
<code class="highlighter-rouge">TIME</code>, <code class="highlighter-rouge">DATE</code> and <code class="highlighter-rouge">TIMESTAMP</code>.</p>
<p>It is important to understand that Avatica and the underlying database ignores the timezone. If you save a <code class="highlighter-rouge">time.Time</code>
to the database, the timezone is ignored and vice-versa. This is why you need to make sure the <code class="highlighter-rouge">location</code> parameter
in your DSN is set to the same value as the location of the <code class="highlighter-rouge">time.Time</code> values you are inserting into the database.</p>
<p>We recommend using <code class="highlighter-rouge">UTC</code>, which is the default value of <code class="highlighter-rouge">location</code>.</p>
<h2 id="apache-phoenix-error-codes">Apache Phoenix Error Codes</h2>
<p>The Go client comes with support for retrieving the error code when an error occurs. This is extremely useful when
you want to take specific action when a particular type of error occurs.</p>
<p>If the error returned is a ResponseError, the <code class="highlighter-rouge">Name</code> field on the error will return the appropriate
Apache Phoenix error code:</p>
<figure class="highlight"><pre><code class="language-go" data-lang="go"><span class="n">_</span><span class="p">,</span><span class="x"> </span><span class="n">err</span><span class="x"> </span><span class="o">:=</span><span class="x"> </span><span class="n">db</span><span class="o">.</span><span class="n">Exec</span><span class="p">(</span><span class="s">"SELECT * FROM table_that_does_not_exist"</span><span class="p">)</span><span class="x"> </span><span class="c">// Query undefined table</span><span class="x">
</span><span class="c">// First, assert the error type</span><span class="x">
</span><span class="n">perr</span><span class="p">,</span><span class="x"> </span><span class="n">ok</span><span class="x"> </span><span class="o">:=</span><span class="x"> </span><span class="n">err</span><span class="o">.</span><span class="p">(</span><span class="n">avatica</span><span class="o">.</span><span class="n">ResponseError</span><span class="p">)</span><span class="x">
</span><span class="c">// If it cannot be asserted</span><span class="x">
</span><span class="k">if</span><span class="x"> </span><span class="o">!</span><span class="n">ok</span><span class="x"> </span><span class="p">{</span><span class="x">
</span><span class="c">// Error was not an Avatica ResponseError</span><span class="x">
</span><span class="p">}</span><span class="x">
</span><span class="c">// Print the Apache Phoenix error code</span><span class="x">
</span><span class="n">fmt</span><span class="o">.</span><span class="n">Println</span><span class="p">(</span><span class="n">perr</span><span class="o">.</span><span class="n">Name</span><span class="p">)</span><span class="x"> </span><span class="c">// Prints: table_undefined</span></code></pre></figure>
<h2 id="version-compatibility">Version Compatibility</h2>
<table>
<thead>
<tr>
<th style="text-align: left">Driver Version</th>
<th style="text-align: left">Phoenix Version</th>
<th style="text-align: left">Calcite-Avatica Version</th>
</tr>
</thead>
<tbody>
<tr>
<td style="text-align: left">3.x.x</td>
<td style="text-align: left">&gt;= 4.8.0</td>
<td style="text-align: left">&gt;= 1.11.0</td>
</tr>
</tbody>
</table>
<div class="section-nav">
<div class="left align-right">
<a href="/avatica/docs/protocol_testing.html" class="prev">Previous</a>
</div>
<div class="right align-left">
<a href="/avatica/docs/go_howto.html" class="next">Next</a>
</div>
</div>
<div class="clear"></div>
</article>
</div>
<div class="unit one-fifth hide-on-mobiles">
<aside>
<h4>Overview</h4>
<ul>
<li class=""><a href="/avatica/docs/index.html">Background</a></li>
<li class=""><a href="/avatica/docs/roadmap.html">Roadmap</a></li>
</ul>
<h4>Avatica Reference</h4>
<ul>
<li class=""><a href="/avatica/docs/client_reference.html">Client Reference</a></li>
<li class=""><a href="/avatica/docs/json_reference.html">JSON Reference</a></li>
<li class=""><a href="/avatica/docs/protobuf_reference.html">Protobuf Reference</a></li>
<li class=""><a href="/avatica/docs/howto.html">HOWTO</a></li>
<li class=""><a href="/avatica/docs/security.html">Security</a></li>
<li class=""><a href="/avatica/docs/compatibility.html">Compatibility</a></li>
<li class=""><a href="/avatica/docs/custom_client_artifacts.html">Custom Client Artifacts</a></li>
<li class=""><a href="/avatica/docs/docker.html">Docker Images</a></li>
<li class=""><a href="/avatica/docs/protocol_testing.html">Protocol Testing</a></li>
</ul>
<h4>Avatica Go Client Reference</h4>
<ul>
<li class="current"><a href="/avatica/docs/go_client_reference.html">Go Client Reference</a></li>
<li class=""><a href="/avatica/docs/go_howto.html">HOWTO</a></li>
</ul>
<h4>Avatica Meta</h4>
<ul>
<li class=""><a href="/avatica/docs/history.html">History</a></li>
<li class=""><a href="/avatica/docs/api/">API</a></li>
</ul>
<h4>Avatica Go Client Meta</h4>
<ul>
<li class=""><a href="/avatica/docs/go_history.html">Go Client History</a></li>
</ul>
</aside>
</div>
<div class="clear"></div>
</div>
</section>
<footer role="contentinfo">
<div id="poweredby">
<a href="http://www.apache.org/">
<span class="sr-only">Apache</span>
<img src="/avatica/img/feather.png" width="190" height="77" alt="Apache Logo"></a>
</div>
<div id="copyright">
<p>The contents of this website are &copy;&nbsp;2019
<a href="https://www.apache.org/">Apache Software Foundation</a>
under the terms of
the <a href="https://www.apache.org/licenses/LICENSE-2.0.html">
Apache&nbsp;License&nbsp;v2</a>. Apache Calcite and its logo are
trademarks of the Apache Software Foundation.</p>
</div>
</footer>
<script>
var anchorForId = function (id) {
var anchor = document.createElement("a");
anchor.className = "header-link";
anchor.href = "#" + id;
anchor.innerHTML = "<span class=\"sr-only\">Permalink</span><i class=\"fa fa-link\"></i>";
anchor.title = "Permalink";
return anchor;
};
var linkifyAnchors = function (level, containingElement) {
var headers = containingElement.getElementsByTagName("h" + level);
for (var h = 0; h < headers.length; h++) {
var header = headers[h];
if (typeof header.id !== "undefined" && header.id !== "") {
header.appendChild(anchorForId(header.id));
}
}
};
document.onreadystatechange = function () {
if (this.readyState === "complete") {
var contentBlock = document.getElementsByClassName("docs")[0] || document.getElementsByClassName("news")[0];
if (!contentBlock) {
return;
}
for (var level = 1; level <= 6; level++) {
linkifyAnchors(level, contentBlock);
}
}
};
</script>
</body>
</html>