Oracle DBA Lesson 53B — Adopting a Compatible Non-CDB

A legacy Oracle 19c non-CDB can become a PDB in a compatible 19c container database. Physical adoption uses its existing data files and converts its dictionary for the new container. The useful sequence is to describe a consistent source, check the destination, freeze the source, copy the files, convert in the new PDB, and validate the destination.

Oracle DBA Lesson 53B — Adopting a Compatible Non-CDB

The source, the destination root, and the destination PDB are three different command contexts. Keeping that distinction explicit prevents a correct command from being used against the wrong database.

Conditions for the worked example

Use this procedure only in the instructor-designated disposable lab, under its approved outage and recovery runbook. The baseline is Oracle Database 19c, single instance on Linux, with SQL*Plus. Earlier releases, cross-platform conversion, and newer-release upgrades need their own supported paths.

Before execution, the instructor must provide and review:

• The exact source and target database identities, release and RU, edition, platform and endian format, installed components and options, character and national character sets, time-zone files, encryption-key inventory, and available feature entitlement. Resolve applicable differences through their documented procedures.
• An isolated non-CDB source with an instructor-provided migration test schema and recorded object and key totals. The shared setup_course_schema.sql requires LABPDB. Do not run it in the non-CDB.
• Tested source recovery, including the required backup, control-file records, and keys. Keep recovery assets protected outside the failure domain being changed. Retain source files and a rehearsed source fallback until acceptance.
• An agreed application outage: stop new source requests, finish or resolve outstanding work, capture the final source baseline, and control service routing throughout adoption.
• A target with LABPDB_ADOPT absent. Record its identity and verify the target root's DB_CREATE_FILE_DEST, destination permissions, and real capacity for a complete copy. A missing or unsuitable destination is a stop condition.
• A protected XML path and target access to every source file it names. The example path /lab/transfer/noncdb.xml is fictional and must be resolved for the lab. XML contains metadata and file locations. Retain the actual data files separately.
• Authorized source and target connections that exercise SYSDBA at connect time. The target administrator must be able to switch into the new PDB and run the Oracle-supplied conversion script. Confirm the target Oracle home and SQL*Plus environment before choosing the script path.

The minimal COPY statement below assumes the descriptor still names the accessible, consistent source files, target OMF is verified, there are no service-name conflicts, and the source has no encrypted user tablespaces needing additional key clauses. An encrypted source requires the documented 19c keystore and key-transfer procedure and recoverable keys before using an adapted statement. If staged source files have moved, review SOURCE_FILE_DIRECTORY or SOURCE_FILE_NAME_CONVERT against their actual locations. Source-location mapping and destination-file naming serve different purposes. See CREATE PLUGGABLE DATABASE and DB_CREATE_FILE_DEST.

All statements and expected observations in these notes are teaching examples. No database execution produced them. Record actual results and errors in the designated lab. The commands form reviewed stages, rather than one unattended script.

1. Describe the consistent source

On the source host, with the instructor-confirmed source Oracle environment and authorized OS authentication, start SQL*Plus:

sqlplus -L / as sysdba

An instructor-supplied prompted connection or an approved wallet can replace OS authentication. First establish the source identity and capture the final application baseline. In this source session:

SHOW USER
SELECT name, cdb, open_mode FROM v$database;

SHUTDOWN IMMEDIATE
STARTUP OPEN READ ONLY

SELECT name, cdb, open_mode FROM v$database;

BEGIN
  DBMS_PDB.DESCRIBE(
    pdb_descr_file => '/lab/transfer/noncdb.xml');
END;
/

The initial query must identify the intended legacy source, with CDB=NO. A clean shutdown followed by a read-only startup establishes the consistent source used for description. Confirm READ ONLY before DESCRIBE. The procedure writes an XML descriptor for the connected non-CDB. Its metadata and file names allow the destination to inspect and adopt that file set. SHUTDOWN, STARTUP, and SHOW are SQL*Plus commands. The anonymous block executes in the database. See Oracle 19c adoption procedure.

2. Check compatibility in the target root

Use a separate connection in the target Oracle environment, connected AS SYSDBA. Verify the target database identity and CDB$ROOT before running the check:

SHOW USER
SHOW CON_NAME
SELECT name, cdb, open_mode FROM v$database;

SET SERVEROUTPUT ON
DECLARE
  compatible BOOLEAN;
