Skip to main content
HashnodeRonald Rosier

Command Palette

Search for a command to run...

Run Oracle in a Docker container on Windows

Updated
•3 min read
Run Oracle in a Docker container on Windows
R
Ronald Rosier

This article goes through the steps of running a docker container with a development or free oracle database.

This is an alternative way from installing Oracle either local or hosting on a VM.

Prerequisite

Docker Desktop (check your license) configured to run Linux containers.

Pull the official Oracle DB container image

Oracle provides pre-build Docker images hosted on their own registry at container-registry.oracle.com.

You'll find a number of images under the Database containers.

For development I use either express or free. Both are falling under the Oracle Free Use Terms and Conditions.

Note: to access any software from oracle, you will need first to create a free Oracle account.

docker login container-registry.oracle.com

# express
docker pull container-registry.oracle.com/database/express:21.3.0-ex

# free
docker pull container-registry.oracle.com/database/free:23.5.0.0

Run the Oracle database with Docker

We create a local directory which will contain the database data files. This will then be mounted to the container, ensuring data persistency between the containers lifecycle.

In my case, I create a local directory which matches the oracle version of my running container.

C:\oracle\data\21.1.3 (express)
C:\oracle\data\23.2 (free)

# express  
docker run --name oracle-21.1.3.0-xe -p 1521:1521 -e ORACLE_PWD=PWD1234-v C:\oracle\data\21.1.3:/opt/oracle/oradata container-registry.oracle.com/database/express:21.3.0-xe

#free
docker run --name oracle-23.5.0.0-free -p 1521:1521 -e ORACLE_PWD=PWD1234 -v C:\oracle\data\23.5:/opt/oracle/oradata container-registry.oracle.com/database/free:23.5.0.0

You should see following in the output window.

2024-09-07 16:38:46 Starting Oracle Net Listener.
2024-09-07 16:38:48 Oracle Net Listener started.
2024-09-07 16:38:48 Starting Oracle Database instance XE.
2024-09-07 16:38:53 Oracle Database instance XE started.
2024-09-07 16:38:53
2024-09-07 16:38:53 The Oracle base remains unchanged with value /opt/oracle 
2024-09-07 16:38:53 #########################
2024-09-07 16:38:53 DATABASE IS READY TO USE!
2024-09-07 16:38:53 #########################

At this moment, you're able to connect to the database using sqlplus once you installed the client packages.

Install client for windows 64-bit

To connect to your database with your application, you will need to install the Oracle client.

You can download the client packages here. Follow the instructions under "Instant Client Installation for Microsoft Windows 64-bit".

For my tests, I installed following packages below. I used version 23.5.0.0.0 and could connect to both the free and express containers.

  • Basic Light Package

  • SQL*Plus Package

Configure tnsnames.ora

It is very common to configure a TNS name as a user-friendly alias for the database connection.

The docker database is a multitenant container database (CDB).
Read more about multitenant architecture.

If your scripts or code do not support CDB, you will need to connect to the underlying PDB (Pluggable Database).

Main issue with scripts and code could be creation of users.
In CDB, you have the notion of Common and Local User.
When connected to the root (CDB), the 'create user' command will create a common user which has a number of restrictions.
For our scripts to work, we need to open a session on the PDB to create a local user only known to that PDB.
https://www.dbasolved.com/2013/06/common-user-vs-local-user-12c-edition/

Create following tnsnames.ora file and save it under {oracle-client-root}/network/admin.

# tnsnames.ora Network Configuration File: C:\oracle\client\instantclient_23_5\network\admin\tnsnames.ora

ALIAS =
  (DESCRIPTION =
    (ADDRESS_LIST =
      (ADDRESS = (PROTOCOL = TCP)(HOST = localhost)(PORT = 1521))
    ) 
    (CONNECT_DATA =
      (SERVER = DEDICATED)
      (SERVICE_NAME = XEPDB1) #FREEPDB1
    )
  )

You may want to set the TNS_ADMIN environment variable to this directory.

Test connection

SqlPlus

Use sqlplus command line tool to connect to the database.

sqlplus sys/PWD1234@//localhost:1521/XEPDB1 as sysdba
# use tnsnames
Sqlplus sys/@ALIAS as sysdba

SQL Developer extension for VS Code

You can use a graphical interface with SQL Developer or the SQL Developer extension in VS Code.

Make sure you select connection type TNS, and specify the tnsnames.ora directory in the settings.

#docker#databases#oracle