Clojure Examples for OCI DBTools

What is this project?

1. In general, this project shows examples using Clojure to call other Java libraries.
2. The specific examples show how to use parts of the Database Tools packages from the Oracle Cloud Infrastructure (OCI) Java SDK.

What is Clojure / Why use it?

This description won't do it justice, but at a high level Clojure is a Lisp dialect written to be compiled and executed by the Java Virtual Machine (JVM). Lisp dialects are written in prefix notation (operator generally precedes the operands) and nested calls are (wrapped in sets of (parentheses)). For example a adding two integers might appear as (+ 40 2). Operators are not limited to two operands. (+ 1 2 3 4 5 6 7 8) is perfectly valid. Clojure forms can be nested so (* 3.14 (* 2 2)) should work fine. Check out the project documentation for a more complete description.

Working on a problem with new constraints and learning to look at it from a new perspective is benefical. Using Clojure to exercise the OCI Java SDK is also practical (see "What is this project?") for understanding how any Clojure developer might do this.

Setup and Prerequisites

TODO: tools / dependencies

Once you have the tools installed and your ~/.oci/config and API keys setup, you can clone this repository with:

git clone https://github.com/icodealot/dbtools-clojure.git

and run it using:

lein run

TODO: Code along?

I've tried to capture setup notes below if you'd rather code along and start your own project. This dbtools-clojure was initially generated using leiningen:

lein new app dbtools-clojure

Given a new Clojure project generated by Leiningen, we need to add dependencies. This is more or less the same as adding dependencies to a Java project managed with maven, et. al. Using lein search we can find the Java packages we need: (oci-java-sdk-common and oci-java-sdk-databasetools)

lein search oci-java-sdk-common

Depending on when you run this you should see output something like:

Searching central ...
[com.oracle.oci.sdk/oci-java-sdk-common "2.46.0"]

Repeat as needed for other dependencies you want to add. I copy/pasted them to the :dependencies section of project.clj

...
  :dependencies [[org.clojure/clojure "1.10.3"]
                 [com.oracle.oci.sdk/oci-java-sdk-common "2.46.0"]
                 [com.oracle.oci.sdk/oci-java-sdk-databasetools "2.46.0"]]
...

Once the project file is updated ask leiningen to download the jar files, which in turn downloads nested dependencies. For example:

lein deps

At the time of this writing, lein deps showed the following:

Retrieving com/oracle/oci/sdk/oci-java-sdk-common/2.46.0/oci-java-sdk-common-2.46.0.pom from central
Retrieving com/oracle/oci/sdk/oci-java-sdk/2.46.0/oci-java-sdk-2.46.0.pom from central
Retrieving com/oracle/oci/sdk/oci-java-sdk-circuitbreaker/2.46.0/oci-java-sdk-circuitbreaker-2.46.0.pom from central
Retrieving com/oracle/oci/sdk/oci-java-sdk-databasetools/2.46.0/oci-java-sdk-databasetools-2.46.0.pom from central
Retrieving com/oracle/oci/sdk/oci-java-sdk-common/2.46.0/oci-java-sdk-common-2.46.0.jar from central
Retrieving com/oracle/oci/sdk/oci-java-sdk-databasetools/2.46.0/oci-java-sdk-databasetools-2.46.0.jar from central
Retrieving com/oracle/oci/sdk/oci-java-sdk-circuitbreaker/2.46.0/oci-java-sdk-circuitbreaker-2.46.0.jar from central

Before I start adding new Clojure namespaces or code, I'll check the project runs correctly:

lein run

and this reports back...

Hello, World!

Now its time to add our own namespaces and code so I'll start with oci/auth.clj and then move on to oci/dbtools.clj. From here you can follow the commit history. Hopefully it is somewhat logical / easy enough to understand, though I am new to Clojure. Mistakes will be made.

Side note: one nice thing about working with Clojure is the REPL (read eval print and loop) which just means that Clojure can be developed interactively. This is not exclusively a Lisp or Clojure feature.

Dependencies

• oci-java-sdk-common : needed for configuration file detail providers so our OCI calls are properly authenticated.
• oci-java-sdk-databasetools : needed to make calls to the Database Tools service (DBTools) in OCI to create or manage connections and private endpoints. If you are used to the OCI command-line interface these operations are accessible using oci dbtools connection <etc.>

TODO: Namespaces

TODO: Anything else?