https://github.com/yeqown/memcached
A memcached Go client package supports cluster usage、meta text protocol and basic text protocol.
https://github.com/yeqown/memcached
cli cluster golang memcached metadata package rendezvous-hashing sasl
Last synced: 11 months ago
JSON representation
A memcached Go client package supports cluster usage、meta text protocol and basic text protocol.
- Host: GitHub
- URL: https://github.com/yeqown/memcached
- Owner: yeqown
- License: mit
- Created: 2025-02-08T10:34:35.000Z (over 1 year ago)
- Default Branch: main
- Last Pushed: 2025-07-28T06:34:07.000Z (12 months ago)
- Last Synced: 2025-07-28T07:34:19.978Z (12 months ago)
- Topics: cli, cluster, golang, memcached, metadata, package, rendezvous-hashing, sasl
- Language: Go
- Homepage:
- Size: 528 KB
- Stars: 5
- Watchers: 1
- Forks: 2
- Open Issues: 2
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
## Memcached
[](https://pkg.go.dev/github.com/yeqown/memcached) [](https://goreportcard.com/report/github.com/yeqown/memcached) [](https://github.com/yeqown/memcached/blob/master/LICENSE) [](https://github.com/yeqown/memcached/releases) [](https://github.com/yeqown/memcached/stargazers) [](https://github.com/yeqown/memcached/issues) [](https://github.com/yeqown/memcached/actions) [](https://codecov.io/gh/yeqown/memcached)
This is a golang package for [Memcached](https://memcached.org/). It is a simple and easy to use package.
### Features
- [x] Completed Memcached text protocol, includes meta text protocol.
- [ ] Integrated serialization and deserialization function
- [x] Cluster support, multiple hash algorithm support, include: crc32, murmur3, redezvous and also custom hash algorithm.
- [x] Fully connection pool features support.
- [x] CLI tool support.
- [x] SASL support.
- [x] support TCP、UDP and Unix domain socket transport.
### Installation
```bash
go get github.com/yeqown/memcached@latest
```
Or you can install the CLI binary by running:
```bash
go install github.com/yeqown/memcached/cmd/memcached-cli@latest
```
More `memcached-cli` usage could be found in [CLI](./cmd/memcached-cli/README.md).
### Usage
There is a simple example to show how to use this package. More examples could be found in the [example](./example) directory.
```go
package main
import (
"context"
"time"
"github.com/yeqown/memcached"
)
func main() {
// 1. build client
// addrs is a string, if you have multiple memcached servers, you can use comma to separate them.
// e.g. "localhost:11211,localhost:11212,localhost:11213"
addrs := "localhost:11211"
// client support options, you can set the options to client.
// e.g. memcached.New(addrs, memcached.WithDialTimeout(5*time.Second))
client, err := memcached.New(addrs)
if err != nil {
panic(err)
}
// 2. use client
// now, you can use the client API to finish your work.
ctx, cancel := context.WithTimeout(context.Background(), 10*time.Second)
defer cancel()
version, err := client.Version(ctx)
if err != nil {
panic(err)
}
println("Version: ", version)
if err = client.Set(ctx, "key", []byte("value"), 0, 0); err != nil {
panic(err)
}
if err = client.Set(ctx, "key2", []byte("value2"), 0, 0); err != nil {
panic(err)
}
items, err := client.Gets(ctx, "key", "key2")
if err != nil {
panic(err)
}
for _, item := range items {
println("key: ", item.Key, " value: ", string(item.Value))
}
}
```
### Support Commands
Now, we have implemented some commands, and we will implement more commands in the future.
| Command | Status | API Usage | Description |
|----------------|--------|---------------------------------------------------------------------------------------------------------------------|-------------------------------------------------------------------|
| ---- | ----- | STORAGE COMMANDS | --- |
| Set | ✅ | `Set(ctx context.Context, key string, value []byte, flags uint32, expiry time.Duration) error` | Set a key-value pair to memcached |
| Add | ✅ | `Add(ctx context.Context, key string, value []byte, flags uint32, expiry time.Duration) error` | Add a key-value pair to memcached |
| Replace | ✅ | `Replace(ctx context.Context, key string, value []byte, flags uint32, expiry time.Duration) error` | Replace a key-value pair to memcached |
| Append | ✅ | `Append(ctx context.Context, key string, value []byte, flags uint32, expiry time.Duration) error` | Append a value to the key |
| Prepend | ✅ | `Prepend(ctx context.Context, key string, value []byte, flags uint32, expiry time.Duration) error` | Prepend a value to the key |
| Cas | ✅ | `Cas(ctx context.Context, key string, value []byte, flags uint32, expiry time.Duration, cas uint64) error` | Compare and set a key-value pair to memcached |
| ---- | ----- | RETRIEVAL COMMANDS | --- |
| Gets | ✅ | `Gets(ctx context.Context, keys ...string) ([]*Item, error)` | Get a value by key from memcached with cas value |
| Get | ✅ | `Get(ctx context.Context, key string) (*Item, error)` | Get a value by key from memcached |
| GetAndTouch | ✅ | `GetAndTouch(ctx context.Context, expiry uint32, key string) (*Item, error)` | Get a value by key from memcached and touch the key's expire time |
| GetAndTouches | ✅ | `GetAndTouches(ctx context.Context, expiry uint32, keys ...string) ([]*Item, error)` | Get a value by key from memcached and touch the key's expire time |
| ----- | ----- | OTHER COMMANDS | --- |
| Delete | ✅ | `Delete(ctx context.Context, key string) error` | Delete a key-value pair from memcached |
| Incr | ✅ | `Incr(ctx context.Context, key string, delta uint64) (uint64, error)` | Increment a key's value |
| Decr | ✅ | `Decr(ctx context.Context, key string, delta uint64) (uint64, error)` | Decrement a key's value |
| Touch | ✅ | `Touch(ctx context.Context, key string, expiry uint32) error` | Touch a key's expire time |
| MetaGet | ✅ | `MetaGet(ctx context.Context, key []byte, options ...MetaGetOption) (*MetaItem, error)` | Get a key's meta information |
| MetaSet | ✅ | `MetaSet(ctx context.Context, key, value []byte, options ...MetaSetOption) (*MetaItem, error)` | Set a key's meta information |
| MetaDelete | ✅ | `MetaDelete(ctx context.Context, key []byte, options ...MetaDeleteOption) (*MetaItem, error)` | Delete a key's meta information |
| MetaArithmetic | ✅ | `MetaArithmetic(ctx context.Context, key []byte, delta uint64, options ...MetaArithmeticOption) (*MetaItem, error)` | Arithmetic a key's meta information |
| MetaDebug | ✅ | `MetaDebug(ctx context.Context, key []byte, options ...MetaDebugOption) (*MetaItemDebug, error)` | Debug a key's meta information |
| MetaNoop | ✅ | `MetaNoop(ctx context.Context) error` | Noop a key's meta information |
| Version | ✅ | `Version(ctx context.Context) (string, error)` | Get memcached server version |
| FlushAll | ✅ | `FlushAll(ctx context.Context) error` | Flush all keys in memcached server |
### Development Guide
#### Prerequisites
- Go 1.21 or higher
- Python (for pre-commit hooks) or just `brew install pre-commit` on MacOS
- Docker (for running memcached in tests)
#### Setting up development environment
1. Clone the repository:
```bash
git clone https://github.com/yeqown/memcached.git
cd memcached
```
2. Install pre-commit hooks:
```bash
pip install pre-commit
# or MacOS
# brew install pre-commit
pre-commit install
```
3. Install golangci-lint:
```bash
go install github.com/golangci/golangci-lint/cmd/golangci-lint@latest
```
#### Running Tests
```bash
go test -v -race -coverprofile=coverage.txt -covermode=atomic ./...
```
#### Code Style
This project follows the standard Go code style guidelines and uses golangci-lint for additional checks. The configuration can be found in [.golangci.yml](./.golangci.yml).
Key points:
- Follow Go standard formatting (enforced by gofmt )
- Ensure all code is properly tested
- Write clear commit messages
- Document public APIs