Database setup

Before the connector can capture anything, the database needs:

1. ARCHIVELOG mode with a valid local archive destination (doctor rules DOC-1 and DOC-12).
2. Minimal supplemental logging at database level (DOC-2).
3. Supplemental logging on every captured table, ideally ALL COLUMNS (DOC-3, see supplemental logging).
4. A mining user with the LogMiner grants. In a container database (CDB) this is a common user (C## prefix) whose CONTAINER_DATA covers every PDB (DOC-4).
5. Oracle Database 19c or later (DOC-15), and for the default cdc.capture.mode=online, a PRIMARY database open READ WRITE (DOC-14).
6. In a CDB, every pluggable database open, with a saved state so that it opens again after a restart (DOC-21). LogMiner reads every container whose redo lies in the range it mines, captured or not, so a closed PDB makes mining wait until it opens (see transient database errors).

oracle-cdc-doctor writes the DBA script for the user and the grants, and checks all of the above against the database named in a connector configuration:

java -jar oracle-cdc-doctor-cli.jar setup-sql --profile production --user c##cdc > setup.sql
# review, set the password, then run it as SYSDBA at CDB$ROOT:
sqlplus / as sysdba @setup.sql
java -jar oracle-cdc-doctor-cli.jar check --config connector.json

The connector's own validate (run by Kafka Connect when a connector is created or updated) runs the doctor's fast rules and refuses the configuration on a blocking finding. check runs every rule, including the slower ones such as DOC-21 that validation leaves out. See oracle-cdc-doctor for the rules and exit codes.

The script

This is the script setup-sql --profile production writes for a container database and the default user. It is generated from the doctor's code, so it is exactly what the command prints. The password is a placeholder: pass --password, or edit the script before running it.

-- Capture user for the OSO CDC Connector for Oracle Database.
-- Generated by oracle-cdc-doctor setup-sql --profile production. Review before running as SYSDBA.
WHENEVER SQLERROR EXIT FAILURE

-- Common user: mines at CDB$ROOT and reads every PDB.
CREATE USER c##cdc IDENTIFIED BY "<change-me>" CONTAINER=ALL;
ALTER USER c##cdc QUOTA UNLIMITED ON users CONTAINER=ALL;
-- A common user sees container data objects (V$PDBS, V$SESSION, V$LOGMNR_CONTENTS, CDB_ views)
-- only for containers in its CONTAINER_DATA set, which defaults to CDB$ROOT alone. Mining at root
-- for several PDBs needs all of them (doctor rule DOC-4 checks this).
ALTER USER c##cdc SET CONTAINER_DATA=ALL CONTAINER=CURRENT;

GRANT CREATE SESSION TO c##cdc CONTAINER=ALL;
GRANT SET CONTAINER TO c##cdc CONTAINER=ALL;
GRANT LOGMINING TO c##cdc CONTAINER=ALL;
GRANT EXECUTE_CATALOG_ROLE TO c##cdc CONTAINER=ALL;
GRANT SELECT ANY TABLE TO c##cdc CONTAINER=ALL;
GRANT FLASHBACK ANY TABLE TO c##cdc CONTAINER=ALL;
GRANT SELECT ANY DICTIONARY TO c##cdc CONTAINER=ALL;
GRANT SELECT ANY TRANSACTION TO c##cdc CONTAINER=ALL;
GRANT EXECUTE ON DBMS_LOGMNR TO c##cdc CONTAINER=ALL;
GRANT EXECUTE ON DBMS_LOGMNR_D TO c##cdc CONTAINER=ALL;
GRANT SELECT ON V_$DATABASE TO c##cdc CONTAINER=ALL;
GRANT SELECT ON V_$LOG TO c##cdc CONTAINER=ALL;
GRANT SELECT ON V_$LOGFILE TO c##cdc CONTAINER=ALL;
GRANT SELECT ON V_$ARCHIVED_LOG TO c##cdc CONTAINER=ALL;
GRANT SELECT ON V_$ARCHIVE_DEST_STATUS TO c##cdc CONTAINER=ALL;
GRANT SELECT ON V_$THREAD TO c##cdc CONTAINER=ALL;
GRANT SELECT ON V_$TRANSACTION TO c##cdc CONTAINER=ALL;
GRANT SELECT ON GV_$TRANSACTION TO c##cdc CONTAINER=ALL;
GRANT SELECT ON V_$SESSION TO c##cdc CONTAINER=ALL;
GRANT SELECT ON GV_$SESSION TO c##cdc CONTAINER=ALL;
GRANT SELECT ON V_$PROCESS TO c##cdc CONTAINER=ALL;
GRANT SELECT ON V_$LOGMNR_CONTENTS TO c##cdc CONTAINER=ALL;
GRANT SELECT ON V_$LOGMNR_LOGS TO c##cdc CONTAINER=ALL;
GRANT SELECT ON V_$LOGMNR_PARAMETERS TO c##cdc CONTAINER=ALL;
GRANT SELECT ON V_$PDBS TO c##cdc CONTAINER=ALL;
GRANT SELECT ON V_$VERSION TO c##cdc CONTAINER=ALL;
GRANT SELECT ON V_$PARAMETER TO c##cdc CONTAINER=ALL;
GRANT SELECT ON V_$SQL TO c##cdc CONTAINER=ALL;

-- Per captured table (repeat for each): full before images for updates.
-- ALTER TABLE <owner>.<table> ADD SUPPLEMENTAL LOG DATA (ALL) COLUMNS;

-- Database level, once:
-- ALTER DATABASE ADD SUPPLEMENTAL LOG DATA;

What the grants are for:

Grant	Used for
CREATE SESSION, SET CONTAINER	Connecting at CDB$ROOT and reading each PDB's dictionary and tables
LOGMINING, EXECUTE_CATALOG_ROLE, EXECUTE ON DBMS_LOGMNR	Starting LogMiner sessions and adding redo logs to them
SELECT ANY TRANSACTION	Reading V$LOGMNR_CONTENTS
SELECT ANY DICTIONARY and the V_$ views	Log inventory, archive destinations, database identity, the data dictionary, and GV$TRANSACTION for orphan detection
SELECT ANY TABLE, FLASHBACK ANY TABLE	Snapshots and LOB reselect, which read tables with AS OF SCN
EXECUTE ON DBMS_LOGMNR_D	Dictionary builds into the redo, which let the connector decode rows written before a later DDL (schema and DDL); without it builds are switched off with an ops event

Pass --non-cdb for a non-container database: the script then has no CONTAINER clauses and no SET CONTAINER grant, and cdc.database.pdbs stays empty in the connector configuration.

ARCHIVELOG

ARCHIVELOG mode needs a restart, so the DBA enables it, together with database-level supplemental logging and a local archive destination:

ALTER SYSTEM SET log_archive_dest_1 = 'LOCATION=/path/to/archive' SCOPE=BOTH;
SHUTDOWN IMMEDIATE;
STARTUP MOUNT;
ALTER DATABASE ARCHIVELOG;
ALTER DATABASE OPEN;
ALTER DATABASE ADD SUPPLEMENTAL LOG DATA;

A local destination with its own free-space monitoring is safer than a fast recovery area that can fill and halt the database. How long archived logs must stay is covered in redo sizing and archive retention.

Platforms

Platform	Status
On-premises and self-managed cloud VMs, single instance, CDB or non-CDB	Supported; setup-sql --platform onprem (the default)
Oracle RAC	Not supported yet. A database with more than one enabled redo thread is refused at start (CDC-5001, doctor rule DOC-13) until the per-thread position ships; a DISABLED thread left by a removed instance is fine
Amazon RDS for Oracle	Preview for 19c: setup-sql --platform rds and RDS-aware doctor checks, qualified on RDS SE2 on 9 October 2026 as a non-CDB and, from release 0.1.3, with the CDB architecture, mined from inside the tenant database in range mode (see Amazon RDS for Oracle)
Autonomous Database	Not supported yet; setup-sql --platform autonomous prints a notice and exits with code 3
Physical standby	Not qualified. With cdc.capture.mode=archive_only the connector accepts a physical standby open read-only (Active Data Guard) and never mines past the SCN redo apply has reached, but it is tested on primary databases only. Online mode on a standby, and a mounted, logical or snapshot standby in any mode, are refused at start (CDC-5001, doctor rule DOC-14)