Install or Provision an Oracle Lab, Configure Listener/Services, and Verify SQLcl/SQL*Plus Connectivity

Learning outcomes

A database installer can finish successfully while the learner still connects to the wrong service, uses an old client, exposes the wrong port, or creates application objects in CDB$ROOT. ServiceHub needs an installation procedure whose final step is evidence, not a green setup dialog. This lesson provides a current Oracle AI Database Free 26ai path and then proves every connection boundary needed for the rest of the course.

1. Choose one supported local path

Windows native: use Oracle’s current 26ai Free Windows package and installation guide. The installer uses SID FREE; if old XE/Free installations or conflicting Oracle environment variables exist, follow Oracle’s pre-install cleanup guidance rather than forcing paths together.

Oracle Linux/RHEL-compatible native: use the current 26ai Free RPM and its preinstallation package. Oracle’s configuration script creates FREE, FREEPDB1, and the default listener. Native installation is useful when you want to inspect Oracle Home, services, ADR files, and OS process state directly.

Docker/Podman: use Oracle’s official Free image. This is the academy’s most reproducible cross-platform learning path where a Linux-container runtime is available.

docker pull container-registry.oracle.com/database/free:latestdocker volume create oracle26ai-data# Set ORACLE_PWD in your shell to a temporary strong lab password.# Do not put a real password in source control or in this lesson file.docker run -d --name oracle26ai-free \  -p 1521:1521 \  -e ORACLE_PWD="$ORACLE_PWD" \  -v oracle26ai-data:/opt/oracle/oradata \  container-registry.oracle.com/database/free:latestdocker logs -f oracle26ai-free

Wait for Oracle’s readiness message before testing connections. Record the image digest and VERSION_FULL once initialization completes. If port 1521 is already occupied, map a different host port such as 1522:1521 and record the change; do not silently edit every later connect string.

2. Verify the listener before blaming SQL

The listener is a network endpoint and service-registration component. On a native host, run lsnrctl status from the Oracle environment. In the container, execute it inside the running container. The expected default Free baseline includes services for the CDB and PDB; applications should normally target the PDB service FREEPDB1.

# Native host with Oracle environment configured:lsnrctl status# Container path:docker exec -it oracle26ai-free lsnrctl status

Check three things separately: an endpoint is listening, the expected service is registered, and the service has a ready handler. A listening TCP port alone does not prove that FREEPDB1 is open or registered.

3. Connect by service and verify the container

Easy Connect syntax lets a client specify host, port, and service directly. SQLcl and SQL*Plus can prompt for a password when it is omitted from the command line, avoiding credentials in shell history. The default application target is:

# SQLcl (executable name is typically sql):sql system@//localhost:1521/FREEPDB1# SQL*Plus:sqlplus system@//localhost:1521/FREEPDB1

After authentication, prove what you reached:

SHOW USERSHOW CON_NAMESELECT banner_full FROM v$version;SELECT product, version, version_full, statusFROM   product_component_version;SELECT instance_name, host_name, version_full, status, database_statusFROM   v$instance;SELECT name, open_mode, database_role, cdbFROM   v$database;SELECT con_id, name, open_modeFROM   v$pdbsORDER  BY con_id;SELECT sys_context('USERENV','SERVICE_NAME') AS service_name,       sys_context('USERENV','CON_NAME') AS con_name,       sys_context('USERENV','SESSION_USER') AS session_userFROM dual;

Expected shape: the instance/database baseline is FREE, the application connection’s current container is FREEPDB1, and the PDB is open read/write. Exact version strings belong to the package you actually installed; do not alter the output to match this guide.

4. ORACLE_HOME, ORACLE_SID, and TNS_ADMIN are not universal connection requirements

A remote application can connect to //dbhost:1521/FREEPDB1 without knowing the server’s Oracle Home or SID. Conversely, a DBA logged onto the database host may use OS authentication and an ORACLE_SID to attach locally. Keep those two paths distinct in runbooks.

5. Local bequeath versus network service connection

On a database host with the Oracle environment configured, an authorized operating-system account can use a local administrative connection such as sqlplus / as sysdba. This is not the same path as a remote TCP connection through the listener. It can work even when the listener is stopped, which makes it invaluable for startup/recovery—but also means it cannot prove network reachability.

# Database host/container only; requires appropriate OS privileges.export ORACLE_SID=FREEsqlplus / as sysdbaSHOW CON_NAMESELECT instance_name, status FROM v$instance;

