Compatibility

Given Avatica’s client-server model, it is no surprise that compatibility isimportant to the users and developers of Apache Calcite Avatica. This documentdefines what guarantees are made by Avatica with respect to compatibilitybetween Avatica client and server across versions. This document is still a workin progress with many areas still requiring definition. Contributions are alwayswelcome.

Avatica Technology Compatibility Kit (TCK)

The Avatica TCK project is a framework designed to automaticallytest 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 andserver components of Avatica to verify that they work as expected. The Rubyscript uses the YAML configuration file to define the set ofclient and server version pairs to run the JUnit tests against.

In the YAML configuration file, a name (e.g. 1.6.0) and the following threeitems define an Avatica version:

  • A filesystem path to an Avatica client jar (e.g. groupId=org.apache.calcite.avatica, artifactId=avatica)
  • A URL to a running instance of an Avatica server
  • A JDBC URL template to the Avatica server for the Avatica client JDBC driver.Users of the TCK define the collection of versions (defined by the aboveinformation) and the location of the avatica-tck jar by a YAMLconfiguration file. An example YAML configuration file isbundled with the project.

Traditionally, Avatica does not provide any implementation of the Avatica serveras the value in Avatica is recognized in the integrating project (e.g. ApacheDrill or Apache Phoenix). However, for the purposes of compatibility testing, itmakes sense that Avatica provides a standalone server instance. A new artifactis introduced to Avatica with the original TCK codebase calledavatica-standalone-server. This artifact is arunnable jar (e.g. java -jar) which starts an instance of the Avatica serveron a random port using the in-memory HSQLDB database. Thisartifacts makes it extremely simple to start a version of the Avatica server forthe specific version of Avatica to be tested.

As mentioned, the Ruby script is the entry point for the TCK. Invoking the Rubyscript which prints a summary of testing each specified version against itself andall other versions in the YAML configuration. An example summary is presentedbelow which is the result of testing versions 1.6.0, 1.7.1 and 1.8.0-SNAPSHOT:

  1. Summary:
  3. Identity test scenarios (ran 3)
  5. Testing identity for version v1.6.0: Passed
  6. Testing identity for version v1.7.1: Passed
  7. Testing identity for version v1.8.0-SNAPSHOT: Failed
  9. All test scenarios (ran 6)
  11. Testing client v1.6.0 against server v1.7.1: Passed
  12. Testing client v1.6.0 against server v1.8.0-SNAPSHOT: Failed
  13. Testing client v1.7.1 against server v1.6.0: Passed
  14. Testing client v1.7.1 against server v1.8.0-SNAPSHOT: Failed
  15. Testing client v1.8.0-SNAPSHOT against server v1.6.0: Failed
  16. Testing client v1.8.0-SNAPSHOT against server v1.7.1: Failed

It is not always expected that all tested version-pairs will pass unless thetest is written with specific knowledge about past bugs in Avatica itself. WhileAvatica tries to handle all of these edge cases implicitly, it is not alwaysfeasible or desirable to do so. Adding new test cases is as easy as writing aJUnit test case in the TCK module, but there is presently noautomation around verifying the test cases as a part of the Maven build.

For more information on running this TCK, including specific instructions forrunning the TCK, reference the provided README file.