.. module:: Oracle


Oracle
=========================

Oracle does not provide a dedicated Python library for Change Data Capture
equivalent to MySQL binary log replication or MongoDB Change Streams.
CDC on Oracle must be implemented using a combination of Oracle built-in
features and a Python connector such as ``cx_Oracle`` (legacy) or
``oracledb`` (current).


Recommended approaches
--------------------------

**Oracle Flashback Technology**
   Flashback Query and Flashback Version Query allow you to retrieve data as
   it appeared at a previous point in time. You can implement a polling-based
   CDC by periodically querying for changes within a time range.

**Database Triggers**
   Triggers execute automatically in response to ``INSERT``, ``UPDATE``, and
   ``DELETE`` events on a table. They can write change records into a dedicated
   audit table that a CDC consumer then reads.

**LogMiner**
   Oracle LogMiner mines redo log files and exposes a SQL interface to the
   changes recorded in them. It is the closest Oracle equivalent to MySQL
   binary log streaming and is the basis of tools like Oracle GoldenGate.


Implementing with ``IProcessor``
----------------------------------

To integrate Oracle CDC with this library, subclass ``IProcessor`` and
implement the three abstract methods:

.. code-block:: python

   from core_cdc.processors.base import IProcessor
   from core_cdc.base import EventType, Record

   class OracleLogMinerProcessor(IProcessor):

       def get_events(self):
           # Query LogMiner or your audit table for new rows
           ...

       def get_event_type(self, event) -> EventType:
           operation = event["operation"]
           mapping = {"INSERT": EventType.INSERT,
                      "UPDATE": EventType.UPDATE,
                      "DELETE": EventType.DELETE}
           return mapping.get(operation, EventType.GLOBAL)

       def process_dml_event(self, event, **kwargs):
           return [Record(
               event_type=self.get_event_type(event),
               record=event["row_data"],
               ...
           )]


Further reading
--------------------------

* `Oracle LogMiner documentation <https://docs.oracle.com/en/database/oracle/oracle-database/19/sutil/oracle-logminer-utility.html>`_
* `Oracle GoldenGate <https://www.oracle.com/integration/goldengate/>`_ — enterprise real-time replication solution
* `python-oracledb <https://python-oracledb.readthedocs.io/>`_ — recommended Python connector (replaces cx_Oracle)