Update the Go driver documentation, Linux installer, and CI (#1527)

.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
+      run: go test . -v

drivers/golang/README.md

@@ -1,58 +1,66 @@
-# 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.
 
 ### Features
 * 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/)
 * Apache Age : https://age.apache.org/
 * 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
 
 ```
 
 ### 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 

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
 )

drivers/golang/go.sum

@@ -4,13 +4,17 @@ 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=
 github.com/stretchr/testify v1.7.0 h1:nwc3DEeHmmLAfoZucVR881uASk0Mfjw8xYJ99tb5CcY=
 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=

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

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