Giraffle

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

The Giraffle plugin has been published to the Gradle plugins repository. You may use it by referencing it within your plugins block. Please referr to the Using the plugin section for instructions.

Using the plugin

Like most Gradle plugins, you simply need to add the id to the plugins closure.

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

The plugin needs the Tigergraph Gsql client. The Tigergraph plugin @ Bintray is published to bintray, and is available via the jcenter() repository. To use the gsql_client you’ll need to add the jcenter() to you repositories block.

repositories {
    jcenter()
}

Kotlin

build.gradle.kts

import com.optum.giraffle.tasks.GsqlTask

plugins {
    id("com.optum.giraffle") version "1.1.0" // <1>
}

repositories {
    jcenter()
}

dependencies {
    gsqlRuntime("com.tigergraph.client:gsql_client:2.3.2.1") // <2>
}

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

tasks.create("createSchema") { // <3>
    dependsOn("dropSchema")
    scriptPath = "schema.gsql"
}

Groovy

build.gradle

import com.optum.giraffle.tasks.GsqlTask

plugins {
    id "com.optum.giraffle" version "1.1.0" // <1>
}

repositories {
    jcenter()
}

dependencies {
    gsqlRuntime "com.tigergraph.client:gsql_client:2.3.2.1" // <2>
}

tigergraph {
    scriptDir = file("db_scripts")
    tokens = []
    serverName = ""
    userName = ""
    password = ""
    adminUserName = ""
    adminPassword = ""
}

task createSchema(type: GsqlTask, dependsOn: [dropSchema] ) { // <3>
    scriptPath = "schema.gsql"
}

Watch this version. You’ll need to update it as development proceeds.
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. You might want to override this value if you need a different version of the gsql_client.
Here’s a new task that will execute the schema.gsql script located in the project’s ./db_scripts/ folder.

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).

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. Add the mavenLocal() repository to your repositories closure.

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"))
}

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.gradle.kts

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

tigergraph {
    tokens.set(tokenMap)
}

Groovy

build.gradle

def tokenMap = ["graphname": "hc"]

tigergraph {
    tokens = 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")
}

Groovy

build.gradle

