The current main branch is under active development for the next major release (v3).

The API on this branch is unstable and subject to change.

For production use and stable API, please use the v2 branch of the repository.

The package go-tarantool contains everything you need to connect to Tarantool 1.10+.

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.

• Installation
  • Build tags
• Documentation
  • API reference
  • Walking-through example
  • Example with encrypting traffic
• Migration guide
• Contributing
• Related libraries
• Alternative connectors

We assume that you have Tarantool version 1.10+ and a modern Linux or BSD operating system.

You need a current version of go, version 1.24 or later (use go version to check the version number). Do not use gccgo-go.

Note: If your go version is older than 1.24 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/v3

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.

1. To run fuzz tests with decimals, you can use the build tag:

   go_tarantool_decimal_fuzzing
   

   Note: It crashes old Tarantool versions.

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() or Call().

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 (
	"context"
	"fmt"
	"time"

	"github.com/tarantool/go-tarantool/v3"
	_ "github.com/tarantool/go-tarantool/v3/datetime"
	_ "github.com/tarantool/go-tarantool/v3/decimal"
	_ "github.com/tarantool/go-tarantool/v3/uuid"
)

func main() {
	ctx, cancel := context.WithTimeout(context.Background(), time.Second)
	defer cancel()
	dialer := tarantool.NetDialer{
		Address: "127.0.0.1:3301",
		User: 	 "guest",
	}
	opts := tarantool.Opts{
		Timeout: time.Second,
	}

	conn, err := tarantool.Connect(ctx, dialer, opts)
	if err != nil {
		fmt.Println("Connection refused:", err)
		return
	}

	data, err := conn.Do(
		tarantool.NewInsertRequest(999).Tuple([]interface{}{99999, "BB"})).Get()
	if err != nil {
		fmt.Println("Error:", err)
	} else {
		fmt.Println("Data:", data)
	}
}

Observation 1: The line "github.com/tarantool/go-tarantool/v3" in the import(...) section brings in all Tarantool-related functions and structures.

Observation 2: Unused import lines are required to initialize encoders and decoders for external msgpack types.

Observation 3: The line starting with "ctx, cancel :=" creates a context object for Connect(). The Connect() call will return an error when a timeout expires before the connection is established.

Observation 4: The line starting with "dialer :=" creates dialer for Connect(). This structure contains fields required to establish a connection.

Observation 5: The line starting with "opts :=" sets up the options for Connect(). In this example, the structure contains only a single value, the timeout. The structure may also contain other settings, see more in documentation for the "Opts" structure.

Observation 6: The line containing "tarantool.Connect" is essential for starting a session. There are three parameters:

• a context,
• the dialer that was set up earlier,
• the option structure that was set up earlier.

There will be only one attempt to connect. If multiple attempts needed, "tarantool.Connect" could be placed inside the loop with some timeout between each try. Example could be found in the example_test, name - ExampleConnect_reconnects.

Observation 7: 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 8: The Insert request, like almost all requests, is preceded by the method Do of object conn which is the object that was returned by Connect().

For SSL-enabled connections, use OpenSSLDialer from the go-tlsdialer package.

Here is small example with importing the go-tlsdialer library and using the OpenSSLDialer:

package tarantool

import (
	"context"
	"fmt"
	"time"

	"github.com/tarantool/go-tarantool/v3"
	_ "github.com/tarantool/go-tarantool/v3/datetime"
	_ "github.com/tarantool/go-tarantool/v3/decimal"
	_ "github.com/tarantool/go-tarantool/v3/uuid"
	"github.com/tarantool/go-tlsdialer"
)

func main() {
	ctx, cancel := context.WithTimeout(context.Background(), time.Second)
	defer cancel()
	dialer := tlsdialer.OpenSSLDialer{
		Address:     "127.0.0.1:3013", 
		User:        "test", 
		Password:    "test", 
		SslKeyFile:  "testdata/localhost.key",
		SslCertFile: "testdata/localhost.crt",
		SslCaFile:   "testdata/ca.crt",
	}
	opts := tarantool.Opts{
		Timeout: time.Second,
	}

	conn, err := tarantool.Connect(ctx, dialer, opts)
	if err != nil {
		fmt.Println("Connection refused:", err)
		return
	}

	data, err := conn.Do(
		tarantool.NewInsertRequest(999).Tuple([]interface{}{99999, "BB"})).Get()
	if err != nil {
		fmt.Println("Error:", err)
	} else {
		fmt.Println("Data:", data)
	}
}

Note that traffic encryption is only available in Tarantool Enterprise Edition 2.10 or newer.

You can implement custom request types by implementing the Request interface. This is useful when you need to send non-standard requests or implement custom response handling.

• Simple custom request - demonstrates how to implement a custom ping request using the DecodeBaseResponse helper.

• Advanced custom request - shows how to implement a custom select request with manual body encoding and response decoding.

• Typed decoding - demonstrates how to implement DecodeTyped for custom response types.

When implementing the Response method:

1. Read all data immediately: The io.Reader is only valid during the Response method call. You must read all response data before returning.

2. Use helpers when possible: DecodeBaseResponse handles the common case and should be preferred unless you need custom response handling.

3. Memory management: Call Release() on responses to free resources. Custom implementations should clean up internal buffers.

You can review the changes between major versions in the migration guide.

See the contributing guide for detailed instructions on how to get started with our project.

The Tarantool team provides several complementary Go libraries that extend the functionality of go-tarantool:

• go-iproto — IPROTO protocol constants generated from Tarantool source code. It provides request types, response codes, keys, and feature flags defined in the Tarantool IPROTO specification for building custom protocol implementations or low-level debugging.

• go-openssl — OpenSSL bindings for Go, forked from libp2p/openssl with fixes for Go 1.13+, Apple M1, static build, and DANE support. It provides TLS functionality used by go-tlsdialer for secure connections.

• go-tlsdialer — TLS dialers for secure connections to Tarantool Enterprise Edition. It serves as an interlayer between go-tarantool and go-openssl, supporting SSL/TLS with certificate verification for encrypted traffic.

• go-tupleconv — Tarantool tuples converter for transforming data between Go types and Tarantool tuple formats. It provides mappers built from configurable converters, supporting automatic type conversion for nullable fields, decimals, and other Tarantool types.

• go-option — Optional types for Go with MessagePack serialization support. It provides zero-allocation optional values (Some/None semantics), useful for distinguishing between nil values and missing fields when working with Tarantool tuples.

• go-config — A library for handling hierarchical configurations with inheritance, validation, and flexible merging strategies. It supports multiple data sources (files, environment variables, etcd, TCS) and resolves effective configuration for entities in distributed systems.

• go-storage — A uniform interface for managing centralized configuration storages with support for multiple backends (etcd, Tarantool Config Storage). It provides transactional operations, conditional predicates, real-time watch, and data integrity features.

• go-vshard-router — A library for sending requests to a sharded Tarantool cluster directly, without using a Tarantool-side vshard router. It implements the vshard routing logic in Go, improving performance by eliminating the intermediate proxy layer.

• go-discovery — Cluster discovery helpers for Tarantool 3.0. It enables automatic detection and connection to cluster instances through etcd-based configuration, providing connection pooling and topology-aware request routing.

• go-tlog — A lightweight and configurable structured logging library. It supports multiple output formats (text, JSON), multiple destinations (stdout, stderr, files), log levels, and automatic stacktraces for errors.

There are two other connectors available from the open source community:

• viciious/go-tarantool,
• FZambia/tarantool.

See feature comparison in the documentation.