github.com/KinWaiYuen/client-go/v2@v2.5.4/README.md (about)

     1  # TiKV Go Client
     2  
     3  TiKV Go Client provides support for interacting with the [TiKV](https://github.com/tikv/tikv) server in the form of a Go library.
     4  
     5  ![Stability Active](https://img.shields.io/badge/Stability-Active-yellow)
     6  [![Go Reference](https://pkg.go.dev/badge/github.com/tikv/client-go/v2.svg)](https://pkg.go.dev/github.com/tikv/client-go/v2)
     7  
     8  [![Unit Test](https://github.com/tikv/client-go/actions/workflows/test.yml/badge.svg)](https://github.com/tikv/client-go/actions/workflows/test.yml)
     9  [![Integration Test](https://github.com/tikv/client-go/actions/workflows/integration.yml/badge.svg)](https://github.com/tikv/client-go/actions/workflows/integration.yml)
    10  [![Compatibility Test](https://github.com/tikv/client-go/actions/workflows/compatibility.yml/badge.svg)](https://github.com/tikv/client-go/actions/workflows/compatibility.yml)
    11  
    12  
    13  ## Package versions
    14  
    15  There are 2 major versions of the `client-go` package.
    16  
    17  - `v2` is the new active version. This version was extracted from [pingcap/tidb](https://github.com/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.
    18  
    19  - `v1` is the previous stable version and is only maintained for bug fixes. You can read the documentation [here](https://tikv.org/docs/4.0/reference/clients/go/).
    20  
    21  ```diff
    22  - warning: The v2 branch is still being refactored and sorted out, and external interfaces may change before the v2.0.0 release. Please use caution in production environments.
    23  ```
    24  
    25  ## Usage/Examples
    26  
    27  ```bash
    28    go get github.com/tikv/client-go/v2@COMMIT_HASH_OR_TAG_VERSION
    29  ```
    30  
    31  More examples can be found in [examples directory](https://github.com/tikv/client-go/tree/master/examples).
    32  
    33  ## Contributing to client-go
    34  
    35  Pull Requests and issues are welcomed. Please check [CONTRIBUTING.md](./CONTRIBUTING.md).
    36  
    37  ## Developing
    38  
    39  ### Running Tests
    40  
    41  Note: All the following tests are included in the [CI](https://github.com/tikv/client-go/actions) and you can submit a Pull Request directly to hand over the work.
    42  
    43  To run unit tests, use following command
    44  
    45  ```bash
    46  go test ./...
    47  ```
    48  
    49  To run code linter, make sure `golangci-lint` is [installed](https://golangci-lint.run/usage/install/#local-installation). Then use following command
    50  
    51  ```bash
    52  golangci-lint run
    53  ```
    54  
    55  `integration_tests` can run against a real TiKV cluster. Here is an example:
    56  
    57  ```bash
    58  ./pd-server &
    59  sleep 5
    60  ./tikv-server &
    61  sleep 10
    62  cd integration_tests
    63  go test --with-tikv
    64  ```
    65  
    66  ### Test with TiDB
    67  
    68  It is a common task to update client-go and then test it with TiDB.
    69  
    70  If you only need to test locally, you can directly use the modified client-go on the same host by replacing:
    71  
    72  ```bash
    73  go mod edit -replace=github.com/tikv/client-go/v2=/path/to/client-go
    74  ```
    75  
    76  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:
    77  
    78  ```bash
    79  go get -d github.com/GITHUB_USERNAME/client-go/v2@DEV_BRANCH
    80  # Output:
    81  # go get: github.com/GITHUB_USERNAME/client-go/v2@none updating to
    82  #         github.com/GITHUB_USERNAME/client-go/v2@v2.0.0-XXXXXXXXXXXXXX-XXXXXXXXXXXX: parsing go.mod:
    83  #         module declares its path as: github.com/tikv/client-go/v2
    84  #                 but was required as: github.com/GITHUB_USERNAME/client-go/v2
    85  go mod edit -replace=github.com/tikv/client-go/v2=github.com/GITHUB_USERNAME/client-go/v2@v2.0.0-XXXXXXXXXXXXXX-XXXXXXXXXXXX
    86  go mod download github.com/tikv/client-go/v2
    87  ```
    88  
    89  ## Used By
    90  
    91  `client-go` is used by the following projects:
    92  
    93  - [TiDB](https://github.com/pingcap/tidb): TiDB is an open source distributed HTAP database compatible with the MySQL protocol
    94  - [BR](https://github.com/pingcap/br): A command-line tool for distributed backup and restoration of the TiDB cluster data
    95  - [TiCDC](https://github.com/pingcap/ticdc): Change data capture for TiDB
    96  - [go-ycsb](https://github.com/pingcap/go-ycsb): A Go port of Yahoo! Cloud Serving Benchmark (YCSB)
    97  - [JuiceFS](https://github.com/juicedata/juicefs): JuiceFS is a distributed POSIX file system built on top of Redis and S3
    98  
    99  ## License
   100  
   101  [Apache License 2.0](http://www.apache.org/licenses/LICENSE-2.0)