BEGIN
  compatible := DBMS_PDB.CHECK_PLUG_COMPATIBILITY(
    pdb_descr_file => '/lab/transfer/noncdb.xml',
    pdb_name       => 'LABPDB_ADOPT');
  IF compatible THEN
    DBMS_OUTPUT.PUT_LINE('YES');
  ELSE
    DBMS_OUTPUT.PUT_LINE('NO');
  END IF;
END;
/

SELECT time, name, cause, type, status, message, action
FROM pdb_plug_in_violations
WHERE name = 'LABPDB_ADOPT'
ORDER BY time, line;

The function returns a Boolean. This block turns it into readable YES or NO. A NO requires diagnosis and documented correction before creation. Recheck after remediation. Review every applicable message with the instructor, including a YES result with associated messages. Use the intended name and check timestamp to separate the current attempt from historical records. TYPE distinguishes ERROR and WARNING. STATUS records PENDING, RESOLVED, or IGNORE. ACTION describes the correction. A historical row is part of the evidence, and a total row count is insufficient as an acceptance rule. See DBMS_PDB and PDB_PLUG_IN_VIOLATIONS.

Correct blocking version, component, option, or SQL patch incompatibilities at the documented stage. Repeat description and checking if source metadata changes. The reviewed runbook must also identify adoption-specific actions that are completed by conversion or initial integration. Follow those stages in order, then verify their messages resolve. A conversion-required message belongs with conversion in the newly created target PDB. It never authorizes running that script in the source or in the root. Keep unresolved issues open in the evidence until their prescribed correction is demonstrated.

3. Shut down the source, then COPY in the target root

After compatibility succeeds, return to the source SQL*Plus session:

SHUTDOWN IMMEDIATE

Keep the source shut down while its described files are copied. Return to the target root session. Verify identity, root context, the absent target name, and the validated OMF destination, then execute:

SHOW CON_NAME

SELECT pdb_name, status
FROM dba_pdbs
WHERE pdb_name = 'LABPDB_ADOPT';

SHOW PARAMETER db_create_file_dest

CREATE PLUGGABLE DATABASE labpdb_adopt
  USING '/lab/transfer/noncdb.xml' COPY;

USING selects the descriptor. COPY creates a separate destination file set. Oracle Managed Files supplies names and locations in this example. Preserve the original source files and protected recovery assets. The new PDB is staged for conversion. Proceed to the conversion script before its normal first open. The second source shutdown is an explicit step in Oracle's adoption procedure. See Oracle 19c adoption procedure and COPY and OMF naming.

NOCOPY keeps the adopted files in place, so dictionary conversion changes that file set. Use it only with an independent, tested recovery copy and a reviewed storage and recovery plan. A directory name alone does not establish recovery independence. COPY's separation helps preserve the source fallback. Retain the tested backup as well.

4. Convert inside LABPDB_ADOPT

In the target SQL*Plus connection established AS SYSDBA, switch into the staged PDB, verify it, and run the conversion script supplied by the target Oracle home:

ALTER SESSION SET CONTAINER=labpdb_adopt;
SHOW CON_NAME

SPOOL noncdb-conversion.log
@?/rdbms/admin/noncdb_to_pdb.sql
SPOOL OFF

SHOW CON_NAME must identify LABPDB_ADOPT before the @ command. ALTER SESSION moves this session's container. @ is SQL*Plus script execution. ? denotes the active Oracle home in this environment. Check that the resolved home supplies the correct 19c script for the target. See SQL*Plus scripts and Oracle home notation.

The script opens the new PDB, performs its dictionary changes, and closes it. Let those script-owned state changes complete successfully before the normal first opening. Preserve the complete log and inspect required outcomes and errors. A final prompt alone is insufficient to approve conversion. This script is specific to a non-CDB source. A normal PDB-to-PDB clone uses its documented creation and opening procedure. See Oracle 19c conversion behavior.

5. Open, validate, and protect the target

After successful conversion, verify the current PDB and open it normally:

SHOW CON_NAME
ALTER PLUGGABLE DATABASE OPEN READ WRITE;

In the target root, capture its resulting state and review the latest relevant plug-in messages:

ALTER SESSION SET CONTAINER=CDB$ROOT;
SHOW CON_NAME

SELECT name, open_mode, restricted
FROM v$pdbs
WHERE name = 'LABPDB_ADOPT';

SELECT pdb_name, status
FROM dba_pdbs
WHERE pdb_name = 'LABPDB_ADOPT';

SELECT time, name, cause, type, status, message, action
FROM pdb_plug_in_violations
WHERE name = 'LABPDB_ADOPT'
ORDER BY time, line;

