Oracle AI Database

The Oracle AI Database sits at the core of the AI Optimizer. It is used for application persistence (settings, test sets, evaluations), storing embeddings for Vector Search and querying structured data via NL2SQL.

Reduced capabilities

The AI Optimizer can be used to interact with language models without having the database configured, but additional functionality such as RAG and NL2SQL, will not be available without the database.

Database Configuration

You can configure the connection to an Oracle AI Database in the client page or by setting environment variables. The AI Optimizer supports multiple database connections, but only one can be active at a time.

Run Local Oracle AI Database Free

Provisioning an on-premises database or an Oracle Cloud database is outside the scope of this guide.

For a local development environment, you can run Oracle AI Database Free in a container:

1. Start the database container:

   podman run -d --name ai-optimizer-db -p 1521:1521 container-registry.oracle.com/database/free:latest-lite

2. Wait until the database is ready:

   Linux/macOS

   until podman logs ai-optimizer-db 2>&1 | grep -q 'DATABASE IS READY TO USE!'; do sleep 5; done

   PowerShell

   while (-not (podman logs ai-optimizer-db 2>&1 | Select-String -Quiet 'DATABASE IS READY TO USE!')) { Start-Sleep -Seconds 5 }

3. Set vector_memory_size:

   podman exec -it ai-optimizer-db sqlplus '/ as sysdba'

   ALTER SYSTEM SET vector_memory_size=512M SCOPE=spfile;
   EXIT;

4. Restart the database and wait for a new ready message:

   Linux/macOS

   ready_lines=$(podman logs ai-optimizer-db 2>&1 | grep -c 'DATABASE IS READY TO USE!' || true)
   podman container restart ai-optimizer-db
   until [ "$(podman logs ai-optimizer-db 2>&1 | grep -c 'DATABASE IS READY TO USE!')" -gt "$ready_lines" ]; do sleep 5; done

   PowerShell

   $readyLines = @(podman logs ai-optimizer-db 2>&1 | Select-String 'DATABASE IS READY TO USE!').Count
   podman container restart ai-optimizer-db
   while (@(podman logs ai-optimizer-db 2>&1 | Select-String 'DATABASE IS READY TO USE!').Count -le $readyLines) { Start-Sleep -Seconds 5 }

After the database is ready, create a database user as described in Database User. When configuring the AI Optimizer on the same host, use //localhost:1521/FREEPDB1 as the connect string.

Using a Wallet/TNS_ADMIN

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

Great things come from unzipped files

If using an ADB-S wallet, unzip its contents into the TNS_ADMIN directory. The .zip file is not 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, mount the TNS_ADMIN directory at /app/tns_admin.

For example:

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

Database User

For both RAG and NL2SQL, the AI Optimizer needs to authenticate to an Oracle AI Database. AI agents use this user to retrieve data, so carefully consider the access granted to it. Use a non-privileged user with a non-SYSTEM tablespace.

For Oracle AI Database Free running in a container, connect as a privileged user and select the pluggable database:

podman exec -it ai-optimizer-db sqlplus '/ as sysdba'

ALTER SESSION SET CONTAINER=FREEPDB1;

Use the following local-development example to create a database user. It grants DB_DEVELOPER_ROLE and an unlimited quota on the default permanent tablespace. For other environments, grant only the privileges and quota required for the intended use. Change the value of c_user_password:

DECLARE
    c_user_name     CONSTANT VARCHAR2(30) := 'DEMO';
    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
    SELECT property_value
    INTO v_default_perm
    FROM database_properties
    WHERE property_name = 'DEFAULT_PERMANENT_TABLESPACE';

    SELECT property_value
    INTO v_default_temp
    FROM database_properties
    WHERE property_name = 'DEFAULT_TEMP_TABLESPACE';

    v_sql := 'CREATE USER ' || DBMS_ASSERT.ENQUOTE_NAME(c_user_name, FALSE) ||
            ' IDENTIFIED BY "' || c_user_password || '" ' ||
            'DEFAULT TABLESPACE ' || v_default_perm || ' ' ||
            'TEMPORARY TABLESPACE ' || v_default_temp;
    EXECUTE IMMEDIATE v_sql;

    EXECUTE IMMEDIATE 'GRANT DB_DEVELOPER_ROLE TO ' ||
        DBMS_ASSERT.ENQUOTE_NAME(c_user_name, FALSE);
    EXECUTE IMMEDIATE 'ALTER USER ' ||
        DBMS_ASSERT.ENQUOTE_NAME(c_user_name, FALSE) || ' DEFAULT ROLE ALL';
    EXECUTE IMMEDIATE 'ALTER USER ' ||
        DBMS_ASSERT.ENQUOTE_NAME(c_user_name, FALSE) || ' QUOTA UNLIMITED ON ' ||
        DBMS_ASSERT.ENQUOTE_NAME(v_default_perm, FALSE);
END;
/
EXIT;

One schema fits none...

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

Deep Data Security Privileges

To use all Deep Data Security management actions, grant the following privileges to the configured database user. Replace <DATABASE_USER> with that username. The privileges are optional: unsupported databases show an availability warning, and a missing privilege disables only its related action.

GRANT CREATE DATA ROLE TO "<DATABASE_USER>";
GRANT DROP DATA ROLE TO "<DATABASE_USER>";
GRANT CREATE END USER TO "<DATABASE_USER>";
GRANT DROP END USER TO "<DATABASE_USER>";
GRANT CREATE DATA GRANT TO "<DATABASE_USER>";
GRANT CREATE END USER CONTEXT TO "<DATABASE_USER>";
GRANT CREATE END USER SECURITY CONTEXT TO "<DATABASE_USER>";
GRANT ADMINISTER ANY DATA GRANT TO "<DATABASE_USER>";
GRANT GRANT ANY DATA ROLE TO "<DATABASE_USER>";
-- Read access so the tool can list data roles, role grants, and end users
GRANT SELECT ON DBA_DATA_ROLES TO "<DATABASE_USER>";
GRANT SELECT ON DBA_DATA_ROLE_GRANTS TO "<DATABASE_USER>";
GRANT SELECT ON DBA_END_USERS TO "<DATABASE_USER>";

To let Vector Search and NL2SQL connect as a Deep Data Security end user, the end user must be able to log in. CREATE SESSION cannot be granted directly to an end user; a standard database role carries it through a data role. As a privileged user, create that role once and let <DATABASE_USER> grant it:

CREATE ROLE AIO_DDS_ROLE;
GRANT CREATE SESSION TO AIO_DDS_ROLE;
GRANT AIO_DDS_ROLE TO "<DATABASE_USER>" WITH ADMIN OPTION;

The tool grants AIO_DDS_ROLE to each locally managed data role it creates, so an end user assigned that data role can be connected as.