Engula
docs
docs

Engula CompatQuick - Engula 2.1 and Redis 7.2 Compatibility Testing Tool

Document Version: v2.1 Last Updated: 2025-09-17 Maintained by: Engula Team

Declaration and Conclusion

Technical Approach

Engula implements kernel-level storage engine replacement within the Redis kernel, while maintaining Redis's protocol, command processing, and client ecosystem.

Compatibility Conclusion

At the design and implementation level, Engula 2.1 and Redis 7.2 can theoretically achieve 100% compatibility (protocol and semantic consistency). Applications do not need to modify code or replace clients.

Design Goals and Comparison Methodology

Goals

Verify the protocol and data structure compatibility level of Engula 2.1 with Redis 7.2.

Metrics

  • Protocol Compatibility: RESP protocol compliance
  • Data Structure Compatibility: Consistency of data structure operations

Comparison Methodology

  • Baseline: Use Redis 7.2's native make test test cases
  • Framework: Adopt Redis native testing framework to ensure test case consistency and reproducibility
  • Evaluation: Compare test results item by item, statistics pass rate and failure reasons

Test Metrics

Data Structure Compatibility: Operational consistency for:

  • String
  • Hash
  • List
  • Set
  • Sorted Set
  • Stream
  • Bitmap
  • HyperLogLog
  • Geo

Verification Principle

Redis uses a Tcl-based testing framework (test.tcl + multiple unit/*.tcl test cases) to drive redis-server and redis-cli, executing commands via RESP protocol and validating expected outputs. Tests run directly through runtest.tcl, supporting features such as module and tag filtering, parallel execution, and data directory isolation, ensuring reproducible results and low coupling to implementation details.

Engula Compatibility Verification Approach:

  • Select Tcl test case sets related to data structures (String, Hash, List, Set, Sorted Set, Stream, Bitmap, HyperLogLog, Geo), use native test driver script runtest.tcl to initiate tests from the client side, then compare whether the expected output of test cases matches the actual response from Engula.
  • Exclude tests that depend on Redis internal memory layout or debugging interfaces (debug/internal representations), without affecting compatibility for user applications.

Tcl Test File List

  • unit/scan
  • unit/type/string
  • unit/type/incr
  • unit/type/list
  • unit/type/list-2
  • unit/type/list-3
  • unit/type/set
  • unit/type/zset
  • unit/type/hash
  • unit/type/stream
  • unit/type/stream-cgroups
  • unit/sort
  • unit/expire
  • unit/pubsub
  • unit/pubsubshard
  • unit/bitops
  • unit/bitfield
  • unit/geo
  • unit/hyperloglog

For more granular test items, refer to the output.log generated by Engula CompatQuick (containing execution details for each test case):

Quick Compatibility Self-Testing (Engula CompatQuick)

Download Testing Tool

Docker Image: registry.cn-guangzhou.aliyuncs.com/montplex/engula-compat-quick

Environment Requirements

Engula CompatQuick is provided as a Docker image and can run on Linux or macOS with Docker installed. Recommended environment:

  • CentOS: Version ≥ 7.9
  • Ubuntu: Version ≥ 18.04
  • Docker: Recommended to use official Docker version (installation guide, VPN may be required in some networks)

Running Engula CompatQuick

1docker pull registry.cn-guangzhou.aliyuncs.com/montplex/engula-compat-quick
2
3# In any folder
4mkdir tmp_test && cd tmp_test
5touch output.log
6touch summary.html
7
8docker run --user $(id -u):$(id -g) -it --rm \
9  -v $(pwd)/output.log:/montplex/output.log \
10  -v $(pwd)/summary.html:/montplex/summary.html \
11  registry.cn-guangzhou.aliyuncs.com/montplex/engula-compat-quick

The running interface will display as shown:

Viewing Results

After execution, a summary.html file will be generated. Open it in a browser to view the results:

The report includes:

  • Compatibility pass statistics
  • Passed command categories and subcategories details

FAQ

Q: Are all data structure test cases included? Are there any deletions?

A: Yes, there are some deletions. Some debug-type test cases have been removed. Debug-type cases test through Redis's original internal data structures. Engula's storage format differs from Redis, and these cases have been transformed to Engula's memory storage format. These cases typically do not affect Redis usage or compatibility with Redis.