tree: c4465a52511702c5ec030482a4995376182633b6 [path history] [tgz]
  1. README.md
  2. build.gradle
  3. gfsh.png
  4. src/
geode-redis/README.md

Redis API for Apache Geode

Introduction
How To Try It
Building Apache Geode
Starting a Geode Server with Redis Enabled
Adding an Additional Geode Redis Server
Shutting Down
Redis Commands

Introduction

The Redis API for Geode allows an application to send Redis commands to Geode. This will allow users to switch seamlessly from native Redis to Geode as a data store/caching solution.

The API allows Geode to listen for and interpret incoming Redis commands on a designated port.

How To Try It

The Redis API for Geode is currently in early access. We’ll build the develop branch of Apache Geode and then connect the Redis-CLI to that instance.

Note: Currently Geode requires Java 8 JDK to build.

Supported Redis Commands

Not all Redis commands are currently supported. The current set of supported Redis commands is listed here.

Building Apache Geode

The Apache Geode source code can be found here

  1. In a terminal, git clone the Geode repo:

    $ git clone https://github.com/apache/geode.git
    
  2. Change the working directory to the Geode directory you cloned

    	$ cd geode
    
  3. Build the Geode application without running the test (REQUIRES JAVA 8)

    $ ./gradlew assemble
    
  4. Once the build has completed, navigate to the geode-assembly directory which contains the Apache Geode Shell - also referred to as GFSH:

    $ cd geode-assembly/build/install/apache-geode/bin
    
  5. Once in that folder run the following command:

    $ ./gfsh
    

You should now see GFSH starting up with a version of 1.14.x.-build.x

screenshot of GFSH running in the terminal

Starting a Geode Server with Redis Enabled

Note: if you wish to run the Geode Redis API on the default Redis port (6379), make sure to stop any applications running on that port before starting the Geode server, especially any native Redis servers.

Using GFSH enter the following commands:

  1. Start a locator. The locator tracks servers and server load. When a client requests a server connection, the locator directs the client to one of the least loaded servers. Learn more.

     gfsh> start locator
    
  2. After the locator has started, start a server that will be able to handle incoming Redis commands.

    For example:

    gfsh> start server --name=redisServer1 --locators=localhost[10334] --server-port=0 --redis-port=6379
    
    • --name: A name you create for your server.
    • --locators: This is the location of the locator you started in step 1.
    • --server-port: The port that Geode clients connect to.
    • --redis-port: The port that your Redis client will connect to.

    Your Geode instance should now be up and running (1 locator and 1 server) and ready to accept Redis commands.

    Keep this terminal open and running so that you can easily shutdown the Geode instance when you are done working locally.

  3. To confirm that things are running correctly, in a separate terminal run:

    $ redis-cli
    

    If working correctly you should now be in the redis-cli and see 127.0.0.1:6379>. If you run the PING command you should receive a response of PONG.

Optional - Adding an Additional Geode Redis Server

If you’re interested in testing Geode scalability, in GFSH run the start server command again BUT make sure you change the --name= and --redis-port= parameters.

For example:

$ start server --name=redisServer2 --locators=localhost[10334] --server-port=0 --redis-port=6380

Shutting Down

To shutdown the Geode instance you started, in the terminal with GFSH running type the following command

$ shutdown --include-locators=true

As this command will shut down the entire Geode instance/cluster, you will be prompted with the following choice:

As a lot of data in memory will be lost, including possibly events in queues, do you really want to shutdown the entire distributed system? (Y/n)

To confirm that everything shutdown correctly, if you execute a Redis command in the redis-cli you should see the following message:

Could not connect to Redis at 127.0.0.1:6379: Connection refused 
not connected>

Redis Commands

The Redis API for Geode currently implements a subset of the full Redis command set. Some commands are unsupported (see table below). Unsupported commands are available to use, but have not been fully tested. There is no guarantee they will work exactly as expected.

Enabling Unsupported Commands

If you already have Geode servers running with Redis enabled, you can execute the following command with gfsh to enable unsupported commands:

redis --enable-unsupported-commands

You can also enable unsupported commands when you start the Geode server by setting the Java property enable-redis-unsupported-commands=true:

start server \
  --J=-Denable-redis-unsupported-commands=true \
  --name=<serverName> \
  --locators=<locatorPort> \
  --redis-port=<redisPort> \
  --redis-bind-address=<redisBindAddress> \
  --redis-password=<redisPassword>

Redis Command Status Return to top

