Skip to content

Latest commit

 

History

History
146 lines (101 loc) · 4.92 KB

README.md

File metadata and controls

146 lines (101 loc) · 4.92 KB
Raw

YottaDB Go Wrapper

Build Status Go Report Card Go Doc Coverage report

Usage (Writing a YDBGo Client application)

YottaDB must be installed. See Get Started for instructions for installing YottaDB. YDBGo supports versions YottaDB r1.24 or later. If you wish to use an earlier version, see the section on Pkg-config Set-up below.

  1. A YottaDB database must be set-up and the environment variables configured. This can be easily done by sourcing /path/to/yottadb/ydb_env_set, e.g.:
source $(pkg-config --variable=prefix yottadb)/ydb_env_set
  1. Create an empty directory anywhere on your file system and go there.
mkdir ydb-example
cd ydb-example
  1. Use go mod init to create a package for your code in a unique namespace:
go mod init example.com/yottadb-example
  1. Create a Go program (e.g. ydb.go) containing your main program with an import of lang.yottadb.com/go/yottadb. E.g.:
package main

import (
	"lang.yottadb.com/go/yottadb"
)

func main() {
	// Set global node ^hello("world")="Sawadee (hello in Thai)"
	err := yottadb.SetValE(yottadb.NOTTP, nil, "สวัสดี", "^hello", []string{"world"})
	if err != nil {
		panic(err)
	}
}

  1. Download the YottaDB module by using go get .

  2. Run the code using go run .

  3. You can verify that the data got saved by running mupip extract -sel=^hello -stdout

  4. go build will create an exe for you (yottadb-example in this case). You can run that directly (e.g. ./yottadb-example).

  5. go install will install the exe for you in $GOPATH/bin or ~/go by default.

Setting up for development using this repository

To work on developing YottaDB Go wrapper, you still need all the previous steps for a "client" application; but you also need to clone this repository in a separate directory, and use go mod edit in the client application directory to make the "client" application point to the YDBGo repository on the file system. In the previous set-up, the "client" application actually points to the published version of the module on the Internet cached locally.

For the purpose of this discussion, let's assume that the YDBGo repository is located at /YDBGo. In our client application directory then:

go mod edit -replace=lang.yottadb.com/go/yottadb=/YDBGo/
go get .

Modify yottadb.SetValE function in /YDBGo/easy_api.go to add a fmt.Println("foo"). The back in the client application, run the code again:

go run .
foo

You will see that we actually now are using the code we modified rather than the code on the Internet.

Here are a few other interesting commands to run inside the YDBGo repo:

  • go build only does a test compilation; it does not produce any files; go install has no effect.
  • To run tests, run go get -t, then go test -v.

Last, if you plan to commit, you should set-up pre-commit hooks.

ln -s ../../pre-commit .git/hooks

Advanced Configuration

Pkg-config Set-up

This package uses pkg-config to find libyottadb.so. The appropriate file is generated by YottaDB r1.24 and greater via ydbinstall (any other installation methods do not install the yottadb.pc file).

If you need to manually generate the yottadb.pc file the contents should look something similar to:

prefix=/usr/local/lib/yottadb/r124

exec_prefix=${prefix}
includedir=${prefix}
libdir=${exec_prefix}

Name: YottaDB
Description: YottaDB database library
Version: r1.24
Cflags: -I${includedir}
Libs: -L${libdir} -lyottadb -Wl,-rpath,${libdir}

Change the prefix to the correct path for your environment.

NOTE: you cannot use environment variables for the prefix path (e.g. $ydb_dist) it must be a fully qualified path.

You can also override the path used by pkg-config to find yottadb.pc with the environment variable PKG_CONFIG_PATH and a path to where the yottadb.pc file resides.

Docker Container

The Dockerfile/container included in this repo pre-installs YottaDB and the Go language and runs on an Ubuntu image. Some basic development tools are also pre-installed (git, gcc, make, vim, etc).

Building the Container

To build the container run:

docker build . -t ydbgo

Using the container to develop YDBGo

docker run --rm -it -v ~/goprojects:/goprojects -v ~/work/gitlab/YDBGo:/YDBGo -v ${PWD}/data:/data -w /goprojects ydbgo bash
. /opt/yottadb/current/ydb_env_set

Then follow the instructions for usage and setting up for development above.