Docker Images

Docker Images for Avatica

Docker) is a popular piece ofsoftware that enables other software to run “anywhere”. In the context of Avatica,we can use Docker to enable a run-anywhere Avatica server. These Docker containerscan be used to easily create a server for the development of custom Avatica clientsor encapsulating database access for testing software that uses Avatica.

Base “avatica-server” Docker Image

Avatica provides a number of Dockercontainers. Each of these images is based on a “parent” “avatica-server” Docker image.

This Docker image has no bindings to a specific database (it has not database-specificJDBC driver included). It only contains a Java runtime and the Avatica Standalone Serverjar (which contains all the necessary dependencies of the Avatica server). This dockerimage is not directly useful for end users; it is useful for those who want to use Avaticawith a database of their choosing.

This Docker image is deployed to the Apache Docker Hub accountand is updated for each release of Avatica.

Database-specific Docker Images

To make the lives of end-users who want to use a specific database easier, some Dockerimages are provided for some common databases. The current databases include:

  • HyperSQL (2.3.1)
  • MySQL (Client 5.1.41, supports MySQL server 4.1, 5.0, 5.1, 5.5, 5.6, 5.7)
  • PostgreSQL (Client 42.0.0, supports PostgreSQL servers >=8.3)

These images are not deployed as the licensing on each database driver is varied. Pleaseunderstand and accept the license of each before using in any software project.

Each of these images include a build.sh script which will build the docker image usingthe latest avatica-server Docker image. The resulting Docker image will be named accordingto the following format: avatica-<database>-server. For example, avatica-hsqldb-server,avatica-mysql-server, and avatica-postgresql-server.

Additionally, Docker Compose configuration files for the abovedatabases (sans HyperSQL) are provided which configure the database’s standard Docker imageand then connect Avatica to that Docker container. For example, the PostgreSQL docker-compose configurationfile will start an instance of PostgreSQL and an instance of the Avatica server, each in their own container,exposing an Avatica server configured against a “real” PostgreSQL database.

All of the Dockerfile and docker-compose.yml files are conveniently provided in an archive foreach release. Here is the layout for release 1.16.0:

  1. avatica-docker-1.16.0/
  2. avatica-docker-1.16.0/hypersql/
  3. avatica-docker-1.16.0/mysql/
  4. avatica-docker-1.16.0/postgresql/
  5. avatica-docker-1.16.0/Dockerfile
  6. avatica-docker-1.16.0/hypersql/build.sh
  7. avatica-docker-1.16.0/hypersql/Dockerfile
  8. avatica-docker-1.16.0/mysql/build.sh
  9. avatica-docker-1.16.0/mysql/docker-compose.yml
  10. avatica-docker-1.16.0/mysql/Dockerfile
  11. avatica-docker-1.16.0/postgresql/build.sh
  12. avatica-docker-1.16.0/postgresql/docker-compose.yml
  13. avatica-docker-1.16.0/postgresql/Dockerfile

Running

Each of the provided database-specific Docker images set an ENTRYPOINT whichencapsulate most of the Java command. The following options are available to specify:

  1. Usage: <main class> [options]
  2.   Options:
  3.     -h, -help, --help
  4.        Print the help message
  5.        Default: false
  6.     -p, --port
  7.        Port the server should bind
  8.        Default: 0
  9.     -s, --serialization
  10.        Serialization method to use
  11.        Default: PROTOBUF
  12.        Possible Values: [JSON, PROTOBUF]
  13.   * -u, --url
  14.        JDBC driver url for the server

For example, to connect to a MySQL server, the following could be used:

  1. $ ./avatica-docker-*/mysql/build.sh
  2. $ docker run --rm -it avatica-mysql-server \
  3.     -u jdbc:mysql://<fqdn>:3306/my_database

To debug these docker images, the ENTRYPOINT can be overriden to launch a shell

  1. $ docker run --rm --entrypoint='' -it avatica-mysql-server /bin/sh

Running Docker containers for custom databases

The provided avatica-server Docker image is designed to be generally reusablefor developers that want to expose a database of their choosing. A custom Dockerfilecan be created by copying what the avatica-mysql-server or avatica-postgresql-serverdo, but this is also achievable via the Docker volumes.

For example, consider we have a JAR with a JDBC driver for our database on our localmachine /home/user/my-database-jars/my-database-jdbc-1.0.jar. We can run the following command tolaunch a custom Avatica server against our database with this JDBC driver.

  1. $ docker run --rm -p 8765:8765 \
  2.     -v /home/user/my-database-jars/:/my-database-jars --entrypoint="" -it avatica-server \
  3.     /usr/bin/java -cp "/home/avatica/classpath/*:/my-database-jars/*" \
  4.     org.apache.calcite.avatica.standalone.StandaloneServer -p 8765 \
  5.     -u "jdbc:my_jdbc_url"

This command does the following:

  • Exposes the internal port 8765 on the local machine as 8765
  • Maps the local directory “home/user/my-database-jars” to the Docker container at “/my-database-jars” using the Docker volumes feature
  • Adds that mapped directory to the Java classpath
  • Sets the correct JDBC URL for the database