Use the Autonomous AI Database Free Container Image

Use the Autonomous AI Database Free Container Image to run Autonomous AI Database in a container in your own environment, without requiring access to the Oracle Cloud Infrastructure Console or to the internet.

About the Free Container Image

You can access the Autonomous AI Database Free Container Image from a repository and run it in your local environment.

Autonomous AI Database provides a fully managed Oracle AI Database that is available on Oracle Cloud Infrastructure. On Oracle Cloud Infrastructure, you perform lifecycle management operations and run Autonomous AI Database using the Oracle Cloud Infrastructure Console and you connect to your database through the public internet or through a private network that you set up (depending on your network configuration and security needs).

Note: Autonomous AI Database supports both the Oracle Autonomous AI Database Free Container Image 19c and Oracle Autonomous AI Database Free Container Image 26ai versions.

The Autonomous AI Database Free Container Image provides an alternative to run Autonomous AI Database in a container in your own environment, without requiring access to Oracle Cloud Infrastructure Console or to the internet. When you run Autonomous AI Database in a container, the container provides a local, isolated environment with additional options for development, testing, and exploration of Oracle Autonomous AI Database features.

Autonomous AI Database Free Container Image License

Describes licensing for Autonomous AI Database Free Container Image.

Autonomous AI Database Free Container Image is subject to licensing.

The container image you have selected and all of the software that it contains is licensed under Oracle Free Use Terms and Conditions that are provided in the container image. Your use of the container is subject to the terms of those licenses.

Autonomous AI Database Free Container Image Features

The Autonomous AI Database Free Container Image provides many of the features available with Autonomous AI Database Serverless.

Each Free Container Image provides two Autonomous AI Database instances, one instance with Lakehouse workload type and one instance with Transaction Processing workload type.
The database will be started with either the Transaction Processing workload type or the Lakehouse workload type based on the workload type you specify during startup.
You can perform database operations using the adb-cli command-line utility.
The Free Container Image resource allocation is 4 ECPUs and 20 GB of storage, and allows a maximum of 30 simultaneous database sessions.
Each Free Container Image supports the Autonomous AI Database consumer groups:
- Lakehouse workload: You connect through HIGH, MEDIUM, or LOW services
- Transaction Processing workload: You connect through HIGH, MEDIUM, LOW, TP, or TPURGENT services
See About Autonomous AI Database Workload Types for more information.
The Free Container Image provides support for the following built-in database tools:
- Database Actions
- Oracle REST Data Services (ORDS)
- Oracle APEX
- Oracle AI Database API for MongoDB

Autonomous AI Database Free Container Image Recommendations and Restrictions

Describes requirements and restrictions for Free Container Image.

Recommendations for Resource Allocation for the Free Container Image

The following is the recommended resource allocation for the Free Container Image:

4 CPUs
8 GB memory

Restrictions for Free Container Image

There is no automatic patching or maintenance windows for the Free Container Image. The repository provides the latest version of the Free Container Image. Check the repository to find newer versions of Free Container Image.
The following Autonomous AI Database built-in tools are not supported:
- Graph
- Oracle Machine Learning
- Data Transforms

When Autonomous AI Database runs in a container, the container provides a local Autonomous AI Database instance. The container image does not include the features that are only available through the Oracle Cloud Infrastructure Console or the APIs. Some features that are available in-database and also available through the Oracle Cloud Infrastructure Console can still be used through in-database commands, such as resetting the ADMIN password. The following lists some of the features that are not available:

Feature	Available or Not Available
Backup an Instance	Not available
Choose a Character Set	Not available
Clone an Instance	Not available
Create an Elastic Pool	Not available
Customer-managed keys	Not available
Database rename	Not available
Data Safe	Not available
Disable compute auto scaling	Not available
Disable Built-in Database Tools	Not available
Disable storage auto scaling	Not available
Disaster recovery options, including Autonomous Data Guard and Backup-Based Disaster Recovery.	Not available
Download wallet	Not available
Enable Built-in Database Tools	Not available
Enable compute auto scaling	Not available
Enable storage auto scaling	Not available
Join an Elastic Pool	Not available
Network ACLs	Not available
Oracle Cloud Infrastructure events	Not available
Performance hub	Not available
Private endpoints	Not available
Real Application Testing	Not available
Resource Principal based authentication	Not available
Restart Instance	Not available
Restore an Instance	Not available
Rotate wallet	Not available
Sample Schema	Not available
Scale down CPU and storage	Not available
Scale up CPU and storage	Not available
Selecting the Instance Patch Level	Not available
Start Instance	Not available
Stop Instance	Not available