Supported CommandsUnsupported Commands
(Implemented - not tested)
Commands Not Implemented
APPENDBITCOUNTACL CAT
AUTHBITOPACL DELUSER
DELBITPOSACL GENPASS
EXISTSDBSIZEACL GETUSER
EXPIREDECRACL HELP
EXPIREATDECRBYACL LIST
GETECHOACL LOAD
HGETALLFLUSHALLACL LOG
HMSETFLUSHDBACL SAVE
HSETGETBITACL SETUSER
HVALSGETRANGEACL USERS
KEYSGETSETACL WHOAMI
PERSISTHDELBGREWRITEAOF
PEXPIREHEXISTSBGSAVE
PEXPIREATHGETBITFIELD
PINGHINCRBYBLPOP
PSUBSCRIBEHINCRBYFLOATBRPOP
PTTLHKEYSBRPOPLPUSH
PUBLISHHLENBZPOPMAX
PUNSUBSCRIBEHMGETBZPOPMIN
QUITHSCANCLIENT CACHING
RENAMEHSETNXCLIENT GETNAME
SADDHSTRLENCLIENT GETREDIR
SETINCRCLIENT ID
SMEMBERSINCRBYCLIENT KILL
SREMINCRBYFLOATCLIENT LIST
SUBSCRIBEINFOCLIENT PAUSE
TTLMGETCLIENT REPLY
TYPEMSETCLIENT SETNAME
UNSUBSCRIBEMSETNXCLIENT TRACKING
PSETEXCLIENT UNBLOCK
SCANCLUSTER ADDSLOTS
SCARDCLUSTER BUMPEPOCH
SDIFFCLUSTER COUNT-FAILURE-REPORTS
SDIFFSTORECLUSTER COUNTKEYSINSLOT
SELECTCLUSTER DELSLOTS
SETBITCLUSTER FAILOVER
SETEXCLUSTER FLUSHSLOTS
SETNXCLUSTER FORGET
SETRANGECLUSTER GETKEYSINSLOT
SHUTDOWNCLUSTER INFO
SINTERCLUSTER KEYSLOT
SINTERSTORECLUSTER MEET
SISMEMBERCLUSTER MYID
SLOWLOGCLUSTER NODES
SMOVECLUSTER REPLICAS
SPOPCLUSTER REPLICATE
SRANDMEMBERCLUSTER RESET
SSCANCLUSTER SAVECONFIG
STRLENCLUSTER SET-CONFIG-EPOCH
SUNIONCLUSTER SETSLOT
SUNIONSTORECLUSTER SLAVES
TIMECLUSTER SLOTS
UNLINK [1]COMMAND
COMMAND COUNT
COMMAND GETKEYS
COMMAND INFO
CONFIG GET
CONFIG RESETSTAT
CONFIG REWRITE
CONFIG SET
DEBUG OBJECT
DEBUG SEGFAULT
DISCARD
DUMP
EVAL
EVALSHA
EXEC
GEOADD
GEODIST
GEOHASH
GEOPOS
GEORADIUS
GEORADIUSBYMEMBER
LASTSAVE
LATENCY DOCTOR
LATENCY GRAPH
LATENCY HELP
LATENCY HISTORY
LATENCY LATEST
LATENCY RESET
LINDEX
LINSERT
LLEN
LOLWUT
LPOP
LPOS
LPUSH
LPUSHX
LRANGE
LREM
LSET
LTRIM
MEMORY DOCTOR
MEMORY HELP
MEMORY MALLOC-STATS
MEMORY PURGE
MEMORY STATS
MEMORY USAGE
MIGRATE
MODULE LIST
MODULE LOAD
MODULE UNLOAD
MONITOR
MOVE
MULTI
OBJECT
PFADD
PFCOUNT
PFMERGE
PSYNC
PUBSUB
RANDOMKEY
READONLY
READWRITE
RENAMENX
REPLICAOF
RESTORE
ROLE
RPOP
RPOPLPUSH
RPUSH
RPUSHX
SAVE
SCRIPT DEBUG
SCRIPT EXISTS
SCRIPT FLUSH
SCRIPT KILL
SCRIPT LOAD
SLAVEOF
SORT
STRALGO LCS
SWAPDB
SYNC
TOUCH
UNWATCH
WAIT
WATCH
XACK
XADD
XCLAIM
XDEL
XGROUP
XINFO
XLEN
XPENDING
XRANGE
XREAD
XREADGROUP GROUP
XREVRANGE
XTRIM
ZADD
ZCARD
ZCOUNT
ZINCRBY
ZINTERSTORE
ZLEXCOUNT
ZPOPMAX
ZPOPMIN
ZRANGE
ZRANGEBYLEX
ZRANGEBYSCORE
ZRANK
ZREM
ZREMRANGEBYLEX
ZREMRANGEBYRANK
ZREMRANGEBYSCORE
ZREVRANGE
ZREVRANGEBYSCORE
ZREVRANK
ZSCAN
ZSCORE
ZUNIONSTORE

NOTES:

[1] - UNLINK is implemented as a synonym to DEL and does not unlink asynchronously.