Skip to content
Get packs

Guide · Open source

How to use Codis: clone, build and run a Redis proxy cluster

Updated · written with AI from the project's own documentation and checked against our catalogue data

Codis is an open-source proxy that sits between your applications and several Redis servers and presents them as one cluster. This guide explains what it does, what you need before installing it, how to get the source code, and when another tool is a better fit. By the end you will know whether Codis suits your Redis setup and where to find the official tutorial for configuration.

CodisCodisLabs/codis · ★ 13.2k · MIT

Quick start

  1. 1Confirm your prerequisites. Make sure you have a Go toolchain, at least one Redis server, and zk or etcd if you want proxy registration.
  2. 2Clone the repository. Run git clone https://github.com/CodisLabs/codis.git to download the source code.
  3. 3Read the official tutorial. Open the Tutorial linked from the README to find the build and configuration steps, since the excerpt does not include them.
  4. 4Build from source. Follow the build steps in the project documentation using your Go toolchain.
  5. 5Connect your Redis servers. Register your Redis servers with Codis as described in the tutorial, then point your applications at the proxy.
  6. 6Test with your existing client. Confirm your current Redis client works through the proxy before moving production traffic.

What Codis does and how it splits data

Codis places a proxy layer between your applications and multiple Redis servers. Your applications talk to the proxy, and the proxy routes each key to the right server.

Keys are divided across servers in slots. Because the data is spread over several machines, the cluster can grow beyond what a single server holds.

  • Presents several Redis servers as one cluster
  • Splits keys across servers in slots
  • Lets any Redis client connect, according to the README's comparison table

Check the prerequisites before you install

The README names three things you need: a Go toolchain, one or more Redis servers, and optionally zk or etcd for proxy registration. The README excerpt does not state which Go version is required, so check the project's own documentation before you build.

zk or etcd is only needed if you want proxies to register so clients can avoid dead proxies, as described in the High Availability section.

  • Go toolchain (required version not stated in the README excerpt)
  • Redis server
  • zk or etcd for proxy registration (optional)

Get the source code with git clone

Codis is installed by cloning the repository and building it yourself. Run the command below to download the source from GitHub.

git clone https://github.com/CodisLabs/codis.git

Understand when Codis is the right choice

The README's comparison table shows that Codis supports resharding without restarting the cluster and pipelining, and that it works with any Redis client. Redis Cluster supports resharding but requires clients that understand the cluster protocol. Twemproxy supports pipelining but not resharding without a restart.

Codis is a good fit for teams that have outgrown a single Redis server, operators who need to add or remove servers while running, and applications whose Redis clients cannot use the Redis Cluster protocol. It is not worth the extra layer if you run one Redis server.

  • Good fit: outgrown one server, need live resharding, existing clients that cannot use cluster protocol, want a web dashboard
  • Poor fit: one Redis server, need the Redis Cluster protocol directly, need a recently released and actively maintained version

Know the maintenance status before you commit

The README says Codis is production-ready and widely used, but the README and latest release point to 2017-era versions, and the last push was in April 2024. Check the Releases page and the commit history yourself before adopting it for a new project.

The README points to a Tutorial, a FAQ and a High Availability section for configuration detail. The English tutorial is marked work in progress, so the Chinese version may be more complete.

  • Releases page: https://github.com/CodisLabs/codis/releases
  • Tutorial, FAQ and High Availability sections are linked from the README

What people use it for

  • Splitting a growing Redis dataset across several servers behind one endpoint
  • Adding or removing Redis servers while the cluster keeps serving traffic
  • Letting applications with standard Redis clients use a clustered setup without changing client code
  • Managing the Redis setup through the built-in GUI website dashboard

Frequently asked questions

Is Codis free to use?

Yes. The README states that Codis is licensed under MIT, and the license file is MIT-LICENSE.txt in the repository. The project also invites you to use it in your product.

What do I need to install Codis?

You need a Go toolchain, a Redis server, and optionally zk or etcd for proxy registration. The README excerpt does not state the required Go version, so check the project documentation.

How do I install Codis?

Clone the repository with git clone https://github.com/CodisLabs/codis.git, then build it from source following the project's tutorial. The README excerpt does not include the build commands.

Is Codis better than Redis Cluster?

It depends on your clients. According to the README comparison, Codis works with any Redis client, while Redis Cluster requires clients that support the cluster protocol. Codis also supports pipelining, which the README lists as unsupported in Redis Cluster.

Is Codis still maintained?

The README points to 2017-era releases and the last push was in April 2024. Check the Releases page and recent commits before adopting it for a new project.

What are alternatives to Codis?

The README compares Codis with Twemproxy and Redis Cluster. Envoy is also listed as a comparable project. Choose based on whether you need live resharding, pipelining and client compatibility.

New agent skills, repos and AI tools — every week

The best new skills and open-source projects, the fastest-growing repos, and one free prompt. Five minutes to read. Unsubscribe anytime.

Our verdict

Codis suits teams that run Redis, have outgrown one server, and need to reshard live while keeping standard Redis clients. Teams with a single Redis server, teams that need the Redis Cluster protocol directly, or teams that need a recently released version should choose a different option.

Install options & downloads