HOWTO

Here’s some miscellaneous documentation about using Avatica.

Building from a source distribution

Prerequisites are Java (JDK 8 or later) on your path.

Unpack the source distribution .tar.gz file,cd to the root directory of the unpacked source,then build using maven:

$ tar xvfz apache-calcite-avatica-1.16.0-src.tar.gz
$ cd apache-calcite-avatica-1.16.0-src
$ ./gradlew build

Running tests describes how to run more or fewertests.

Building from Git

Prerequisites are Git,and Java (JDK 8 or later) on your path.

Create a local copy of the GitHub repository,cd to its root directory,then build using maven:

$ git clone git://github.com/apache/calcite-avatica.git avatica
$ cd avatica
$ ./gradlew build

Note: gdub simplifies ./gradlew build to gw build,and it simplifies cases like ../../gradlew … to gw … as well.

Running tests describes how to run more or fewertests.

Running tests

The test suite will run by default when you build, unless you specify-x test

$ ./gradlew assemble # build the artifacts
$ ./gradlew build -x test # build the artifacts, verify code style, skip tests
$ ./gradlew check # verify code style, execute tests
$ ./gradlew test # execute tests
$ ./gradlew checkstyleMain checkstyleTest # verify code style

You can use ./gradlew assemble to build the artifacts and skip all tests and verifications.

To run tests in docker:

• You will need to have docker and Docker Compose installed.

docker-compose run test

Contributing

See the developers guide.

Getting started

See the developers guide.

Advanced topics for developers

The following sections might be of interest if you are adding featuresto particular parts of the code base. You don’t need to understandthese topics if you are just building from source and running tests.

Advanced topics for committers

The following sections are of interest to Calcite committers and inparticular release managers.

Set up PGP signing keys (for Calcite committers)

Follow instructions here tocreate a key pair. (On Mac OS X, I did brew install gpg andgpg —gen-key.)

Add your public key to theKEYSfile by following instructions in the KEYS file.(The KEYS file is not present in the git repo or in a release tarball because that would beredundant.)

Run a GPG agent

By default, Maven plugins which require you to unlock a GPG secret keywill prompt you in the terminal. To prevent you from having to enterthis password numerous times, it is highly recommended to install andrun gpg-agent.

This can be started automatically via an ~/.xsession on Linux or somescripting in your shell’s configuration script of choice (e.g. ~/.bashrc or ~/.zshrc)

GPG_AGENT=$(which gpg-agent)
GPG_TTY=`tty`
export GPG_TTY
if [[ -f "$GPG_AGENT" ]]; then
  envfile="${HOME}/.gnupg/gpg-agent.env"
  if test -f "$envfile" && kill -0 $(grep GPG_AGENT_INFO "$envfile" | cut -d: -f 2) 2>/dev/null; then
      source "$envfile"
  else
      eval "$(gpg-agent --daemon --log-file=~/.gpg/gpg.log --write-env-file "$envfile")"
  fi
  export GPG_AGENT_INFO  # the env file does not contain the export statement
fi

Also, ensure that default-cache-ttl 6000 is set in ~/.gnupg/gpg-agent.confto guarantee that your credentials will be cached for the duration of the build.

Set up Nexus repository credentials (for Calcite committers)

Gradle provides multiple ways to configure project properties.For instance, you could update $HOME/.gradle/gradle.properties.

Note: the build script would print the missing properties, so you can try running it and let it complain on the missing ones.

The following options are used:

asfCommitterId=
asfNexusUsername=
asfNexusPassword=
asfSvnUsername=
asfSvnPassword=

Note: when https://github.com/vlsi/asflike-release-environment is used, the credentials are takend fromasfTest… (e.g. asfTestNexusUsername=test)

Note: if you want to uses gpg-agent, you need to pass useGpgCmd property, and specify the key idvia signing.gnupg.keyName.

Making a snapshot (for Calcite committers)

Before you start:

• Set up signing keys as described above.
• Make sure you are using JDK 8 (not 9 or 10).

# Make sure that there are no junk files in the sandbox
git clean -xn
./gradlew -Pasf publish

Making a release candidate (for Calcite committers)

Before you start:

• Set up signing keys as described above.
• Make sure you are using JDK 8 (not 9 or 10).
• Check that README, site/_docs/howto.md, site/_docs/docker_images.md have the correct version number.
• Check that NOTICE has the current copyright year.
• Check that calcite.avatica.version has the proper value in /gradle.properties.
• Add release notes to site/_docs/history.md. Include the commit history,and say which versions of Java, Guava and operating systems the release istested against.
• Generate a report of vulnerabilities that occur among dependencies,using ./gradlew dependencyCheckUpdate dependencyCheckAggregate.
• Make sure thatevery “resolved” JIRA case (including duplicates) hasa fix version assigned (most likely the version we arejust about to release)

The release candidate process does not add commits,so there’s no harm if it fails. It might leave -rc tag behindwhich can be removed if required.

You can perform a dry-run release with a help of https://github.com/vlsi/asflike-release-environmentThat would perform the same steps, however it would push changes to the mock Nexus, Git, and SVN servers.

If any of the steps fail, fix the problem, andstart again from the top.

To prepare a release candidate directly in your environment:

Pick a release candidate index and ensure it does not interfere with previous candidates for the version.

# Make sure that there are no junk files in the sandbox
git clean -xn
# Dry run the release candidate (push to asf-like-environment)
./gradlew prepareVote -Prc=1
# Push release candidate to ASF servers
./gradlew prepareVote -Prc=1 -Pasf

To prepare a release candidate in Docker:

• You will need to have Docker and Docker Compose installed.

• The script expects you to mount your ~/.gnupg directory into the /.gnupg directory in the container. Once mounted into the container,the script will make a copy of the contents and move it to a different location, so that it will not modify the contents of your original~/.gnupg directory during the build.

• Start the asflike-release-environment to prepare a staging environment for a dry-run.

# On Linux (dry-run):
docker-compose run -v ~/.gnupg:/.gnupg dry-run
# On Windows (dry-run):
docker-compose run -v /c/Users/username/AppData/Roaming/gnupg:/.gnupg dry-run
# On Linux (push to ASF servers):
docker-compose run -v ~/.gnupg:/.gnupg publish-release-for-voting
# On Windows (push to ASF servers):
docker-compose run -v /c/Users/username/AppData/Roaming/gnupg:/.gnupg publish-release-for-voting

Checking the artifacts

• In the release/build/distributions directory should be these 3 files, among others:
  • apache-calcite-avatica-X.Y.Z-src.tar.gz
  • apache-calcite-avatica-X.Y.Z-src.tar.gz.asc
  • apache-calcite-avatica-X.Y.Z-src.tar.gz.sha512
• Note that the file names start apache-calcite-avatica-.
• In the source distro .tar.gz (currently there isno binary distro), check that all files belong to a directory calledapache-calcite-avatica-X.Y.Z-src.
• That directory must contain files NOTICE, LICENSE,README, README.md
  • Check that the version in README is correct
• Make sure that there is no KEYS file in the source distros
• For each .jar (for example core/build/libs/avatica-core-X.Y.Z.jarand server/build/libs/avatica-server-X.Y.Z-sources.jar),verify that the META-INF directory contains the correctcontents for LICENSE and NOTICE per thesource/classes contained. Refer to the ASF licensing documentation onwhat is required.
• Check PGP, per this

Verify the staged artifacts in the Nexus repository:

• Go to https://repository.apache.org/ and login
• Under Build Promotion, click Staging Repositories
• In the Staging Repositories tab there should be a line with profile org.apache.calcite
• Navigate through the artifact tree and make sure the .jar, .pom, .asc files are present

Cleaning up after a failed release attempt (for Calcite committers)

If something is not correct, you can fix it, commit it, and prepare the next candidate.The release candidate tags might be kept for a while.

Validate a release

# Check that the signing key (e.g. 2AD3FAE3) is pushed
gpg --recv-keys key
# Check keys
curl -O https://dist.apache.org/repos/dist/release/calcite/KEYS
# Sign/check sha256 hashes
# (Assumes your O/S has a 'shasum' command.)
function checkHash() {
  cd "$1"
  for i in *.{pom,gz}; do
    if [ ! -f $i ]; then
      continue
    fi
    if [ -f $i.sha256 ]; then
      if [ "$(cat $i.sha256)" = "$(shasum -a 256 $i)" ]; then
        echo $i.sha256 present and correct
      else
        echo $i.sha256 does not match
      fi
    else
      shasum -a 256 $i > $i.sha256
      echo $i.sha256 created
    fi
  done
}
checkHash apache-calcite-avatica-X.Y.Z-rcN