On Windows, the environment/service mechanics differ; follow the Windows Free guide and use the Oracle service plus appropriate local administrative privileges. Do not copy a Unix export command into PowerShell and assume the architecture differs because syntax failed.

6. Deliberately wrong connection: create a local user in CDB$ROOT

A learner connects to //localhost:1521/FREE instead of FREEPDB1, sees CDB$ROOT, and tries to create SERVICEHUB_OWNER as if the root were an ordinary application database. Oracle’s multitenant rules reject an ordinary local-user name in the root, commonly with ORA-65096: invalid common user or role name. Prefixing the account with C## merely to silence the error creates a common user and changes its scope—the wrong repair for an application schema.

SHOW CON_NAMESELECT sys_context('USERENV','SERVICE_NAME') AS service_name FROM dual;-- If this reports CDB$ROOT for an application setup, disconnect.-- Reconnect to the PDB service instead:-- sql system@//localhost:1521/FREEPDB1SHOW CON_NAME

The safe repair is to use the correct PDB service and create local application users there. Chapter 13 will teach common versus local users explicitly. For now, always run SHOW CON_NAME before privileged DDL.

7. Troubleshoot connectivity in dependency order

1. Process/service: is the Oracle database service/container running?
2. Database state: is the instance started and database open?
3. PDB state: is FREEPDB1 open?
4. Listener: is an endpoint listening on the expected address/port?
5. Registration: is FREEPDB1 registered with a ready handler?
6. Network: does firewall/container port mapping allow the client to reach it?
7. Descriptor: is the client using the correct host, port, and service?
8. Authentication/TLS: are credentials and client network settings correct?

This order prevents a common anti-pattern: changing listener.ora because an application password is wrong, or resetting a password because the PDB is closed.

8. Hands-on lab: produce a connectivity acceptance record

Capture the following evidence in a text file stored beside your lab notes—not in a production secret store and not with passwords.

# Client identitysql -version# Listener (host/container)lsnrctl status# In SQLcl after connecting to FREEPDB1:SHOW USERSHOW CON_NAMESELECT banner_full FROM v$version;SELECT instance_name, host_name, version_full FROM v$instance;SELECT name, open_mode FROM v$pdbs ORDER BY con_id;SELECT value AS compatible FROM v$parameter WHERE name='compatible';SELECT sys_context('USERENV','SERVICE_NAME') AS service_name FROM dual;

Acceptance criteria:

• The database process/container is running and the PDB is open.
• The listener exposes the expected endpoint and FREEPDB1 is registered.
• SQLcl or SQL*Plus can connect using a PDB service descriptor.
• The session reports FREEPDB1, not CDB$ROOT, for application setup.
• The record includes exact VERSION_FULL, COMPATIBLE, client version, platform/container image identity, and port mapping.
• No real password is stored in the HTML, shell history, source repository, or lab evidence card.

9. Production judgment

A successful SELECT 1 FROM dual proves only that one session reached a database service. Production readiness additionally requires supported software, current security patching, secure listener/network configuration, certificate/TLS policy where applicable, backups and restore tests, monitoring, resource sizing, least privilege, and an HA/DR design consistent with SLOs. Oracle AI Database Free deliberately cannot satisfy the supported-patching boundary, so keep it as a learning environment.

Record environment variables only when they are truly part of the deployment. Prefer service-oriented application connection descriptors; use local SYSDBA connections for controlled administration, not as an application shortcut. Lesson 5 now builds the disposable ServiceHub schema and a baseline logical export.

10. Summary and next step

You now have a reproducible Oracle AI Database Free path and, more importantly, a verification chain: process → database → PDB → listener → registered service → network → descriptor → authenticated session. ORACLE_HOME, ORACLE_SID, and TNS_ADMIN have specific roles rather than being magic variables. The deliberate wrong-container exercise showed why checking CON_NAME before administrative DDL is a safety habit. Next, you will create least-privilege users, deterministic sample data, storage assumptions, reset scripts, and a baseline export.

Authoritative references

• Oracle AI Database Free Quick Start — current 26ai package and official container paths
• Oracle AI Database Free Installation Guide for Linux — FREE/FREEPDB1 creation, listener, environment, and native installation
• Oracle AI Database Free Installation Guide for Windows — current Windows installation and service behavior
• Oracle Net Services Administrator’s Guide — listener, service registration, and connect descriptors
• Oracle SQLcl Downloads — current SQLcl release and command-line tooling