Oracle

Connect Oracle as a source for an initial full load and redo-log CDC into operational state or analytics targets. Complete the database preparation that matches the read mode you plan to use.

Before you begin

Connector availability and licensing

The Oracle connector artifact bundles ojdbc8, orai18n, and xdb under the Oracle Free Use Terms; commercial connector use remains subject to the applicable agreement. It is distributed as an official preview artifact separate from the base server image. Before applying Oracle connections on a new or upgraded server, register the connector:

connectors
register oracle

In production and air-gapped environments, you can also mount the connector JAR into TAPSTATE_CONNECTORS_SEED_DIR for automatic boot-time registration. See When registration is required.

Source

Choose the outcome you need. Each tab is a complete preparation path; you do not need to combine steps from both tabs.

CREATE USER tapstate IDENTIFIED BY "replace-with-a-secret";
GRANT CREATE SESSION TO tapstate;
GRANT SELECT ON V_$DATABASE TO tapstate;

GRANT SELECT ON app_schema.orders TO tapstate;
GRANT SELECT ON app_schema.customers TO tapstate;

CREATE USER tapstate IDENTIFIED BY "replace-with-a-secret";

GRANT CREATE SESSION,
      ALTER SESSION,
      EXECUTE_CATALOG_ROLE,
      SELECT ANY DICTIONARY,
      SELECT ANY TRANSACTION,
      SELECT ANY TABLE
TO tapstate;

GRANT SELECT ON V_$DATABASE TO tapstate;

-- Oracle 12c and later
GRANT LOGMINING TO tapstate;

SELECT LOG_MODE FROM V$DATABASE;

SHUTDOWN IMMEDIATE;
STARTUP MOUNT;
ALTER DATABASE ARCHIVELOG;
ALTER DATABASE OPEN;

-- Minimal supplemental logging at database level:
ALTER DATABASE ADD SUPPLEMENTAL LOG DATA;

-- Identification logging on replicated tables:
ALTER TABLE app_schema.orders
  ADD SUPPLEMENTAL LOG DATA (ALL) COLUMNS;

ALTER SYSTEM SWITCH LOGFILE;

Create a connection

Tapstate stores each Oracle connection as a .tap.yml file in the workspace.

Create tapstate-work/source/orders_oracle.tap.yml. For a full-load-only source, use mode: snapshot; for CDC, use mode: cdc.

version: tapstate/v1
kind: source
id: orders_oracle
connector: oracle
config:
  host: oracle.internal
  port: 1521
  thinType: SERVICE_NAME
  database: ${ORACLE_SERVICE_NAME}
  schema: APP_SCHEMA
  user: ${ORACLE_READER_USER}
  password: ${ORACLE_READER_PASSWORD}
mode: cdc
tables:
  - ORDERS
  - /CUSTOMERS_.*/

For Oracle 23c (Free), specify autoLog: false in config because the automatic LogMiner requests CONTINUOUS_MINE, which is unsupported in Oracle 23c. In addition, ensure schema, table, and column identifiers remain within 30 characters; v0.6 refuses unsupported LogMiner identifiers before capture starts. This LogMiner check does not apply to a full-load-only read.

Connect Oracle source to an operational target such as MongoDB:

version: tapstate/v1
kind: pipeline
id: orders_to_operational_state
source: orders_oracle
serve:
  from: /.*/
  sync:
    - id: write_operational_state
      source: operational_state
      write_mode: upsert
      ddl: fail

Oracle is certified as a source in the current product path. Writing to Oracle as a pipeline sync target is not supported.

Validate the configuration

tapstate validate --workdir tapstate-work

Validation does not resolve the host, credentials, or an Oracle server. To verify the connection against the database, register the Oracle connector, apply the workspace, and run test:

tapstate -w tapstate-work

connect http://127.0.0.1:8080
login admin
register oracle -o json
apply
test orders_oracle -o json

Use a staging schema to verify:

1. table discovery and a small snapshot;
2. an insert, update, and delete through CDC;
3. a log switch while the task is running;
4. restart from the saved redo position;
5. representative NUMBER, timestamp, LOB, and empty-string values.

These checks help confirm the database-side prerequisites without changing them:

SELECT LOG_MODE, SUPPLEMENTAL_LOG_DATA_MIN
FROM V$DATABASE;

SELECT DEST_NAME, STATUS, DESTINATION
FROM V$ARCHIVE_DEST_STATUS
WHERE STATUS <> 'INACTIVE';

SELECT RESOURCE_NAME, LIMIT
FROM DBA_PROFILES
WHERE PROFILE = (SELECT PROFILE FROM DBA_USERS WHERE USERNAME = 'TAPSTATE')
  AND RESOURCE_NAME = 'CONNECT_TIME';

Limitations

• LogMiner capture refuses schema, table, and column names longer than 30 characters before starting. Review the reported identifier or use an appropriate capture mode; a successful snapshot does not prove LogMiner CDC can start.
• INTERVAL and XMLTYPE are not supported by the LogMiner baseline. The direct raw-log baseline does not support TIMESTAMP WITH LOCAL TIME ZONE.
• Oracle empty strings become NULL. A source NOT NULL string column can therefore fail when written to Oracle if the source contains empty strings.
• DDL and a large burst of DML on the same table can make dictionary reconstruction unreliable. Stage schema changes separately from heavy write windows when possible.
• RAC LogMiner capture can produce duplicate events during recovery. Downstream writes need stable keys and idempotent handling, especially for tables without primary keys.
• Oracle 19c LogMiner scans online redo together with archived logs. In RAC, it must follow multiple redo threads; large redo logs and uneven archiving can increase incremental-read latency.
• Large or long-running uncommitted transactions retain mining state. After a restart, recovery can resume from the earliest uncommitted SCN and replay already-seen events, so the destination must handle them idempotently.
• Virtual columns require staging with representative changes. If their incremental values cannot be reproduced reliably, pre-create the target shape or exclude the virtual expression from the replicated contract.
• Archive-log exhaustion stops recoverable CDC. Monitor the recovery area and long-running or uncommitted transactions.
• A restrictive profile CONNECT_TIME can terminate the mining session and interrupt CDC. Use a service-account profile that matches the pipeline's expected lifetime.
• Partition-table DML can be captured, but adding partitions is not part of the documented DDL baseline.
• Configure Oracle Net encryption according to your environment and use the connection settings supplied by your tapstate deployment.

Reference

Connection settings

The documented current source path uses the fields below.

Additional catalog fields

The catalog recognizes the fields below for advanced or deployment-specific connectivity:

Database-side reference

This table summarizes Oracle behavior for the connector. Verify uncommon types and deployment-specific capture paths with representative data before migration.

Data compatibility

Method-specific source exclusions are listed in Limitations.