Get approval for a release via Apache voting process (for Calcite committers)

Release vote on dev list.Note: the draft mail is printed as the final step of prepareVote task,and you can find the draft in /build/prepareVote/mail.txt

To: dev@calcite.apache.org
Subject: [VOTE] Release apache-calcite-avatica-X.Y.Z (release candidate N)
Hi all,
I have created a build for Apache Calcite Avatica X.Y.Z, release candidate N.
Thanks to everyone who has contributed to this release.
<Further details about release.> You can read the release notes here:
https://github.com/apache/calcite-avatica/blob/XXXX/site/_docs/history.md
The commit to be voted upon:
https://gitbox.apache.org/repos/asf/calcite-avatica/commit/NNNNNN
Its hash is XXXX.
The artifacts to be voted on are located here:
https://dist.apache.org/repos/dist/dev/calcite/apache-calcite-avatica-X.Y.Z-rcN/
The hashes of the artifacts are as follows:
src.tar.gz.sha256 XXXX
A staged Maven repository is available for review at:
https://repository.apache.org/content/repositories/orgapachecalcite-NNNN
Release artifacts are signed with the following key:
https://people.apache.org/keys/committer/jhyde.asc
Please vote on releasing this package as Apache Calcite Avatica X.Y.Z.
The vote is open for the next 72 hours and passes if a majority of
at least three +1 PMC votes are cast.
[ ] +1 Release this package as Apache Calcite X.Y.Z
[ ]  0 I don't feel strongly about it, but I'm okay with the release
[ ] -1 Do not release this package because...
Here is my vote:
+1 (binding)
Julian

After vote finishes, send out the result:

Subject: [RESULT] [VOTE] Release apache-calcite-avatica-X.Y.Z (release candidate N)
To: dev@calcite.apache.org
Thanks to everyone who has tested the release candidate and given
their comments and votes.
The tally is as follows.
N binding +1s:
<names>
N non-binding +1s:
<names>
No 0s or -1s.
Therefore I am delighted to announce that the proposal to release
Apache Calcite Avatica X.Y.Z has passed.
Thanks everyone. We’ll now roll the release out to the mirrors.
There was some feedback during voting. I shall open a separate
thread to discuss.
Julian

Use the Apache URL shortener to generateshortened URLs for the vote proposal and result emails. Examples:s.apache.org/calcite-1.2-vote ands.apache.org/calcite-1.2-result.

Publishing a release (for Calcite committers)

After a successful release vote, we need to push the releaseout to mirrors, and other tasks.

Choose a release date.This is based on the time when you expect to announce the release.This is usually a day after the vote closes.Remember that UTC date changes at 4pm Pacific time.

In JIRA, search forall issues resolved in this release,and do a bulk update changing their status to “Closed”,with a change comment“Resolved in release X.Y.Z (YYYY-MM-DD)”(fill in release number and date appropriately).Uncheck “Send mail for this update”.

Tip: Push the git tag only after the staged nexus artifacts are promoted in the repository. This is because pushing thetag triggers Docker Hub to start building the docker images immediately and the build will pull in the promoted artifacts.If the artifacts are not yet available, the build on Docker Hub will fail. It’s best to continue with the following stepsafter you have confirmed that the nexus artifacts were promoted properly.

Publishing directly in your environment:

# Dry run publishing the release (push to asf-like-environment)
./gradlew publishDist -Prc=1
# Publish the release to ASF servers
./gradlew publishDist -Prc=1 -Pasf

If there are more than 2 releases in SVN (see https://dist.apache.org/repos/dist/release/calcite),clear out the oldest ones:

svn rm https://dist.apache.org/repos/dist/release/calcite/apache-calcite-avatica-X.Y.Z

The old releases will remain available in therelease archive.

Publishing a release using docker:

This assumes that a rc release was tagged and pushed to the git repository.

docker-compose run promote-release

Add release notes and announce the release

Add a release note by copyingsite/_posts/2016-11-01-release-1.9.0.md,generate the javadoc and copy to site/target/avatica/javadocAggregatepublish the site,and check that it appears in the contents in news.

After 24 hours, announce the release by sending an email toannounce@apache.org.You can usethe 1.8.0 announcementas a template. Be sure to include a brief description of the project.

Publishing the web site (for Calcite committers)

See instructions insite/README.md.