1. Using Oracle Autonomous Database Serverless
  2. Tasks
  3. Use the Oracle Autonomous Database Free Container Image

Use the Oracle Autonomous Database Free Container Image

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

Parent topic: Tasks

About the Autonomous Database Free Container Image

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

Autonomous Database provides a fully managed Oracle Database that is available on Oracle Cloud Infrastructure. On Oracle Cloud Infrastructure, you perform lifecycle management operations and run Autonomous 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 Database supports both the Oracle Autonomous Database Free Container Image 19c and Oracle Autonomous Database Free Container Image 23ai versions.

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

Parent topic: Use the Oracle Autonomous Database Free Container Image

Oracle Autonomous Database Free Container Image License

Describes licensing for Oracle Autonomous Database Free Container Image.

Oracle Autonomous Database Free Container Image is subject to licensing.

This Licensing Information document is specifically for the Oracle Database in Oracle Autonomous Database Free Container Image. This document is a part of the product or program documentation under the terms of your Oracle license agreement and is intended to help you understand the program editions, entitlements, restrictions, prerequisites, special license rights, and/or separately licensed third party technology terms associated with the Oracle software program(s) covered by this document (the "Program(s)"). Information for other Oracle Database editions (such as Enterprise Edition) will be added to this document once they are released. Entitled or restricted use products or components identified in this document that are not provided with the particular Program may be obtained from the Oracle Software Delivery Cloud website (https://edelivery.oracle.com) or from media Oracle may provide. If you have a question about your license rights and obligations, please contact your Oracle sales representative, review the information provided in Oracle’s Software Investment Guide (http://www.oracle.com/us/corporate/pricing/software-investment-guide/index.html), and/or contact the applicable Oracle License Management Services representative listed on http://www.oracle.com/us/corporate/license-management-services/index.html.

See Database Licensing Information User Manual for more information.

Parent topic: About the Autonomous Database Free Container Image

Oracle Autonomous Database Free Container Image Features

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

  • Each Autonomous Database Free Container Image provides two Autonomous Database instances, one instance with Data Warehouse workload type and one instance with Transaction Processing workload type.

  • The database will be started with either the Transaction Processing workload type or the Data Warehouse workload type based on the workload type you specify during startup.

  • You can perform database operations using the adb-cli command-line utility.

  • The Autonomous Database Free Container Image resource allocation is 4 ECPUs and 20 GB of storage, and allows a maximum of 30 simultaneous database sessions.

  • Each Autonomous Database Free Container Image supports the Autonomous Database consumer groups:

    • Data Warehouse 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 Database Workload Types for more information.

  • The Autonomous Database Free Container Image provides support for the following built-in database tools:

    • Database Actions

    • Oracle REST Data Services (ORDS)

    • Oracle APEX

    • Oracle Database API for MongoDB

Parent topic: About the Autonomous Database Free Container Image

Oracle Autonomous Database Free Container Image Recommendations and Restrictions

Describes requirements and restrictions for Autonomous Database Free Container Image.

Recommendations for Resource Allocation for the Autonomous Database Free Container Image

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

  • 4 CPUs

  • 8 GB memory

Restrictions for Autonomous Database Free Container Image

  • There is no automatic patching or maintenance windows for the Autonomous Database Free Container Image. The repository provides the latest version of the Autonomous Database Free Container Image. Check the repository to find newer versions of Autonomous Database Free Container Image.

  • The following Autonomous Database built-in tools are not supported:

    • Graph
    • Oracle Machine Learning
    • Data Transforms

  • When Autonomous Database runs in a container, the container provides a local Autonomous 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 Autonomous Database 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.

Parent topic: About the Autonomous Database Free Container Image

Container Registry Locations for Oracle Autonomous Database Free Container Image

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

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

  1. Start a podman virtual machine.
    For example:
    podman machine init 
podman machine set --cpus 4 --memory 8192 
podman machine start
  2. Obtain the Autonomous Database Free Container Image.

    Oracle Cloud Infrastructure Registry:

    For example, use podman command to pull the latest Autonomous Database Free Container Image image: 

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

    Note:

    Autonomous Database Serverless (ADB- S) 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 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 Database Free" on Oracle Cloud Infrastructure Registry.

    GitHub Packages:

    For example, use podman command to pull the Autonomous Database Free Container Image from: GitHub Packages: 

    podman pull ghcr.io/oracle/adb-free:latest-23ai
  3. Verify the image.

    For example:

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

Parent topic: Use the Oracle Autonomous Database Free Container Image

Start Autonomous Database Free Container Image

After you download Oracle Autonomous 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 Data Warehouse workload type based on the workload type you specify.

  1. Start a container to run Autonomous Database 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 Database Serverless (ADB- S) 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 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

Parent topic: Use the Oracle Autonomous Database Free Container Image

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"

Parent topic: Use the Oracle Autonomous Database Free Container Image

Connect to an Autonomous Database Free Container Image

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

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

Parent topic: Use the Oracle Autonomous Database Free Container Image

ORDS/APEX/Database Actions

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.

Parent topic: Connect to an Autonomous Database Free Container Image

Available TNS Aliases

You can use any one of the following aliases to connect to Autonomous Database free container.

Table 3-5 Available TNS Aliases

Protocol Transaction Processing Workload Data Warehouse 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 Database for information on the service names in tnsnames.ora.

Parent topic: Connect to an Autonomous Database Free Container Image

Setup a Wallet and Connect

Perform the following steps to setup a wallet and connect:

  1. Copy the generated wallet to your host.

    When you start the container, Autonomous 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.

  2. Set the value of the TNS_ADMIN environment variable to the wallet directory.

    For example:

    export TNS_ADMIN=/scratch/tls_wallet
  3. If you want to connect to a remote host where the Autonomous Database 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
  4. Connect to the Autonomous Database instance.

    For example use sqlplus to connect to the Transaction Processing workload Autonomous Database instance: 

    sqlplus admin/password@myatp_low_tls

    For example, use sqlplus to connect to the Data Warehouse workload Autonomous Database instance: 

    sqlplus admin/password@myadw_low_tls

Parent topic: Connect to an Autonomous Database Free Container Image

Setup TLS Walletless Connection and Connect

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 walletless connection and connect.

  1. 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
  2. Connect to the Autonomous Database instance.

    For example, use sqlplus to connect to the Transaction Processing workload Autonomous Database instance: 

    sqlplus admin/password@myatp_low

    For example, use sqlplus to connect to the Data Warehouse workload Autonomous Database instance: 

    sqlplus admin/password@myadw_low

Parent topic: Connect to an Autonomous Database Free Container Image

Migrate Data Between Autonomous Database Free Containers

When a new version of the Autonomous Database 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 Autonomous Database Free Container Image when a new update is available.

  1. Create a podman volume.

    For example:

    podman volume create adb_container_volume
  2. 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
     }
]
  3. 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 Database Serverless (ADB- S) 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 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.

  4. This example assumes you have previously created your data in schema, app_user.
  5. Export the data from app_user's schema to the container volume.
    1. 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
    2. 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_%U.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;
/
  6. 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.

  7. 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
  8. 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
  9. 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
  10. 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_%U.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;
/
  11. Verify the import log.
  12. Verify the import data.

Parent topic: Use the Oracle Autonomous Database Free Container Image