Run SQL API database query – Virtuoso

The sqlApiDBQuery extension sends a SQL query to a backend SQL API endpoint from inside a Virtuoso journey.

This is useful when your test needs to fetch database values through an API and reuse the returned response in later journey steps.

Parameters:

url required, the base URL of the backend service that handles SQL database requests. This must be a string. The extension appends /SQLInterface to this value before sending the request;
query required, the SQL query string that should be sent to the backend SQL interface.

Note: The url value should be the base API URL only. Do not include /SQLInterface in the input because the extension adds it automatically.

How to apply this to your journey

Use the extension in a journey by calling sqlApiDBQuery with the execute command. Pass each value to the matching extension input using as inputName.

Note: The SQL query is sent to the backend as text inside a JSON request body. Make sure the backend service validates, authorizes, parameterizes, and sanitizes the query before executing it.

To run a SQL query through the API:

execute "sqlApiDBQuery" using "https://api.example.com/v1/query" as url, "SELECT * FROM Users WHERE Age > 30" as query returning $response

To run the same query with a filtered result:

execute "sqlApiDBQuery" using "https://api.example.com/v1/query" as url, "SELECT id, email FROM Users WHERE Status = 'Active'" as query returning $activeUsers

You can also use Virtuoso variables to make the same step reusable across different API endpoints or SQL queries:

execute "sqlApiDBQuery" using "$Url" as url, "$query" as query returning $response

Example setup using variables before calling the extension:

store value "https://api.example.com/v1/query" in $Url
store value "SELECT * FROM Users WHERE Age > 30" in $query
execute "sqlApiDBQuery" using "$Url" as url, "$query" as query returning $response

For example, the final request URL used by the extension will be:

https://api.example.com/v1/query/SQLInterface

When the request is successful, the extension returns the API response as a JSON string in the output variable. For example:

{"rows":[{"id":1,"email":"user@example.com"}],"count":1}

This extension requires the following resource:

https://cdnjs.cloudflare.com/ajax/libs/axios/0.21.1/axios.min.js

The extension should be configured as:

Run asynchronously: Yes
Scope: Global

Limitation: This extension depends on the configured backend /SQLInterface endpoint, the externally loaded Axios resource, and browser network access from the Virtuoso execution environment. It does not execute SQL directly in Virtuoso; it sends the supplied query string to the API, so authentication, authorization, query validation, parameterization, audit logging, and SQL injection protection must be handled by the backend service. The extension always appends /SQLInterface to the provided url, so including that path in the input or using an endpoint with unusual trailing-slash handling may call the wrong URL. It has no built-in retry, pagination, cancellation, or custom timeout logic, and async extension scripts must complete within Virtuoso's documented 120-second maximum execution window. If the API response contains an error field, or if Axios, CORS, proxy rules, CDN loading, network routing, or backend validation fails, the step fails through doneError. Because this extension performs a browser-based HTTP request, validate it in each browser, device, and remote-grid configuration used by the plan, especially when CORS, corporate proxy rules, VPN access, response size, or environment-specific API routing differs from the default execution browser.

Add the extension to your Virtuoso instance

Select the domain that matches your Virtuoso account.

Add extension to Virtuoso - https://app.virtuoso.qa/ →	Add extension to Virtuoso Free Trial - https://app2.virtuoso.qa/ →
Add extension to Virtuoso US - https://app-us.virtuoso.qa/ →	Add extension to Virtuoso UK - https://app-uk.virtuoso.qa/ →

View source

Last updated: 22/05/2026

Resources:

https://cdnjs.cloudflare.com/ajax/libs/axios/0.21.1/axios.min.js

const makeRequest = async (url, query) => {
  try {
    const { data } = await axios.post(
      url,
      '"' + query + '"',
      {
        headers: {
          'Content-Type': 'application/json'
        }
      }
    );

    if (data.error) {
      console.log(data.error);
      doneError(JSON.stringify(data));
    }

    done(JSON.stringify(data));
  } catch (e) {
    console.log(e.message);
    doneError(e);
  }
};

if (!url) {
  throw new Error('URL parameter is missing');
}

url += "/SQLInterface";

if (!query) {
  throw new Error('Query parameter is missing');
}

makeRequest(url, query);

How to apply this to your journey

Related articles