Redis client (go-redis) for Go: complete guide with examples

Introduction to go-redis: a powerful Redis client for Go

Redis is a high-performance in-memory key-value data store. It is used for caching, session management, message queues, leaderboards, and much more. To interact with Redis from Go, there are several libraries, and go-redis (package github.com/redis/go-redis/v9) is the most popular, actively maintained, and feature-rich.

This library provides a clean, idiomatic Go API for working with all Redis data structures (strings, lists, sets, hashes, sorted sets, HyperLogLog, streams, geospatial data) and supports advanced features such as clustering, Sentinel, Pub/Sub, pipelining, and Lua scripts. go-redis fully supports Redis 7 and 8.

In this guide, we will cover installation, main methods, common errors, and write a real practical example.

Installing go-redis

Installation is done with the standard go get command:

go get github.com/redis/go-redis/v9

After running this command, the dependency will appear in your go.mod. Make sure you have Go version 1.18 or higher installed.

You will also need a running Redis server (locally or remotely). For testing, you can start Redis in Docker:

docker run --name my-redis -p 6379:6379 -d redis

Quick start: connecting and making the first request

Create a file main.go and write a simple program that connects to Redis, sets and reads a value.

package main

import (    "context"    "fmt"    "github.com/redis/go-redis/v9")

func main() {    // Create a context (recommended to use context.Background())    ctx := context.Background()

    // Create a client    rdb := redis.NewClient(&redis.Options{        Addr:     "localhost:6379", // Redis server address        Password: "",               // password (if any)        DB:       0,                // database number (default 0)    })

    // Check the connection with Ping    pong, err := rdb.Ping(ctx).Result()    if err != nil {        panic(fmt.Sprintf("Failed to connect to Redis: %v", err))    }    fmt.Println("Connected:", pong)

    // Set the key "name" with the value "Alice"    err = rdb.Set(ctx, "name", "Alice", 0).Err()    if err != nil {        panic(err)    }

    // Read the value for the key "name"    val, err := rdb.Get(ctx, "name").Result()    if err != nil {        panic(err)    }    fmt.Println("name:", val)

    // Close the connection when the program exits    defer rdb.Close()}

Run the program:

go run main.go

You should see:

Connected: PONGname: Alice

Main go-redis methods (8+)

All go-redis methods return a *Cmd object (or its specialization), which has the .Result() method to get the result and error, .Val() to get only the value, and .Err() to get only the error. This allows flexible handling of results.

1. Set — setting a key's value

What it does: Sets the value for the specified key. You can set a time-to-live (TTL) or 0 for persistent storage.

Parameters:

• ctx context.Context — context for managing execution time
• key string — key name
• value interface{} — value (will be serialized)
• expiration time.Duration — time-to-live (0 means no TTL)

Example:

err := rdb.Set(ctx, "