Skip to content

viciious/go-tarantool

Folders and files

NameName
Last commit message
Last commit date

Latest commit

6f8008d · Oct 28, 2024
Oct 28, 2024
Aug 21, 2019
May 30, 2023
Aug 19, 2017
Apr 13, 2020
May 6, 2019
Oct 28, 2024
Jul 7, 2017
Jan 27, 2022
Nov 1, 2022
Oct 28, 2024
Aug 28, 2019
Oct 28, 2024
Jul 31, 2024
Nov 2, 2023
Aug 22, 2022
Aug 21, 2019
Jan 27, 2022
Jan 27, 2022
Jan 27, 2022
May 20, 2020
Sep 9, 2022
Aug 26, 2024
Apr 29, 2020
Oct 28, 2024
Mar 26, 2018
May 27, 2024
Jan 27, 2022
Jan 27, 2022
Dec 12, 2023
Jan 27, 2022
Aug 28, 2019
Feb 21, 2022
Oct 28, 2024
Jun 27, 2022
Jun 27, 2022
Jan 27, 2022
May 20, 2020
Jul 7, 2017
Aug 28, 2019
Aug 22, 2022
Mar 31, 2022
May 27, 2024
Mar 14, 2023
Mar 19, 2018
May 20, 2020
Aug 28, 2019
May 20, 2020
Aug 28, 2020
Nov 23, 2020
Jan 27, 2022
May 20, 2020
Mar 19, 2018
Feb 21, 2022
Apr 29, 2020
May 27, 2024
May 20, 2020
Jul 31, 2024
May 5, 2023
Aug 22, 2022
Mar 20, 2018
Jan 27, 2022
May 5, 2023
May 5, 2023
Jul 7, 2017
Jan 27, 2022
Oct 14, 2020
Jan 27, 2022
May 20, 2020
Mar 14, 2023

Repository files navigation

go-tarantool GoDoc Build Status

The go-tarantool package has everything necessary for interfacing with Tarantool 1.6+.

The advantage of integrating Go with Tarantool, which is an application server plus a DBMS, is that Go programmers can handle databases with responses that are faster than other packages according to public benchmarks.

Table of contents

Key features

  • Support for both encoding and decoding of Tarantool queries/commands, which leads us to the following advantages:
    • implementing services that mimic a real Tarantool DBMS is relatively easy; for example, you can code a service which would relay queries and commands to a real Tarantool instance; the server interface is documented here;
    • replication support: you can implement a service which would mimic a Tarantool replication slave and get on-the-fly data updates from the Tarantool master, an example is provided here.
  • The interface for sending and packing queries is different from other go-tarantool implementations, which you may find more aesthetically pleasant to work with: all queries are represented with different types that follow the same interface rather than with individual methods in the connector, e.g. conn.Exec(&Update{...}) vs conn.Update({}).

Installation

Pre-requisites:

  • Tarantool version 1.6 or 1.7,
  • a modern Linux, BSD or Mac OS operating system,
  • a current version of go, version 1.8 or later (use go version to check the version number).

If your go version is older than 1.8, or if go is not installed, download the latest tarball from golang.org and say:

sudo tar -C /usr/local -xzf go1.8.3.linux-amd64.tar.gz
sudo chmod -R a+rwx /usr/local/go

Make sure go and go-tarantool are on your path. For example:

export PATH=$PATH:/usr/local/go/bin
export GOPATH="/usr/local/go/go-tarantool"

The go-tarantool package is in the viciious/go-tarantool repository. To download and install, say:

go get github.com/viciious/go-tarantool

This should bring source and binary files into subdirectories of /usr/local/go, making it possible to access by adding github.com/viciious/go-tarantool in the import {...} section at the start of any Go program.

Hello World

Here is a very short example Go program which tries to connect to a Tarantool server.

package main

import (
    "context"
    "fmt"
    "github.com/viciious/go-tarantool"
)

func main() {
    opts := tarantool.Options{User: "guest"}
    conn, err := tarantool.Connect("127.0.0.1:3301", &opts)
    if err != nil {
        fmt.Printf("Connection refused: %s\n", err.Error())
	return
    }

    query := &tarantool.Insert{Space: "examples", Tuple: []interface{}{uint64(99999), "BB"}}
    resp := conn.Exec(context.Background(), query)

    if resp.Error != nil {
        fmt.Println("Insert failed", resp.Error)
    } else {
        fmt.Println(fmt.Sprintf("Insert succeeded: %#v", resp.Data))
    }

    conn.Close()
}

