# Data Sources

> Create reusable connections to CSV, Excel, databases, JSON, or APIs, then bind their columns into tests with [[variable]] tokens for single-row or iterate-all execution.

Source: https://totalshiftleft.ai/help-center/product-documentation/data-sources

## Overview

A **Data Source** is a saved, reusable connection to external data — an uploaded or referenced CSV/Excel file, a JSON file or URL, a database query, or an API endpoint. You create it once, then bind its columns into any test. This guide walks the **Data Sources** manager and the per-test **Data Source** configuration exactly as they appear in Shift Left Studio. Explore the capability at [data sources](/features/test-data/data-sources).

Data Sources use `[[variable]]` tokens. This is a different system from the **Data-driven testing** panel, which uses `{{row.COLUMN}}` tokens — never mix the two. For the inline/no-code path, see [Data-driven testing](/help-center/product-documentation/data-driven-testing).

## Before you begin

- Open the **Data Sources** manager for your project. It opens as a panel titled **Data Sources** with a **Create Data Source** button in the top-right.
- If no project is selected you'll see *"Project ID is required"* — pick a project first.
- Existing sources are listed as cards showing the **name**, description, an uppercase **type** badge (e.g. `CSV`), and the created date. Each card has three icon buttons: **Test Data Source** (play), **Edit Data Source** (pencil), and **Delete Data Source** (trash).

## Step 1 — Open the Create Data Source form

1. Click **Create Data Source**. A modal titled **Create Data Source** opens.
2. Fill the common fields:

| Field | What it does |
|-------|--------------|
| **Name *** | Required identifier for the source. |
| **Description** | Optional notes. |
| **Type *** | The connector type: **CSV**, **Excel**, **Database**, **JSON**, or **API**. Changing the type resets the type-specific fields below. |

## Step 2 — Fill the type-specific fields

### CSV

1. Choose **File Path** or **Upload File**. For **File Path**, enter a path like `/path/to/file.csv`. For **Upload File**, pick a `.csv` file (it uploads when you save).
2. Set the **Delimiter** (default `,`).
3. Tick **Has Headers** if the first row holds column names. When ticked, set **Header Row (0-based)** — the row number where headers live.
4. Optionally set **Data Range (Optional)** in `startRow:endRow` form, e.g. `2:100`. Leave empty to read all rows.

### Excel

1. Choose **File Path** (`/path/to/file.xlsx`) or **Upload File** (`.xlsx`/`.xls`).
2. Set **Sheet Name** (leave empty to use the first sheet).
3. Tick **Has Headers** and set **Header Row (0-based)** if applicable.
4. Optionally set **Data Range (Optional)**, e.g. `A1:C10` or `Sheet1!A3:B4`.

### Database

1. Choose the **Database Type**: **MySQL**, **PostgreSQL**, **SQL Server**, **SQLite**, **MongoDB**, or **Oracle**.
2. For **SQLite**, enter the **Database File Path** (e.g. `/path/to/database.db`). For all others, enter **Host**, **Port** (the placeholder shows the default for the selected engine, e.g. 3306 for MySQL), **Database**, **Username**, and **Password**.
3. Enter the **Query**. For SQL engines use SQL like `SELECT * FROM table LIMIT 100`. For MongoDB use the documented JSON form, e.g. `{"collection": "users", "find": {}, "options": {"limit": 100}}`.

### JSON

1. Choose **File Path or URL** — enter a local path (`/path/to/file.json`) or an `https://…` URL — or **Upload File** and pick a `.json` file. A value starting with `http` is treated as a URL automatically.

### API

1. Enter the **Endpoint URL** (e.g. `https://api.example.com/data`).
2. Choose the **Method**: **GET** or **POST**.

## Step 3 — Save

Click **Create** (the button reads **Update** when editing an existing source; during save it shows **Creating…** / **Updating…**, and **Uploading…** while a file uploads). Uploaded files attach after the source is created, so the source saves first and then the file transfers. Secrets such as passwords, tokens, and connection strings are never returned in listings.

## Step 4 — Test the connection

On a source card, click the **Test Data Source** (play) button. A result banner appears on the card:

- Success: *"Connection successful. N rows found."*
- Failure: *"Connection failed: …"* with the error.

Use **Edit Data Source** to change settings (removing an uploaded file is done here via **Remove**), and **Delete Data Source** to remove it — a **Delete data source** confirmation asks *"Are you sure you want to delete '…'? This cannot be undone."*

## Step 5 — Bind a data source into a test

Open the test and go to its data-source configuration:

1. **Data Source** — pick your source from the dropdown (each entry shows name and type, e.g. `Customers (CSV)`). Choose **None (use default test data)** to detach it.
2. A collapsible **Preview (N rows, M columns)** section shows the first rows so you can see the columns.
3. **Auto-create variables from all columns** — tick this checkbox to create one variable per column automatically. Leave it off to define variables selectively.

### Variable Definitions

Under **Variable Definitions**, click **Add Variable** for each value you want to expose. The help text reads: *"Define variables from data source columns. Use `[[variableName]]` in headers, assertions, body, or parameters."* Each row has:

| Field | What it does |
|-------|--------------|
| **Source field** | The column to read (choose from the detected columns). |
| **Use as: [[ … ]]** | The variable name; reference it elsewhere as `[[variableName]]`. A copy button copies the `[[…]]` token to your clipboard. |
| **Default value** | Value used when the column is missing. |
| **Map to param** | Tick to also bind the variable straight into a test parameter, then pick the target from the **Select parameter** dropdown (each option shows the parameter name and location, e.g. `userId (query)`). |

A collapsible **Available Variables (N)** panel lists every resulting `[[variable]]` with a sample value so you can confirm the names before using them.

### Execution Strategy

Set **Execution Strategy**:

- **Single Row (use one row per execution)** — uses one row; set the **Row Index** (0-based, default 0).
- **Iterate All (run test once per row)** — runs the test once for every row in the source.

## Troubleshooting

- **"Project ID is required to configure data sources"** — the test isn't associated with a project; open it from within a project.
- **Columns show "Loading columns…"** — the preview hasn't loaded yet; wait, or reselect the source.
- **Connection failed on Test Data Source** — verify host/port/credentials or the file path/URL; the banner shows the underlying error.
- **A `[[variable]]` isn't substituted** — confirm the variable name matches exactly, and that the **Source field** is set for that row.

## Related articles

- [Data-driven testing](/help-center/product-documentation/data-driven-testing)
- [Test Configuration](/help-center/product-documentation/test-config)
- [Secret managers](/help-center/product-documentation/secret-managers)
- [Test case](/help-center/product-documentation/test-case)