TiKV Go Client

TiKV Go Client provides support for interacting with the TiKV server in the form of a Go library.

Package versions

There are 2 major versions of the client-go package.

v2 is the latest stable version. This version was extracted from pingcap/tidb and it includes new TiKV features like Follower Read, 1PC, Async Commit. The development of this version is on the master branch. The documentation for this version is below.
v1 is the previous stable version and is only maintained for bug fixes. You can read the documentation here.

Usage/Examples

  # valid versions be like @latest, @e5f932ae270887550b0cd221343dbd6b870b6c8f, @v2.0.0, @v2.0.1...
  go get github.com/tikv/client-go/v2@COMMIT_HASH_OR_TAG_VERSION

Explanation of related concepts and sample code can be found in the Client-Go Wiki. There are also executable examples in examples directory.

Contributing to client-go

Pull Requests and issues are welcomed. Please check CONTRIBUTING.md.

Developing

Running Tests

Note: All the following tests are included in the CI and you can submit a Pull Request directly to hand over the work.

To run unit tests, use following command

go test ./...

To run code linter, make sure golangci-lint is installed. Then use following command

golangci-lint run

integration_tests can run against a real TiKV cluster. Here is an example:

./pd-server &
sleep 5
./tikv-server &
sleep 10
cd integration_tests
go test --with-tikv

Test with TiDB

It is a common task to update client-go and then test it with TiDB.

If you only need to test locally, you can directly use the modified client-go on the same host by replacing:

go mod edit -replace=github.com/tikv/client-go/v2=/path/to/client-go

If you want to push your TiDB code to GitHub for running CI or for code review, you need to change the client-go used by TiDB to your developing branch using the following steps:

go get -d github.com/GITHUB_USERNAME/client-go/v2@DEV_BRANCH
# Output:
# go get: github.com/GITHUB_USERNAME/client-go/v2@none updating to
#         github.com/GITHUB_USERNAME/client-go/v2@v2.0.0-XXXXXXXXXXXXXX-XXXXXXXXXXXX: parsing go.mod:
#         module declares its path as: github.com/tikv/client-go/v2
#                 but was required as: github.com/GITHUB_USERNAME/client-go/v2
go mod edit -replace=github.com/tikv/client-go/v2=github.com/GITHUB_USERNAME/client-go/v2@v2.0.0-XXXXXXXXXXXXXX-XXXXXXXXXXXX
go mod download github.com/tikv/client-go/v2

Used By

client-go is used by the following projects:

TiDB: TiDB is an open source distributed HTAP database compatible with the MySQL protocol
BR: A command-line tool for distributed backup and restoration of the TiDB cluster data
TiCDC: Change data capture for TiDB
go-ycsb: A Go port of Yahoo! Cloud Serving Benchmark (YCSB)
JuiceFS: JuiceFS is a distributed POSIX file system built on top of Redis and S3
tcli: A CLI tool for TiKV, for human being :)

License

Apache License 2.0

tikv / client-go

readme