Overview

This guide walks through setting up a custom connector for Oracle Database 11g using a pre-built example implementation.

Oracle 11g requires special handling compared to later Oracle versions — the oracledb Python driver must run in thick mode (thin mode only supports Oracle 12.1+), and identifiers are limited to 30 bytes. This example connector handles these constraints and provides a full-mode connector — Monte Carlo connects directly to Oracle to collect metadata, query logs, and run monitors.

This implementation is available as a reference in the mcd-public-resources repository. You can use it as-is or as a starting point for your own customizations.

Feature support

Prerequisites

• A running custom-connector-setup repository — see Custom Connectors for initial setup.
• An Oracle 11g instance with a user that has read access to the schemas and tables you want to monitor.
• The Oracle user must have SELECT privileges on V$SQL for query log collection.
• Network connectivity between your build/deployment environment and the Oracle instance.

Setup

1. Scaffold the connector

Use the create_connector script to scaffold the connector directory. This generates a unique identifier for your connector in manifest.json — this ID is how Monte Carlo distinguishes connector types, so it must be generated per-installation.

python scripts/create_connector.py oracle_db_v11

2. Replace with the example implementation

Clone or download the example from mcd-public-resources and replace the stub files with the pre-built implementation:

cp <path-to-mcd-public-resources>/custom_connectors/oracle_db_v11/connector.py connectors/oracle_db_v11/
cp <path-to-mcd-public-resources>/custom_connectors/oracle_db_v11/Dockerfile.extra connectors/oracle_db_v11/

Add the database driver to connectors/oracle_db_v11/requirements.txt:

oracledb==2.5.1

The Dockerfile.extra installs Oracle Instant Client 19 (required for thick mode). It handles architecture detection for both arm64 and x64 environments. After copying, regenerate the test Dockerfile:

python scripts/generate_test_dockerfile.py

3. Configure credentials

Create connectors/oracle_db_v11/credentials.json using the example as a reference:

{
  "connect_args": {
    "host": "your-oracle-host.example.com",
    "port": 1521,
    "service_name": "XE",
    "user": "monte_carlo",
    "password": "<your-password>"
  }
}

4. Build and run the test suite

Build the test Docker image, then run each test section to validate the connector against your database:

docker compose build

# Verify connection
CONNECTOR=oracle_db_v11 docker compose run --rm test -m connection

# Metadata templates
CONNECTOR=oracle_db_v11 docker compose run --rm test -m metadata

# Custom SQL monitors
CONNECTOR=oracle_db_v11 docker compose run --rm test -m custom_monitors

# Query language prerequisites
CONNECTOR=oracle_db_v11 docker compose run --rm test -m ql_prerequisites

# Metric templates
CONNECTOR=oracle_db_v11 docker compose run --rm test -m ql_metrics

5. Export and build the agent image

Once all tests pass, export capabilities and build the deployable image:

# Export capabilities and passing templates
CONNECTOR=oracle_db_v11 docker compose run --rm test --export

# Build the agent image
python scripts/generate_agent_image.py --connector oracle_db_v11

6. Deploy, register, and connect

From here, follow the standard custom connector workflow:

1. Push the image to your container registry and deploy the agent.
2. Register the connector by running agent validations in the Monte Carlo UI.
3. Add the connection through the UI or API, providing your production Oracle credentials.
4. Validate with monitors by creating test monitors once your tables appear in the catalog.

Oracle 11g-specific notes

This connector includes workarounds for Oracle 11g limitations that are worth understanding if you plan to customize it:

• FROM DUAL injection — Oracle requires a FROM clause on all SELECT statements. The connector automatically appends FROM DUAL to bare SELECT expressions generated by Monte Carlo.
• 30-byte identifier limit — Oracle 11g limits identifiers to 30 bytes. The connector automatically shortens long double-quoted identifiers (e.g., metric aliases) and maps them back to the original names in the result set.
• NLS session configuration — The connector sets NLS_DATE_FORMAT, NLS_TIMESTAMP_FORMAT, and NLS_TIMESTAMP_TZ_FORMAT at session initialization to ensure consistent date handling.