> ## Documentation Index
> Fetch the complete documentation index at: https://docs.popsink.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Oracle Source

The Oracle Source Connector is an advanced tool designed to synchronize Oracle databases with Popsink efficiently and in real-time. It enables the real-time transfer of data, ensuring that the latest database changes are mirrored to the target systems. This capability is crucial for maintaining up-to-date business intelligence, enabling real-time analytics, and enhancing operational workflows.

## Compatible versions

| | |
| - | - |
| **Oracle Database** | 19c, 21c, 23ai, 26ai |
| **Capture method** | LogMiner (default), LogMiner unbuffered, or XStream Out — see [Choosing a capture adapter](#choosing-a-capture-adapter) |
| **Deployments** | Single instance and RAC; multitenant (CDB/PDB) and non-CDB |
| **Managed services** | Amazon RDS for Oracle, Oracle Base Database Service (OCI) |
| **CDC engine** | Debezium 3.5 |

<Note>Oracle 12c and 11g are not supported. On 23ai and 26ai, capture is available through LogMiner only — XStream is validated on 19c and 21c.</Note>

## **Prerequisites**

Before deploying the Oracle Source Connector, certain prerequisites must be met to ensure a smooth integration process:

1. **Allowlisting Popsink's IP address**: Ensure that Popsink's egress IP is allowed through the database firewall, so communication between the Oracle database and Popsink is uninterrupted. The per-region addresses are listed in [Egress IP addresses](/deployment/connectivity/egress-ips).
2. **Database Log Mode Configuration**: The Oracle database Archive Mode should be set to ArchiveLog.
3. **Supplemental Logging**: Supplemental Logs should be enable on the source you wish to replicate. This can me done at Database or Table Level :

   * At Database Level

   ```sql theme={null}
   ALTER DATABASE ADD SUPPLEMENTAL LOG DATA;
   ```

   * At Table Level

   ```sql theme={null}
   ALTER TABLE **{db.name}** ADD SUPPLEMENTAL LOG DATA (ALL) COLUMNS;
   ```

   > Note: If using AWS RDS, additional steps may be required. Please consult the relevant AWS RDS documentation and do feel free to reach out for help.

These three prerequisites apply to every capture adapter. XStream Out has additional requirements, described in [XStream Out configuration](#xstream-out-configuration).

## Choosing a capture adapter

The connector can read changes in three different ways. All three produce the same events on the Popsink side — they differ in what they cost the source database and in what they require from your DBA.

| Adapter | How it captures | When to choose it |
| - | - | - |
| **LogMiner** *(default)* | Mines the online and archived redo logs through `DBMS_LOGMNR`, and buffers open transactions inside the connector until they commit | The default, and the right answer for most sources. No extra licence, and it works on every supported deployment |
| **LogMiner unbuffered** | Mines the same redo logs, but Oracle only hands back committed data, so the connector keeps no transaction buffer of its own | Sources with very large or long-running transactions, or long catch-ups after an outage, where the buffered adapter runs out of memory. It trades connector memory for more work on the source |
| **XStream Out** | Reads logical change records (LCRs) from an XStream outbound server | Lowest latency, no mining load on the source, and no redo re-reading on catch-up. Requires an Oracle GoldenGate licence and an outbound server created by your DBA |

<Info>LogMiner is the adapter every Oracle connector runs today. **LogMiner unbuffered** and **XStream** are being rolled out — get in touch with Popsink before you plan a migration to either one, so we can confirm availability on your data plane and size the change with you.</Info>

<Note>XStream is a licensed Oracle GoldenGate feature. Using it without a GoldenGate licence is a licence violation — confirm your entitlement with Oracle before enabling it. On managed services such as Amazon RDS for Oracle, check with your provider that `DBMS_XSTREAM_ADM` and outbound servers are available on your instance class.</Note>

<Warning>The adapter is chosen when the connector is created. LogMiner records its position as an SCN, while XStream records it as an LCR position, so moving an existing connector to or from XStream loses its position and requires a re-seed. Switching between the two LogMiner adapters is safe.</Warning>

## **Required Permissions**

Although you *could* use a **`superuser`**, we do recommend setting up dedicated users for security reasons. The user account that the Oracle Source Connector utilizes must have sufficient privileges. The following SQL statements outline the necessary permissions for both LogMiner adapters:

```sql theme={null}
GRANT CREATE SESSION TO {username} CONTAINER=ALL;
GRANT SET CONTAINER TO {username} CONTAINER=ALL;
GRANT SELECT ON V_$DATABASE to {username} CONTAINER=ALL;
GRANT FLASHBACK ANY TABLE TO {username} CONTAINER=ALL;
GRANT SELECT ANY TABLE TO {username} CONTAINER=ALL;
GRANT SELECT_CATALOG_ROLE TO {username} CONTAINER=ALL;
GRANT EXECUTE_CATALOG_ROLE TO {username} CONTAINER=ALL;
GRANT SELECT ANY TRANSACTION TO {username} CONTAINER=ALL;
GRANT LOGMINING TO {username} CONTAINER=ALL;
GRANT CREATE TABLE TO {username} CONTAINER=ALL;
GRANT LOCK ANY TABLE TO {username} CONTAINER=ALL;
GRANT CREATE SEQUENCE TO {username} CONTAINER=ALL;
GRANT EXECUTE ON DBMS_LOGMNR TO {username} CONTAINER=ALL;
GRANT EXECUTE ON DBMS_LOGMNR_D TO {username} CONTAINER=ALL;
GRANT SELECT ON V_$LOG TO {username} CONTAINER=ALL;
GRANT SELECT ON V_$LOG_HISTORY TO {username} CONTAINER=ALL;
GRANT SELECT ON V_$LOGMNR_LOGS TO {username} CONTAINER=ALL;
GRANT SELECT ON V_$LOGMNR_CONTENTS TO {username} CONTAINER=ALL;
GRANT SELECT ON V_$LOGMNR_PARAMETERS TO {username} CONTAINER=ALL;
GRANT SELECT ON V_$LOGFILE TO {username} CONTAINER=ALL;
GRANT SELECT ON V_$ARCHIVED_LOG TO {username} CONTAINER=ALL;
GRANT SELECT ON V_$ARCHIVE_DEST_STATUS TO {username} CONTAINER=ALL;
GRANT SELECT ON V_$TRANSACTION TO {username} CONTAINER=ALL;
```

Replace **`{username}`** with the actual username being used for the connection.

If you selected the XStream adapter, grant the privileges described in [XStream Out configuration](#xstream-out-configuration) instead — the `DBMS_LOGMNR` and `LOGMINING` grants above are not needed.

## XStream Out configuration

This section is only relevant if you chose the **XStream** adapter. Everything here is done by your DBA on the source database, before the connector is created. Popsink connects to the outbound server you create here; the Oracle Instant Client and XStream libraries the connector needs are part of the Popsink image, so there is nothing to install on your side.

The examples use two accounts, following Oracle's own separation of duties:

* an **XStream administrator** (`c##popsinkadmin`) that creates and owns the outbound server,
* the **connect user** (`c##popsinkuser`) that Popsink authenticates as and that attaches to the outbound server.

On a non-CDB database, drop the `c##` prefix and the `CONTAINER=ALL` clauses.

### 1. Enable GoldenGate replication

XStream requires the GoldenGate replication parameter, alongside the ArchiveLog mode and supplemental logging already covered in the [prerequisites](#prerequisites).

```sql theme={null}
ALTER SYSTEM SET ENABLE_GOLDENGATE_REPLICATION=TRUE SCOPE=BOTH;
```

### 2. Create the XStream administrator

```sql theme={null}
CREATE TABLESPACE xstream_adm_tbs
  DATAFILE '/opt/oracle/oradata/ORCLCDB/xstream_adm_tbs.dbf'
  SIZE 25M REUSE AUTOEXTEND ON MAXSIZE UNLIMITED;

CREATE USER c##popsinkadmin IDENTIFIED BY {password}
  DEFAULT TABLESPACE xstream_adm_tbs
  QUOTA UNLIMITED ON xstream_adm_tbs
  CONTAINER=ALL;

GRANT CREATE SESSION, SET CONTAINER TO c##popsinkadmin CONTAINER=ALL;

BEGIN
  DBMS_XSTREAM_AUTH.GRANT_ADMIN_PRIVILEGE(
    grantee                 => 'c##popsinkadmin',
    privilege_type          => 'CAPTURE',
    grant_select_privileges => TRUE,
    container               => 'ALL');
END;
/
```

### 3. Create the connect user

This is the user whose credentials you enter in the Popsink form.

```sql theme={null}
CREATE TABLESPACE xstream_tbs
  DATAFILE '/opt/oracle/oradata/ORCLCDB/xstream_tbs.dbf'
  SIZE 25M REUSE AUTOEXTEND ON MAXSIZE UNLIMITED;

CREATE USER c##popsinkuser IDENTIFIED BY {password}
  DEFAULT TABLESPACE xstream_tbs
  QUOTA UNLIMITED ON xstream_tbs
  CONTAINER=ALL;

GRANT CREATE SESSION TO c##popsinkuser CONTAINER=ALL;
GRANT SET CONTAINER TO c##popsinkuser CONTAINER=ALL;
GRANT SELECT ON V_$DATABASE TO c##popsinkuser CONTAINER=ALL;
GRANT FLASHBACK ANY TABLE TO c##popsinkuser CONTAINER=ALL;
GRANT SELECT ANY TABLE TO c##popsinkuser CONTAINER=ALL;
GRANT SELECT_CATALOG_ROLE TO c##popsinkuser CONTAINER=ALL;
GRANT EXECUTE_CATALOG_ROLE TO c##popsinkuser CONTAINER=ALL;
```

### 4. Create the outbound server

Connect as the XStream administrator — **to the CDB root** on a multitenant deployment — and create one outbound server per connector. List the schemas or tables you intend to replicate; the outbound server only forwards changes for what it captures, so it acts as a first, server-side filter.

```sql theme={null}
DECLARE
  tables  DBMS_UTILITY.UNCL_ARRAY;
  schemas DBMS_UTILITY.UNCL_ARRAY;
BEGIN
  tables(1)  := NULL;
  schemas(1) := 'SALES';
  schemas(2) := NULL;
  DBMS_XSTREAM_ADM.CREATE_OUTBOUND(
    server_name  => 'POPSINK_OUT',
    table_names  => tables,
    schema_names => schemas);
END;
/
```

Then hand the outbound server to the connect user, so Popsink can attach to it:

```sql theme={null}
BEGIN
  DBMS_XSTREAM_ADM.ALTER_OUTBOUND(
    server_name  => 'POPSINK_OUT',
    connect_user => 'c##popsinkuser');
END;
/
```

<Note>On a multitenant database, the outbound server lives in the CDB root while the tables live in a PDB. Give Popsink the PDB in the connector form, and make sure the schemas you listed above are the ones in that PDB.</Note>

### 5. Verify the setup

```sql theme={null}
SELECT server_name, capture_name, connect_user, source_database
  FROM dba_xstream_outbound;

SELECT server_name, state FROM v$xstream_outbound_server;
```

The outbound server must exist, be attached to the connect user, and be in a running state before the connector is created. Popsink's **Check Credentials** step runs these checks for you and reports a clear error if the outbound server is missing or disabled.

## Steps

Go to: **[Sources](https://app.popsink.com/sources) -**> [**Create New**](https://app.popsink.com/sources/add) then select the **Oracle** connector and **Continue**

In the *Credentials* sections fill in the required information.

### **`host`**

* **Description**: The hostname or IP address of the Oracle database server.
* **Type**: **`string`**
* **Example**: **`oracle-db-server.example.com`**

### **`port`**

* **Description**: The port number on which the Oracle database server is listening.
* **Type**: **`integer`**
* **Default**: **`1521`** (default port for Oracle database)
* **Example**: **`1521`**

### **`user`**

* **Description**: The username used to connect to the Oracle database.
* **Type**: **`string`**
* **Example**: **`popsink_user`**

### **`password`**

* **Description**: The password associated with the specified user for authentication.
* **Type**: **`string`**
* **Example**: **`p@ssw0rd123`**

### **`service_name`** or **`sid`**

Provide **exactly one** of the two:

* **`service_name`**: The Oracle service name to connect to.
  * **Type**: **`string`**
  * **Example**: **`ORCLPDB1`**
* **`sid`**: The Oracle System Identifier, for legacy databases that are not service-name addressable.
  * **Type**: **`string`**
  * **Example**: **`ORCL`**

### Advanced Options

| Field | Default | Description |
| - | - | - |
| **Adapter** | `LogMiner` | How changes are captured: `LogMiner`, `LogMiner unbuffered` or `XStream` — see [Choosing a capture adapter](#choosing-a-capture-adapter) |
| **XStream Outbound Server** | — | Name of the outbound server created with `DBMS_XSTREAM_ADM.CREATE_OUTBOUND`, for example `POPSINK_OUT`. Required with the XStream adapter, and ignored otherwise |
| **Poll Interval (ms)** | `2000` | How often the connector polls for new redo log activity. LogMiner adapters only |
| **Initial Load** | `true` | Snapshot existing rows before streaming changes |

## Connecting through an SSH Tunnel

If the database is only reachable through a bastion host, enable **SSH Tunnel** and provide:

| Field | Required | Description |
| - | - | - |
| **SSH Host** | Yes | Hostname or IP of the bastion host |
| **SSH Port** | Yes | SSH port (default `22`) |
| **SSH User** | Yes | User to authenticate as on the bastion |
| **SSH Private Key** | Yes | **Base64-encoded** private key for the SSH user |

The **Host** and **Port** above stay as the database is addressed *from the
bastion*. For key generation, bastion hardening and the other connectivity
options (IPsec VPN, Tailscale), see
[Tunnels and private connectivity](/deployment/connectivity/tunnels).

### Table Selection

After a successful credential check, pick the tables to replicate from the discovered list. The selection is stored as a comma-separated whitelist in `SCHEMA.TABLE` format.

With the XStream adapter, this selection is applied on top of what the outbound server already captures: a table that the outbound server does not capture never reaches the connector, whatever you select here.

You can use **Check Credentials** at any moment to verify the validity of your inputs.

Once the validity check has passed, the next step is the standard *Informations* page where you may give the connector a name and select which of your teams should own this connector.

Create the connector and you are now done. The connector may take a few minutes to synchronize with the source database.

## **Conclusion**

The Oracle Source Connector is an essential component for creating a reliable data pipeline between Oracle databases and Popsink. By following the guidelines provided in this document, you can ensure a successful setup and enjoy a robust, real-time data integration experience.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.