Using Oracle True Cache as a Redis Server

Use Redis clients to fetch Oracle AI Database rows and JSON-relational duality-view documents 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.

Why Use True Cache with Redis Clients

Read-heavy applications often use a separate Redis cache in front of the database. In that model, the application must populate the cache and keep cached values synchronized with database changes.

True Cache lets an existing Redis application use supported Redis commands to read Oracle AI Database rows and JSON-relational duality-view documents. The application continues to update the primary database, and True Cache applies those committed changes through redo. Redis reads return data that is consistent with the data available in True Cache.

This model avoids a separate Redis data copy and the application logic needed to populate, invalidate, or synchronize that copy. JSON-relational duality views also let Redis clients retrieve application-shaped JSON documents instead of only scalar row values.

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

The first SQL key in the example fetches the row from the EMPS table or view in the HR schema whose EMP_ID column equals 1002. Unquoted schema, table, and column names are automatically converted to uppercase.

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 all column values, including invisible columns, in ascending internal column ID order and 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, including invisible columns, 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` always returns `OK` but doesn’t update database rows.	`SET` `key` `value`	Simple string	Command: `SET hr.emps:emp_id=2 value` Reply: `OK`
`MSET`	Accept update requests for multiple SQL keys. `MSET` always returns `OK` but doesn’t update database rows.	`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` always returns `OK` but doesn’t update database rows.	`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` always returns `OK` but doesn’t update database rows.	`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`

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:

Only SQL keys are supported.
Redis commands not listed in this topic aren’t supported.
SET, MSET, HSET, and JSON.SET don’t update True Cache.
True Cache doesn’t maintain a separate Redis key-value cache.
True Cache doesn’t provide the Redis DEFAULT user.
Redis access control lists (ACLs) for keys aren’t supported. Use Oracle AI Database privileges and roles to control access to tables and views.
Oracle True Cache as a Redis server isn’t supported on Oracle Autonomous AI Database Serverless.
The name of a database schema, table, view, or column in a SQL key cannot contain a period, colon, or equal sign.