๐Ÿ—„๏ธ Database Configuration

To use the Retrieval-Augmented Generation (RAG) functionality of the AI Optimizer, you will need to setup/enable an embedding model and have access to an Oracle Database 23ai. Both the Always Free Oracle Autonomous Database Serverless (ADB-S) and the Oracle Database 23ai Free are supported. They are a great, no-cost, way to get up and running quickly.

Configuration

The database can either be configured through the AI Optimizer interface or by using environment variables.


Interface

To configure the Database from the AI Optimizer, navigate to Configuration -> Database:

Database Config Database Config

Provide the following input:

  • DB Username: The pre-created database username where the embeddings will be stored
  • DB Password: The password for the DB Username
  • Database Connect String: The full connection string or TNS Alias for the Database. This is normally in the form of (DESCRIPTION=(ADDRESS=(PROTOCOL=tcp)(HOST=<hostname>)(PORT=<port>))(CONNECT_DATA=(SERVICE_NAME=<service_name>))) or //<hostname>:<port>/<service_name>
  • Wallet Password (Optional): If the connection to the database uses mTLS, provide the wallet password. Review Using a Wallet for additional setup instructions.

Once all fields are set, click the Save button.


Environment Variables

The following environment variables can be set, prior to starting the AI Optimizer, to automatically configure the database:

  • DB_USERNAME: The pre-created database username where the embeddings will be stored
  • DB_PASSWORD: The password for the DB Username
  • DB_DSN: The connection string or TNS Alias for the Database. This is normally in the form of (description=... (service_name=<service_name>)) or //host:port/service_name.
  • DB_WALLET_PASSWORD (Optional): If the connection to the database uses mTLS, provide the wallet password. Review Using a Wallet for additional setup instructions.

For Example:

export DB_USERNAME="DEMO"
export DB_PASSWORD=MYCOMPLEXSECRET
export DB_DSN="//localhost:1521/OPTIMIZER"
export DB_WALLET_PASSWORD=MYCOMPLEXWALLETSECRET

Using a Wallet/TNS_ADMIN Directory

For mTLS database connectivity or, if you prefer to specify a TNS alias instead of a full connect string, you can use the contents of a TNS_ADMIN directory.

Great things come from unzipped files.

If using and ADB-S wallet, unzip the contents into the TNS_ADMIN directory. The .zip file will not be recognized.

Bare-Metal

For bare-metal installations, set the TNS_ADMIN environment variable to the location of your unzipped wallet files before starting the AI Optimizer.

Container

When starting the container, volume mount the configuration file to /app/tns_admin for it to be used.

For example:

podman run -v $TNS_ADMIN$:/app/tns_admin -p 8501:8501 -it --rm ai-optimizer-aio

Database User

A database user is required to store the embeddings, used for RAG, into the Oracle Database. A non-privileged user with a non-SYSTEM tablespace should be used for this purpose. Use the below syntax as an example of creating a new user with least privileges (change the value of c_user_password):

DECLARE
    c_user_password dba_users.password%TYPE := 'MYSUPERSECRET';
    v_default_perm  database_properties.property_value%TYPE;
    v_default_temp  database_properties.property_value%TYPE;
    v_sql           VARCHAR2(500);
BEGIN    
    -- Get default permanent tablespace
    SELECT property_value 
      INTO v_default_perm
      FROM database_properties 
     WHERE property_name = 'DEFAULT_PERMANENT_TABLESPACE';

    -- Get default temporary tablespace
    SELECT property_value 
      INTO v_default_temp
      FROM database_properties 
     WHERE property_name = 'DEFAULT_TEMP_TABLESPACE';

    -- Build dynamic CREATE USER statement
    v_sql := 'CREATE USER demo IDENTIFIED BY "' || c_user_password || '" ' ||
             'DEFAULT TABLESPACE ' || v_default_perm || ' ' ||
             'TEMPORARY TABLESPACE ' || v_default_temp;
    EXECUTE IMMEDIATE v_sql;
END;
/
GRANT "DB_DEVELOPER_ROLE" TO "DEMO";
ALTER USER "DEMO" DEFAULT ROLE ALL;
ALTER USER "DEMO" QUOTA UNLIMITED ON DATA;

If running on a supported database for SelectAI and want to use the feature, grant the following additional privileges and open appropriate ACLs:

GRANT EXECUTE ON DBMS_CLOUD_AI TO DEMO;
GRANT EXECUTE ON DBMS_CLOUD_PIPELINE TO DEMO;
One schema fits none…

Creating multiple users in the same database allows developers to separate their experiments simply by changing the “Database User”