Commands for Interacting w/ Databases using dbCONNECT
You can read about the purpose of these powerful commands in this article.
The table(s) below list the commands in the ascending alphabetic order within each category along with a brief description of the purpose behind the command. By clicking on the hyperlinked command name in the table(s) below, you can review more detailed information about a specific command that includes the syntax for you to follow when using the commands.
Please note that these commands (constructs) are supported within Worksoft SaaS application (Edit Test Script screen) only and NOT supported in QaSCRIBE test authoring tool.
| Command | Purpose |
|---|---|
| dbBlockEnd | This command signifies the end of a dbCONNECT Block within a Test Script. Each dbBlockEnd must be accompanied by a matching dbBlockOpen that exists before it within the same Test Script. There can be more than one dbCONNECT Blocks within a single Test Script. dbCONNECT Blocks are also referred to as dbBlocks for simplicity. |
| dbBlockOpen | This command signifies the beginning of a dbCONNECT Block within a Test Script.
Each dbBlockOpen must be accompanied by a matching dbBlockEnd that exists after it within the same Test Script. There can be more than one dbCONNECT Blocks within a single Test Script. dbCONNECT Blocks are also referred to as dbBlocks for simplicity. |
| dbExecuteQuery | This command is the main query that is responsible for getting the SQL query, identified by a label, executed by the appropriate dbCONNECT Tunnel operating on one of your company's servers.
Worksoft SaaS does NOT execute SQL query from/on its cloud but sends the query to the appropriate dbCONNECT on your end along with the database alias name that corresponds to a real database behind your AUT. When dbCONNECT Tunnel receives this query execution request from Worksoft SaaS, in the context of a test being executed within your domain, dbCONNECT reads from db.json (that drives your dbCONNECT tunnel) the connection string to connect to the database that the 'dbAlias' in your test refers to, and get the SQL query executed. Since it may take some time for the dbCONNECT and/or your database to execute the SQL query, Worksoft SaaS waits asynchronously for the query result to be sent back from dbCONNECT. When the SQL query execution completes, dbCONNECT sends the result set back to Worksoft SaaS, and the test that is executing in Worksoft SaaS, that was waiting for the query execution results, proceeds with the test execution. If the response does NOT go back to Worksoft SaaS within the maximum time allowed for a query (as specified explicitly by the use of dbSetTimeOut command or implicitly applied with a default value if that command is not used), the test that in Worksoft SaaS that was waiting for the results of the SQL query, will automatically abort the test. If the result set returned by dbCONNECT has more rows than stipulated by the MaxResultSetSize (as specified explicitly by the user of dbSetMaxResultset command or implicitly applied with a default value if that command is not used), Worksoft SaaS will truncate the results to the top N rows from the returned result set. |
| dbgetQueryExecutionErrorCode | This command is used to retrieve (read) the SQL Error Code that corresponds to a failed SQL query that was executed by dbCONNECT.
This command must be used usually immediately after a dbExecuteQuery and within the same dbBlock. |
| dbgetQueryExecutionErrorText | This command is used to retrieve (read) the SQL Error Text that corresponds to a failed SQL query that was executed by dbCONNECT.
This command must be used usually immediately after a dbExecuteQuery and within the same dbBlock. |
| dbLabelQuery | This command is used to "label" a SQL query in the context of a particular dbBlock.
Once used, you can refer to the SQL query within the current dbBlock using that label (instead of using the SQL query itself). The SQL query could have variables (as placeholders) which then could be populated (replaced/filled) using the dbSetQueryValue command that follows this command but before the dbExecuteQuery command within the current dbBlock. The variables within the SQL Query have to be of the format ${variableName}. |
| dbSetContext | This command is used to specify to Worksoft SaaS the "database" within which the SQL queries within the current dbBlock must be executed AND the "dbCONNECT tunnel" (that is operating within your company's firewalls) that will service the execution of those queries.
As a security best practice, Worksoft SaaS does NOT need to know any more information (connection string data like IP addresses, host names, schema names, usernames, passwords, etc) about the databases (behind your company's applications (AUTs) and behind your firewalls) beyond the alias name(s) you give to those database(s). The "db.json" file that drives the dbCONNECT tunnel (operating within your company's infrastructure) is where you can specify the database connection strings and assign a 'db alias name' which then you'd use safely in Worksoft SaaS. Since db.json is on your company's network, Worksoft SaaS cannot access the db connection strings. The "dbCONNECT Tunnel Name" is a name you give to your dbCONNECT Tunnel when you start the Tunnel. The name you give must be unique. |
| dbSetMaxResultSetCount | This command is used to specify the maximum size of the result set for all queries that get executed within the current dbBlock. This is to prevent poorly written queries that could potentially bring back into Worksoft SaaS large result set that have negative consequences of depleting the capacity within your domain by unnecessarily running data driven tests on the result set returned by such bad queries.
If this command is not explicitly used within a dbBlock, a default value will be used. Default value is X records (rows). |
| dbSetQueryValue | This command is used to set the "value(s)" for a particular variable (parameter) within the SQL query. A variable/parameter within your SQL Query has to be identified by a namestring in the format ${variableName}. For each variable (parameter) within your SQL query, you must use this command separately, to set its value. |
| dbSetTimeout | This command can be used to set the "timeout" for all DB Queries that get executed in the context of a dbBlock.
Test execution gets aborted if no response comes back from Worksoft SaaS dbCONNECT tunnel within the value set. If this command is NOT used within a dbBlock, a default value will be applied for the timeout. Default value is X seconds. |