Use the Autonomous Database Free Container Image

Use the 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.

About the Free Container Image

You can access the 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 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.

Autonomous Database Free Container Image License

Describes licensing for Autonomous Database Free Container Image.

Autonomous 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 Database Free Container Image Features

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

  • Each 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 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 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 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

Autonomous 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 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 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 Database Free Container Image

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

You can obtain the 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 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 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 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 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

Start Free Container Image

After you download 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 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 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

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

Connect to ORDS, APEX, or Database Actions from an Autonomous 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 Database Container Image

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

Table 3-7 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.

Connect to an Autonomous Database Container Image with a Wallet

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

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

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

Describes the steps to connect to an Autonomous 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.

  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

Migrate Data Between Autonomous 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.

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