---
title: "Database step"
section: "Step reference"
description: "How the SmartestQA Database (JDBC) step works: connection, SQL rules and warnings, Output Values mapped by column order, run-time behaviour and errors."
url: https://docs.smartestqa.ai/en/automate-steps-database.html
audience: [customer, admin]
updated: 2026-11-08
keywords: "database step jdbc sql query select insert update delete stored procedure output values column postgresql mysql oracle sql server configuration data source"
---
# Step reference: Database step

The Database step runs one SQL query during the test. Use it to check that the UI really stored an order, to read a value the screen does not show, or to prepare test data.

## In short

**On this page you can**

- Run SELECT, INSERT, UPDATE, DELETE or a stored procedure call during a test.
- Save the columns of the first row as variables with Output Values .
- Check what the UI saved by asserting on a column value.
- Use variables inside the query, for example WHERE id = {{tc:orderId}} .
- Reach databases inside your network by running on your agent.

**How to use it**

1. Create the database connection on the Data Source page first.
2. Click More › Database and fill Test Step Name .
3. Pick the Configuration and write the SQL Query with explicit columns.
4. List one output name per column in Output Values , in the same order.
5. Add an Assertion on {{tc:status}} , save and run.

**At a glance**

- **Added from:** **More** › **Database**. Chip: **DB**.
- **Project types:** WEB, MOBILE, DESKTOP.
- **Databases:** PostgreSQL, MySQL, Oracle, SQL Server.
- **Connects from:** The machine that runs the test: [the server or your agent](https://docs.smartestqa.ai/en/schedule-where.html#run-environment).
- **Produces:** One [variable](https://docs.smartestqa.ai/en/automate-test-data.html#produce-variables) per output name, from the first row.
- **On error:** The step ends as ERROR and the test case stops.

## Add a Database step

1. **Have a connection**

   The connection (host, port, database, user) is created once per project on the [**Data Source** page](https://docs.smartestqa.ai/en/data-source-connections.html#add-db), with a connection test. If none exists, the **Configuration** list is empty.
2. **Open the dialog**

   Click **More** › **Database**. The dialog **DB Requests** opens. Fill [**Test Step Name**](https://docs.smartestqa.ai/en/automate-editor.html#rename-step), for example `Order status in DB`.
3. **Pick the configuration**

   Choose the connection under **Configuration**.
4. **Write the query**

   Type the **SQL Query**. Name the columns you want: `SELECT status, total FROM orders WHERE id = {{tc:orderId}}`. The dialog checks the query as you type; see [SQL rules](https://docs.smartestqa.ai/en/automate-steps-database.html#sql-rules).
5. **Name the outputs**

   In **Output Values** list one name per column, separated by commas, in column order: `status, total`. Then **Add**.

   The step shows the chip **DB**. When you select it, the right panel shows a **DB Requests** tab with the query and outputs.

## SQL rules

- Any query type works: SELECT, INSERT, UPDATE, DELETE, CREATE / ALTER / DROP and stored procedures (CALL / EXEC).
- **SELECT needs named columns.** `SELECT *` is refused: “Asterisk (*) is not allowed. Please specify explicit column names.” The query must have the form `SELECT … FROM …`. Aliases are fine: `SELECT COUNT(id) AS n FROM orders`.
- Quote table and column names that are uppercase or reserved words: `SELECT username FROM "user"`.
- Changes are permanent: modifying queries are committed. The dialog warns, without blocking:

  - “No WHERE clause detected — this query will affect ALL rows. Are you sure?”
  - “Caution: This operation (DROP/TRUNCATE) can permanently delete data or tables.”
  - “This query makes permanent changes in the database (committed). Please make sure before continuing.”
  - “A stored procedure / routine call will be executed.”
- [Variables](https://docs.smartestqa.ai/en/automate-test-data.html#resolution) are resolved before the query runs. Put text values in quotes: `WHERE email = '{{tc:email}}'`.

## Output Values

Output names are mapped to the query’s columns **by position**, not by name: the first name gets the first column, the second name the second column. The values come from the first row of the result. Each name becomes a [variable](https://docs.smartestqa.ai/en/automate-test-data.html#produce-variables): `{{tc:status}}`, `{{tc:total}}`.

Example · from the dialog’s own help

```text
Query:          SELECT firstname, lastname FROM "user" WHERE id = 1
Output Values:  firstname, lastname
Result:         firstname → 1st column, lastname → 2nd column
Use later:      Type step value {{tc:firstname}}
```

- **Output Values** is required: “Output values cannot be empty.”
- If you list more names than the query has columns, the extra names stay empty.
- If the query returns no row, no variable is set; an [Assertion](https://docs.smartestqa.ai/en/automate-steps-assertions.html#assertion-step) on it sees an empty value.

## At run time

- The query runs from the machine that runs the test. A database in your office network is reachable from [your agent](https://docs.smartestqa.ai/en/schedule-where.html#agent), not from the server.
- The query timeout is 30 seconds; at most 100 rows are fetched.
- Log on success: `Query executed successfully (…). Rows: 1`, followed by the query, the connection and the extracted values.
- Any error ends the step as ERROR and stops the test case. The log adds a hint, for example: “The column "Status" was not found in the table. Column names are case-sensitive; if a name is uppercase or a reserved word, wrap it in double quotes (e.g. "User").”

| Hint in the log | Meaning |
| --- | --- |
| The column "…" was not found in the table. | Wrong column name or case. Quote it. |
| The table "…" was not found. | Wrong table name or case, or another schema. |
| SQL syntax error. Review the query near the marked position (^). | The SQL is not valid for this database. |
| Database authentication failed. Check the connection username/password. | The [connection’s](https://docs.smartestqa.ai/en/data-source-connections.html#edit) credentials are wrong. |
| Could not connect to the database. Check host, port, credentials and that the database is reachable. | Network, firewall or wrong host. Run on an [agent](https://docs.smartestqa.ai/en/agent-pool-agents.html) inside the network. |
| The JDBC driver could not be loaded. | The [driver class](https://docs.smartestqa.ai/en/data-source-connections.html#db-examples) in the connection is wrong. |

Fixes for each are in [Troubleshooting › Integrations](https://docs.smartestqa.ai/en/automate-steps-troubleshooting.html#integrations).
