{"id":26121518,"url":"https://github.com/mkbeh/xredis","last_synced_at":"2026-04-19T21:00:27.324Z","repository":{"id":281372683,"uuid":"900911468","full_name":"mkbeh/xredis","owner":"mkbeh","description":"library provides an API for working with Redis, using go-redis and integration with OpenTelemetry for tracing and metrics","archived":false,"fork":false,"pushed_at":"2025-11-19T19:37:42.000Z","size":59,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-11-19T21:14:14.927Z","etag":null,"topics":["go","golang","redis","redis-client","redis-cluster"],"latest_commit_sha":null,"homepage":"","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/mkbeh.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"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,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2024-12-09T17:41:05.000Z","updated_at":"2025-11-19T19:37:18.000Z","dependencies_parsed_at":"2025-08-06T12:12:09.057Z","dependency_job_id":"914bb2e3-c4c7-487f-a2ef-f914355bd2e7","html_url":"https://github.com/mkbeh/xredis","commit_stats":null,"previous_names":["mkbeh/xredis"],"tags_count":7,"template":false,"template_full_name":null,"purl":"pkg:github/mkbeh/xredis","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mkbeh%2Fxredis","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mkbeh%2Fxredis/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mkbeh%2Fxredis/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mkbeh%2Fxredis/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/mkbeh","download_url":"https://codeload.github.com/mkbeh/xredis/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mkbeh%2Fxredis/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":32022561,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-18T20:23:30.271Z","status":"online","status_checked_at":"2026-04-19T02:00:07.110Z","response_time":55,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"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":["go","golang","redis","redis-client","redis-cluster"],"created_at":"2025-03-10T14:23:35.999Z","updated_at":"2026-04-19T21:00:27.318Z","avatar_url":"https://github.com/mkbeh.png","language":"Go","funding_links":[],"categories":[],"sub_categories":[],"readme":"# xredis\n\nA Go Redis client wrapper built on [go-redis](https://github.com/redis/go-redis) with built-in OpenTelemetry tracing,\nPrometheus metrics, and support for both standalone and cluster modes.\n\n## Features\n\n- Standalone and cluster client support\n- OpenTelemetry tracing and metrics via `redisotel`\n- Prometheus metrics via custom collector\n- TLS support\n- Rate limiting via `rdb.Limiter`\n- Configurable marshaller (defaults to `json.Marshal`)\n- Hash operations with struct mapping\n- Pipeline-based bulk delete\n\n## Installation\n\n```bash\ngo get github.com/mkbeh/xredis\n```\n\n## Quick start\n\n```go\npackage main\n\nimport (\n\t\"context\"\n\t\"fmt\"\n\n\tredis \"github.com/mkbeh/xredis\"\n)\n\nfunc main() {\n\tclient, err := redis.NewClient(\n\t\tredis.WithConfig(\u0026redis.Config{\n\t\t\tAddrs: \"localhost:6379\",\n\t\t}),\n\t\tredis.WithClientID(\"my-service\"),\n\t)\n\tif err != nil {\n\t\tpanic(err)\n\t}\n\tdefer client.Close()\n\n\tctx := context.Background()\n\n\tif err := client.Set(ctx, \"greeting\", \"hello\", 0); err != nil {\n\t\tpanic(err)\n\t}\n\n\tvar value string\n\tif err := client.Get(ctx, \"greeting\", \u0026value); err != nil {\n\t\tpanic(err)\n\t}\n\n\tfmt.Println(value) // hello\n}\n```\n\nMore examples: [examples/sample](https://github.com/mkbeh/xredis/tree/main/examples/sample)\n\n## Cluster mode\n\n```go\nclient, err := redis.NewClusterClient(\nredis.WithConfig(\u0026redis.Config{\nAddrs: \"node1:6379,node2:6379,node3:6379\",\n}),\n)\n```\n\n## Hash operations\n\n```go\n// Set individual hash field\nclient.HSet(ctx, \"user:1\", \"name\", \"Alice\", time.Hour)\n\n// Set all fields from a struct\ntype User struct {\nName  string `redis:\"name\"`\nEmail string `redis:\"email\"`\n}\nclient.HSetObject(ctx, \"user:1\", User{Name: \"Alice\", Email: \"alice@example.com\"}, time.Hour)\n\n// Get all fields into a struct\nvar u User\nclient.HGetAll(ctx, \"user:1\", \u0026u)\n```\n\n## Observability\n\n```go\nclient, err := redis.NewClient(\nredis.WithConfig(cfg),\nredis.WithTraceProvider(tp),\nredis.WithMeterProvider(mp),\nredis.WithMetricsNamespace(\"myapp\"),\nredis.WithDBStatement(false), // hide raw commands from traces\n)\n```\n\nPrometheus metrics are registered automatically on client creation.\n\n## TLS\n\n```go\nclient, err := redis.NewClient(\nredis.WithConfig(cfg),\nredis.WithTLS(\u0026tls.Config{\nMinVersion: tls.VersionTLS12,\n}),\n)\n```\n\n## Options reference\n\n| Option                     | Description                                                       |\n|----------------------------|-------------------------------------------------------------------|\n| `WithConfig(cfg)`          | Connection and pool configuration                                 |\n| `WithClientID(id)`         | Human-readable client name prefix (UUID appended automatically)   |\n| `WithLogger(l)`            | Custom `slog.Logger`                                              |\n| `WithMarshaller(fn)`       | Custom marshal function for `SetStruct` (default: `json.Marshal`) |\n| `WithTLS(cfg)`             | TLS configuration                                                 |\n| `WithLimiter(l)`           | Rate limiter (standalone mode only)                               |\n| `WithTraceProvider(tp)`    | OpenTelemetry tracer provider                                     |\n| `WithMeterProvider(mp)`    | OpenTelemetry meter provider                                      |\n| `WithMetricsNamespace(ns)` | Prometheus metrics namespace                                      |\n| `WithDBStatement(on)`      | Include raw commands in traces                                    |\n| `WithDBSystem(s)`          | Override `db.system` attribute in traces and metrics              |\n| `WithAttributes(attrs...)` | Additional OpenTelemetry attributes for traces and metrics        |\n\n## Configuration\n\nAll fields can be set programmatically via `Config` or through environment variables.\n\n| Env variable                    | Default          | Description                                               |\n|---------------------------------|------------------|-----------------------------------------------------------|\n| `REDIS_ADDRS`                   | `127.0.0.1:6379` | Comma-separated list of `host:port` addresses             |\n| `REDIS_NETWORK`                 | `tcp`            | Network type: `tcp` or `unix`                             |\n| `REDIS_PROTOCOL`                | `3`              | RESP protocol version: `2` or `3`                         |\n| `REDIS_USERNAME`                | —                | ACL username (Redis 6+)                                   |\n| `REDIS_PASSWORD`                | —                | Password                                                  |\n| `REDIS_DB`                      | `0`              | Database index (standalone only)                          |\n| `REDIS_MAX_RETRIES`             | `3`              | Max retries; `-1` disables                                |\n| `REDIS_MIN_RETRY_BACKOFF`       | `8ms`            | Min backoff between retries; `-1` disables                |\n| `REDIS_MAX_RETRY_BACKOFF`       | `512ms`          | Max backoff between retries; `-1` disables                |\n| `REDIS_MAX_REDIRECTS`           | `len(nodes)+1`   | Max MOVED/ASK redirects (cluster only)                    |\n| `REDIS_READONLY`                | `true`           | Route read commands to replicas (cluster only)            |\n| `REDIS_ROUTE_BY_LATENCY`        | `false`          | Route reads to the nearest node (cluster only)            |\n| `REDIS_ROUTE_RANDOMLY`          | `false`          | Route reads to a random node (cluster only)               |\n| `REDIS_DIAL_TIMEOUT`            | `5s`             | Timeout for new connections                               |\n| `REDIS_READ_TIMEOUT`            | `3s`             | Socket read timeout; `-1` blocks; `-2` disables deadline  |\n| `REDIS_WRITE_TIMEOUT`           | `3s`             | Socket write timeout; `-1` blocks; `-2` disables deadline |\n| `REDIS_CONTEXT_TIMEOUT_ENABLED` | `false`          | Respect context deadlines for commands                    |\n| `REDIS_POOL_SIZE`               | `10×GOMAXPROCS`  | Connection pool size per node                             |\n| `REDIS_POOL_FIFO`               | `false`          | `true` = FIFO pool; `false` = LIFO                        |\n| `REDIS_POOL_TIMEOUT`            | `ReadTimeout+1s` | Wait time for a free connection                           |\n| `REDIS_MIN_IDLE_CONNS`          | `0`              | Minimum idle connections                                  |\n| `REDIS_MAX_IDLE_CONNS`          | `0`              | Maximum idle connections                                  |\n| `REDIS_MAX_ACTIVE_CONNS`        | `0` (unlimited)  | Maximum active connections per node                       |\n| `REDIS_CONN_MAX_IDLE_TIME`      | `30m`            | Max idle time per connection; `-1` disables               |\n| `REDIS_CONN_MAX_LIFETIME`       | unlimited        | Max lifetime per connection                               |\n| `REDIS_DISABLE_INDENTITY`       | `false`          | Disable `CLIENT SETNAME` on connect                       |\n| `REDIS_UNSTABLE_RESP3`          | `false`          | Enable unstable RESP3 mode for Redis Search               |\n\n## Error handling\n\n```go\nimport \"errors\"\n\nval, ok, err := client.String(ctx, \"key\")\nif err != nil {\n// real error\n}\nif !ok {\n// key does not exist\n}\n\nerr = client.HGetAll(ctx, \"key\", \u0026dst)\nif errors.Is(err, redis.ErrKeyNotFound) {\n// key does not exist\n}\n```\n\nExported errors:\n\n| Error                 | Description                               |\n|-----------------------|-------------------------------------------|\n| `ErrKeyNotFound`      | Key or field does not exist               |\n| `ErrInvalidFieldType` | Unsupported field type for hash operation |\n\n## License\n\n[MIT](LICENSE)","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmkbeh%2Fxredis","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmkbeh%2Fxredis","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmkbeh%2Fxredis/lists"}