> For the complete documentation index, see [llms.txt](https://developer.harness.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://developer.harness.io/database-devops/setup-db-devops/jdbc-connection-string/set-up-connectors.md).

# Setting Up JDBC Connectors

This topic describes how to set up JDBC Connectors within Harness DB DevOps.

### Set up JDBC connectors <a href="#set-up-jdbc-connectors" id="set-up-jdbc-connectors"></a>

#### JDBC connectors <a href="#jdbc-connectors" id="jdbc-connectors"></a>

A JDBC connector connects Harness to your database instance. The connector accepts the following:

* **JDBC URL**: The database URL (**string**)
* **Username**: Username (**string / secret**)
* **Password**: Password (**secret**)

It performs a test connection using a delegate with a delegate selector or any available delegate. Ensure the delegate has network access to the database.

The JDBC connector is used for connecting to your database instance.

{% embed url="<https://app.tango.us/app/embed/88d2d030-448f-473a-a73f-889de8f0621b?skipCover=false&defaultListView=false&skipBranding=true&makeViewOnly=true&hideAuthorAndDetails=true>" %}
Create JDBC Connector in Harness
{% endembed %}

**URL examples**

| Database            | JDBC URL Format                                                                                                                      |
| ------------------- | ------------------------------------------------------------------------------------------------------------------------------------ |
| **ORACLE**          | `jdbc:oracle:thin:@//{host}:{port}/{servicename}`                                                                                    |
| **POSTGRES**        | `jdbc:postgresql://{host}:{port}/{dbName}?sslmode=disable`                                                                           |
| **COCKROACHDB**     | `jdbc:postgresql://{host}:{port}/{dbName}`                                                                                           |
| **SQLSERVER**       | `jdbc:sqlserver://{host}:{port};trustServerCertificate=true;databaseName={dbName}`                                                   |
| **MYSQL**           | `jdbc:mysql://{host}:{port}/{dbName}`                                                                                                |
| **MONGODB**         | `mongodb://{host}:{port}/{dbName}?authSource=admin`                                                                                  |
| **MongoDB Atlas**   | `mongodb+srv://{username}:{password}@{cluster}/{dbName}?authSource=admin`                                                            |
| **GOOGLE SPANNER**  | `jdbc:cloudspanner:/projects/{project-id}/instances/{instance-id}/databases/{database-name}?lenient=true`                            |
| **GOOGLE ALLOYDB**  | `jdbc:postgresql://{host}:{port}/{dbName}`                                                                                           |
| **SNOWFLAKE**       | `jdbc:snowflake://{host}/?warehouse={wh}&db={dbName}&schema={dbSchema}&role={authRole}`                                              |
| **MongoDB SSL**     | `mongodb://{host}:{port}/{dbName}?tls=true&authSource=admin`                                                                         |
| **POSTGRES SSL**    | `jdbc:postgresql://{host}:{port}/{dbName}?ssl=true`                                                                                  |
| **SQLSERVER SSL**   | `jdbc:sqlserver://{host}:{port};databaseName={dbName};encrypt=true;trustServerCertificate=false;`                                    |
| **MYSQL SSL**       | `jdbc:mysql://{host}:{port}/{dbName}?useSSL=true`                                                                                    |
| **ORACLE SSL**      | `jdbc:oracle:thin:@(DESCRIPTION=(ADDRESS=(PROTOCOL=TCPS)(HOST={host})(PORT={port}))(CONNECT_DATA=(SERVICE_NAME={servicename})))`     |
| **COCKROACHDB SSL** | `jdbc:postgresql://{host}:{port}/{dbName}?sslmode=require`                                                                           |
| **DocumentDB**      | `mongodb://{host}:{port}/{dbName}?tls=true&tlsAllowInvalidHostnames=true&directConnection=true&retryWrites=false&authSource=admin`   |
| **BIGQUERY**        | `jdbc:bigquery://https://www.googleapis.com/bigquery/v2:443;ProjectId={project-id};DefaultDataset={dataset-name};Location={region};` |
| **DB2 LUW**         | `jdbc:db2://{host}:50000/{dbName}`                                                                                                   |
| **DB2 LUW SSL**     | `jdbc:db2://{host}:50000/{dbName}?sslConnection=true`                                                                                |
| **DB2 for i**       | `jdbc:as400://{host}/{library};translate binary=true;date format=iso`                                                                |
| **DB2 z/OS**        | `jdbc:db2://{host}:446/{locationName}`                                                                                               |
| **DB2 z/OS SSL**    | `jdbc:db2://{host}:446/{locationName}?sslConnection=true`                                                                            |

***

### Set up MongoDB connectors <a href="#set-up-mongodb-connectors" id="set-up-mongodb-connectors"></a>

MongoDB connections in Harness DB DevOps support both self-hosted and cloud-based MongoDB instances.

#### Prerequisites for MongoDB <a href="#prerequisites-for-mongodb" id="prerequisites-for-mongodb"></a>

Configure the following before connecting:

1. **Connection format:**
   * Use `mongodb+srv://` for MongoDB Atlas and cloud instances.
   * Use `mongodb://` for self-hosted instances.
2. **Authentication**:
   * **Username/password:** Database user credentials
   * **authSource:** Must be specified (typically `admin`)
   * **Database:** Target database name must be included in the URL
3. **Network access:**
   * Ensure the delegate has network connectivity to the MongoDB cluster
   * For MongoDB Atlas, whitelist the delegate's IP address

#### MongoDB URL requirements <a href="#mongodb-url-requirements" id="mongodb-url-requirements"></a>

The following requirements apply when constructing your MongoDB connection string:

* The connection string **must** include `+srv` for cloud instances
* The target `database` must be specified in the URL path
* The database user must have appropriate read/write permissions on the target database

***

### Set up Google Spanner connectors <a href="#set-up-google-spanner-connectors" id="set-up-google-spanner-connectors"></a>

Google Spanner uses a unique JDBC URL format and does not require a traditional password for authentication. Instead, authentication is handled via Google Service Account (GSA) credentials or Keyless authentication.

#### Prerequisites for Google Spanner <a href="#prerequisites-for-google-spanner" id="prerequisites-for-google-spanner"></a>

Harness DB DevOps supports two authentication methods for Google Spanner:

1. **Google Service Account (GSA)** json key file authentication.
   * Provide a Google Service Account (GSA) JSON key
   * The service account must have the following IAM roles:
     * `roles/spanner.databaseAdmin`
     * `roles/spanner.databaseUser`
2. **Keyless Authentication** using Workload Identity Federation (WIF) or other supported methods.

   * Uses Workload Identity (GKE) or IAM-based authentication
   * No JSON key is required
   * The Harness Delegate inherits permissions via the mapped **Kubernetes Service Account (KSA)** mapped to a **Google Service Account (GSA)**.

   Requirements:

   * Configure IAM binding between the KSA (used by the delegate) and the GSA with the same roles:
     * `roles/spanner.databaseAdmin`
     * `roles/spanner.databaseUser`

{% hint style="info" %}
**NOTE**

**Why use keyless authentication?** This approach improves security by eliminating long-lived credentials and reducing operational overhead.
{% endhint %}

{% hint style="warning" %}
**POSTGRESQL NOT SUPPORTED FOR SPANNER**

The PostgreSQL dialect for Spanner is not currently supported and will cause pipeline failures with an image pull error. Use the standard Cloud Spanner GQL.
{% endhint %}

***

### Set up AlloyDB connectors <a href="#set-up-alloydb-connectors" id="set-up-alloydb-connectors"></a>

AlloyDB connections in Harness DB DevOps require a **Host**, **Port**, and **Database**. The username and password are also required for authentication.

#### Prerequisites for AlloyDB <a href="#prerequisites-for-alloydb" id="prerequisites-for-alloydb"></a>

Configure the following before connecting to AlloyDB:

1. **Connection format:** Use `jdbc:postgresql://{HOST}:{PORT}/{DBNAME}` for AlloyDB instances.
2. **Authentication:** Database user credentials (username and password).
3. **Network access:**
   * Ensure the Harness Delegate has network connectivity to the AlloyDB instance. (Both are in same VPC, which is also default behavior in GCP).

***

### Set up Snowflake connectors <a href="#set-up-snowflake-connectors-setting-up-snowflake" id="set-up-snowflake-connectors-setting-up-snowflake"></a>

Snowflake connections in Harness DB DevOps require a specific JDBC URL format that includes the account identifier, warehouse, database, schema, and role. If the role is not specified, the default role for the user will be used. In addition, PKI authentication is required to authenticate to Snowflake.

#### Prerequisites for Snowflake <a href="#prerequisites-for-snowflake" id="prerequisites-for-snowflake"></a>

To connect to Snowflake, you need to provide the following information:

* **PKI Authentication**: Use Public Key Infrastructure (PKI) authentication by providing the username, private key file reference, and an optional private key passphrase reference while configuring the JDBC connector.

The private key file reference is a secret file, and the passphrase reference is a secret text. If your private key is encrypted, you can provide the passphrase to decrypt it. For example:

```
"username": "john_doe",
         "privateKeyFileRef": "snowflake-trial-private-key",
         "privateKeyPassphraseRef": "snowflake-trial-passphrase"
```

{% hint style="info" %}
**NOTE**

Username and Password authentication method for the snowflake is deprecated, and The preferred method for service accounts using public/private key cryptography.
{% endhint %}

***

### Set up Amazon DocumentDB connectors <a href="#set-up-amazon-documentdb-connectors" id="set-up-amazon-documentdb-connectors"></a>

Amazon DocumentDB is supported via the **MongoDB Native Executor**. DocumentDB clusters run in private VPC subnets and require an SSH tunnel through an EC2 instance for external access.

#### Prerequisites for DocumentDB <a href="#prerequisites-for-documentdb" id="prerequisites-for-documentdb"></a>

Before connecting to DocumentDB, ensure you have the following:

* **DocumentDB cluster**: Running cluster in AWS VPC
* **EC2 instance**: Instance in the same VPC as your DocumentDB cluster with SSH access enabled (port 22)
* **Amazon RDS CA certificate**: [Download the global bundle](https://truststore.pki.rds.amazonaws.com/global/global-bundle.pem)
* **Network access**: Delegate must have SSH connectivity to the EC2 instance

#### Set up the SSH tunnel <a href="#set-up-the-ssh-tunnel" id="set-up-the-ssh-tunnel"></a>

Establish an SSH tunnel from your delegate to DocumentDB via the EC2 instance:

```bash
ssh -L 27017:YOUR-DOCDB-CLUSTER-ENDPOINT:27017 \
    ec2-user@YOUR_EC2_PUBLIC_IP \
    -i ~/path/to/your-key.pem \
    -N
```

Replace `YOUR-DOCDB-CLUSTER-ENDPOINT` with your cluster endpoint and `YOUR_EC2_PUBLIC_IP` with the EC2 public IP.

{% hint style="info" %}
**NOTE**

Add the Amazon RDS CA certificate to your trust store to enable SSL connections to DocumentDB. Go to [Enable JDBC SSL truststore support](/database-devops/use-db-devops/database-authentication-and-security/ssl.md#5-enable-jdbc-ssl-truststore-support) to add the Amazon RDS CA certificate to your delegate environment.
{% endhint %}

***

### Set up BigQuery connectors <a href="#set-up-bigquery-connectors-setting-up-bigquery" id="set-up-bigquery-connectors-setting-up-bigquery"></a>

BigQuery connections in Harness DB DevOps support OIDC authentication using Workload Identity Federation for keyless authentication.

#### Prerequisites for BigQuery <a href="#prerequisites-for-bigquery" id="prerequisites-for-bigquery"></a>

Enable the following GCP APIs and IAM roles before connecting.

**Required GCP APIs:**

* **BigQuery API** (`bigquery.googleapis.com`): Core BigQuery data access
* **IAM Service Account Credentials API** (`iamcredentials.googleapis.com`): Generates service account access tokens from workload tokens
* **Security Token Service API** (`sts.googleapis.com`): Exchanges Harness JWT for GCP workload access token

Enable the APIs:

```bash
gcloud services enable bigquery.googleapis.com \
  iamcredentials.googleapis.com \
  sts.googleapis.com \
  --project=YOUR_PROJECT_ID
```

**Required IAM roles for the service account:**

* `roles/bigquery.dataViewer` (read-only) or `roles/bigquery.admin` (full access)
* `roles/bigquery.jobUser` (required to run queries and schema operations)
* `roles/iam.serviceAccountTokenCreator` (for OIDC token exchange)
* `roles/iam.workloadIdentityUser` (for Workload Identity Pool binding)

**BigQuery JDBC URL format:**

```
jdbc:bigquery://https://www.googleapis.com/bigquery/v2:443;ProjectId=PROJECT_ID;DefaultDataset=DATASET_NAME;Location=REGION;
```

**Example:**

```
jdbc:bigquery://https://www.googleapis.com/bigquery/v2:443;ProjectId=cd-play;DefaultDataset=Step_execution_data;Location=asia-south1;
```

**Required parameters:**

* `ProjectId`: Your GCP project ID where BigQuery datasets reside
* `DefaultDataset`: The default BigQuery dataset for schema operations
* `Location`: The BigQuery dataset location (for example, `us-central1`, `asia-south1`)

{% hint style="info" %}
**IMPORTANT**

BigQuery uses OIDC authentication with Workload Identity Federation. Do not include `OAuthType` or `OAuthAccessToken` parameters in the URL when using OIDC. The Simba BigQuery JDBC driver is included in Harness Database DevOps plugin images.

Go to [Configure OIDC authentication for GCP databases](/database-devops/use-db-devops/database-authentication-and-security/oidc-authentication.md) to set up keyless authentication for BigQuery.
{% endhint %}

***

### Set up IBM DB2 connectors <a href="#set-up-ibm-db2-connectors" id="set-up-ibm-db2-connectors"></a>

IBM DB2 is a family of data management products that includes three variants, each running on different platforms and requiring different JDBC drivers and connection formats.

Harness DB DevOps supports:

* **DB2 LUW**: DB2 for Linux, Unix, and Windows
* **DB2 for i**: DB2 for iSeries (AS/400)
* **DB2 z/OS**: DB2 for IBM Mainframe

{% hint style="info" %}
**NOTE**

Go to [Set up IBM DB2](/database-devops/setup-db-devops/jdbc-connection-string/set-up-db2-connector.md) for detailed prerequisites, license requirements, and configuration instructions for each DB2 variant.
{% endhint %}

#### DB2 JDBC URL quick reference <a href="#db2-jdbc-url-quick-reference" id="db2-jdbc-url-quick-reference"></a>

| Variant            | JDBC URL Format                                                       |
| ------------------ | --------------------------------------------------------------------- |
| **DB2 LUW**        | `jdbc:db2://{host}:50000/{dbName}`                                    |
| **DB2 LUW (SSL)**  | `jdbc:db2://{host}:50000/{dbName}?sslConnection=true`                 |
| **DB2 for i**      | `jdbc:as400://{host}/{library};translate binary=true;date format=iso` |
| **DB2 z/OS**       | `jdbc:db2://{host}:446/{locationName}`                                |
| **DB2 z/OS (SSL)** | `jdbc:db2://{host}:446/{locationName}?sslConnection=true`             |

{% hint style="warning" %}
**DB2 Z/OS LICENSE REQUIREMENT**

DB2 z/OS requires a customer-provided IBM DB2 Connect license JAR (`db2jcc_license_cisuz.jar`). Go to [Set up IBM DB2](/database-devops/setup-db-devops/jdbc-connection-string/set-up-db2-connector.md#providing-the-db2-zos-license-jar) to configure the license.
{% endhint %}

***

### Connector FAQ <a href="#connector-faq" id="connector-faq"></a>

The following FAQs cover common connector configuration questions.

#### Why can I not connect to my Oracle database with a `sys as sysdba` username? <a href="#why-can-i-not-connect-to-my-oracle-database-with-a-andnbsp-sys-as-sysdba-andnbsp-username" id="why-can-i-not-connect-to-my-oracle-database-with-a-andnbsp-sys-as-sysdba-andnbsp-username"></a>

Sometimes, users want to login to their database using the `sys as sysdba` username. To do so properly with Harness:

1. Your **JDBC URL** should have the query parameter `internal_logon=sysdba`
2. Your **Username** should be `sys`.

Go to [Oracle's documentation](https://docs.oracle.com/en/database/oracle/oracle-database/23/jjdbc/data-sources-and-URLs.html#GUID-44572C63-10D2-478A-BB2E-ACF6674C59CC) for information about logging on as `sys`.

#### IBM DB2 setup instructions <a href="#ibm-db2-setup-instructions" id="ibm-db2-setup-instructions"></a>

Go to [Set up IBM DB2](/database-devops/setup-db-devops/jdbc-connection-string/set-up-db2-connector.md) for detailed instructions on configuring DB2 LUW, DB2 for i, and DB2 z/OS connectors, including license provisioning for z/OS.

### Next steps <a href="#next-steps" id="next-steps"></a>

* Go to [Set up IBM DB2 connector](/database-devops/setup-db-devops/jdbc-connection-string/set-up-db2-connector.md) to configure DB2 LUW, DB2 for i, and DB2 z/OS connections including license provisioning.
* Go to [Secure database connectivity with SSL](/database-devops/use-db-devops/database-authentication-and-security/ssl.md) to enable encrypted connections for your database.
* Go to [Create a pipeline in Database DevOps](/database-devops/use-db-devops/deployment-pipeline-configuration/create-a-pipeline.md) to use your connector in a deployment pipeline.