{"id":34147444,"url":"https://github.com/tarantool/go-vshard-router","last_synced_at":"2026-03-13T00:32:15.060Z","repository":{"id":269318689,"uuid":"906258709","full_name":"tarantool/go-vshard-router","owner":"tarantool","description":"go vshard-router implementation for tarantool ","archived":false,"fork":false,"pushed_at":"2025-09-19T07:02:35.000Z","size":1169,"stargazers_count":16,"open_issues_count":19,"forks_count":3,"subscribers_count":7,"default_branch":"master","last_synced_at":"2025-09-28T09:09:13.567Z","etag":null,"topics":["bucket","client","go","golang","library","no-sql","sharding","tarantool","vshard"],"latest_commit_sha":null,"homepage":"https://www.tarantool.io/en/doc/latest/reference/reference_rock/vshard/","language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/tarantool.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2024-12-20T13:54:57.000Z","updated_at":"2025-09-19T07:02:39.000Z","dependencies_parsed_at":"2025-01-13T11:24:13.238Z","dependency_job_id":"57dc2b08-5ad9-4bc8-a285-02d71b36d81e","html_url":"https://github.com/tarantool/go-vshard-router","commit_stats":null,"previous_names":["tarantool/go-vshard-router"],"tags_count":26,"template":false,"template_full_name":null,"purl":"pkg:github/tarantool/go-vshard-router","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tarantool%2Fgo-vshard-router","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tarantool%2Fgo-vshard-router/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tarantool%2Fgo-vshard-router/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tarantool%2Fgo-vshard-router/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/tarantool","download_url":"https://codeload.github.com/tarantool/go-vshard-router/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tarantool%2Fgo-vshard-router/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":30451565,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-03-12T21:31:01.033Z","status":"ssl_error","status_checked_at":"2026-03-12T21:30:43.161Z","response_time":114,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.5:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"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":["bucket","client","go","golang","library","no-sql","sharding","tarantool","vshard"],"created_at":"2025-12-15T04:23:37.763Z","updated_at":"2026-03-13T00:32:15.051Z","avatar_url":"https://github.com/tarantool.png","language":"Go","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Go VShard Router\n\n\u003cimg align=\"right\" width=\"159px\" src=\"docs/static/logo.png\" alt=\"логотип go vshard router\"\u003e\n\n[![Go Reference](https://pkg.go.dev/badge/github.com/tarantool/go-vshard-router.svg)](https://pkg.go.dev/github.com/tarantool/go-vshard-router)\n[![Actions Status][actions-badge]][actions-url]\n[![Go Report Card](https://goreportcard.com/badge/github.com/tarantool/go-vshard-router)](https://goreportcard.com/report/github.com/tarantool/go-vshard-router)\n[![Code Coverage][coverage-badge]][coverage-url]\n[![License](http://img.shields.io/badge/license-mit-blue.svg?style=flat-square)](https://raw.githubusercontent.com/KaymeKaydex/go-vshard-router/master/LICENSE)\n\nTranslations:\n- [Русский](https://github.com/tarantool/go-vshard-router/blob/master/README_ru.md)\n\n\ngo-vshard-router is a library for sending requests to a sharded tarantool cluster directly,\nwithout using tarantool-router. This library based on [tarantool vhsard library router](https://github.com/tarantool/vshard/blob/master/vshard/router/init.lua) and [go-tarantool connector](https://github.com/tarantool/go-tarantool). go-vshard-router takes a new approach to creating your cluster\n\n```mermaid\ngraph TD\n    %% Old Cluster Schema\n    subgraph Old_Cluster_Schema[\"Old Cluster Schema\"]\n        direction LR\n        subgraph Tarantool Database Cluster\n            subgraph Replicaset 1\n                Master_001_1\n                Replica_001_2\n            end\n        end\n\n        ROUTER1[\"Tarantool vshard-router 1_1\"] --\u003e Master_001_1\n        ROUTER2[\"Tarantool vshard-router 1_2\"] --\u003e Master_001_1\n        ROUTER3[\"Tarantool vshard-router 1_3\"] --\u003e Master_001_1\n        ROUTER1[\"Tarantool vshard-router 1_1\"] --\u003e Replica_001_2\n        ROUTER2[\"Tarantool vshard-router 1_2\"] --\u003e Replica_001_2\n        ROUTER3[\"Tarantool vshard-router 1_3\"] --\u003e Replica_001_2\n\n        GO[\"Golang service\"]\n        GO --\u003e ROUTER1\n        GO --\u003e ROUTER2\n        GO --\u003e ROUTER3\n    end\n\n    %% New Cluster Schema\n    subgraph New_Cluster_Schema[\"New Cluster Schema\"]\n        direction LR\n        subgraph Application Host\n            Golang_Service\n        end\n\n        Golang_Service --\u003e |iproto| MASTER1\n        Golang_Service --\u003e |iproto| REPLICA1\n\n        MASTER1[\"Master 001_1\"]\n        REPLICA1[\"Replica 001_2\"]\n\n        subgraph Tarantool Database Cluster\n            subgraph Replicaset 1\n                MASTER1\n                REPLICA1\n            end\n        end\n    end\n```\n\n## Getting started\n### Prerequisites\n\n- **[Go](https://go.dev/)**: any one of the **two latest major** [releases](https://go.dev/doc/devel/release) (we test it with these).\n\n### Getting Go-Vshard-Router\nWith [Go module](https://github.com/golang/go/wiki/Modules) support, simply add the following import\n\n```\nimport \"github.com/tarantool/go-vshard-router/v2\"\n```\nto your code, and then `go [build|run|test]` will automatically fetch the necessary dependencies.\n\nOtherwise, run the following Go command to install the `go-vshard-router` package:\n\n```sh\n$ go get -u github.com/tarantool/go-vshard-router/v2\n```\n\n### Running Go-Vshard-Router\n\nFirst you need to import Go-Vshard-Router package for using Go-Vshard-Router\n\n```go\npackage main\n\nimport (\n  \"context\"\n  \"fmt\"\n  \"strconv\"\n  \"time\"\n\n  vshardrouter \"github.com/tarantool/go-vshard-router/v2\"\n  \"github.com/tarantool/go-vshard-router/v2/providers/static\"\n\n  \"github.com/google/uuid\"\n  \"github.com/tarantool/go-tarantool/v2\"\n)\n\nfunc main() {\n  ctx := context.Background()\n\n  directRouter, err := vshardrouter.NewRouter(ctx, vshardrouter.Config{\n    DiscoveryTimeout: time.Minute,\n    DiscoveryMode:    vshardrouter.DiscoveryModeOn,\n    TopologyProvider: static.NewProvider(map[vshardrouter.ReplicasetInfo][]vshardrouter.InstanceInfo{\n      {Name: \"replcaset_1\", UUID: uuid.New()}: {\n        {Addr: \"127.0.0.1:1001\", Name: \"1_1\"},\n        {Addr: \"127.0.0.1:1002\", Name: \"1_2\"},\n      },\n      {Name: \"replcaset_2\", UUID: uuid.New()}: {\n        {Addr: \"127.0.0.1:2001\", Name: \"2_1\"},\n        {Addr: \"127.0.0.1:2002\", Name: \"2_2\"},\n      },\n    }),\n    TotalBucketCount: 128000,\n    PoolOpts: tarantool.Opts{\n      Timeout: time.Second,\n    },\n  })\n  if err != nil {\n    panic(err)\n  }\n\n  user := struct {\n    ID uint64\n  }{\n    ID: 123,\n  }\n\n  bucketID := directRouter.BucketIDStrCRC32(strconv.FormatUint(user.ID, 10))\n\n  resp, err := directRouter.Call(\n    ctx,\n    bucketID,\n    vshardrouter.CallModeBRO,\n    \"storage.api.get_user_info\",\n    []interface{}{\u0026struct {\n      BucketID uint64                 `msgpack:\"bucket_id\" json:\"bucket_id,omitempty\"`\n      Body     map[string]interface{} `msgpack:\"body\"`\n    }{\n      BucketID: bucketID,\n      Body: map[string]interface{}{\n        \"user_id\": \"123456\",\n      },\n    }}, vshardrouter.CallOpts{Timeout: time.Second * 2},\n  )\n  if err != nil {\n    panic(err)\n  }\n\n  info := \u0026struct {\n    BirthDay int\n  }{}\n\n  err = resp.GetTyped(\u0026[]interface{}{info})\n  if err != nil {\n    panic(err)\n  }\n\n  interfaceResult, err := resp.Get()\n  if err != nil {\n    panic(err)\n  }\n\n  fmt.Printf(\"interface result: %v\", interfaceResult)\n  fmt.Printf(\"get typed result: %v\", info)\n}\n```\n### Providers\n\u003cimg align=\"center\"  src=\"docs/static/providers.png\" alt=\"topology\"\u003e\n\nWe understand that the implementations of loggers, metrics,\nand topology sources can vary significantly in both implementation and usage.\nTherefore, go-vshard-router gives you the flexibility to choose the tools you deem appropriate\nor implement them yourself by using interfaces.\n\n#### Topology\nYou can use topology (configuration) providers as the source of router configuration.  \nCurrently, the following providers are supported:\n\n- **etcd** (for configurations similar to [moonlibs/config](https://github.com/moonlibs/config?tab=readme-ov-file#example-of-etcd-configuration-for-vshard-based-applications-etcdclustervshard) in etcd v2 for Tarantool versions below 3)\n- **static** (for specifying configuration directly in the code for ease of testing)\n- **[viper](providers/viper/README.md)**\n  - etcd v3\n  - consul\n  - files\n\n#### Metrics\nMetrics providers are also available,\nyou can use ready-made metrics providers that can be registered in prometheus and passed to go-vshard-router.\nThis will allow you not to think about options and metrics settings.\nThe following providers are currently available:\n- **[prometheus](providers/prometheus)**\n\n#### Logs\n\n- stdout (builtin)\n- **[slog](providers/slog)**\n\n### Learn more examples\n#### Quick Start\nLearn with th [Quick Start](docs/doc.md), which include  examples and theory.\n#### [Customer service](examples/customer/README.md)\nService with go-vshard-router on top of the tarantool example from the original vshard library using raft\n\n## Benchmarks\n### Go Bench\n\n| Benchmark                             | Runs   | Time (ns/op) | Memory (B/op) | Allocations (allocs/op) |\n|---------------------------------------|--------|---------------|----------------|-------------------------|\n| BenchmarkCallSimpleInsert_GO-12       | 14929  | 77443        | 2308           | 34                      |\n| BenchmarkCallSimpleInsert_Lua-12      | 10196  | 116101       | 1098           | 19                      |\n| BenchmarkCallSimpleSelect_GO-12       | 20065  | 60521        | 2534           | 40                      |\n| BenchmarkCallSimpleSelect_Lua-12      | 12064  | 99874        | 1153           | 20                      |\n\n\n### [K6](https://github.com/grafana/k6)\nTopology:\n- 4 replicasets (x2 instances per rs)\n- 4 tarantool proxy\n- 1 golang service\n\nconstant VUes scenario:\nat a load close to production\n\n```select```\n- go-vshard-router: uncritically worse latency, but 3 times more rps\n  ![Image alt](docs/static/direct.png)\n- tarantool-router: (80% cpu, heavy rps kills proxy at 100% cpu) \n  ![Image alt](docs/static/not-direct.png)\n\n\n[actions-badge]: https://github.com/tarantool/go-vshard-router/actions/workflows/main.yml/badge.svg\n[actions-url]: https://github.com/tarantool/go-vshard-router/actions/workflows/main.yml\n[coverage-badge]: https://coveralls.io/repos/github/tarantool/go-vshard-router/badge.svg?branch=master\n[coverage-url]: https://coveralls.io/github/tarantool/go-vshard-router?branch=master","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftarantool%2Fgo-vshard-router","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ftarantool%2Fgo-vshard-router","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftarantool%2Fgo-vshard-router/lists"}