Oracle True Cache is one of the many exciting features available with Oracle Database 23ai. If you’d like to see how it looks and feels, you can use Oracle Database 23ai Free to give it a go. This post describes how to do exactly that using the following stack:

Let’s get started

The Oracle Database 23ai container image is used to set up a working True Cache system. In the end, there will be 2 instances

  • pri-db-free
  • tru-cc-free

The True Cache setup will happen automagically for you. The primary database instance will be stored on a podman volume. The True Cache instance however requires you to use host volumes.

You will undoubtedly notice the use of rootless Podman. Rootless Podman requires a few extra steps you would not normally need to perform if you used Docker. The rootless nature should add some extra security however and makes it worth your while. A more robust, secure setup is rarely bad.

The --userns=keep-id flag is passed to the podman run command . This way the container inherits the local user’s settings for its volumes (more information). The container expects the volume to be owned by oracle, with a uid of 54321 and a gid of 54321. This is exactly how the host user is configured for this article, as you can see here:

[oracle@devbox testing]$ hostname
    devbox
    
    [oracle@devbox testing]$ id -a
    uid=54321(oracle) gid=54321(dba) groups=54321(dba) context=unconfined_u:unconfined_r:unconfined_t:s0-s0:c0.c1023
    
    [oracle@devbox testing]$ sestatus
    SELinux status:                 enabled
    SELinuxfs mount:                /sys/fs/selinux
    SELinux root directory:         /etc/selinux
    Loaded policy name:             targeted
    Current mode:                   enforcing
    Mode from config file:          enforcing
    Policy MLS status:              enabled
    Policy deny_unknown status:     allowed
    Memory protection checking:     actual (secure)
    Max kernel policy version:      33
    
    [oracle@devbox testing]$ cat /etc/oracle-release 
    Oracle Linux Server release 9.5

SELinux is enabled, again, with the intent of improving the overall security posture. Make sure you uid/gid combination matches, or else the True Cache setup will fail. The article assumes you are logged in as oracle with uid/gid 54321, matching those in the container images.

Auxiliary structures

Before you can start you need to create meet a few additional prerequisites. These include:

  • a Podman volume for the database instance
  • a host directory to store the True Cache instance’s data
  • a network to allow database and True Cache instances to communicate

Note that if you run into trouble, it’s best to start from scratch. At the very least you should consider rename the volume and host directory for a clean start.

The following bash variables have been defined to keep things consistent throughout the article:

DB_DATA_VOL=db-pri-vol
    TC_DATA_DIR=$(pwd)/data/tc
    SECRETS_DIR=$(pwd)/data/secrets
    TC_NETWORK=tc-network
    TAG=23.7.0.0

Creating the podman resources is as simple as executing the following commands:

mkdir -vp "${TC_DATA_DIR}"
    podman network create "${TC_NETWORK}"
    podman volume create "${DB_DATA_VOL}"

Later on you will need to provide IP addresses to the podman run command. Once the network is created you can assign a couple of IP addresses on the network and store them in additional environment variables, like so

DB_IP=$(\
        podman network inspect "${TC_NETWORK}" | \
        jq -r '.[].subnets[0].subnet' | \
        awk -F. '{ $4=100; OFS="."; print $1, $2, $3, $4 }'
    ) 
    TC_IP=$(\
        podman network inspect "${TC_NETWORK}" | \
        jq -r '.[].subnets[0].subnet' | \
        awk -F. '{ $4=200; OFS="."; print $1, $2, $3, $4 }'
    )

Next up yopu need to create the podman secrets as follows. Please don’t change the secret names, the containers expect them to be named oracle_pwd and oracle_pwd_privkey. Unlike regular database operations, these encrypted secrets are mandatory for the use of Oracle’s True Cache container images.

mkdir -vp "${SECRETS_DIR}" && cd "${SECRETS_DIR}"
    openssl genrsa -out key.pem
    openssl rsa -in key.pem -out key.pub -pubout
    read -s -p "enter the password: " pwd
    echo -n $pwd > pwdfile.txt
    openssl pkeyutl -in ./pwdfile.txt -out ./pwdfile.enc -pubin -inkey ./key.pub -encrypt
    
    podman secret create oracle_pwd  ./pwdfile.enc
    podman secret create oracle_pwd_privkey ./key.pem