Note: When you run Free Container Image in a container, you can start an instance, stop an instance, or restart an instance by starting, stopping or restarting the container.

Container Registry Locations for Autonomous AI Database Free Container Image

There are multiple locations where you can obtain Autonomous AI Database Free Container Image, including: Oracle Cloud Infrastructure Registry (Container Registry) and GitHub.

You can obtain the Autonomous AI Database Free Container Image in multiple locations. The examples shown use podman commands (see Podman for more information).

Start a podman virtual machine.

For example:

podman machine init
podman machine set --cpus 4 --memory 8192
podman machine start

Obtain the Free Container Image.

Oracle Cloud Infrastructure Registry:

For example, use podman command to pull the latest Free Container Image image:
```
podman pull container-registry.oracle.com/database/adb-free:latest-23ai
```
Note:

Oracle Autonomous AI Database Serverless also supports 19c container images.
- For 19c container image names, specify latest tag as your database version.
- In the above example, to pull the Autonomous AI Database Free Container Image 19c , use the following command in the image name tag:
```
podman pull container-registry.oracle.com/database/adb-free:latest
```
Throughout the document, the image name tag refers to the latest-23ai version.
For more details and additional information, search for “Oracle Autonomous AI Database Free” on Oracle Cloud Infrastructure Registry.

GitHub Packages:

For example, use podman command to pull the Free Container Image from: GitHub Packages:
```
podman pull ghcr.io/oracle/adb-free:latest-23ai
```

Verify the image.

For example:

podman images container-registry.oracle.com/database/adb-free:latest-23ai

Start Free Container Image

After you download Autonomous AI Database Free Container Image, you can start the image in a container.

The database will be started with either the Transaction Processing workload type or the Lakehouse workload type based on the workload type you specify.

Start a container to run Free Container Image.

For example, with podman:

podman run -d \

-p 1521:1522 \

-p 1522:1522 \

-p 8443:8443 \

-p 27017:27017 \

-e WORKLOAD_TYPE='ATP' \

-e WALLET_PASSWORD=*** \

-e ADMIN_PASSWORD=*** \

--cap-add SYS_ADMIN \

--device /dev/fuse \

--name adb-free \
container-registry.oracle.com/database/adb-free:latest-23ai

Command notes:

Autonomous AI Database Serverless also supports 19c container images.
- For 19c container image names, specify latest tag as your database version.
- In the above example, to start a container to run the Autonomous AI Database Free Container Image 19c, use the following command in the image name tag:
```
container-registry.oracle.com/database/adb-free:**latest**
```
Throughout the document, the image name tag refers to the latest-23ai version.
The WORKLOAD_TYPE can be either ATP or ADW. The default value is ATP.
By default, the database is named either MYATP or MYADW, depending on the passed WORKLOAD_TYPE value. Optionally, if you want a different database name than the default, you can set the DATABASE_NAME parameter. The database name can contain only alphanumeric characters.
On container startup, the corresponding MY<WORKLOAD_TYPE>.pdb is downloaded and plugged in from a public Object Storage bucket.
The wallet is generated using the provided WALLET_PASSWORD.
It is necessary to change the ADMIN_PASSWORD upon initial login.
Ensure you check the following requirements when you create or modify the ADMIN_PASSWORD:
- The password must be between 12 and 30 characters long and must include at least one uppercase letter, one lowercase letter, and one numeric character.
- The password cannot contain the username.
Ensure you check the following requirements when you create or modify the WALLET_PASSWORD:
- The password must be between 8 and 30 characters long and include alphabetic characters combined with numeric characters or special characters.
For an OFS mount, the container starts with SYS_ADMIN capability. Also, virtual device /dev/fuse must be accessible.

This -p options specify that the following ports are forwarded to the container process:

Port	Description
1521	TLS
1522	mTLS
8443	HTTPS port for ORDS / APEX and Database Actions
27017	Mongo API

If you are behind a corporate proxy, include -e options to specify environment variables for proxies. For example, with podman:

podman run -d \

