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).

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 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 a Resource 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 a Resource 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 rung 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 in mulitple locations. The examples shown use podman commands (see Podman for more information).

  1. 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

    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
  2. Verify the image.

    For example:

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

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 Autonomous Database Free Container Image includes two Autonomous Database instances: MY_ATP, with Transaction Processing workload type, and MY_ADW with Data Warehouse workload type.

  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 \
--hostname localhost \
--cap-add SYS_ADMIN \
--device /dev/fuse \
--name adb_container \
container-registry.oracle.com/database/adb-free:latest

    Command notes:

    • For an OFS mount, the container starts with SYS_ADMIN capability. Also, virtual device /dev/fuse must be accessible.

    • --hostname is the Fully Qualified Domain Name (FQDN) of your host.

    • 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 SQL Developer
      27017 Mongo API (MY_ATP)

    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 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 \
--hostname localhost \
--cap-add SYS_ADMIN \
--device /dev/fuse \
--name adb_container \
container-registry.oracle.com/database/adb-free:latest
  2. Change the preinstalled default expired password for the ADMIN user for the instances: MY_ATP and MY_ADW.

    The Autonomous Database Free Container Image instances have default expired passwords:

    • MY_ATP: Default expired ADMIN password: Welcome_MY_ATP_1234.

    • MY_ADW: Default expired ADMIN password: Welcome_MY_ADW_1234

    To change these passwords, run change_expired_password.sh and specify an Autonomous Database instance.

    Note:

    If you do not run this script, you'll be prompted to set a new password at the first login.

    For example, to change the password for the MY_ATP instance: 

    podman exec container_id/u01/scripts/change_expired_password.sh MY_ATP 
          admin Welcome_MY_ATP_1234 new_password
    SQL*Plus: Release 19.0.0.0.0 - Production on Thu Aug 17 04:00:02 2023
Version 19.20.0.1.0

Copyright (c) 1982, 2023, Oracle.  All rights reserved.

ERROR:
ORA-28001: the password has expired


Changing password for admin
New password:
Retype new password:
Password changed

Connected to:
Oracle Database 19c Enterprise Edition Release 19.0.0.0.0 - Production
Version 19.20.0.1.0

The container start command uses the --hostname to generate self-signed SSL certs to serve HTTPS traffic on port 8443.

If you run Oracle Autonomous Database Free Container Image on a host whose FQDN is example.com, when you start the container specify --hostname example.com. After the container is running, access Oracle APEX and SQL Developer using the specified hostname (or localhost).

Built-in Database Tool MY_ATP MY_ADW Example
Oracle APEX https://localhost:8443/ords/my_atp/ https://localhost:8443/ords/my_adw/ https://example.com:8443/ords/my_atp
Database Actions https://localhost:8443/ords/my_atp/sql-developer https://localhost:8443/ords/my_adw/sql-developer https://example.com:8443/ords/my_adw/sql-developer

Parent topic: Use the Oracle Autonomous Database Free Container Image

Setup Wallet and Connect to Autonomous Database Free Container Image

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

The Autonomous Database Free Container Image includes two Autonomous Database instances: MY_ATP, with Transaction Processing workload type, and MY_ADW with Data Warehouse workload type.

You can connect to an Autonomous Database instance running in a container as follows:

  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_walletfolder: 

    podman cp container_id:/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@my_atp_low

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

    sqlplus admin/password@my_adw_low

The $TNS_ADMIN/tnsnames.ora contains the available TNS aliases that you can use to connect to an Autonomous Database instance.

Autonomous Database Transaction Processing Workload TNS Aliases

For mTLS use one of the following:

  • my_atp_medium
  • my_atp_high
  • my_atp_low
  • my_atp_tp
  • my_atp_tpurgent

For TLS use one of the following:

  • my_atp_medium_tls
  • my_atp_high_tls
  • my_atp_low_tls
  • my_atp_tp_tls
  • my_atp_tpurgent_tls

Autonomous Database Data Warehouse Workload TNS Aliases

For mTLS use one of the following:

  • my_adw_medium
  • my_adw_high
  • my_adw_low

For TLS use one of the following:

  • my_adw_medium_tls
  • my_adw_high_tls
  • my_adw_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: Use the Oracle 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 \
--hostname `hostname -f` \
--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
  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/**************@my_adw_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 \
--hostname `hostname -f` \
--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
  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