Giraffle

This plugin creates a dsl for Tigergraph. The dsl allows you to describe connections to a Tigergraph server.

Status

The Giraffle plugin is still under development. To use this plugin, you’ll need to publish it to your local maven repository. This is typically is ~/.m2/repository. Soon we’ll publish this plugin to a Maven repository.

Development Assistance

Fork and clone this repository. After this you should be able to make changes, compile, test and publish. The publishToMavenLocal will make the plugin available to your Gradle projects.

Using the plugin

In order to use this plugin you’ll need to install this plugin and Tigergraph’s gsql client.

To install the gradle plugin, follow the instructions outlined in Development Assistance.

To install the gsql client, you’ll need to obtain it from your Tigergraph installation. Once you’ve obtained the plugin, I find it handy to publish it to your local Maven repository.

The jar you’ll need is the gsql_client.jar. Instructions to find it can be found at Tigergraph’s documentation site

After obtaining the jar, use Maven’s install plugin to install it in your local repository.

Example:

mvn install:install-file \ # (1)
    -Dfile=./gsql_client.jar \ # (2)
    -DgroupId=com.tigergraph.client \ # (3)
    -DartifactId=Driver \ # (4)
    -Dversion=2.1.7 \ # (5)
    -Dpackaging=jar # (6)

1. The maven command to package and install your code.

2. The source file for this command.

3. The group to install this code to.

4. The name of the artifact we are creating.

5. The version to create when installing this artifact.

6. The type of package to create.

At this point you should have 2 jars installed locally. With these installed you can create your gradle build file that uses the plugin.

init.gradle.kts

initscript {
    repositories {
        mavenLocal() // (1)
    }
    dependencies {
        classpath("com.optum.giraffle:tigergraph-gradle-plugin:0.1.0")
    }
}

1. This is where we’ve installed this plugin and the Tigergraph gsql client.

build.gradle.kts

plugins {
    id("com.optum.giraffle) version "0.1.0" (1)
}

val tigergraph by configurations.creating // (2)
dependencies {
    tigergraph("com.tigergraph.client:Driver:2.1.7")
}

tigergraph {
    scriptDir.set(file("scripts"))
    tokens.set(emptyMap())
    serverName.set("")
    userName.set("")
    password.set("")
    adminUserName.set("")
    adminPassword.set("")
}

1. Watch this version. You’ll need to update it as development proceeds.

2. This configuration isn’t required. The defaults within the plugin provide this dependency already. However, if you need to override the defaults, this is how you do that.

This should put everything in order. The plugin defines a couple of tasks, and a dsl to handle connection parameters to your Tigergraph server(s).

Plugin DSL and Tasks

The plugin creates a dsl, custom task types, and custom tasks.

Tigergraph DSL

The dsl provided by this plugin allow configuration that applies to all the tasks and types created by the plugin.

DSL Components

All the components belong within a tigergraph closure. All of these are properties, and need to be set accordingly.

scriptDir

The scriptDir configuration is a file path location for where the gsql scripts for your project live.

The default value for scriptDir is db_scripts. It is not necessary to set this value if you’ve placed you scripts in this directory already.

Example: Kotlin

build.gradle.kts

tigergraph {
    scriptDir.set(file("scripts"))
}

Example: Groovy

build.gradle

tigergraph {
    scriptDir = file("scripts")
}

tokens

This plugin supports token replacement within your source scripts. Internally it uses an Ant filter. Simply provide a map as the parameter to this property, and your sources will have the tokens replaced before execution.

Example: Kotlin

build.gradl.kts

val tokenMap: LinkedHashMap<String, String> = linkedMapOf("graphname" to "hc")

tigergraph {
    tokens.set(tokenMap)
}

This configuration will take each occurrence of @graphname@ and replace it with the value of hc within the source scripts.

serverName

The serverName property configures which server to execute your scripts against.

Example: Kotlin

build.gradle.kts

tigergraph {
    serverName.set("dbsw00001")
}

userName

The userName property configures the username to use for connecting to tigergraph. This is the default username to use. When a script requires elevated privileges, see adminUserName and superUser.

password

The password property configures the password to use for connecting to tigergraph. This is property is used in conjunction with userName.

adminUserName

The adminUserName property configures the username to use for connecting to tigergraph. This is used when the superUser property is set on a gsql script. See superUser.

adminPassword

The adminPassword property configures the password to use for connecting to tigergraph. This is property is used in conjunction with adminUserName.

gsqlCopyTasks

The plugin defines this task, and adds it to the project. This task copies files from the scriptDir directory and copies the files to the project’s buildDir.

This is the step where token replacement occurs, as defined by the tokens property.

gsqlTaskType

This defines a task type that allows you to execute your scripts against the tigergraph server with the properties set by the Tigergraph DSL

To use this task type you simply need to define the name of the script to execute, and optionally the superUser directive.

scriptPath

The path, relative to scriptDir to execute.

superUser

The directive that indicates whether this can be executed by the default user (false), or the superUser (true).

Examples

I like using this with plugin in conjunction with the Properties plugin. This allows you to use and configure different environments.

gradle.properties

username=joe
password=joehasabadpassword
host=dbsrv001
graphname=hc

build.gradle.kts

import com.optum.giraffle.tasks.GsqlCopySources
import com.optum.giraffle.tasks.GsqlTask

plugins {
    id("com.optum.giraffle") version "0.1.0"
}

repositories {
    mavenLocal()
    jcenter()
}

val graphname: String by project // (1)
val host: String by project
val username: String by project
val password: String by project
val tokenMap: LinkedHashMap<String, String> = linkedMapOf("graphname" to graphname) // (2)

tigergraph { // (3)
    scriptDir.set(file("db_scripts"))
    tokens.set(tokenMap)
    serverName.set(host)
    userName.set(username)
    password.set(password)
}

val createSchema by tasks.creating(GsqlTask::class) {
    group = "Tigergraph Schema"
    description = "Create the schema on the database"
    scriptPath = "schema.gsql" // (4)
    superUser = true // (5)
}

1. by project is how you references project properties using the Kotlin DSL for Gradle.

2. This is how you create a Kotlin map to pass to a property.

3. Our Tigergraph DSL. These settings apply for all interactions with Tigergraph.

4. The path to the source script relative to scriptDir.

5. Informs the plugin which credentials to use.