tigergraph {
    serverName = "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.

gsqlNewProject

The plugin defines this task to help initialized a new Tigeraph Gradle project. This is an interactive task that asks you questions about your project and creates a build file, property file(s), a gitignore file, and a skelton directory structure. To use this feature create a build file in an empty directory:

Kotlin

build.gradle.kts

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

Groovy

build.gradle

plugins {
    id "com.optum.giraffle" version "1.1.0"
}

With one of these files in place, run

$ gradle gsqlNewProject --console=plain # (1)

I suggest using the --console=plain option for interactive tasks. It doesn’t display the timer and percentage completed. These outputs make interactive tasks messy.

Running this task will ask you a series of questions, and create a bare bones project for you.

gsqlShell

This task invokes the gsql command, logs you into the server using the credentials configured by your properties file, and drops you to an interactive shell.

$ gradle gsqlShell --console=plain #

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. When using the properties plugin always add an entry to my .gitignore for gradle-local.properties. This way you won’t commit credentials to your code repository.

Consider a directory layout as follows:

├── .gitignore
├── build.gradle.kts
├── db_scripts
│   ├── drop.gsql
│   ├── schema.gsql
│   └── show_graph.gsql
├── gradle-local.properties
├── gradle.properties
├── init.gradle.kts
└── settings.gradle.kts

Kotlin

build.gradle.kts

import com.optum.giraffle.tasks.GsqlTask

plugins {
    id("com.optum.giraffle") version "1.1.0"
    id("net.saliman.properties") version "1.4.6"
}

repositories {
    jcenter()
}

val gsqlGraphname: String by project // <1>
val gsqlHost: String by project
val gsqlUserName: String by project
val gsqlPassword: String by project
val gsqlAdminUserName: String by project
val gsqlAdminPassword: String by project
val tokenMap: LinkedHashMap = linkedMapOf("graphname" to gsqlGraphname) // <2>
val grpSchema: String = "Tigergraph Schema"

tigergraph { // <3>
    scriptDir.set(file("db_scripts"))
    tokens.set(tokenMap)
    serverName.set(gsqlHost)
    userName.set(gsqlUserName)
    password.set(gsqlPassword)
    adminUserName.set(gsqlAdminUserName)
    adminPassword.set(gsqlAdminPassword)
}

val createSchema by tasks.creating(GsqlTask::class) { // <4>
    group = grpSchema
    description = "Create the schema on the database"
    dependsOn("dropSchema") // <5>
    scriptPath = "schema.gsql" // <6>
    superUser = true // <7>
}

tasks.create("dropSchema") { // <8>
    group = grpSchema
    description = "Drops the schema on the database"
    scriptPath = "drop.gsql"
    superUser = true
}

Groovy

build.gradle

import com.optum.giraffle.tasks.GsqlTask

plugins {
    id "com.optum.giraffle" version "1.1.0"
    id "net.saliman.properties" version "1.4.6"
}

repositories {
    jcenter()
}

def tokenMap = ["graphname": gsqlGraphname] // <2>
def grpSchema = "Tigergraph Schema"

tigergraph { // <3>
    scriptDir = file("db_scripts")
    tokens = tokenMap
    serverName = gsqlHost
    userName = gsqlUserName
    password = gsqlPassword
    adminUserName = gsqlAdminUserName
    adminPassword = gsqlAdminPassword
}

task dropSchema(type: GsqlTask) {
    group = grpSchema
    description = "Drops the schema on the database"
    scriptPath = "drop.gsql"
    superUser = true
}

task createSchema(type: GsqlTask,
    dependsOn: [dropSchema] // <5>
) { // <4>
    group = grpSchema
    description = "Create the schema on the database"
    scriptPath = "schema.gsql" // <6>
    superUser = true // <7>
}

by project is how you references project properties using the Kotlin DSL for Gradle.
This is how you create a Kotlin map to pass to a property.
Our Tigergraph DSL. These settings apply for all interactions with Tigergraph.
One way to create a task using the custom task type created by the plugin.
This task will execute after the task that it dependsOn.
The path to the source script relative to scriptDir.
Informs the plugin which credentials to use.
Another way to create a task.

db_scripts/schema.gsql

CREATE VERTEX Person ( primary_id ssn STRING, firstName STRING, lastName STRING)
CREATE UNDIRECTED EDGE FRIENDS (FROM Person, TO Person, effectiveDate DATETIME)

CREATE GRAPH @graphname@(Person, FRIENDS)

db_scripts/drop.gsql

USE GRAPH @graphname@

DROP GRAPH @graphname@

USE GLOBAL

DROP EDGE FRIENDS
DROP VERTEX Person

gradle.properties

gsqlHost=
gsqlUserName=
gsqlPassword=
gsqlAdminUserName=
gsqlAdminPassword=
gsqlGraphname=hc

gradle-local.properties

gsqlHost=localhost
gsqlUserName=tigergraph
gsqlPassword=tigergraph
gsqlAdminUserName=tigergraph
gsqlAdminPassword=tigergraph

This setup will allow you to deploy your schema against your Tigergraph database.

gradle createSchema

jd-xpi13 / giraffle Goto Github PK

giraffle's Introduction

Giraffle

Using the plugin

Development Assistance

Plugin DSL and Tasks

Tigergraph DSL

DSL Components

scriptDir

tokens

serverName

userName

password

adminUserName

adminPassword

gsqlNewProject

gsqlShell

gsqlCopyTasks

gsqlTaskType

scriptPath

superUser

Examples

giraffle's People

Contributors

Recommend Projects

Recommend Topics

Recommend Org