https://github.com/cattlecloud/memc
memc is a modern and generics enabled memcached client library for Go
https://github.com/cattlecloud/memc
go go-library memcached memcached-clients
Last synced: about 1 month ago
JSON representation
memc is a modern and generics enabled memcached client library for Go
- Host: GitHub
- URL: https://github.com/cattlecloud/memc
- Owner: cattlecloud
- License: bsd-3-clause
- Created: 2024-10-16T01:05:54.000Z (over 1 year ago)
- Default Branch: main
- Last Pushed: 2026-01-31T12:31:32.000Z (about 2 months ago)
- Last Synced: 2026-01-31T23:44:58.835Z (about 2 months ago)
- Topics: go, go-library, memcached, memcached-clients
- Language: Go
- Homepage: https://cattlecloud.net/go/memc
- Size: 96.7 KB
- Stars: 1
- Watchers: 0
- Forks: 0
- Open Issues: 3
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# memc
`memc` is a modern and generics enabled memcached client library for Go.
_requires go1.23+_
October 2024:
(!) This package is very new and may contain bugs and missing features.
### Getting Started
The `memc` package can be added to a Go project with `go get`.
```shell
go get cattlecloud.net/go/memc@latest
```
```go
import "cattlecloud.net/go/memc"
```
### Examples
##### Connecting to memcached.
Supports connecting via TCP or Unix Domain Socket.
```go
client := memc.New(
[]string{"localhost:11211"},
)
```
For sockets, simply specify the socket filepath.
```go
client := memc.New(
[]string{"/var/lib/app/cache.socket"},
)
```
##### Setting a value in memcached.
```go
err := memc.Set(client, "my/key/name", "some_value")
```
Note that the `memc` library can handle arbitrary value types, as long as they
can be encoded using Go's built-in `gob` package. The library automatically
handles serialization on writes and de-serialization on reads.
```go
err := memc.Set(client, "my/key/name", &Person{Name: "Bob"})
```
##### Reading a value from memcached.
The `memc` package will automatically convert the value `[]byte` into the type
of your Go variable.
```go
value, err := memc.Get[T](client, "my/key/name")
```
##### Incrementing/Decrementing a counter in memcached.
The `memc` package provides `Increment` and `Decrement` for increasing or
decreasing a value by a given delta. Note that the value must already be stored,
and must be in the form of an ASCII string representation of a number. The delta
value must be positive.
```go
err := memc.Set(client, "/my/counter", "100")
```
Using `Increment` to increase the counter value by 1.
```go
v, err := memc.Increment("/my/counter", 1)
// v is now 101
```
Using `Decrement` to decrease the value by 5.
```go
v, err := memc.Decrement("/my/counter", 5)
// v is now 96
```
##### Sharding memcached instances.
The memcached can handle sharding writes and reads across multiple memcached
instances. It does this by hashing the key space and deterministically choosing
an assigned instance. To enable this behavior simply give the `Client` each
memcached instance address.
```go
client := memc.New(
[]string{
"10.0.0.1:11211",
"10.0.0.2:11211",
"10.0.0.3:11211",
},
)
```
##### Configuring default expiration.
The `Client` sets a default expiration time on each value. This expiration time
can be configured when creating the client.
```go
client := memc.New(
// ...
SetDefaultTTL(2 * time.Minute),
)
```
##### Configuration idle connection pool.
The `Client` maintains an idle connection pool for each memcached instance it
has connected to. The number of idle connections to maintain per instance can be
adjusted.
```go
client := memc.New(
// ...
SetIdleConnections(4),
)
```
##### Closing the client.
The `Client` can be closed so that idle connections are closed and no longer
consuming resources. In-flight requests will be closed once complete. Once
closed the client cannot be reused.
```go
_ = memc.Close()
```
### License
The `cattlecloud.net/go/memc` module is open source under the [BSD-3-Clause](LICENSE) license.