Oracle Database XE Release 21c (21.3.0.0) Docker Image Documentation
Oracle Database XE Release 21c is the developer edition of the industry-leading relational database server. The Oracle XE Database server Docker image contains Oracle Database Express Edition Release 21c (21.3.0.0) running on Oracle Linux 7. This image contains a default database in a multitenant configuration with one pluggable database.
For more information on Oracle Database server Release 21c, see:
http://docs.oracle.com/en/database/
Using This Image
Starting an Oracle Database Server Instance
The Oracle XE Database 21c server Docker image contains a pre-built database, so the startup time is very fast. Fast startup can be helpful in CI/CD scenarios. To start an Oracle Database server instance, run the following command where,<oracle-db> is the name of the container:
$ docker run -d --name <oracle-db>
container-registry.oracle.com/database/express:21.3.0-xe
When the container is started, a random password is used for the SYS, SYSTEM and PDBADMIN users. This is termed as the default password.
Note:
- Throughout this document, words enclosed within angle brackets < > indicate variables in code lines.
- To change the default password, see: "Changing the Default Password for SYS User"
- To learn about advanced use cases, see: "Custom Configurations"
The Oracle Database server is ready to use when the STATUS field shows (healthy) in the docker ps output.
Custom Configurations
To facilitate custom configurations, the Oracle Database server container provides configuration parameters that you can use when starting the container. For example, this is the detailed docker run command supporting all custom configurations:
docker run --name <container name> \
-p <host port>:1521 -p <host port>:5500 \
-e ORACLE_PWD=<your database passwords> \
-e ORACLE_CHARACTERSET=<your character set> \
-v [<host mount point>:]/opt/oracle/oradata \
container-registry.oracle.com/database/express:21.3.0-xe
Parameters:
--name: The name of the container (default: auto generated)
-p: The port mapping of the host port to the container port.
Two ports are exposed: 1521 (Oracle Listener), 5500 (EM Express)
-e ORACLE_PWD: The Oracle Database SYS, SYSTEM and PDB_ADMIN password (default: auto generated)
-e ORACLE_CHARACTERSET:
The character set to use when creating the database (default: AL32UTF8)
-v /opt/oracle/oradata
The data volume to use for the database.
Has to be writable by the Unix "oracle" (uid: 54321) user inside the container!
If omitted the database will not be persisted over container recreation.
-v /opt/oracle/scripts/startup | /docker-entrypoint-initdb.d/startup
Optional: A volume with custom scripts to be run after database startup.
For further details see the "Running scripts after setup and on startup" section below.
-v /opt/oracle/scripts/setup | /docker-entrypoint-initdb.d/setup
Optional: A volume with custom scripts to be run after database setup.
For further details see the "Running scripts after setup and on startup" section below.
The supported configuration options are:
- ORACLE_PWD:
This parameter modifies the password for the
SYS, SYSTEM and PDBADMIN users. This parameter is optional, and the default value is randomly generated. Note: If you use this option, then the password will be visible as a container environment variable, and cannot be changed later on.
- ORACLE_CHARACTERSET:
This parameter modifies the character set of the database. This parameter is optional, and the default value is set to AL32UTF8. Please Note that, this parameter will set the character set only when a new database is created i.e. a host system directory is mounted using -v option while running the image (Please refer to Mounting Docker volume/host directory for database persistence section).
- Podman Secret Support:
This option is supported only when the Podman runtime is being used to run the Oracle Database 21c XE container image.
Secret is a utility to pass secure strings of text to the container, such as ssh-keys, or passwords. To specify the password for SYS, SYSTEM and PDBADMIN users securely, create a secret named oracle_pwd. The command is as follows:
echo "<Your Password>" | podman secret create oracle_pwd -
After you create the secret, you open the container securely by using the following command:
podman run --name=<container_name> --secret=oracle_pwd container-registry.oracle.com/database/express:21.3.0-xe
Changing the Default Password for SYS User
On the first startup of the container, a random password is generated for the database if a password is not provided by using the -e option, as described in the "Custom Configurations" section.
To change the password for these accounts, use the docker exec command, to run the setPassword.sh script that is found in the container. Note that the container must be running before you run the script.
For example:
$ docker exec <oracle-db> ./setPassword.sh <your_password>
Database Alert Logs
You can access the database alert log by using the following command, where <oracle-db> is the name of the container:
$ docker logs <oracle-db>
Oracle Enterprise Manager Express
The Oracle XE Database inside the container also has Oracle Enterprise Manager (OEM) Express configured. To access OEM Express, start your browser, and enter the OEM URL: https://localhost:5500/em/
Connecting to the Oracle XE Database Server Container
After the Oracle Database server indicates that the container has started, and the STATUS field shows (healthy), client applications can connect to the database.
Connecting from Within the Container
You can connect to the Oracle Database server by running a SQL*Plus command from within the container using one of the following commands:
$ docker exec -it <oracle-db> sqlplus / as sysdba
$ docker exec -it <oracle-db> sqlplus sys/<your_password>@XE as sysdba
$ docker exec -it <oracle-db> sqlplus system/<your_password>@XE
$ docker exec -it <oracle-db> sqlplus pdbadmin/<your_password>@XEPDB1
Connecting from Outside the Container
By default, Oracle Database exposes port 1521 for Oracle client connections, using Oracle's SQL*Net protocol. SQL*Plus or any Oracle Java Database Connectivity (JDBC) client can be used to connect to the database server from outside of the container.
To connect from outside of the container, start the container with the -p option, as described in the detailed Docker run command in the "Custom Configurations" section.
Discover the mapped port by running the following command:
$ docker port <oracle-db>
To connect from outside of the container using SQL*Plus, run the following commands:
# To connect to the database at the CDB$ROOT level as sysdba:
$ sqlplus sys/<your password>@//localhost:1521/XE as sysdba
# To connect as non sysdba at the CDB$ROOT level:
$ sqlplus system/<your password>@//localhost:1521/XE
# To connect to the default Pluggable Database (PDB) within the XE Database:
$ sqlplus pdbadmin/<your password>@//localhost:1521/XEPDB1
Reusing the Existing Database
If the database is started using a host system directory mounted at an /opt/oracle/oradata location inside the container, as explained in the Custom Configuration section under ""Mounting Docker volume/host directory for database persistence", then the data files remain persistent even after the container is destroyed. Another container with the same data files can be started by reusing the host system directory.
To reuse this directory on the host system for the data volume, run the following commands:
$ docker run -d --name <oracle-db> -v
<writable_host_directory_path>:/opt/oracle/oradata
container-registry.oracle.com/database/express:21.3.0-xe
Running Scripts After Setup and On Startup
The Docker images can be configured to run scripts after setup and on startup. Currently, .sh and .sql extensions are supported. For post-setup scripts, mount the volume /opt/oracle/scripts/setup to include scripts in this directory. For post-startup scripts, mount the volume /opt/oracle/scripts/startup to include scripts in this directory. Both of these locations are also represented by the symbolic link /docker-entrypoint-initdb.d. This configuration provides synergy with other database Docker images. You can decide whether to put the setup and startup scripts under /opt/oracle/scripts, or under /docker-entrypoint-initdb.d.
After the database is set up or started, the scripts in those folders are run against the database in the container. SQL scripts are run as SYSDBA, and shell scripts are run as the current user. To ensure proper order for running scripts, Oracle recommends that you prefix your scripts with a number. For example: 01_users.sql, 02_permissions.sql, and so on.
Note: The startup scripts are run after the first time that the database setup is complete.
The following example mounts the local directory /home/oracle/myScripts to /opt/oracle/scripts/startup, which is then searched for custom startup scripts:
$ docker run -d --name <oracle-db> -v
/home/oracle/myScripts:/opt/oracle/scripts/startup
container-registry.oracle.com/database/express:21.3.0-xe
Documentation Accessibility
For information about Oracle's commitment to accessibility, visit the Oracle Accessibility Program website at https://www.oracle.com/corporate/accessibility/.
Oracle Database XE Release 21c (21.3.0.0) Docker Image Documentation
Copyright © 2005, 2022, Oracle and/or its affiliates.
Oracle Free Use Terms and Conditions
Definitions
"Oracle" refers to Oracle America, Inc. "You" and "Your" refers to (a) a company or organization (each an “Entity”) accessing the Programs, if use of the Programs will be on behalf of such Entity; or (b) an individual accessing the Programs, if use of the Programs will not be on behalf of an Entity. "Program(s)" refers to Oracle software provided by Oracle pursuant to the following terms and any updates, error corrections, and/or Program Documentation provided by Oracle. "Program Documentation" refers to Program user manuals and Program installation manuals, if any. If available, Program Documentation may be delivered with the Programs and/or may be accessed from www.oracle.com/documentation. "Separate Terms" refers to separate license terms that are specified in the Program Documentation, readmes or notice files and that apply to Separately Licensed Technology. "Separately Licensed Technology" refers to Oracle or third party technology that is licensed under Separate Terms and not under the terms of this license.
Separately Licensed Technology
Oracle may provide certain notices to You in Program Documentation, readmes or notice files in connection with Oracle or third party technology provided as or with the Programs. If specified in the Program Documentation, readmes or notice files, such technology will be licensed to You under Separate Terms.
Your rights to use Separately Licensed Technology under Separate Terms are not restricted in any way by the terms herein. For clarity, notwithstanding the existence of a notice, third party technology that is not Separately Licensed Technology shall be deemed part of the Programs licensed to You under the terms of this license.
Source Code for Open Source Software
For software that You receive from Oracle in binary form that is licensed under an open source license that gives You the right to receive the source code for that binary, You can obtain a copy of the applicable source code from https://oss.oracle.com/sources/ or http://www.oracle.com/goto/opensourcecode.
If the source code for such software was not provided to You with the binary, You can also receive a copy of the source code on physical media by submitting a written request pursuant to the instructions in the "Written Offer for Source Code" section of the latter website.
The following license terms apply to those Programs that are not provided to You under Separate Terms.
License Rights and Restrictions
Oracle grants to You, as a recipient of this Program, a nonexclusive, nontransferable, limited license to, subject to the conditions stated herein, (a) internally use the unmodified Programs for the purposes of developing, testing, prototyping and demonstrating your applications, and running the Programs for your own internal business operations; and (b) redistribute unmodified Programs and Programs Documentation, under the terms of this License, provided that You do not charge Your end users any additional fees for the use of the Programs. You may make copies of the Programs to the extent reasonably necessary for exercising the license rights granted herein and for backup purposes. You are granted the right to use the Programs to provide third party training in the use of the Programs and associated Separately Licensed Technology only if there is express authorization of such use by Oracle on the Program's download page or in the Program Documentation.
Your license is contingent on Your compliance with the following conditions:
- You include a copy of this license with any distribution by You of the Programs;
- You do not remove markings or notices of either Oracle's or a licensor's proprietary rights from the Programs or Program Documentation;
- You comply with all U.S. and applicable export control and economic sanctions laws and regulations that govern Your use of the Programs (including technical data);
- You do not cause or permit reverse engineering, disassembly or decompilation of the Programs (except as allowed by law) by You nor allow an associated party to do so.
For clarity, any source code that may be included in the distribution with the Programs is provided solely for reference purposes and may not be modified, unless such source code is under Separate Terms permitting modification.
Ownership
Oracle or its licensors retain all ownership and intellectual property rights to the Programs.
Information Collection
The Programs' installation and/or auto-update processes, if any, may transmit a limited amount of data to Oracle or its service provider about those processes to help Oracle understand and optimize them. Oracle does not associate the data with personally identifiable information. Refer to Oracle's Privacy Policy at www.oracle.com/privacy.
Disclaimer of Warranties; Limitation of Liability
THE PROGRAMS ARE PROVIDED "AS IS" WITHOUT WARRANTY OF ANY KIND. ORACLE FURTHER DISCLAIMS ALL WARRANTIES, EXPRESS AND IMPLIED, INCLUDING WITHOUT LIMITATION, ANY IMPLIED WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, OR NONINFRINGEMENT.
IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW WILL ORACLE BE LIABLE TO YOU FOR DAMAGES, INCLUDING ANY GENERAL, SPECIAL, INCIDENTAL OR CONSEQUENTIAL DAMAGES ARISING OUT OF THE USE OR INABILITY TO USE THE PROGRAM (INCLUDING BUT NOT LIMITED TO LOSS OF DATA OR DATA BEING RENDERED INACCURATE OR LOSSES SUSTAINED BY YOU OR THIRD PARTIES OR A FAILURE OF THE PROGRAM TO OPERATE WITH ANY OTHER PROGRAMS), EVEN IF SUCH HOLDER OR OTHER PARTY HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGES.
Last updated: 5 April, 2022