SQL Query Step

The Run SQL Query step executes a SQL statement against a database and stores the result for assertions or later steps.

When to Use

• Verifying that an API call correctly persisted data to the database.
• Seeding test data before API requests.
• Cleaning up test data after a test case.
• Checking database state independently of API responses.

Why: The database is the system of record. Querying it directly verifies persistence that an API response may not fully expose.

Quickest Scenario

1. Add a Run SQL Query step.
2. In the SQL Query panel, pick a project SQL connection profile, or click settings Configure to set the connection inline.
3. Choose the Result Type (Nothing, ScalarValue or Query).
4. Type the SQL in the Query Editor.
5. Run. Results appear in the Query Result area (Data Table / Raw Result tabs) and are captured in Result / ResultTable.

Configuration

The panel shows:

• A SQL connection-profile picker. When a profile is active, the inline fields are hidden.
• A settings Configure button (visible only when no profile is active) that opens the connection configuration.
• A Result Type combo box.
• A Query Editor.
• A Query Result area with two tabs: Data Table (live DataTable view) and Raw Result (read-only text).

Connection options

Option	Description
Connection Profile	A project-level SqlConnectionProfile (type Sql). Supplies DB type, server, credentials and connection parameters.
Database Type	SQL Server, PostgreSQL, SQLite, MySQL or Oracle. The first three are built in; MySQL and Oracle come from the extension package described below.
Use Connection String	Toggle between a direct connection string and server/user/password fields.
Server / Database	Host (or IP) and database name.
Authentication (SQL Server)	Windows, Server or Mixed.
Trust Server Certificate	Appends TrustServerCertificate=True (dev/staging with self-signed certs).
Username / Password	Credentials. Password is stored encrypted.

Result Types

Result Type	Stored in Result / ResultTable
Nothing	Rows affected (count). ResultTable has one column.
ScalarValue	First column of the first row. ResultTable has one column.
Query	Full data table rendered as CSV using your CSV separator setting. ResultTable holds the rows.

Parameter Reference

Property	Description
Executor.DatabaseType	Target SQL engine.
Executor.UseConnectionString	Use a raw connection string instead of server fields.
Executor.ConnectionString	Raw connection string (when enabled).
Executor.Server / Executor.DatabaseName	Server host and database name.
Executor.SqlAuthenticationMode	Windows / Server / Mixed (SQL Server only).
Executor.TrustServerCertificate	Append TrustServerCertificate=True.
Executor.Username / Executor.Password	Credentials (password encrypted).
Executor.ConnectionProfileName	Project SqlConnectionProfile to use.
Executor.ResultType	SqlResultType.Nothing / .ScalarValue / .Query.
Executor.Query	The SQL statement (supports ${VariableName}).
Result	Assertion target (DefaultAssertionTargetProperty); scalar or CSV text.
ResultTable	DataTable of the query result.

tip

Because the step derives from AssertionStepBase, assert directly against Result (or ResultTable) after the run.

Common Patterns

Seed Test Data

INSERT INTO ApiKeys (Key, UserId, CreatedAt)
VALUES ('${GeneratedApiKey}', ${UserId}, GETDATE())

Verify Data Persistence

SELECT Status FROM Orders WHERE OrderId = '${CreatedOrderId}'
-- Then assert: Result equals "Confirmed"

Clean Up After Test

DELETE FROM Orders WHERE OrderId = '${CreatedOrderId}'

Supported Databases

Three engines are supported out of the box — no extra package needed:

• SQL Server
• PostgreSQL
• SQLite

MySQL and Oracle are provided by the Aethrix.Database.Providers extension package, which is distributed separately from Aethrix Studio and installed into the project from the Extension Hub. Until that package is present, both Test Connection and a step run report that the engine requires the plugin.

note

A SQL connection profile always lists all five engines in Database Type, so a project can be prepared for the extension before it is installed — the two extension engines simply report the missing plugin until then.

See Also

• NoSQL Query Step
• Data Transfer Step
• Connection Profiles