1. Docs
  2. Reference
  3. Step reference
  4. Database step

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.

3 min read Updated CustomersAdmins

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.
Produces
One variable 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, 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, 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.

  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 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: {{tc:status}}, {{tc:total}}.

Example · from the dialog’s own help
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 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, 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 logMeaning
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 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 inside the network.
The JDBC driver could not be loaded.The driver class in the connection is wrong.

Fixes for each are in Troubleshooting › Integrations.

Didn’t find your answer?Write to support with your project name and what you see on screen.

info@smartestqa.ai
© 2026 Selenity Technology · SmartestQAsmartestqa.aiThis page as MarkdownChecked against smarttest-fe predev 2a8c79cc, smarttest-be 633c2a03, smarttest-testsuite 017fcec