{"id":13792703,"url":"https://github.com/tarantool/go-tarantool","last_synced_at":"2025-05-12T14:32:02.373Z","repository":{"id":24812546,"uuid":"28226810","full_name":"tarantool/go-tarantool","owner":"tarantool","description":"Tarantool 1.10+ client for Go language","archived":false,"fork":true,"pushed_at":"2025-04-10T07:38:18.000Z","size":1106,"stargazers_count":190,"open_issues_count":34,"forks_count":60,"subscribers_count":25,"default_branch":"master","last_synced_at":"2025-04-10T08:37:32.529Z","etag":null,"topics":["go","tarantool","tarantool-connector"],"latest_commit_sha":null,"homepage":"https://pkg.go.dev/github.com/tarantool/go-tarantool/v2","language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":"fl00r/go-tarantool-1.6","license":"bsd-2-clause","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/tarantool.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null}},"created_at":"2014-12-19T11:26:52.000Z","updated_at":"2025-04-03T07:53:59.000Z","dependencies_parsed_at":"2023-09-26T16:38:00.796Z","dependency_job_id":"e4bd642b-3b51-4c3a-8336-4bc2ecbc932d","html_url":"https://github.com/tarantool/go-tarantool","commit_stats":null,"previous_names":["mialinx/go-tarantool-1.6"],"tags_count":13,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tarantool%2Fgo-tarantool","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tarantool%2Fgo-tarantool/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tarantool%2Fgo-tarantool/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tarantool%2Fgo-tarantool/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/tarantool","download_url":"https://codeload.github.com/tarantool/go-tarantool/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":253754968,"owners_count":21958934,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["go","tarantool","tarantool-connector"],"created_at":"2024-08-03T22:01:15.177Z","updated_at":"2025-05-12T14:32:01.750Z","avatar_url":"https://github.com/tarantool.png","language":"Go","funding_links":[],"categories":["Connectors"],"sub_categories":["Administration"],"readme":"\u003ca href=\"http://tarantool.org\"\u003e\n\t\u003cimg src=\"https://avatars2.githubusercontent.com/u/2344919?v=2\u0026s=250\" align=\"right\"\u003e\n\u003c/a\u003e\n\n[![Go Reference][godoc-badge]][godoc-url]\n[![Actions Status][actions-badge]][actions-url]\n[![Code Coverage][coverage-badge]][coverage-url]\n[![Telegram][telegram-badge]][telegram-url]\n[![GitHub Discussions][discussions-badge]][discussions-url]\n[![Stack Overflow][stackoverflow-badge]][stackoverflow-url]\n\n# Client in Go for Tarantool\n\nThe package `go-tarantool` contains everything you need to connect to\n[Tarantool 1.10+][tarantool-site].\n\nThe advantage of integrating Go with Tarantool, which is an application server\nplus a DBMS, is that Go programmers can handle databases and perform on-the-fly\nrecompilations of embedded Lua routines, just as in C, with responses that are\nfaster than other packages according to public benchmarks.\n\n## Table of contents\n\n* [Installation](#installation)\n  * [Build tags](#build-tags)\n* [Documentation](#documentation)\n  * [API reference](#api-reference)\n  * [Walking\\-through example](#walking-through-example)\n  * [Example with encrypting traffic](#example-with-encrypting-traffic)\n* [Migration guide](#migration-guide)\n* [Contributing](#contributing)\n* [Alternative connectors](#alternative-connectors)\n\n## Installation\n\nWe assume that you have Tarantool version 1.10+ and a modern Linux or BSD\noperating system.\n\nYou need a current version of `go`, version 1.20 or later (use `go version` to\ncheck the version number). Do not use `gccgo-go`.\n\n**Note:** If your `go` version is older than 1.20 or if `go` is not installed,\ndownload and run the latest tarball from [golang.org][golang-dl].\n\nThe package `go-tarantool` is located in [tarantool/go-tarantool][go-tarantool]\nrepository. To download and install, say:\n\n```\n$ go get github.com/tarantool/go-tarantool/v2\n```\n\nThis should put the source and binary files in subdirectories of\n`/usr/local/go`, so that you can access them by adding\n`github.com/tarantool/go-tarantool` to the `import {...}` section at the start\nof any Go program.\n\n### Build tags\n\nWe define multiple [build tags](https://pkg.go.dev/go/build#hdr-Build_Constraints).\n\nThis allows us to introduce new features without losing backward compatibility.\n\n1. To run fuzz tests with decimals, you can use the build tag:\n   ```\n   go_tarantool_decimal_fuzzing\n   ```\n   **Note:** It crashes old Tarantool versions.\n\n## Documentation\n\nRead the [Tarantool documentation][tarantool-doc-data-model-url]\nto find descriptions of terms such as \"connect\", \"space\", \"index\", and the\nrequests to create and manipulate database objects or Lua functions.\n\nIn general, connector methods can be divided into two main parts:\n\n* `Connect()` function and functions related to connecting, and\n* Data manipulation functions and Lua invocations such as `Insert()` or `Call()`.\n\nThe supported requests have parameters and results equivalent to requests in\nthe [Tarantool CRUD operations][tarantool-doc-box-space-url].\nThere are also Typed and Async versions of each data-manipulation function.\n\n### API Reference\n\nLearn API documentation and examples at [pkg.go.dev][godoc-url].\n\n### Walking-through example\n\nWe can now have a closer look at the example and make some observations\nabout what it does.\n\n```go\npackage tarantool\n\nimport (\n\t\"context\"\n\t\"fmt\"\n\t\"time\"\n\n\t\"github.com/tarantool/go-tarantool/v2\"\n\t_ \"github.com/tarantool/go-tarantool/v2/datetime\"\n\t_ \"github.com/tarantool/go-tarantool/v2/decimal\"\n\t_ \"github.com/tarantool/go-tarantool/v2/uuid\"\n)\n\nfunc main() {\n\tctx, cancel := context.WithTimeout(context.Background(), time.Second)\n\tdefer cancel()\n\tdialer := tarantool.NetDialer{\n\t\tAddress: \"127.0.0.1:3301\",\n\t\tUser: \t \"guest\",\n\t}\n\topts := tarantool.Opts{\n\t\tTimeout: time.Second,\n\t}\n\n\tconn, err := tarantool.Connect(ctx, dialer, opts)\n\tif err != nil {\n\t\tfmt.Println(\"Connection refused:\", err)\n\t\treturn\n\t}\n\n\tdata, err := conn.Do(\n\t\ttarantool.NewInsertRequest(999).Tuple([]interface{}{99999, \"BB\"})).Get()\n\tif err != nil {\n\t\tfmt.Println(\"Error:\", err)\n\t} else {\n\t\tfmt.Println(\"Data:\", data)\n\t}\n}\n```\n\n**Observation 1:** The line \"`github.com/tarantool/go-tarantool/v2`\" in the\n`import(...)` section brings in all Tarantool-related functions and structures.\n\n**Observation 2:** Unused import lines are required to initialize encoders and\ndecoders for external `msgpack` types.\n\n**Observation 3:** The line starting with \"`ctx, cancel :=`\" creates a context\nobject for `Connect()`. The `Connect()` call will return an error when a\ntimeout expires before the connection is established.\n\n**Observation 4:** The line starting with \"`dialer :=`\" creates dialer for\n`Connect()`. This structure contains fields required to establish a connection.\n\n**Observation 5:** The line starting with \"`opts :=`\" sets up the options for\n`Connect()`. In this example, the structure contains only a single value, the\ntimeout. The structure may also contain other settings, see more in\n[documentation][godoc-opts-url] for the \"`Opts`\" structure.\n\n**Observation 6:** The line containing \"`tarantool.Connect`\" is essential for\nstarting a session. There are three parameters:\n\n* a context,\n* the dialer that was set up earlier,\n* the option structure that was set up earlier.\n\nThere will be only one attempt to connect. If multiple attempts needed,\n\"`tarantool.Connect`\" could be placed inside the loop with some timeout\nbetween each try. Example could be found in the [example_test](./example_test.go),\nname - `ExampleConnect_reconnects`.\n\n**Observation 7:** The `err` structure will be `nil` if there is no error,\notherwise it will have a description which can be retrieved with `err.Error()`.\n\n**Observation 8:** The `Insert` request, like almost all requests, is preceded\nby the method `Do` of object `conn` which is the object that was returned\nby `Connect()`.\n\n### Example with encrypting traffic\n\nFor SSL-enabled connections, use `OpenSSLDialer` from the\n[go-tlsdialer](https://github.com/tarantool/go-tlsdialer) package.\n\nHere is small example with importing the `go-tlsdialer` library and using the\n`OpenSSLDialer`:\n\n```go\npackage tarantool\n\nimport (\n\t\"context\"\n\t\"fmt\"\n\t\"time\"\n\n\t\"github.com/tarantool/go-tarantool/v2\"\n\t_ \"github.com/tarantool/go-tarantool/v2/datetime\"\n\t_ \"github.com/tarantool/go-tarantool/v2/decimal\"\n\t_ \"github.com/tarantool/go-tarantool/v2/uuid\"\n\t\"github.com/tarantool/go-tlsdialer\"\n)\n\nfunc main() {\n\tctx, cancel := context.WithTimeout(context.Background(), time.Second)\n\tdefer cancel()\n\tdialer := tlsdialer.OpenSSLDialer{\n\t\tAddress:     \"127.0.0.1:3013\", \n\t\tUser:        \"test\", \n\t\tPassword:    \"test\", \n\t\tSslKeyFile:  \"testdata/localhost.key\",\n\t\tSslCertFile: \"testdata/localhost.crt\",\n\t\tSslCaFile:   \"testdata/ca.crt\",\n\t}\n\topts := tarantool.Opts{\n\t\tTimeout: time.Second,\n\t}\n\n\tconn, err := tarantool.Connect(ctx, dialer, opts)\n\tif err != nil {\n\t\tfmt.Println(\"Connection refused:\", err)\n\t\treturn\n\t}\n\n\tdata, err := conn.Do(\n\t\ttarantool.NewInsertRequest(999).Tuple([]interface{}{99999, \"BB\"})).Get()\n\tif err != nil {\n\t\tfmt.Println(\"Error:\", err)\n\t} else {\n\t\tfmt.Println(\"Data:\", data)\n\t}\n}\n```\n\nNote that [traffic encryption](https://www.tarantool.io/en/doc/latest/enterprise/security/#encrypting-traffic)\nis only available in Tarantool Enterprise Edition 2.10 or newer.\n\n## Migration guide\n\nYou can review the changes between major versions in the\n[migration guide](./MIGRATION.md).\n\n## Contributing\n\nSee [the contributing guide](CONTRIBUTING.md) for detailed instructions on how\nto get started with our project.\n\n## Alternative connectors\n\nThere are two other connectors available from the open source community:\n\n* [viciious/go-tarantool](https://github.com/viciious/go-tarantool),\n* [FZambia/tarantool](https://github.com/FZambia/tarantool).\n\nSee feature comparison in the [documentation][tarantool-doc-connectors-comparison].\n\n[tarantool-site]: https://tarantool.io/\n[godoc-badge]: https://pkg.go.dev/badge/github.com/tarantool/go-tarantool/v2.svg\n[godoc-url]: https://pkg.go.dev/github.com/tarantool/go-tarantool/v2\n[actions-badge]: https://github.com/tarantool/go-tarantool/actions/workflows/testing.yml/badge.svg\n[actions-url]: https://github.com/tarantool/go-tarantool/actions/workflows/testing.yml\n[coverage-badge]: https://coveralls.io/repos/github/tarantool/go-tarantool/badge.svg?branch=master\n[coverage-url]: https://coveralls.io/github/tarantool/go-tarantool?branch=master\n[telegram-badge]: https://img.shields.io/badge/Telegram-join%20chat-blue.svg\n[telegram-url]: http://telegram.me/tarantool\n[discussions-badge]: https://img.shields.io/github/discussions/tarantool/tarantool\n[discussions-url]: https://github.com/tarantool/tarantool/discussions\n[stackoverflow-badge]: https://img.shields.io/badge/stackoverflow-tarantool-orange.svg\n[stackoverflow-url]: https://stackoverflow.com/questions/tagged/tarantool\n[golang-dl]: https://go.dev/dl/\n[go-tarantool]: https://github.com/tarantool/go-tarantool\n[tarantool-doc-data-model-url]: https://www.tarantool.io/en/doc/latest/book/box/data_model/\n[tarantool-doc-box-space-url]: https://www.tarantool.io/en/doc/latest/reference/reference_lua/box_space/\n[godoc-opts-url]: https://pkg.go.dev/github.com/tarantool/go-tarantool/v2#Opts\n[tarantool-doc-connectors-comparison]: https://www.tarantool.io/en/doc/latest/book/connectors/#go-feature-comparison\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftarantool%2Fgo-tarantool","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ftarantool%2Fgo-tarantool","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftarantool%2Fgo-tarantool/lists"}