redis-replicator: consuming the Redis replication stream from Java

redis-replicator taps the replication stream, not the Redis API

Most tools that need to know what a Redis instance is doing go through the client API and ask for it. redis-replicator takes the other route. It is an implementation of the Redis replication protocol written in Java, and it can parse, filter and broadcast RDB and AOF events in real time. That means the input is the same byte stream a replica would receive, so the feed contains the writes as they happen rather than a sampled view of the current keyspace.

The intended users are Java developers who need that stream. A team that wants to keep a local cache in step with a primary Redis, or a database that mirrors Redis state, or a pipeline that moves data to a destination of its own, all need the write stream rather than the current value of every key. The project also describes itself as a tool that can parse, filter, split and merge RDB files, analyse memory usage offline, synchronise data between two Redis instances, and let users define their own sink services for migrating Redis data to custom destinations.

One definitional detail matters for anyone writing a filter. In this project, Command refers to writable commands such as set and hmset, and explicitly excludes readable commands such as get and hmget.

Events, listeners and the filter you build on top

The shape of the API is visible in the basic usage example the README opens with. You construct a Replicator against a Redis URI and register an event listener that receives every event the replicator produces:

Replicator replicator = new RedisReplicator("redis://127.0.0.1:6379");
replicator.addEventListener(new EventListener() {
    @Override
    public void onEvent(Replicator replicator, Event event) {

The example continues past that point with the body of the listener method. The important part is the structure: the replicator is the source, the listener is where your logic lives, and the event type is what you switch on. Filtering therefore happens in your own code rather than through a query language in the library, which is what makes the tool usable for a specific destination, since the interesting predicate is always the one your sink cares about.

The event model also has a lifecycle. The README documents lifecycle events as a separate topic, alongside a trace event log for seeing what the replicator itself is doing. Those two together are the debugging path: the trace log tells you what arrived and in what order, and the lifecycle events tell you when the stream connected, switched mode or closed.

Extending the protocol: commands, Redis modules and custom RDB parsers

The advanced sections of the README describe three extension paths, and they are the reason to choose this library over something narrower. The first is command extension, laid out as a sequence: write a command, write a command parser, register the parser, handle the command event, then put it together. The second is module extension for Redis server modules, which starts with compiling the Redis test modules and uncommenting the relevant lines in redis.conf before you write a module parser and register parsers and handle events. The third is writing your own RDB parser.

Each path is a genuine amount of work, and none of it is optional. Handling a Redis module means the server has to be running that module in the first place, which is a deployment decision rather than a library decision. Writing a custom RDB parser is the escape hatch for a data format the built-in parsers do not cover, and the README also keeps a list of built-in command parsers so you can check before writing your own.

The project documents support for Redis 6 with SSL and ACL, Redis 7 with function support, and Redis 7.4 with TTL hash. That is a concrete compatibility story rather than a vague promise, and it is what tells you whether a new server release is something you can adopt or something you have to wait for.

The version table: which library release matches your Redis server

Version compatibility is handled explicitly, with a table mapping Redis server versions to the redis-replicator release range that supports them. The current range pairs Redis 2.6 to 8.4.x with redis-replicator 3.11.0 and later, Redis 2.6 to 8.2.x with 3.10.0, Redis 2.6 to 8.0.x with 3.9.0, and Redis 2.6 to 7.2.x with the 3.8.x line. Older server versions map to progressively older library lines, down to Redis 2.6 to 5.0.x with 2.6.1 through 3.3.3.

One row is worth pausing on. Redis 2.6 to 3.2.x is paired with version 1.0.18 and is marked as not supported, so a very old server is outside what the current library claims to handle. The table also records release candidates as separate rows, which is a hint that Redis itself, not the library, is where the version churn happens.

The build requirements follow the same explicit style. Compiling needs JDK 9 or newer, running needs JDK 8 or newer, Maven 3.3.1 or newer is required, and the supported Redis range is stated as 2.6 to 8.4. The default branch is master, and the latest release listed is v3.11.0, published on 2025-11-29, after v3.10.0 in October 2025 and v3.9.0 in June 2025.

Adding the Maven dependency and building from source

Installation is the standard Maven coordinate. The dependency block in the README pins the release explicitly:

<dependency>
    <groupId>com.moilioncircle</groupId>
    <artifactId>redis-replicator</artifactId>
    <version>3.11.0</version>
</dependency>

For a source build, the README gives four steps, which you run in order from a shell:

# Step 1: Install JDK 11+ for compilation
# Step 2: Clone the repository
git clone https://github.com/leonchen83/redis-replicator.git
# Step 3: Navigate to the project directory
cd redis-replicator
# Step 4: Build the project
mvn clean install package -DskipTests

Note the mismatch between the step comment, which asks for JDK 11 or newer, and the requirements list, which says compilation needs JDK 9 or newer. Both are satisfied by a current JDK, and the runtime floor of JDK 8 is what matters if you consume the artifact from an older service.

There is no server component to install. This is a library, so your first real use is a JVM program that creates a Replicator against a Redis URI, registers a listener, and does something with each event. The URI format is a documented topic in its own right, so the connection string is where you should look first if the replicator will not attach.

Where the data goes: caches, databases, sinks and offline RDB work

The output side is where the design choices are most visible, because redis-replicator deliberately stops at the event stream. Synchronising Redis data to a local cache or to a database is listed as a capability, and defining your own sink services for migrating Redis data to custom destinations is called out separately. The difference matters: with a custom sink, the shape of the destination, the batching and the retry behaviour are your code, not configuration. The library produces events and you decide what a write means in your world.

The offline side of the project is separate from the streaming side. The tool can parse, filter, split and merge RDB files, and it can analyse memory usage offline. That is a different use case from live replication, and it is the one that matters when you have inherited a large RDB file and need to understand what is inside it or carve it up before loading it somewhere. Merging and splitting files is the kind of operation that keeps a copy of data out of the server entirely.

Syncing data between two Redis instances is also described, which puts redis-replicator in the same space as tools built for replication, and the difference in approach is worth naming. Where a purpose-built replication tool understands the replication handshake and handles failover as its core job, this library is a protocol implementation that hands you the events. The control is yours, and so is the responsibility.

Failure modes to plan for: full sync, huge values and EOFException

A protocol implementation is only as good as its edge cases, and the README names several of them. Avoiding full sync is listed as a topic, which tells you the library does not do it for you and that a configuration choice on your side determines whether you receive an initial snapshot or only incremental changes. Handle huge key-value pairs is another named topic, and it matters for anyone filtering a stream because a single oversized value can stall a consumer that assumes small records. EOFException has its own section, which is the kind of topic that only earns a heading when people actually hit it.

Connection concerns have their own group of topics: SSL connection, authentication, and ACL support under Redis 6. A tool that attaches to a production instance has to negotiate TLS and credentials, and the fact that these are documented separately from the main usage flow suggests they are configuration steps rather than defaults.

The project also carries a changelog, a code of conduct and an examples directory with Java sources under examples/com, and the release history shows steady minor releases through 2025. The last push to the repository was on 2026-05-07, and the repository is not archived. On licensing, the project ships a LICENSE file, and the README also displays a separate Anti 996 licence badge with matching ANTI-996-LICENSE and ANTI-996-LICENSE_CN files at the root, so read both before you redistribute anything built on it.

Editorial conclusion

redis-replicator is the right choice for a Java team that needs a live stream of Redis writes to maintain a local cache, feed a database or drive a migration, and the version table makes it possible to match a library release to your server release precisely. It is the wrong tool for a non-Java stack, for a one-off export, and for anyone who needs the project to manage a full sync for them, because avoiding full sync and handling huge values are documented as topics you configure yourself. Before adopting it, confirm your Redis version falls in a supported row of the compatibility table, note that Redis 2.6 to 3.2.x is not supported, check the authentication, ACL and SSL settings your server needs, and read the build requirements of JDK 9 or newer for compilation. The last push was on 2026-05-07 and the current release is v3.11.0.

Frequently asked questions

Official sources

1. Issues
2. leonchen83/redis-replicator on GitHub
3. License: Apache-2.0
4. README
5. Releases