Implementation:Mage ai Mage ai OracleDB Source

Knowledge Sources	Mage Integrations Oracle Database
Domains	Data_Integration, OracleDB, Source_Connector, SQL_Based
Last Updated	2026-02-09 00:00 GMT

Overview

Concrete tool for extracting data from Oracle Database tables provided by the Mage integrations source connector framework.

Description

The OracleDB source connector extends the SQL-based Source class (mage_integrations.sources.sql.base.Source) to implement data extraction from Oracle Database. It connects through an OracleDBConnection wrapper using host, port, service name, username, password, and an optional mode (thin or thick client). Discovery queries Oracle's all_tab_columns, all_cons_columns, and all_constraints views via a CTE to enumerate tables, columns, data types, nullability, and constraint information (primary keys and unique constraints). System schemas (SYS, SYSTEM, MDSYS, etc.) are explicitly excluded. Duplicate column entries are deduplicated using ROW_NUMBER(). Column names in SQL queries are wrapped in double quotes via update_column_names(). The connector provides Oracle-specific pagination using OFFSET ... ROWS FETCH NEXT ... ROWS ONLY syntax. Datetime comparison statements use Oracle's TO_DATE and TO_TIMESTAMP functions with appropriate format masks, supporting multiple datetime formats (date-only, datetime with microseconds, and ISO 8601 with T separator). The test_connection() method executes SELECT name FROM v$database to verify connectivity, with proper cursor and connection cleanup in a finally block. Non-datetime comparison values use CAST for type safety.

Usage

Use this source connector when building a Mage data pipeline that needs to extract data from Oracle Database. Configure with host, port, service, user, password, and optionally mode (defaults to thin).

Code Reference

Source Location

Repository: mage-ai
File: mage_integrations/mage_integrations/sources/oracledb/__init__.py
Lines: 1-152

Signature

class OracleDB(Source):
    @property
    def host(self) -> str:
        ...
    @property
    def port(self) -> str:
        ...
    @property
    def service(self) -> str:
        ...
    @property
    def user(self) -> str:
        ...
    @property
    def password(self) -> str:
        ...
    @property
    def mode(self) -> str:
        ...
    def update_column_names(self, columns: List[str]) -> List[str]:
        ...
    def build_discover_query(self, streams: List[str] = None):
        ...
    def build_connection(self) -> OracleDBConnection:
        ...
    def test_connection(self):
        ...
    def convert_datetime(self, value: str) -> str:
        ...
    def _build_comparison_statement(self, col, val, properties, operator='=') -> str:
        ...
    def _limit_query_string(self, limit, offset, **kwargs):
        ...

Import

from mage_integrations.sources.oracledb import OracleDB

I/O Contract

Inputs

Name	Type	Required	Description
config	dict	Yes	Configuration dictionary with Oracle Database connection settings
catalog	Catalog	No	Singer catalog specifying streams to extract
state	dict	No	Previous sync state for incremental extraction

Configuration Parameters

Name	Type	Required	Description
host	str	Yes	Oracle database host address
port	str	Yes	Oracle database port number
service	str	Yes	Oracle service name
user	str	Yes	Database username
password	str	Yes	Database password
mode	str	No	Connection mode: 'thin' (default) or 'thick'

Outputs

Name	Type	Description
catalog	Catalog	Discovered tables with schemas from Oracle data dictionary views (from discover())
records	Generator[List[Dict]]	Batches of extracted records via SQL queries (inherited from SQL base Source)

Usage Examples

from mage_integrations.sources.oracledb import OracleDB

config = {
    "host": "oracle.example.com",
    "port": "1521",
    "service": "ORCL",
    "user": "admin",
    "password": "password123",
    "mode": "thin",
}

source = OracleDB(config=config)

# Discover available streams
catalog = source.discover()

# Test connection
source.test_connection()

Related Pages

Implements Principle

Requires Environment

Environment:Mage_ai_Mage_ai_Python_3_9_Runtime

Page Connections

Double-click a node to navigate. Hold to expand connections.

Principle

Implementation

Heuristic

Environment