JDBC Source Connector — Oracle

Type

Source

Class

io.aiven.connect.jdbc.JdbcSourceConnector

Target System

Database (Oracle)

Maintainer

Aiven

License

Apache License 2.0

Project

github.com/aiven/jdbc-connector-for-apache-kafka

Download

Maven Central

This page documents version 6.12.0. Newer versions should be compatible unless there are breaking changes, but field names or default values may differ. If you notice discrepancies, please contact Axual Support.
The JDBC Oracle connector requires the Oracle JDBC driver to be placed in the connector’s plugin directory. Select the JAR matching your Java runtime version: ojdbc8.jar for Java 8, ojdbc11.jar for Java 11, or ojdbc17.jar for Java 17+. The driver must be obtained separately from the Oracle JDBC Downloads page.

Description

The JDBC Source Connector for Oracle periodically polls Oracle tables and publishes new or changed rows as records to Kafka topics.

It is maintained by Aiven as part of the open-source github.com/aiven/jdbc-connector-for-apache-kafka.

Features

  • Poll Oracle tables and publish rows to Kafka topics

  • Multiple polling modes: incrementing, timestamp, timestamp+incrementing, and bulk

  • Configurable table whitelist and topic prefix for flexible topic naming

  • Offset tracking ensures rows are not re-published across connector restarts

When to Use

  • You need to periodically ingest rows from an Oracle table into Kafka.

  • Your use case tolerates polling latency — near-real-time is sufficient.

  • You want a simple database integration without CDC operational overhead.

When NOT to Use

  • You need real-time change data capture — use the Debezium Oracle CDC Connector instead.

  • Your database schema changes frequently — this connector does not support schema evolution.

Installation

The connector is available from the Maven Central.

  1. Navigate to the releases page and select the version matching your Kafka Connect installation.

  2. Download the JAR file.

  3. Download the Oracle JDBC driver (ojdbc8.jar for Java 8, ojdbc11.jar for Java 11, or ojdbc17.jar for Java 17+) from the Oracle JDBC Downloads page and add it to the connector plugin directory.

For installation steps, see Installing Connector Plugins.

Configuration

For the complete configuration reference, see the official source connector documentation.

To configure a connector in Axual Self-Service, see Starting Connectors.

Getting Started

Prerequisites

Oracle Database instance

You need a running Oracle Database instance reachable from the Kafka Connect cluster.

Axual stream

The stream where the connector will produce events must already exist in Axual Self-Service. See Creating streams if you need to create it.

Steps

Step 1 — Create a connector application

  1. Follow the Creating streams documentation in order to create one stream and deploy it onto an environment.
    The name of the stream will be oracle_EMPLOYEES.
    The key/value types will be JSON/JSON.

  2. Follow the Configure and install a connector documentation to set up a new Connector-Application.
    Let’s call it my.oracle.source.
    The plugin name is io.aiven.connect.jdbc.JdbcSourceConnector.
    If a plugin isn’t available, ask a platform operator to install plugins.

Step 2 — Configure the connector

  1. Provide the following minimal configuration:

    connector.class

    io.aiven.connect.jdbc.JdbcSourceConnector

    connection.url

    jdbc:oracle:thin:@//123.123.123.123:1521/ORCLPDB1
    Replace with your Oracle host and service name.

    connection.user

    system

    connection.password

    Your database password

    mode

    incrementing

    incrementing.column.name

    EMPLOYEE_ID
    The primary key column.

    table.whitelist

    EMPLOYEES
    Case-sensitive.

    topic.prefix

    oracle_

    value.converter

    org.apache.kafka.connect.json.JsonConverter

    value.converter.schemas.enable

    true

    For advanced options, see the official source connector documentation.

Step 3 — Start the connector

Start the connector application from Axual Self-Service.

Step 4 — Verify

In Axual Self-Service, use stream-browse on oracle_EMPLOYEES to confirm events are arriving.

Cleanup

When you are done:

  1. Stop the connector application in Axual Self-Service.

  2. Remove stream access for the application if no longer needed.

Known limitations

  • The Oracle JDBC driver must be manually provided — it is not bundled with the connector. Use ojdbc8.jar for Java 8, ojdbc11.jar for Java 11, or ojdbc17.jar for Java 17+.

  • table.whitelist values are case-sensitive — the table name must match exactly as it appears in Oracle.

  • Schema evolution is not supported — changes to the source table schema require manual reconfiguration.

Examples

Minimal configuration

{
  "name": "my-jdbc-oracle-source",
  "config": {
    "connector.class": "io.aiven.connect.jdbc.JdbcSourceConnector",
    "connection.url": "jdbc:oracle:thin:@//oracle.example.com:1521/ORCLPDB1",
    "connection.user": "system",
    "connection.password": "<your-database-password>",
    "mode": "incrementing",
    "incrementing.column.name": "EMPLOYEE_ID",
    "table.whitelist": "EMPLOYEES",
    "topic.prefix": "oracle_",
    "value.converter": "org.apache.kafka.connect.json.JsonConverter",
    "value.converter.schemas.enable": "true"
  }
}

License

Oracle JDBC Connector is licensed under the Apache License, Version 2.0.