| <% set_title("Redis API for", product_name) %> |
| |
| <!-- |
| Licensed to the Apache Software Foundation (ASF) under one or more |
| contributor license agreements. See the NOTICE file distributed with |
| this work for additional information regarding copyright ownership. |
| The ASF licenses this file to You under the Apache License, Version 2.0 |
| (the "License"); you may not use this file except in compliance with |
| the License. You may obtain a copy of the License at |
| |
| http://www.apache.org/licenses/LICENSE-2.0 |
| |
| Unless required by applicable law or agreed to in writing, software |
| distributed under the License is distributed on an "AS IS" BASIS, |
| WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. |
| See the License for the specific language governing permissions and |
| limitations under the License. |
| --> |
| |
| The Redis API for <%=vars.product_name%> allows <%=vars.product_name%> to function as a drop-in replacement for a |
| highly-available Redis data store, letting Redis applications take advantage of |
| <%=vars.product_name%>’s scaling capabilities without changing their client code. Redis clients connect to a <%=vars.product_name%> |
| server in the same way they connect to a Redis server, using a hostname and a port number, with |
| optional password authentication. |
| |
| <img src="../images/redis_api_for_geode.png" class="image" /> |
| |
| ## <a id="using-the-api" class="no-quick-link"></a>Using the Redis API for <%=vars.product_name%> |
| |
| The <%=vars.product_name%> cluster must have at least one server that is set up to handle the incoming Redis |
| commands. |
| |
| Use gfsh to start at least one server with a command of the form: |
| |
| ```pre |
| start server \ |
| --name=<serverName> \ |
| --locators=<locatorPort> \ |
| --redis-port=<redisPort> \ |
| --redis-bind-address=<redisBindAddress> \ |
| --redis-password=<redisPassword> |
| ``` |
| |
| Replace `<serverName>` with the name of your server. |
| |
| Replace `<locatorPort>` with your locator port. |
| |
| Replace `<redisPort>` with the port that the <%=vars.product_name%> server listens on for Redis commands. The typical port used with a Redis cluster is 6379. |
| |
| Replace `<redisBindAddress>` with the address of the server host. |
| |
| Replace `<redisPassword>` with the password clients use to authenticate. |
| |
| To confirm the server is listening, run: |
| |
| ``` pre |
| redis-cli -h <redisBindAddress> -p <redisPort> -a <redisPassword> ping |
| ``` |
| |
| Replace `<redisBindAddress>`,`<redisPort>`, and `<redisPassword>` with the same values as the server. |
| |
| If the server is functioning properly, you should see a response of `PONG`. |
| |
| ## <a id="included-commands" class="no-quick-link"></a>Included Redis Commands |
| |
| The Redis API for <%=vars.product_name%> currently supports the following commands. See [Redis commands](https://redis.io/commands/) for a complete list of and more information on Redis commands. |
| |
| **Note**: These commands are supported for Redis 5. |
| |
| - **Connection**: AUTH, PING, QUIT |
| - **Hashes**: HGETALL, HMSET, HSET |
| - **Keys**: DEL, EXISTS, EXPIRE, EXPIREAT, KEYS, PERSIST, PEXPIRE, PEXPIREAT, PTTL, RENAME, TTL, TYPE |
| - **Publish/Subscribe**: PUBLISH, PSUBSCRIBE, PUNSUBSCRIBE, SUBSCRIBE, UNSUBSCRIBE |
| - **Sets**: SADD, SMEMBERS, SREM |
| - **Strings**: APPEND, GET, SET |
| |
| The following Redis API for <%=vars.product_name%> commands are **unsupported**. Unsupported |
| commands are available to use, but have not been fully tested. There is no guarantee they will work |
| exactly as expected. |
| |
| - **Connection**: ECHO, SELECT |
| - **Hashes**: HDEL, HEXISTS, HGET, HINCRBY, HINCRBYFLOAT, HKEYS, HLEN, HMGET, HSCAN, HSETNX, HVALS |
| - **Keys**: SCAN, UNLINK |
| - **Server**: DBSIZE, FLUSHALL (no async option), FLUSHDB (no async option), SHUTDOWN, TIME |
| - **Sets**: SCARD, SDIFF, SDIFFSTORE, SINTER, SINTERSTORE, SISMEMBER, SMOVE, SPOP, SRANDMEMBER, |
| SSCAN, SUNION, SUNIONSTORE |
| - **Strings**: BITCOUNT, BITOP, BITPOS, DECR, DECRBY, GETBIT, GETRANGE, GETSET, INCR, INCRBY, INCRBYFLOAT, MGET, |
| MSET, MSETNX, PSETEX, SETBIT, SETEX, SETNX, SETRANGE, STRLEN |
| |
| |
| If you already have some Geode servers running with Redis enabled, you can execute the following |
| command with gfsh to enable unsupported commands: |
| |
| ```pre |
| 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`: |
| |
| ```pre |
| start server \ |
| --J=-Denable-redis-unsupported-commands=true \ |
| --name=<serverName> \ |
| --locators=<locatorPort> \ |
| --redis-port=<redisPort> \ |
| --redis-bind-address=<redisBindAddress> \ |
| --redis-password=<redisPassword> |
| ``` |
| |
| Commands not listed above are **not implemented**. |
| |
| ## <a id="advantages-over-redis" class="no-quick-link"></a>Advantages of <%=vars.product_name%> over Redis |
| |
| <%=vars.product_name%>’s primary advantage is its **scalability**. While the Redis server is single threaded, <%=vars.product_name%> supports high concurrency. Many Redis clients can execute commands on the <%=vars.product_name%> cluster simultaneously. |
| |
| <%=vars.product_name%>'s architecture and management features help detect and resolve **network partitioning** problems without explicit management on the part of the Redis client. |
| |
| ## <a id="expiration-accuracy" class="no-quick-link"></a>Expiration Accuracy |
| |
| Keys are expired in two ways, actively and passively: |
| |
| - With active expiration, expiration is evaluated whenever a key is accessed. If the key is due to expire, it is deleted. Active expiration is accurate to the millisecond. |
| - With passive expiration, keys are evaluated every second. If they are due to expire, they are deleted. Passive expiration is accurate to the second. |
| |
| ## <a id="high-availability-model" class="no-quick-link"></a>High Availability Model |
| |
| Data is stored in a single partitioned region that has one redundant copy. |
| In practice this means that the cluster can tolerate the loss of a single server without the loss of |
| data. |
| |
| ## <a id="loss-of-connections" class="no-quick-link"></a>Loss of Connections |
| |
| There are a number of events that might occur within the <%=vars.product_name%> cluster that can result |
| in the cluster closing the connection to the Redis client. Losing the connection to the cluster does not |
| imply that the server is no longer available. |
| |
| When the connection is lost, the client should attempt to reconnect to the same server before |
| attempting to connect to another server. |
| The Redis client is responsible for knowing the addresses of all servers. |
| |
| In the case of a connection failure, an invoked command may or may not complete. |
| The Redis client is responsible for deciding if the command should be retried. |