The package go-tarantool
contains everything you need to connect to
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 and perform on-the-fly recompilations of embedded Lua routines, just as in C, with responses that are faster than other packages according to public benchmarks.
We assume that you have Tarantool version 1.6+ and a modern Linux or BSD operating system.
You need a current version of go
, version 1.13 or later (use go version
to
check the version number). Do not use gccgo-go
.
Note: If your go
version is older than 1.13 or if go
is not installed,
download and run the latest tarball from golang.org.
The package go-tarantool
is located in tarantool/go-tarantool
repository. To download and install, say:
$ go get github.com/tarantool/go-tarantool
This should put the source and binary files in subdirectories of
/usr/local/go
, so that you can access them by adding
github.com/tarantool/go-tarantool
to the import {...}
section at the start
of any Go program.
We define multiple build tags.
This allows us to introduce new features without losing backward compatibility.
- To disable SSL support and linking with OpenSSL, you can use the tag:
go_tarantool_ssl_disable
- To change the default
Call
behavior fromCall16
toCall17
, you can use the build tag:Note: In future releases,go_tarantool_call_17
Call17
may be used as defaultCall
behavior. - To replace usage of
msgpack.v2
withmsgpack.v5
, you can use the build tag:Note: In future releases,go_tarantool_msgpack_v5
msgpack.v5
may be used by default. We recommend to read msgpack.v5 migration notes and try to use msgpack.v5 before the changes. - To run fuzz tests with decimals, you can use the build tag:
Note: It crashes old Tarantool versions and requires Go 1.18+.
go_tarantool_decimal_fuzzing
Read the Tarantool documentation to find descriptions of terms such as "connect", "space", "index", and the requests to create and manipulate database objects or Lua functions.
In general, connector methods can be divided into two main parts:
Connect()
function and functions related to connecting, and- Data manipulation functions and Lua invocations such as
Insert()
orCall()
.
The supported requests have parameters and results equivalent to requests in the Tarantool CRUD operations. There are also Typed and Async versions of each data-manipulation function.
Learn API documentation and examples at pkg.go.dev.
We can now have a closer look at the example and make some observations about what it does.
package tarantool
import (
"fmt"
"github.com/tarantool/go-tarantool"
)
func main() {
opts := tarantool.Opts{User: "guest"}
conn, err := tarantool.Connect("127.0.0.1:3301", opts)
if err != nil {
fmt.Println("Connection refused:", err)
}
resp, err := conn.Insert(999, []interface{}{99999, "BB"})
if err != nil {
fmt.Println("Error", err)
fmt.Println("Code", resp.Code)
}
}
Observation 1: The line "github.com/tarantool/go-tarantool
" in the
import(...)
section brings in all Tarantool-related functions and structures.
Observation 2: The line starting with "Opts :=
" sets up the options for
Connect()
. In this example, the structure contains only a single value, the
username. The structure may also contain other settings, see more in
documentation for the "Opts
" structure.
Observation 3: The line containing "tarantool.Connect
" is essential for
starting a session. There are two parameters:
- a string with
host:port
format, and - the option structure that was set up earlier.
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 Insert
request, like almost all requests, is preceded by
"conn.
" which is the name of the object that was returned by Connect()
.
There are two parameters:
- a space number (it could just as easily have been a space name), and
- a tuple.
Most function names and argument types in msgpack.v5
and msgpack.v2
have not changed (in our code, we noticed changes in EncodeInt
, EncodeUint
and RegisterExt
). But there are a lot of changes in a logic of encoding and
decoding. On the plus side the migration seems easy, but on the minus side you
need to be very careful.
First of all, EncodeInt8
, EncodeInt16
, EncodeInt32
, EncodeInt64
and EncodeUint*
analogues at msgpack.v5
encode numbers as is without loss of
type. In msgpack.v2
the type of a number is reduced to a value.
Secondly, a base decoding function does not convert numbers to int64
or
uint64
. It converts numbers to an exact type defined by MessagePack. The
change makes manual type conversions much more difficult and can lead to
runtime errors with an old code. We do not recommend to use type conversions
and give preference to *Typed
functions (besides, it's faster).
There are also changes in the logic that can lead to errors in the old code,
as example. Although in
msgpack.v5
some functions for the logic tuning were added (see
UseLooseInterfaceDecoding, UseCompactInts etc), it is still impossible
to achieve full compliance of behavior between msgpack.v5
and msgpack.v2
. So
we don't go this way. We use standard settings if it possible.
See the contributing guide for detailed instructions on how to get started with our project.
There are two other connectors available from the open source community:
See feature comparison in the documentation.