Using Oracle True Cache as a Redis Server

Use Redis clients to fetch Oracle AI Database rows from True Cache by using SQL keys and supported Redis commands.

True Cache can accept Redis wire protocol connections. Existing Redis applications can connect to the True Cache endpoint and use supported Redis commands to read database rows.

Note:

You can use the information in this section to configure the Oracle Redis Server on Oracle AI Database, Active Data Guard, and True Cache.

See also:

Configure the Redis Protocol Dispatcher

On True Cache, add a Redis protocol dispatcher.

Set the DISPATCHERS parameter with PRE=REDIS. Use the SERVICE attribute to specify the target pluggable database (PDB) service.

DISPATCHERS='(ADDRESS=(PROTOCOL=tcps)(HOST=true_cache_host)(PORT=redis_port))(SERVICE=pdb_service_name)(PRE=REDIS)'

Use tcps so Redis wire protocol traffic is protected with transport layer security (TLS). Use a certificate for the container database (CDB) or host that owns the Redis protocol endpoint.

Connect and Authenticate

Use a Redis client that supports TLS and the Redis AUTH command. Each Redis connection must authenticate before it fetches SQL keys.

redis-cli -h true_cache_host -p redis_port --tls
AUTH db_user db_user_password
OK

The Redis user name is an Oracle AI Database user. Database authentication, profiles, privileges, and roles control access to the underlying tables and views.

Use SQL Keys

A SQL key identifies a row in a table, view, or JSON-relational duality view. The value returned for a SQL key comes from the row identified by that key.

Use this SQL key format:

[schema_name.]table_name:column_name=value[:column_name=value...]

For example:

hr.emps:emp_id=1002
hr.employees:first_name=Steven:job_id=AD_PRES
hr.emp_dept_view:"id"=1001

If a SQL key includes more than one column, then Oracle True Cache applies an AND condition. You can specify the columns in any order.

Use Supported Redis Commands

Oracle True Cache supports Redis commands that fetch SQL keys and commands that simplify SQL key syntax. It supports only version 2 of the Redis Serialization Protocol (RESP2). The reply descriptions use RESP2 response types.

Command Use Syntax Reply Type Example
GET Return a SQL key value. GET key Bulk string containing the values of all columns, separated by colons (:) Command:
GET hr.emps:emp_id=1

Reply:
1:John:Doe:1:75000
MGET Return values for multiple SQL keys. MGET key1 [key2 ...] Array of bulk strings Command:
MGET hr.emps:emp_id=2 hr.depts:dept_id=1

Reply:
2:Jane:Smith:2:65000
1:IT
HGET Return one field value for a SQL key. HGET key field Bulk string Command:
HGET hr.emps:emp_id=3 first_name

Reply:
Alice
HMGET Return multiple field values for a SQL key. HMGET key field1 [field2 ...] Array of bulk strings Command:
HMGET hr.emps:emp_id=1 first_name last_name

Reply:
John
Doe
HGETALL Return all field values for a SQL key. HGETALL key Array of bulk strings Command:
HGETALL hr.emps:emp_id=2

Reply:
EMP_ID
2
FIRST_NAME
Jane
LAST_NAME
Smith
DEPT_ID
2
SALARY
65000
JSON.GET Return a SQL key value, or selected paths, in JSON serialized format. JSON.GET key [path ...] Bulk string Command:
JSON.GET hr.emps:emp_id=3 $.first_name $.last_name

Reply:
{"FIRST_NAME":"Alice","LAST_NAME":"Brown"}
SET Accept an update request for a SQL key. SET key value Simple string Command:
SET hr.emps:emp_id=2 value

Reply:
OK
MSET Accept update requests for multiple SQL keys. MSET key value [key value ...] Simple string Command:
MSET hr.emps:emp_id=1 value1 hr.emps:emp_id=2 value2

Reply:
OK
HSET Accept a field update request for a SQL key. HSET key field value Simple string Command:
HSET hr.emps:emp_id=2 first_name Jane

Reply:
OK
JSON.SET Accept a JSON path update request for a SQL key. JSON.SET key path json Simple string Command:
JSON.SET hr.emps:emp_id=2 $.first_name "Jane"

Reply:
OK
AUTH Authenticate the Redis connection as an Oracle AI Database user. AUTH db_user_name db_user_password Simple string Command:
AUTH hr HrPassW0rd47%

Reply:
OK
CLIENT SET-SCHEMA Set the default schema for SQL keys in the current Redis connection. CLIENT SET-SCHEMA schema_name Simple string Command:
CLIENT SET-SCHEMA hr

Reply:
OK
CLIENT SET-TABLE Set the default table for SQL keys in the current Redis connection. CLIENT SET-TABLE table_name Simple string Command:
CLIENT SET-TABLE emps

Reply:
OK
CLIENT SET-COLUMN Set the default column for SQL keys in the current Redis connection. CLIENT SET-COLUMN column_name Simple string Command:
CLIENT SET-COLUMN first_name

Reply:
OK
CLIENT RESET-SCHEMA Unset the default schema for SQL keys in the current Redis connection. CLIENT RESET-SCHEMA Simple string Command:
CLIENT RESET-SCHEMA

Reply:
OK
CLIENT RESET-TABLE Unset the default table for SQL keys in the current Redis connection. CLIENT RESET-TABLE Simple string Command:
CLIENT RESET-TABLE

Reply:
OK
CLIENT RESET-COLUMN Unset the default column for SQL keys in the current Redis connection. CLIENT RESET-COLUMN Simple string Command:
CLIENT RESET-COLUMN

Reply:
OK

SET, MSET, HSET, and JSON.SET always return OK, but they don’t update database rows.

For a non-existent key or field, True Cache replies with a bulk string containing an error message.

Simplify SQL Keys

Use CLIENT SET-SCHEMA, CLIENT SET-TABLE, and CLIENT SET-COLUMN to set defaults for the current Redis connection. These commands let applications use shorter SQL keys.

CLIENT SET-SCHEMA scott
OK
CLIENT SET-TABLE emp
OK
CLIENT SET-COLUMN ename
OK
JSON.GET ALLEN $.empno $.job
{"EMPNO":7499,"JOB":"SALESMAN"}

In this example, ALLEN resolves to the full SQL key scott.emp:ename=ALLEN.

Use CLIENT RESET-SCHEMA, CLIENT RESET-TABLE, or CLIENT RESET-COLUMN to unset a default schema, table, or column in the current Redis connection.

CLIENT RESET-COLUMN
OK

Restrictions

Use these restrictions when you design applications that use True Cache as a Redis server: