Skip to main content
Database assertions are an experimental feature. The syntax and behavior may change in future releases.
Database assertions let you verify that an HTTP request produced the expected side effects in your database. After sending a request, hitspec runs a SQL query and asserts on the results.

Security

Database assertion blocks execute SQL queries against your database. You must pass the --allow-db flag to enable them. Without this flag, >>>db blocks are skipped.

Basic Usage

Use the @db annotation to specify a database connection and a >>>db block for queries and assertions:

Connection Strings

Specify the database connection using the @db annotation:

Query and Assert Syntax

Inside a >>>db block, use query to run SQL and expect to assert on the result columns:

Supported Operators

If you omit the operator, hitspec defaults to == (exact match). So expect active true is equivalent to expect active == true.

Examples

Verify Record Creation

Verify Record Deletion

Verify Aggregates

Variable interpolation works inside >>>db blocks. You can use captured values, environment variables, and built-in functions in your SQL queries.
For CI/CD, use environment variables for database credentials and pass the --allow-db flag explicitly in your pipeline configuration.
Last modified on July 13, 2026