-p 1521:1522 \

-p 1522:1522 \

-p 8443:8443 \

-p 27017:27017 \

-e WORKLOAD_TYPE='ATP' \

-e WALLET_PASSWORD=*** \

-e ADMIN_PASSWORD=*** \

-e http_proxy=http://*example-corp-proxy.com*:80/ \

-e https_proxy=http://*example-corp-proxy.com*:80/ \

-e no_proxy=localhost,127.0.0.1 \

-e HTTP_PROXY=http://*example-corp-proxy.com*:80/  \

-e HTTPS_PROXY=http://*example-corp-proxy.com*:80/  \

-e NO_PROXY=localhost,127.0.0.1 \

--cap-add SYS_ADMIN \

--device /dev/fuse \

--name adb-free \
container-registry.oracle.com/database/adb-free:latest-23ai

Perform Database Operations using adb-cli

The adb-cli command-line utility can be used to perform database operations after the container is up and running.

To use adb-cli, you can define the following alias for convenience:

alias adb-cli="podman exec <container_name> adb-cli"

Available Commands

You can view the list of available commands using the following command:

adb-cli --help
Usage: adb-cli [OPTIONS] COMMAND [ARGS]...
    ADB-S Command Line Interface (CLI) to perform container-runtime database operations
Options:
    -v, --version Show the version and exit.
    --help Show this message and exit.
Commands:
    add-database
    change-password

Add Database: You can add a database using the following command:

adb-cli add-database --workload-type "ATP" --admin-password "Welcome_MY_ATP_1234"

Change Password: You can change the admin password using the following command:

adb-cli change-password --database-name "MYATP"
    --old-password "Welcome_MY_ATP_1234" --new-password "Welcome_12345"

Connect to an Free Container Image

When the Free Container Image is running in a container, you can connect to an Autonomous AI Database instance.

To connect to an Autonomous AI Database instance running in a container, you can either setup the wallet and connect or use a TLS walletless connection.

Connect to ORDS, APEX, or Database Actions from an Autonomous AI Database Container Image

The container hostname is used to generate self-signed SSL certificates to serve HTTPS traffic on port 8443. Oracle APEX and Database Actions can be accessed using the container host (or simply localhost).

Application	URL
Oracle APEX	https://localhost:8443/ords/apex
Database Actions	https://localhost:8443/ords/sql-developer

Note: For additional databases plugged in using adb-cli add-database command, use the URL formats https://localhost:8443/ords/{database_name}/apex and https://localhost:8443/ords/{database_name}/sql-developer to access APEX and Database Actions respectively.

Available TNS Aliases for Connecting to an Autonomous AI Database Container Image

You can use any one of the following aliases to connect to an Autonomous AI Database Container Image.

Protocol	Transaction Processing Workload	Lakehouse Workload
mTLS	myatp_medium myatp_high myatp_low myatp_tp myatp_tpurgent	myadw_medium myadw_high myadw_low
TLS	myatp_medium_tls myatp_high_tls myatp_low_tls myatp_tp_tls myatp_tpurgent_tls	myadw_medium_tls myadw_high_tls myadw_low_tls

The TNS alias mappings for these connect strings are in $TNS_ADMIN/tnsnames.ora. See Manage Concurrency and Priorities on Autonomous AI Database for information on the service names in tnsnames.ora.

Connect to an Autonomous AI Database Container Image with a Wallet

Describes the steps to connect to an Autonomous AI Database container image with a Wallet.

Perform the following steps to setup a wallet and connect:

Copy the generated wallet to your host.

When you start the container, Autonomous AI Database generates a wallet in /u01/app/oracle/wallets/tls_wallet.

For example, copy the generated wallet to the local folder /scratch/tls_wallet:
```
podman cp adb-free:/u01/app/oracle/wallets/tls_wallet /scratch/tls_wallet
```
This copies the wallet to the folder: /scratch/tls_wallet.
Set the value of the TNS_ADMIN environment variable to the wallet directory.

For example:
```
export TNS_ADMIN=/scratch/tls_wallet
```
If you want to connect to a remote host where the Free Container Image is running, replace localhost in $TNS_ADMIN/tnsnames.ora with the remote host FQDN.

For example:
```
sed -i 's/localhost/example.com/g' $TNS_ADMIN/tnsnames.ora
```
Connect to the Autonomous AI Database instance.

