tree: f46fc434a4ed048f56cdded500ac5df224adff52 [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
KEYSGETRANGEACL USERS
PERSISTGETSETACL WHOAMI
PEXPIREHDELBGREWRITEAOF
PEXPIREATHEXISTSBGSAVE
PINGHGETBITFIELD
PSUBSCRIBEHINCRBYBLPOP
PTTLHINCRBYFLOATBRPOP
PUBLISHHKEYSBRPOPLPUSH
PUNSUBSCRIBEHLENBZPOPMAX
QUITHMGETBZPOPMIN
RENAMEHSCANCLIENT CACHING
SADDHSETNXCLIENT GETNAME
SETHSTRLENCLIENT GETREDIR
SMEMBERSHVALSCLIENT ID
SREMINCRCLIENT KILL
SUBSCRIBEINCRBYCLIENT LIST
TTLINCRBYFLOATCLIENT PAUSE
TYPEINFOCLIENT REPLY
UNSUBSCRIBEMGETCLIENT SETNAME
MSETCLIENT TRACKING
MSETNXCLIENT UNBLOCK
PSETEXCLUSTER ADDSLOTS
SCANCLUSTER BUMPEPOCH
SCARDCLUSTER COUNT-FAILURE-REPORTS
SDIFFCLUSTER COUNTKEYSINSLOT
SDIFFSTORECLUSTER DELSLOTS
SELECTCLUSTER FAILOVER
SETBITCLUSTER FLUSHSLOTS
SETEXCLUSTER FORGET
SETNXCLUSTER GETKEYSINSLOT
SETRANGECLUSTER INFO
SHUTDOWNCLUSTER KEYSLOT
SINTERCLUSTER MEET
SINTERSTORECLUSTER MYID
SISMEMBERCLUSTER NODES
SLOWLOGCLUSTER REPLICAS
SMOVECLUSTER REPLICATE
SPOPCLUSTER RESET
SRANDMEMBERCLUSTER SAVECONFIG
SSCANCLUSTER SET-CONFIG-EPOCH
STRLENCLUSTER SETSLOT
SUNIONCLUSTER SLAVES
SUNIONSTORECLUSTER SLOTS
TIMECOMMAND
UNLINK [1]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.