| <!DOCTYPE HTML> |
| <html lang="en-US"> |
| <head> |
| <meta charset="UTF-8"> |
| <title>Compatibility</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>Compatibility</h1> |
| <!-- |
| |
| --> |
| |
| <p>Given Avatica’s client-server model, it is no surprise that compatibility is |
| important to the users and developers of Apache Calcite Avatica. This document |
| defines what guarantees are made by Avatica with respect to compatibility |
| between Avatica client and server across versions. This document is still a work |
| in progress with many areas still requiring definition. Contributions are always |
| welcome.</p> |
| |
| <h2 id="avatica-technology-compatibility-kit-tck">Avatica Technology Compatibility Kit (TCK)</h2> |
| |
| <p>The <a href="https://github.com/apache/calcite-avatica/tree/master/tck">Avatica TCK project</a> is a framework designed to automatically |
| test an Avatica client against an Avatica server. A collection of JUnit tests, |
| a YAML configuration file, and a Ruby script defines the TCK. |
| The JUnit tests invoke specific portions of both the client and |
| server components of Avatica to verify that they work as expected. The Ruby |
| script uses the YAML configuration file to define the set of |
| client and server version pairs to run the JUnit tests against.</p> |
| |
| <p>In the YAML configuration file, a name (e.g. <code class="highlighter-rouge">1.6.0</code>) and the following three |
| items define an Avatica version:</p> |
| |
| <ol> |
| <li>A filesystem path to an Avatica client jar (e.g. groupId=org.apache.calcite.avatica, artifactId=avatica)</li> |
| <li>A URL to a running instance of an Avatica server</li> |
| <li>A JDBC URL template to the Avatica server for the Avatica client JDBC driver.</li> |
| </ol> |
| |
| <p>Users of the TCK define the collection of versions (defined by the above |
| information) and the location of the <a href="https://github.com/apache/calcite-avatica/tree/master/tck">avatica-tck</a> jar by a YAML |
| configuration file. An <a href="https://github.com/apache/calcite-avatica/tree/master/tck/src/main/resources/example_config.yml">example YAML configuration file</a> is |
| bundled with the project.</p> |
| |
| <p>Traditionally, Avatica does not provide any implementation of the Avatica server |
| as the value in Avatica is recognized in the integrating project (e.g. Apache |
| Drill or Apache Phoenix). However, for the purposes of compatibility testing, it |
| makes sense that Avatica provides a standalone server instance. A new artifact |
| is introduced to Avatica with the original TCK codebase called |
| <a href="https://github.com/apache/calcite-avatica/tree/master/standalone-server">avatica-standalone-server</a>. This artifact is a |
| runnable jar (e.g. <code class="highlighter-rouge">java -jar</code>) which starts an instance of the Avatica server |
| on a random port using the in-memory <a href="http://hsqldb.org/">HSQLDB database</a>. This |
| artifacts makes it extremely simple to start a version of the Avatica server for |
| the specific version of Avatica to be tested.</p> |
| |
| <p>As mentioned, the Ruby script is the entry point for the TCK. Invoking the Ruby |
| script which prints a summary of testing each specified version against itself and |
| all other versions in the YAML configuration. An example summary is presented |
| below which is the result of testing versions 1.6.0, 1.7.1 and 1.8.0-SNAPSHOT:</p> |
| |
| <div class="highlighter-rouge"><div class="highlight"><pre class="highlight"><code>Summary: |
| |
| Identity test scenarios (ran 3) |
| |
| Testing identity for version v1.6.0: Passed |
| Testing identity for version v1.7.1: Passed |
| Testing identity for version v1.8.0-SNAPSHOT: Failed |
| |
| All test scenarios (ran 6) |
| |
| Testing client v1.6.0 against server v1.7.1: Passed |
| Testing client v1.6.0 against server v1.8.0-SNAPSHOT: Failed |
| Testing client v1.7.1 against server v1.6.0: Passed |
| Testing client v1.7.1 against server v1.8.0-SNAPSHOT: Failed |
| Testing client v1.8.0-SNAPSHOT against server v1.6.0: Failed |
| Testing client v1.8.0-SNAPSHOT against server v1.7.1: Failed |
| </code></pre></div></div> |
| |
| <p>It is not always expected that all tested version-pairs will pass unless the |
| test is written with specific knowledge about past bugs in Avatica itself. While |
| Avatica tries to handle all of these edge cases implicitly, it is not always |
| feasible or desirable to do so. Adding new test cases is as easy as writing a |
| JUnit test case in the <a href="https://github.com/apache/calcite-avatica/tree/master/tck/src/main/java/org/apache/calcite/avatica/tck/tests">TCK module</a>, but there is presently no |
| automation around verifying the test cases as a part of the Maven build.</p> |
| |
| <p>For more information on running this TCK, including specific instructions for |
| running the TCK, reference the provided <a href="https://github.com/apache/calcite-avatica/tree/master/tck/README.md">README</a> file.</p> |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| <div class="section-nav"> |
| <div class="left align-right"> |
| |
| |
| |
| <a href="/avatica/docs/security.html" class="prev">Previous</a> |
| |
| </div> |
| <div class="right align-left"> |
| |
| |
| |
| |
| |
| <a href="/avatica/docs/custom_client_artifacts.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="current"><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=""><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 © 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 License 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> |
