From a5a26ee1187cbf8613ce83d69a41816495f23027 Mon Sep 17 00:00:00 2001 From: John Gemignani Date: Wed, 31 Jan 2024 12:29:42 -0800 Subject: [PATCH] Update the Go driver documentation, Linux installer, and CI (#1527) Updated the Go driver documentation, Linux installer, and Github CI file. The documentation needed to clarify what was needed. The installer needed to be fixed. The CI file needed to have the updated Go versions. The driver installation for Linux will no longer install Java, Golang, or ANTLR for the user. This is left to the users system administrator. Instead, it will validate the current installation of those components, then build and install the driver. Also updated - modified: drivers/golang/go.mod modified: drivers/golang/go.sum --- .github/workflows/go-driver.yml | 4 +- drivers/golang/README.md | 34 +++-- drivers/golang/go.mod | 4 +- drivers/golang/go.sum | 4 + drivers/golang/install.sh | 237 +++++++++++++++--------------- drivers/golang/parser/generate.sh | 3 + 6 files changed, 150 insertions(+), 136 deletions(-) diff --git a/.github/workflows/go-driver.yml b/.github/workflows/go-driver.yml index 59030d38f..07125abdc 100644 --- a/.github/workflows/go-driver.yml +++ b/.github/workflows/go-driver.yml @@ -12,7 +12,7 @@ jobs: runs-on: ubuntu-latest strategy: matrix: - go-version: [ '1.18', '1.19' ] + go-version: [ '1.20', '1.21' ] defaults: run: @@ -38,4 +38,4 @@ jobs: run: go build -v ./... - name: Test - run: go test . -v \ No newline at end of file + run: go test . -v diff --git a/drivers/golang/README.md b/drivers/golang/README.md index b4adc6646..308472f74 100644 --- a/drivers/golang/README.md +++ b/drivers/golang/README.md @@ -1,4 +1,4 @@ -# age AGType parser and driver support for Golang +# age AGType parser and driver support for Golang AGType parser and driver support for [Apache AGE](https://age.apache.org/), graph extension for PostgreSQL. @@ -6,27 +6,29 @@ AGType parser and driver support for [Apache AGE](https://age.apache.org/), grap * Unmarshal AGE result data(AGType) to Vertex, Edge, Path * Cypher query support for 3rd. Party sql driver (enables to use cypher queries directly) -### Prerequisites -* over Go 1.18 / 1.19 -* This module runs on golang standard api [database/sql](https://golang.org/pkg/database/sql/) and [antlr4-python3](https://github.com/antlr/antlr4/tree/master/runtime/Go/antlr) +### Prerequisites (Required) +* Java 11, or greater, installed. +* Go 1.18, or greater, installed. +* This module runs on the golang standard api [database/sql](https://golang.org/pkg/database/sql/) and [antlr4-python3](https://github.com/antlr/antlr4/tree/master/runtime/Go/antlr) +* ANTLR 4.11.1, or greater, installed. ### Installation (From source) Run (Windows): install.bat Run (Linux & OSX): ``` -sh install.sh +cd age/drivers/golang +./install.sh ``` -### Go get -``` +### Go get +``` go get github.com/apache/age/drivers/golang ``` ### gomod -``` +``` require github.com/apache/age/drivers/golang {version} ``` - Check [latest version](https://github.com/apache/age/releases) ### For more information about [Apache AGE](https://age.apache.org/) @@ -34,17 +36,23 @@ Check [latest version](https://github.com/apache/age/releases) * GitHub : https://github.com/apache/age * Document : https://age.apache.org/docs/ -### Check AGE loaded on your PostgreSQL +### Check that Apache AGE is loaded on your PostgreSQL database Connect to your containerized Postgres instance and then run the following commands: ```(sql) -# psql +# psql CREATE EXTENSION age; LOAD 'age'; SET search_path = ag_catalog, "$user", public; ``` ### Test -Check out and rewrite DSN in age/drivers/golang/age/age_test.go +For the tests to work, please make sure the following has been done. +* The driver has been successfully installed following the instructions above. +* Make sure the database you will run tests against has Apache AGE installed. +* Make sure to modify the DSN value in age/drivers/golang/age/age_test.go +* Make sure the DSN has the correct database and connect string. +* Make sure the database has a graph called testGraph created. + ``` cd age/drivers/golang/age go test . -v @@ -52,7 +60,7 @@ go test . -v ``` ### Samples -* Usage 1: using database/sql API and Cypher execution function 'ExecCypher' +* Usage 1: using database/sql API and Cypher execution function 'ExecCypher' Sample : [samples/sql_api_sample.go](samples/sql_api_sample.go) * Usage 2: using Age Wrapper diff --git a/drivers/golang/go.mod b/drivers/golang/go.mod index ce3294245..c97454247 100644 --- a/drivers/golang/go.mod +++ b/drivers/golang/go.mod @@ -23,13 +23,13 @@ go 1.19 require ( github.com/antlr/antlr4/runtime/Go/antlr/v4 v4.0.0-20230321174746-8dcc6526cfb1 - github.com/lib/pq v1.10.7 + github.com/lib/pq v1.10.9 github.com/stretchr/testify v1.7.0 ) require ( github.com/davecgh/go-spew v1.1.0 // indirect github.com/pmezard/go-difflib v1.0.0 // indirect - golang.org/x/exp v0.0.0-20230321023759-10a507213a29 // indirect + golang.org/x/exp v0.0.0-20240119083558-1b970713d09a // indirect gopkg.in/yaml.v3 v3.0.0 // indirect ) diff --git a/drivers/golang/go.sum b/drivers/golang/go.sum index 3c2ce3252..957ce775f 100644 --- a/drivers/golang/go.sum +++ b/drivers/golang/go.sum @@ -4,6 +4,8 @@ github.com/davecgh/go-spew v1.1.0 h1:ZDRjVQ15GmhC3fiQ8ni8+OwkZQO4DARzQgrnXU1Liz8 github.com/davecgh/go-spew v1.1.0/go.mod h1:J7Y8YcW2NihsgmVo/mv3lAwl/skON4iLHjSsI+c5H38= github.com/lib/pq v1.10.7 h1:p7ZhMD+KsSRozJr34udlUrhboJwWAgCg34+/ZZNvZZw= github.com/lib/pq v1.10.7/go.mod h1:AlVN5x4E4T544tWzH6hKfbfQvm3HdbOxrmggDNAPY9o= +github.com/lib/pq v1.10.9 h1:YXG7RB+JIjhP29X+OtkiDnYaXQwpS4JEWq7dtCCRUEw= +github.com/lib/pq v1.10.9/go.mod h1:AlVN5x4E4T544tWzH6hKfbfQvm3HdbOxrmggDNAPY9o= github.com/pmezard/go-difflib v1.0.0 h1:4DBwDE0NGyQoBHbLQYPwSUPoCMWR5BEzIk/f1lZbAQM= github.com/pmezard/go-difflib v1.0.0/go.mod h1:iKH77koFhYxTK1pcRnkKkqfTogsbg7gZNVY4sRDYZ/4= github.com/stretchr/objx v0.1.0/go.mod h1:HFkY916IF+rwdDfMAkV7OtwuqBVzrE8GR6GFx+wExME= @@ -11,6 +13,8 @@ github.com/stretchr/testify v1.7.0 h1:nwc3DEeHmmLAfoZucVR881uASk0Mfjw8xYJ99tb5Cc github.com/stretchr/testify v1.7.0/go.mod h1:6Fq8oRcR53rry900zMqJjRRixrwX3KX962/h/Wwjteg= golang.org/x/exp v0.0.0-20230321023759-10a507213a29 h1:ooxPy7fPvB4kwsA2h+iBNHkAbp/4JxTSwCmvdjEYmug= golang.org/x/exp v0.0.0-20230321023759-10a507213a29/go.mod h1:CxIveKay+FTh1D0yPZemJVgC/95VzuuOLq5Qi4xnoYc= +golang.org/x/exp v0.0.0-20240119083558-1b970713d09a h1:Q8/wZp0KX97QFTc2ywcOE0YRjZPVIx+MXInMzdvQqcA= +golang.org/x/exp v0.0.0-20240119083558-1b970713d09a/go.mod h1:idGWGoKP1toJGkd5/ig9ZLuPcZBC3ewk7SzmH0uou08= gopkg.in/check.v1 v0.0.0-20161208181325-20d25e280405 h1:yhCVgyC4o1eVCa2tZl7eS0r+SDo693bJlVdllGtEeKM= gopkg.in/check.v1 v0.0.0-20161208181325-20d25e280405/go.mod h1:Co6ibVJAznAaIkqp8huTwlJQCZ016jof/cbN4VW5Yz0= gopkg.in/yaml.v3 v3.0.0-20200313102051-9f266ea9e77c/go.mod h1:K4uyk7z7BCEPqu6E+C64Yfv1cQ7kz7rIZviUmN+EgEM= diff --git a/drivers/golang/install.sh b/drivers/golang/install.sh index 8cd1a7d80..1465a217c 100755 --- a/drivers/golang/install.sh +++ b/drivers/golang/install.sh @@ -1,141 +1,140 @@ #!/bin/sh +# get OS os=$(uname) + +# get architecture arch=$(uname -m) -java=$(java -version 2>&1 | head -n 1 | cut -d ' ' -f 3 | cut -d '.' -f 1 | cut -d '"' -f 2) -# Check JDK version -echo "Checking for JDK..." -if ! java -version >/dev/null 2>&1 || [ $java -lt 11 ]; then - echo "JDK not found or less than version 11, would you like to install? ()" - echo "Y/N ->" - read answer - if [ "$answer" = y ] || [ "$answer" = Y ]; then - echo "Installing..." - if [[ "$os" == "Darwin" ]]; then - cd /tmp - if [[ "$arch" == "x86_64" ]]; then - curl "https://download.oracle.com/java/20/latest/jdk-20_macos-x64_bin.dmg" -o jdk-20_bin.dmg - elif [[ "$arch" == "arm64" ]]; then - curl "https://download.oracle.com/java/20/latest/jdk-20_macos-aarch64_bin.dmg" -o jdk-20_bin.dmg - fi - hdiutil mount jdk-20_bin.dmg - # sudo installer -pkg "/Volumes/JDK 20/JDK 20.pkg" -target "/" - sudo open -w "/Volumes/JDK 20/JDK 20.pkg" - hdiutil unmount "/Volumes/JDK 20" - rm jdk-20_bin.dmg - - elif [[ "$os" == "Linux" ]]; then - mkdir -p ~/tmp/jdk20 - cd ~/tmp/jdk20 - if [[ "$arch" == "x86_64" ]]; then - curl "https://download.oracle.com/java/20/latest/jdk-20_linux-x64_bin.tar.gz" -o jdk-20_bin.tar.gz - elif [[ "$arch" == "arm64" ]]; then - curl "https://download.oracle.com/java/20/latest/jdk-20_linux-aarch64_bin.tar.gz" -o jdk-20_bin.tar.gz - fi - sudo tar zxvf jdk-20_bin.tar.gz -C /usr/local/ - cd ~/ - rm -rf ~/tmp/jdk20/ - fi - echo "JDK installation complete." - else - echo "Please install JDK >= 11.0.16" - exit 0 - fi +# Check Java installation +echo "Checking for minimum Java installation..." + +java_version=$(java -version 2>&1 | awk -F '"' '/version/ {print $2}') + +if [ ! -z $java_version ]; then + echo "Java version $java_version" else - echo "JDK already installed." + echo "Java not found. Please install Java." fi -antlr=$(/usr/local/jdk-20/bin/jar xf /usr/local/antlr/antlr-*-complete.jar META-INF/MANIFEST.MF >/dev/null 2>&1 && grep 'Implementation-Version' META-INF/MANIFEST.MF | cut -d ' ' -f 2 && rm -rf META-INF) -# Check ANTLR installation and version -echo "Checking for ANTLR..." -check_antlr () { - if [ ! -z $antlr ]; then - if ([ "$(echo $antlr | cut -d '.' -f 1)" -lt 4 ] && [ "$(echo $antlr | cut -d '.' -f 2)" -lt 11 ] && [ "$(echo $antlr | cut -d '.' -f 3)" -lt 1 ]); then - return 0 - else - return 1 - fi - else - return 0 - fi -} - -if check_antlr; then - echo "ANTLR not found in Default Location or less than version 4.11.1, would you like to Install?" - echo "(If installed in other location, please edit the location inside the shell script before running)" - echo "Y/N ->" - read answer - if [ "$answer" = y ] || [ "$answer" = Y ]; then - mkdir -p ~/tmp/antlr4.11.1 - cd ~/tmp/antlr4.11.1 - curl -LO "https://www.antlr.org/download/antlr-4.11.1-complete.jar" - sudo mkdir -p /usr/local/antlr - sudo mv ~/tmp/antlr4.11.1/antlr-4.11.1-complete.jar /usr/local/antlr/antlr-4.11.1-complete.jar - - echo 'export CLASSPATH=".:/usr/local/antlr/antlr-4.11.1-complete.jar"' >>~/.bashrc - . ~/.bashrc - echo "ANTLR installation complete." - else - echo "Please install ANTLR >= 4.11.1" - exit 0 - fi - # +# Get Java version +java_major=$(echo $java_version | cut -d '.' -f1) +java_minor=$(echo $java_version | cut -d '.' -f2) +java_patch=$(echo $java_version | cut -d '.' -f3) + +# Check Java version +java_version_flag=0 +if [ $java_major -lt 11 ]; then + java_version_flag=0 +elif [ $java_minor -lt 0 ]; then + java_version_flag=0 +elif [ $java_patch -lt 0 ]; then + java_version_flag=0 else - echo "ANTLR already installed." + java_version_flag=1 fi -# Check Go installation and version -echo "Checking for Go..." -if ! command -v go >/dev/null 2>&1 || { [ $(go version | grep -o -E '[0-9]+\.[0-9]+' | head -n 1 | cut -d '.' -f 1) -lt 1 ] && [ $(go version | grep -o -E '[0-9]+\.[0-9]+' | head -n 1 | cut -d '.' -f 2) -lt 19 ]; }; then - echo "Go not installed or version is less than 1.19, would you like to install?" - echo "Y/N ->" - read answer - if [ "$answer" = y ] || [ "$answer" = Y ]; then - if [[ "$os" == "Darwin" ]]; then - cd /tmp - if [[ "$arch" == "x86_64" ]]; then - curl "https://go.dev/dl/go1.20.2.darwin-amd64.pkg" -o go1.20.2.pkg - elif [[ "$arch" == "arm64" ]]; then - curl "https://go.dev/dl/go1.20.2.darwin-arm64.pkg" -o go1.20.2.pkg - fi - - #sudo installer -pkg "go1.20.2.pkg" -target "/" - sudo open -w golang.pkg - - elif [[ "$os" == "Linux" ]]; then - mkdir -p ~/tmp/go1.20.2 - cd ~/tmp/go1.20.2 - if [[ "$arch" == "x86_64" ]]; then - curl "https://go.dev/dl/go1.20.2.linux-amd64.tar.gz" -o go1.20.2.tar.gz - elif [[ "$arch" == "arm64" ]]; then - curl "https://go.dev/dl/go1.20.2.linux-arm64.tar.gz" -o go1.20.2.tar.gz - fi - - if command -v go >/dev/null 2>&1; then - rm -rf /usr/local/go - fi - sudo tar -C /usr/local -xzf go1.20.2.linux-amd64.tar.gz - - if ! [[ ":$PATH:" == *":/usr/local/go/bin:"* ]]; then - export PATH=$PATH:/usr/local/go/bin - fi - fi - echo "Go installation complete" - else - echo "Please install Go >= 1.19" - exit 0 - fi +if [ $java_version_flag -eq 0 ]; then + echo "Java version less than 11.0.0" + echo "NOTE: If a newer version of Java is installed, but not set as " + echo " the current version, exit and select it before continuing." + exit 0 else - echo "Go already installed." + echo "Java is installed." + echo "" fi +# Check ANTLR installation +echo "Checking for minimum ANTLR installation..." +jar xf /usr/local/antlr/antlr-*-complete.jar META-INF/MANIFEST.MF >/dev/null 2>&1 +antlr_version=$(grep 'Implementation-Version' META-INF/MANIFEST.MF | cut -d ' ' -f 2) +rm -rf META-INF +if [ ! -z $antlr_version ]; then + echo "ANTLR version $antlr_version" +else + echo "ANTLR not found. Please install ANTLR." + exit 0 +fi +# Check ANTLR version +antlr_version_flag=0 +antlr_major=$(echo $antlr_version | cut -d '.' -f 1) +antlr_minor=$(echo $antlr_version | cut -d '.' -f 2) +antlr_patch=$(echo $antlr_version | cut -d '.' -f 3 | sed 's/\r//') + +if [ $antlr_major -lt 4 ]; then + antlr_version_flag=0 +elif [ $antlr_minor -lt 11 ]; then + antlr_version_flag=0 +elif [ $antlr_patch -lt 1 ]; then + antlr_version_flag=0 +else + antlr_version_flag=1 +fi + +if [ $antlr_version_flag -eq 0 ]; then + echo "ANTLR version less than 4.11.1" + exit 0 +else + echo "ANTLR is installed." + echo "" +fi + +# Check Go installation +echo "Checking for minimum Golang installation..." +go_version=$(go version 2>&1 | cut -d' ' -f3) + +if [ ! -z $go_version ]; then + echo "Golang version $go_version" +else + echo "Golang not found. Please install Golang." + exit 0 +fi + +# Check Go version +go_version_flag=0 +go_major=$(echo $go_version | cut -d '.' -f1 | cut -d 'o' -f 2) +go_minor=$(echo $go_version | cut -d '.' -f2) +go_patch=$(echo $go_version | cut -d '.' -f3) + +if [ $go_major -lt 1 ]; then + go_version_flag=0 +elif [ $go_minor -lt 18 ]; then + go_version_flag=0 +elif [ $go_patch -lt 0 ]; then + go_version_flag=0 +else + go_version_flag=1 +fi + +if [ $go_version_flag -eq 0 ]; then + echo "Golang version less than 1.19.0" + exit 0 +else + echo "Golang is installed." + echo "" +fi + +# Check CLASSPATH +echo "Checking for ANTLR in CLASSPATH..." +test_classpath=$(echo $CLASSPATH | grep antlr) + +if [ ! -z $test_classpath ]; then + echo "CLASSPATH = $CLASSPATH" + echo "" +else + echo "ANTLR not set in CLASSPATH. Please set up CLASSPATH." + exit 0 +fi + +# Generate Parser and Lexer echo "Generating Parser & Lexer..." -java -Xmx500M -cp "/usr/local/lib/antlr-4.11.1-complete.jar:$CLASSPATH" org.antlr.v4.Tool -Dlanguage=Go -visitor Age.g4 +java -Xmx500M org.antlr.v4.Tool -Dlanguage=Go -visitor parser/Age.g4 +# Install Golang driver echo "Installing Driver..." go get -u ./... + echo "Successfully Installed Driver!" exit 0 diff --git a/drivers/golang/parser/generate.sh b/drivers/golang/parser/generate.sh index e45501b4e..9fa3cafc1 100755 --- a/drivers/golang/parser/generate.sh +++ b/drivers/golang/parser/generate.sh @@ -1,4 +1,7 @@ #!/bin/sh +# +# Please be aware that this is used by the CI scripts +# GRAMMAR_LOC="$(dirname $(pwd))/parser" mkdir -p ~/tmp/antlr