Overview

This guide walks through setting up a custom connector for CockroachDB using a pre-built example implementation.

CockroachDB is a distributed SQL database compatible with the PostgreSQL wire protocol. This example connector uses psycopg2 as its database driver and implements a full-mode connector — Monte Carlo connects directly to CockroachDB 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.
• A CockroachDB cluster with a user that has read access to the databases and tables you want to monitor.
• The CockroachDB user must have the VIEWACTIVITY privilege for query log collection (access to crdb_internal.statement_statistics).

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 cockroach_db

2. Replace with the example implementation

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

cp <path-to-mcd-public-resources>/custom_connectors/cockroach_db/connector.py connectors/cockroach_db/

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

psycopg2-binary==2.9.9

No Dockerfile.extra is needed — psycopg2-binary has no system-level dependencies.

3. Configure credentials

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

{
  "connect_args": {
    "host": "your-cockroachdb-host.example.com",
    "port": 26257,
    "database": "defaultdb",
    "user": "monte_carlo",
    "password": "<your-password>",
    "sslmode": "require"
  }
}

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=cockroach_db docker compose run --rm test -m connection

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

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

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

# Metric templates
CONNECTOR=cockroach_db 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=cockroach_db docker compose run --rm test --export

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

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 CockroachDB credentials.
4. Validate with monitors by creating test monitors once your tables appear in the catalog.