For example use sqlplus to connect to the Transaction Processing workload Autonomous AI Database instance:
```
sqlplus admin/password@myatp_low_tls
```
For example, use sqlplus to connect to the Lakehouse workload Autonomous AI Database instance:
```
sqlplus admin/password@myadw_low_tls
```

Connect to an Autonomous AI Database Container Image without a Wallet (TLS)

Describes the steps to connect to an Autonomous AI Database container image without a Wallet (TLS).

To connect without a wallet, you need to update your client’s truststore with the self-signed certificate generated at container start.

Perform the following steps to setup a TLS connection and connect.

Copy /u01/app/oracle/wallets/tls_wallet/adb_container.cert from the container and update your system truststore.

For example:

podman cp adb-free:/u01/app/oracle/wallets/tls_wallet/adb_container.cert adb_container.cert
sudo cp adb_container.cert /etc/pki/ca-trust/source/anchors
sudo update-ca-trust

Connect to the Autonomous AI Database instance.

For example, use sqlplus to connect to the Transaction Processing workload Autonomous AI Database instance:
```
sqlplus admin/password@myatp_low
```
For example, use sqlplus to connect to the Data Warehouse workload Autonomous AI Database instance:
```
sqlplus admin/password@myadw_low
```

Migrate Data Between Autonomous AI Database Free Containers

When a new version of the Free Container Image is available, you can migrate data from a container to another container.

For example, use existing data that you created in a container by migrating that data to the latest version of Free Container Image when a new update is available.

Create a podman volume.

For example:

podman volume create adb_container_volume

Verify the volume mountpoint.

The mountpoint is a podman managed directory location.

podman inspect adb_container_volume

[
     {
          "Name": "adb_container_volume",
          "Driver": "local",
          "Mountpoint": "/share/containers/storage/volumes/adb_container_volume/_data",
          "CreatedAt": "2023-09-11T21:23:34.305877073Z",
          "Labels": {},
          "Scope": "local",
          "Options": {},
          "MountCount": 0,
          "NeedsCopyUp": true,
          "NeedsChown": true
     }
]

Start the source container, mounting the volume to /u01/data in the container.

For example:
```
podman run -d \

-p 1521:1522 \

-p 1522:1522 \

-p 8443:8443 \

-p 27017:27017 \

-e WORKLOAD_TYPE='ATP' \

-e WALLET_PASSWORD=*** \

-e ADMIN_PASSWORD=*** \

--cap-add SYS_ADMIN \

--device /dev/fuse \

--name source_adb_container \

--volume adb_container_volume:/u01/data \
container-registry.oracle.com/database/adb-free:latest-23ai
```
Note:

Autonomous AI Database Serverless also supports 19c container images.
- For 19c container image names, specify latest tag as your database version.
- In the above example, to start the Autonomous AI Database Free Container Image 19c , use the following command in the image name tag:
```
container-registry.oracle.com/database/adb-free:latest
```
Throughout the document, the image name tag refers to the latest-23ai version.
This example assumes you have previously created your data in schema, app_user.

Export the data from app_user's schema to the container volume.

Connect as ADMIN and create ORA_EXP_DIR directory pointing to /u01/data.