Cut and paste this example into a file named example.go.

Start a Tarantool server on localhost, and make sure it is listening on port 3301. Set up a space named examples exactly as described in the Tarantool manual's Connectors section.

Again, make sure PATH and GOPATH point to the right places. Then build and run example.go:

go build example.go
./example

You should see: messages saying "Insert failed" or "Insert succeeded".

If that is what you see, then you have successfully installed go-tarantool and successfully executed a program that connected to a Tarantool server and manipulated the contents of a Tarantool database.

Walking through the example

We can now have a closer look at the example.go program and make some observations about what it does.

Observation 1: the line "github.com/viciious/go-tarantool" in the import(...) section brings in all Tarantool-related functions and structures. It is common to bring in context and fmt as well.

Observation 2: the line beginning with "Opts :=" sets up the options for Connect(). In this example, there is only one thing in the structure, a user name. The structure can also contain:

  • ConnectTimeout (the number of milliseconds the connector will wait a new connection to be established before giving up),
  • QueryTimeout (the default maximum number of milliseconds to wait before giving up - can be overriden on per-query basis),
  • DefaultSpace (the name of default Tarantool space)
  • Password (user's password)
  • UUID (used for replication)
  • ReplicaSetUUID (used for replication)

Observation 3: the line containing "tarantool.Connect" is one way to begin a session. There are two parameters:

  • a string with host:port format (or "/path/to/tarantool.socket"), and
  • the option structure that was set up earlier.

There is an alternative way to connect, we will describe it later.

Observation 4: the err structure will be nil if there is no error, otherwise it will have a description which can be retrieved with err.Error().

Observation 5: the conn.exec request, like many requests, is preceded by "conn." which is the name of the object that was returned by Connect(). In this case, for Insert, there are two parameters:

  • a space name (it could just as easily have been a space number), and
  • a tuple.

All the requests described in the Tarantool manual can be expressed in a similar way within connect.Exec(), with the format "&name-of-request{arguments}". For example: &ping{}. For a long example:

    data, err := conn.Exec(context.Background(), &Update{
        Space: "tester",
        Index: "primary",
        Key:   1,
        Set: []Operator{
            &OpAdd{
                Field:    2,
                Argument: 17,
            },
            &OpAssign{
                Field:    1,
                Argument: "Hello World",
            },
        },
    })

API reference

Read the Tarantool manual to find descriptions of terms like "connect", "space", "index", and the requests for creating and manipulating database objects or Lua functions.

The source files for the requests library are:

  • connection.go for the Connect() function plus functions related to connecting, and
  • insert_test.go for an example of a data-manipulation function used in tests.

See comments in these files for syntax details:

The supported requests have parameters and results equivalent to requests in the Tarantool manual. Browsing through the other *.go programs in the package will show how the packagers have paid attention to some of the more advanced features of Tarantool, such as vclock and replication.

Alternative way to connect

Here we show a variation of example.go, where the connect is done a different way.

package main

import (
    "context"
    "fmt"
    "github.com/viciious/go-tarantool"
)

func main() {
    opts := tarantool.Options{User: "guest"}
    tnt := tarantool.New("127.0.0.1:3301", &opts)
    conn, err := tnt.Connect()
    if err != nil {
        fmt.Printf("Connection refused: %s\n", err.Error())
	return
    }

    query := &tarantool.Insert{Space: "examples", Tuple: []interface{}{uint64(99999), "BB"}}
    resp := conn.Exec(context.Background(), query)

    if resp.Error != nil {
        fmt.Println("Insert failed", resp.Error)
    } else {
        fmt.Println(fmt.Sprintf("Insert succeeded: %#v", resp.Data))
    }

    conn.Close()
}

In this variation, tarantool.New returns a Connector instance, which is a goroutine-safe singleton object that can transparently handle reconnects.

Help

To contact go-tarantool developers on any problems, create an issue at viciious/go-tarantool.

The developers of the Tarantool server will also be happy to provide advice or receive feedback.