The normal initial READ WRITE opening completes integration. Check OPEN_MODE=READ WRITE, STATUS=NORMAL, and the intended access and restriction state. Correlate messages with this creation, conversion, and open attempt, and verify that the required actions are complete. See V$PDBS and DBA_PDBS.

Test fresh application connections through the reviewed destination service. Confirm the destination identity, compare the recorded object inventory and key totals, and run the agreed functional tests. Review jobs, directory paths, database links, service routing, and privileged accounts against the migration plan. Perform a small authorized write, commit, and read test through a second fresh connection when the plan permits it. Take and verify a new target backup before acceptance, using the rehearsed backup procedure. Retain the required recovery records and keys.

Worked data check

Suppose the instructor's isolated source contains MIG_TEST.ORDERS(order_id, amount) and a manifest captured before shutdown. As an authorized observer in the source, record:

SELECT object_type, status, COUNT(*) AS object_count
FROM dba_objects
WHERE owner = 'MIG_TEST'
GROUP BY object_type, status
ORDER BY object_type, status;

SELECT COUNT(*) AS rows_total,
       COUNT(DISTINCT order_id) AS distinct_keys,
       MIN(order_id) AS first_key,
       MAX(order_id) AS last_key,
       SUM(amount) AS amount_total
FROM mig_test.orders;

Run the same approved queries in LABPDB_ADOPT after conversion and opening, and compare them against that source manifest. If the authored baseline is three rows with keys 101, 102, and 103 and an amount total of 150, the target should match those recorded checks. A missing row or a changed total fails this comparison and needs investigation. Retain the complete key comparison and the functional test results required by the plan. These summary totals cover only the stated checks. For a different supplied schema, adapt the queries with the instructor rather than creating the shared course schema in the source.

Independent practice and recovery

Complete an instructor-reviewed adoption runbook outside the short video. Record both database identities and environments, the source baseline, the clean read-only state, the descriptor and check evidence, the second source shutdown, the copied destination locations, the verified conversion container, the full conversion log, the normal opening, and the relevant plug-in message outcomes. Finish the application, service, and account checks and the new target backup.

Pass when you can explain why each command belongs in its recorded session and show that the actual target opens normally, the source test schema's object and key totals match, services and intended account access pass, functional work succeeds, and the backup exists with its required dependencies. Keep pending conditions visible. An unavailable lab is an unexecuted practice.

If creation or conversion fails, stop progression, preserve the logs and target files, and inspect the actual target status and alert-log evidence. DDL and conversion-script changes require a rehearsed recovery or reset procedure. SQL ROLLBACK cannot undo this adoption. Use the protected source fallback only through the reviewed plan, including service routing and reconciliation of any target writes. An UNUSABLE target may require a reviewed drop before the same name can be recreated. Diagnose and review before removal. See PDB state and creation failures.

Cleanup removes only the disposable target after the instructor reviews the evidence, using the target-only lifecycle procedure taught in Lesson 48. Verify its exact identity and file ownership first. Preserve the source files, the backup, and the recovery keys until the agreed retention and release point. Leave the original source and unrelated PDBs intact.

Video check: No. noncdb_to_pdb.sql belongs to non-CDB adoption.

Recap

Describe the consistent source, check compatibility, shut down and copy, convert in the verified PDB, then open, validate, and back up.

Quiz

1. Which source condition belongs before DBMS_PDB.DESCRIBE in this procedure?

A clean, transactionally consistent source opened READ ONLY A source with application writes continuing throughout description A converted target already open READ WRITE A target root running the source conversion script

2. A target compatibility check returns NO. What is the next action?

Create with NOCOPY to bypass the check Run the conversion script in CDB$ROOT Inspect current plug-in messages, apply documented remediation, and recheck Treat a successful XML write as acceptance

3. What extra source action follows a successful compatibility gate and precedes CREATE with COPY?

Open the source READ WRITE Shut down the source again Drop the source tablespaces Delete the XML descriptor

4. Where and when should noncdb_to_pdb.sql run?

In every normal PDB clone after its first open In the source non-CDB before description In the target root immediately after any connection In the verified new PDB, AS SYSDBA, before its normal first open

5. Why require independent recovery before a NOCOPY adoption?

Conversion changes the same adopted files that remain in place NOCOPY automatically creates a new backup A ROLLBACK reverses the conversion if it fails XML contains a complete copy of application rows

All statements and expected observations in these notes are teaching examples. No database execution produced them. Record actual results and errors in the designated lab. The commands form reviewed stages, rather than one unattended script.

AIOps Pro

https://www.apps-dba.com/ https://x.com/AIOpsPro https://www.youtube.com/@AIOpsPro