sqlplus admin/**************@myadw_high

SQL> exec DBMS_CLOUD_CONTAINER_ADMIN.create_export_directory('/u01/data');

SQL> select directory_path from dba_directories where directory_name='ORA_EXP_DIR';

DIRECTORY_PATH

--------------------------------------------------------------------------------
/u01/data

Run the export job in schema mode and for both ADMIN and APP_USER schemas.

SET scan off
SET serveroutput ON
SET escape off

DECLARE
    h1 NUMBER;
    s VARCHAR2(1000):=NULL;
    errorvarchar VARCHAR2(100):= 'ERROR';
    tryGetStatus NUMBER := 0;
    success_with_info EXCEPTION;
    PRAGMA EXCEPTION_INIT(success_with_info, -31627);
BEGIN
    h1 := dbms_datapump.OPEN(operation => 'EXPORT', job_mode => 'SCHEMA', job_name => 'EXPORT_MY_ADW_4', version => 'COMPATIBLE');
    tryGetStatus := 1;
    dbms_datapump.add_file(handle => h1, filename => 'EXPORT_MY_ADW.LOG', directory => 'ORA_EXP_DIR', filetype => DBMS_DATAPUMP.KU$_FILE_TYPE_LOG_FILE);
    dbms_datapump.metadata_filter(handle => h1, name => 'SCHEMA_EXPR', VALUE => 'IN(''ADMIN'', ''APP_USER'')');
    dbms_datapump.add_file(handle => h1, filename => 'MY_ADW_%L.DMP', directory => 'ORA_EXP_DIR', filesize => '500M',  filetype => DBMS_DATAPUMP.KU$_FILE_TYPE_DUMP_FILE);
    dbms_datapump.start_job(handle => h1, skip_current => 0, abort_step => 0);
    dbms_datapump.detach(handle => h1);
    errorvarchar := 'NO_ERROR';
EXCEPTION
    WHEN OTHERS THEN
    BEGIN
        IF ((errorvarchar = 'ERROR')AND(tryGetStatus=1)) THEN
            DBMS_DATAPUMP.DETACH(h1);
        END IF;
    EXCEPTION
    WHEN OTHERS THEN
        NULL;
    END;
    RAISE;
END;
/

Verify the export.

List the files in the container /u01/data.
```
podman exec -it source_adb_container bash
cd /u01/data
```
Verify the export log (export log), check for any errors and successful completion.
Stop and remove the source container.
```
podman stop source_adb_container
podman rm source_adb_container
```
Note: The adb_container_volume will live across container restarts and removals.

Start a destination container mounting the same volume to /u01/data in the container.

podman run -d \

-p 1521:1522 \

-p 1522:1522 \

-p 8443:8443 \

-p 27017:27017 \

-e WORKLOAD_TYPE='ATP' \

-e WALLET_PASSWORD=*** \

-e ADMIN_PASSWORD=*** \

--cap-add SYS_ADMIN \

--device /dev/fuse \

--name dest_adb_container \

--volume adb_container_volume:/u01/data \
container-registry.oracle.com/database/adb-free:latest-23ai

Import data in destination container.

Connect as ADMIN and create ORA_EXP_DIR directory pointing to/u01/data.

SQL> exec DBMS_CLOUD_CONTAINER_ADMIN.create_export_directory('/u01/data');

PL/SQL procedure successfully completed.

SQL> select directory_path from dba_directories where directory_name='ORA_EXP_DIR';

DIRECTORY_PATH

--------------------------------------------------------------------------------
/u01/data

Run the import PL/SQL commands.

SET scan off
SET serveroutput ON
SET escape off

DECLARE
    h1 NUMBER;
    s VARCHAR2(1000):=NULL;
    errorvarchar VARCHAR2(100):= 'ERROR';
    tryGetStatus NUMBER := 0;
    success_with_info EXCEPTION;
    PRAGMA EXCEPTION_INIT(success_with_info, -31627);
BEGIN
    h1 := dbms_datapump.OPEN(operation => 'IMPORT', job_mode => 'SCHEMA', job_name => 'IMPORT_MY_ADW_4', version => 'COMPATIBLE');
    tryGetStatus := 1;
    dbms_datapump.add_file(handle => h1, filename => 'IMPORT_MY_ADW.LOG', directory => 'ORA_EXP_DIR', filetype => DBMS_DATAPUMP.KU$_FILE_TYPE_LOG_FILE);
    dbms_datapump.metadata_filter(handle => h1, name => 'SCHEMA_EXPR', VALUE => 'IN(''ADMIN'', ''APP_USER'')');
    dbms_datapump.add_file(handle => h1, filename => 'MY_ADW_%L.DMP', directory => 'ORA_EXP_DIR', filesize => '500M',  filetype => DBMS_DATAPUMP.KU$_FILE_TYPE_DUMP_FILE);
    dbms_datapump.start_job(handle => h1, skip_current => 0, abort_step => 0);
    dbms_datapump.detach(handle => h1);
    errorvarchar := 'NO_ERROR';
EXCEPTION
    WHEN OTHERS THEN
    BEGIN
        IF ((errorvarchar = 'ERROR')AND(tryGetStatus=1)) THEN
            DBMS_DATAPUMP.DETACH(h1);
        END IF;
    EXCEPTION
    WHEN OTHERS THEN
        NULL;
    END;
    RAISE;
END;
/

Verify the import log.
Verify the import data.