---
title: "Connections (DB and Kafka)"
section: "Data Source"
description: "Set up SmartestQA database (JDBC) and Kafka connections: URL and driver examples, SASL settings, Test Connection, password handling, folders and safe deletion."
url: https://docs.smartestqa.ai/en/data-source-connections.html
audience: [customer, admin]
updated: 2026-11-08
keywords: "connection database jdbc url driver class postgresql mysql oracle kafka bootstrap servers sasl scram ssl test connection password delete anyway"
---
# Data Source: Connections: databases and Kafka

A connection is the login to an outside system, stored once in the project. DB steps, DB-bound keys and Kafka steps pick it by name, so no step ever holds the password.

## In short

**On this page you can**

- Add a database connection with its JDBC URL, driver class, user and password.
- Add a Kafka connection with bootstrap servers and optional SSL or SASL.
- Check a connection with Test Connection before tests use it.
- Change a connection without retyping its password.
- See which keys and test cases use a database before you delete it.

**How to use it**

1. Open Connections and click New DB or New Kafka Connection .
2. Fill the required fields; the label says “(Required)”.
3. Click Test Connection and fix the cause if it fails.
4. Click Save .
5. Pick the connection by name in a DB step, a Kafka step or a DB-bound key.

The **Connections** tab has two lists: **Databases** and [**Kafka**](https://docs.smartestqa.ai/en/automate-steps-kafka.html#add-kafka-step). “DB connections feed keys from an SQL query; Kafka connections are used by message steps.”

## Add a database connection

1. **Click New DB**

   Go to **Data Source** › **Connections** and click **New DB**, or **Add** on a folder row. The **Database Connection** panel opens.
2. **Fill the fields**

   | Field | Required | Notes |
   | --- | --- | --- |
   | **Name** | Yes | What steps show, for example `Orders DB (TEST)`. Unique in the project. |
   | **Database Url** | Yes | Must start with `jdbc:`. Examples below. |
   | **DB Driver Class** | Yes | The JDBC driver class for the database type. |
   | **Username** | No | Leave empty only for databases that need no login. |
   | **Password** | For a new connection | Stored encrypted and never sent back to the screen. |
   | **Folder** | No | **Main** or one of your folders. |
3. **Test it**

   Click **Test Connection**. It needs only the URL and the driver class.

   “Connection test successful.” On failure the message says why and adds the driver’s own text underneath; see [Test Connection fails](https://docs.smartestqa.ai/en/data-source-troubleshooting.html#fix-test-connection-failed).
4. **Save**

   **Save** stays disabled until the required fields are filled (“Please fill in the required fields.”).

   “DB configuration saved successfully.” The connection appears under **Databases**.

### URL and driver examples

| Database | Database Url | DB Driver Class |
| --- | --- | --- |
| PostgreSQL | `jdbc:postgresql://db.test.example.com:5432/shop` | `org.postgresql.Driver` |
| MySQL | `jdbc:mysql://db.test.example.com:3306/shop` | `com.mysql.cj.jdbc.Driver` |
| Oracle (SID) | `jdbc:oracle:thin:@db.test.example.com:1521:ORCL` | `oracle.jdbc.OracleDriver` |
| Oracle (service) | `jdbc:oracle:thin:@db.test.example.com:1521/shop` | `oracle.jdbc.OracleDriver` |

SSL options go into the URL the way your driver expects them, for example `?sslmode=require` for PostgreSQL. Do not put the password in the URL: it would be visible to everyone in the list.

> **Note: The driver class is checked by Test Connection, the URL by the run**
>
> **Test Connection** loads the **DB Driver Class** on the SmartestQA server. A test run reads the database type from the start of the **Database Url** (`jdbc:postgresql`, `jdbc:mysql`, `jdbc:oracle`) and connects with its own client. Keep both consistent.

## Add a Kafka connection

1. **Click New Kafka Connection**

   In **Connections**, click **New Kafka Connection**. The **Kafka Connection** panel opens.
2. **Fill the fields**

   | Field | Required | Notes |
   | --- | --- | --- |
   | **Name** | Yes | Unique in the project. |
   | **Bootstrap Servers** | Yes | “Comma-separated host:port list, e.g. broker1:9092,broker2:9092”. |
   | **Security Protocol** | No | `PLAINTEXT` (default), `SSL`, `SASL_PLAINTEXT`, `SASL_SSL`. |
   | **SASL Mechanism** | With SASL_* | `PLAIN`, `SCRAM-SHA-256`, `SCRAM-SHA-512`. “Only used with SASL_PLAINTEXT / SASL_SSL”. |
   | **SASL Username** | With SASL_* |  |
   | **SASL Password** | With SASL_*, new connection | Stored encrypted, never shown again. |
   | **Folder** | No |  |
3. **Test and save**

   **Test Connection** asks the brokers for the cluster and gives up after 5 seconds. Then click **Save** (“Kafka configuration saved.”).

> **Warning: Testing a saved SASL connection**
>
> For Kafka, **Test Connection** uses only what is in the form. The stored SASL password is not loaded into the form, so type it again before you test a saved SASL connection. Leaving it empty when you save keeps the stored password.

## Change a connection

- Click the connection in its list. The password field is empty and labelled “Password (leave empty to keep current)”: “Fill in to change; leave empty to keep the current password”.
- For a database, **Test Connection** uses the URL, driver and user in the form, and the stored password when you leave the field empty. The password is read on the server and never sent to your browser.
- Changing a connection affects every [DB step](https://docs.smartestqa.ai/en/automate-steps-database.html), DB-bound key or [Kafka step](https://docs.smartestqa.ai/en/automate-steps-kafka.html) that uses it, from their next run on.

A DB or Kafka step selects one connection, whatever the run’s environment. For another database per environment, create one connection per environment and name them clearly, for example `Orders DB (TEST)`. [Environment-specific keys](https://docs.smartestqa.ai/en/data-source-variables.html#environments) apply to keys and datasets, not to connections.

## Folders

Each list has its own folders: **New folder** in the list header, then **Rename** or **Delete** in the folder menu (**Folder actions**). Deleting a folder never deletes connections: “Are you sure you want to delete this folder? Configurations inside will move to the root.” Search the lists with **Search by name**.

## Delete a connection

### A database connection

1. **Open it and click Delete**

   The dialog **Delete DB Configuration** first loads where the connection is used.
2. **Not used**

   “Are you sure you want to delete this DB configuration?” Confirm with **Delete**.
3. **Used**

   The dialog lists **Test Cases using this configuration** (with “Go to Automate page for details”) and **Data Sources using this configuration** (“Go to Data Source page for details”). “If you click Delete Anyway, the DB steps using this configuration will be deleted and data source feeds will be cleared.”

   **Delete Anyway**: every [DB step](https://docs.smartestqa.ai/en/automate-steps-database.html) on it is removed from its test case, and every key bound to it stays but loses its query (empty value). There is no undo.

> **Important: Delete Anyway changes test cases**
>
> Tests lose their DB steps and may pass for the wrong reason. Prefer: open each listed test case, switch its DB steps to another connection, then delete.

### A Kafka connection

“Are you sure you want to delete this Kafka configuration?” There is no usage check: make sure no [Kafka step](https://docs.smartestqa.ai/en/automate-steps-kafka.html) still selects it.

## If something goes wrong

- [“Connection test failed: …”](https://docs.smartestqa.ai/en/data-source-troubleshooting.html#fix-test-connection-failed)
- [Test Connection works, the run cannot connect](https://docs.smartestqa.ai/en/data-source-troubleshooting.html#fix-works-in-test-fails-in-run)
- [“Password is required for a new connection.”](https://docs.smartestqa.ai/en/data-source-troubleshooting.html#fix-password-required)
- [“This name already exists in this project…”](https://docs.smartestqa.ai/en/data-source-troubleshooting.html#fix-name-exists)
- [Kafka “Connection test failed.”](https://docs.smartestqa.ai/en/data-source-troubleshooting.html#fix-kafka-test-failed)