Both of these secrets will later be used by the containers /opt/oracle/decryptPassword.sh to extract the unencrypted password.

Starting the database instance

With the passwords, network, and volume in place it’s time to start the database instance:

podman run --rm -d --name pri-db-free \
    --hostname pri-db-free \
    --net="${TC_NETWORK}" \
    --ip "${DB_IP}" \
    -p :1521 \
    --secret=oracle_pwd \
    --secret=oracle_pwd_privkey \
    --add-host="tru-cc-free:${TC_IP}" \
    -e ENABLE_ARCHIVELOG=true \
    -e ENABLE_FORCE_LOGGING=true \
    -v "${DB_DATA_VOL}":/opt/oracle/oradata \
    container-registry.oracle.com/database/free:"${TAG}"

After the download completed, it takes about 5-10 seconds to start the database. You can use podman logs pri-db-free to tail the database’s alert.log. Once you see DATABASE OPEN you can proceed with the next step.

Starting the True Cache instance

Start the True Cache instance as follows, adjusting PDB_TC_SVCS as needed. The values provided in PDB_TC_SVCS are used during the container’s bootstrap process to configure the necessary database services. The variable takes a semi-colon separated list of tuples in the form <PDB name>:<primary service name>:<associated True Cache service name>. You can read more about True Cache network configuration in the official documenation.

podman run --rm -d --name tru-cc-free \
    --hostname tru-cc-free \
    --net="${TC_NETWORK}" \
    --ip "${TC_IP}" \
    -p :1521 \
    --secret=oracle_pwd \
    --secret=oracle_pwd_privkey \
    --add-host="pri-db-free:${DB_IP}" \
    -e TRUE_CACHE=true \
    -e PRIMARY_DB_CONN_STR=${DB_IP}:1521/FREE \
    -e PDB_TC_SVCS="FREEPDB1:sales1:sales1_tc;FREEPDB1:sales2:sales2_tc;FREEPDB1:sales3:sales3_tc;FREEPDB1:sales4:sales4_tc" \
    -v ${TC_DATA_DIR}:/opt/oracle/oradata:Z --userns=keep-id \
    container-registry.oracle.com/database/free:"${TAG}"

This command stars the True Cache instance and configures everything automagically. Wait a bit until you see both containers started and healthy:

$ podman ps
    CONTAINER ID  IMAGE                                                 COMMAND               CREATED         STATUS                   PORTS                    NAMES
    8e4e54833991  container-registry.oracle.com/database/free:23.5.0.0  /bin/bash -c $ORA...  49 minutes ago  Up 49 minutes (healthy)  0.0.0.0:36637->1521/tcp  pri-db-free
    1e873dd723a4  container-registry.oracle.com/database/free:23.5.0.0  bash                  49 minutes ago  Up 49 minutes (healthy)  0.0.0.0:38113->1521/tcp  tru-cc-free

Verification

A quick check against the dictionary reveals the working True Cache configuration. Connecting against the True Cache instance you can see that for yourself:

select
      name,
      open_mode,
      database_role,
      controlfile_type
    from
      v$database
    /
     
    NAME      OPEN_MODE            DATABASE_ROLE    CONTROLFIL
    --------- -------------------- ---------------- ----------
    FREE      READ ONLY WITH APPLY TRUE CACHE       TRUE CACHE
     
    select
      true_cache_name,
      primary_name,
      status,
      remote_version
    from
      v$true_cache
    /
     
    TRUE_CACHE_NAME                PRIMARY_NAME    STATUS               REMOTE_VERSION
    ------------------------------ --------------- -------------------- ------------------
    FREE                           FREE            HEALTHY              23.0.0.0.0

Summary

This post describes how to set up True Cache using rootless Podman on Oracle Linux 9.5 x86-64. Please review the licensing guide if you plan to use True Cache and read up on its features in the True Cache User’s Guide.