YottaDB Go Wrapper

| |

Deprecation Warning

The YDBGo v2 API is in field test. If you use the v1 API rest assured that it remains fully supported. Please refer to Migrating v1 to v2 for details on migration and on applications that simultaneously use v1 and v2 APIs during migration.

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

2. Create an empty directory anywhere on your file system and go there.

mkdir ydb-example
cd ydb-example

3. Use go mod init to create a package for your code in a unique namespace:

go mod init example.com/yottadb-example

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

5. Download the YottaDB module by using go get .

6. Run the code using go run .

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

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

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

Developing this wrapper

To develop the YottaDB Go wrapper itself you may wish to import your local version of the wrapper from a separate local client of the wrapper. To do this, clone the wrapper, then in a separate directory set up the client as above. Then use go work commands to point it to the wrapper on your local file system rather than the internet repository. Run the following commands in the client directory:

go work init
go work use /your/local/path/to/YDBGo  # Set this path to your YDBGo clone
git ignore go.work

The git ignore line prevents you from committing this local change to the public who will not have your local wrapper clone.

Now you can modify the YottaDB Go wrapper on your local file system, and it will be immediately used by your client application, even before you commit the wrapper changes.

Testing

To test this wrapper:

• 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
go install honnef.co/go/tools/cmd/staticcheck@latest

Advanced Configuration

Setup pkg-config

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.