Benefits of Using Cloud Database Connection Configuration
Before the introduction of cloud database connection configuration functionality, running a test scenario with database operations via CLI required completing several cumbersome steps:
- Manual Export Process: Locate the database connection configuration export entry in the product interface and export it as a file
- File Management: Transfer the exported database connection configuration file to the CLI execution machine
- Path Configuration: Copy the file path on the machine
- Command Modification: Update the command line options with the actual path values, for example:
apidog run --access-token $APIDOG_ACCESS_TOKEN -t 123456 -e 123456 -n 1 -r html,cli --database-connection /Users/xxx/yyy/database-connections.json
This process involved numerous preparatory tasks, and any changes to the database connection configuration required repeating all these steps. The overall user experience was inefficient and tedious.
With cloud database connection configuration, you can completely eliminate the need to export configuration files, transfer them to CLI execution machines, and manually specify option values in command lines. Simply set the actual values for variables in the cloud database connection configuration to run successfully, significantly improving the user experience.
Method 1: Using Local Values + Cloud Database Connection Configuration
When all database connections in your test scenarios use configurations saved in the cloud, the database connection configuration export option will not appear (since it's no longer needed). During CLI execution, the system can directly retrieve the required variables from the cloud database connection configuration and find actual variable values according to variable replacement rules to establish connections.
Step-by-Step Implementation:
Configure Environment Variables: In environment management, set the actual database connection values in the local values of corresponding variables for each environment you need to use.
Ensure Variable-Based Configuration: Make sure your database connection configuration uses variables completely (except for ports), ensuring it's saved as a cloud database connection.
Verify Test Scenario Configuration: Confirm that all test scenarios you want to run via CLI use "cloud database connection configuration" (i.e., configurations saved with variables).
Export Local Values: Navigate to the CI/CD page, select "Export local values for use" under Environment/Global Variables, then click the export button.
Review and Modify Export File: In the exported file, you'll see environment variable values used by the database connection configuration. You can manually modify these values in the file if needed. Place the file on the CLI machine and copy the file path.
Configure CI/CD Command: In the CI/CD page, insert your Access Token, copy the command, and paste the actual path of the variable file into the option value:
apidog run --access-token $APIDOG_ACCESS_TOKEN -t 123456 -e 123456 -n 1 -r html,cli --variables /Users/xxx/yyy/pptest_variables.json
Execute and Verify: Run the CLI command above. The database connection should work correctly and execute successfully.
Review Results: If result printing is configured, you can view database connection execution details in the uploaded report details.
Important Considerations:
⚠️ Security Note: Local values still use local file storage for actual database connection configurations to ensure data security. If you need to change connection configurations, manually modify the corresponding variable values in this file.
⚠️ Remote Values Warning: While using remote values for database connection configuration variables can avoid the extra operations of exporting local value files and adding additional command line options (and allows direct modification of remote values in the Apidog client), this approach poses data security risks and is ❌ not recommended.
⚠️ Plain Text Usage: If you use plain text completely or partially (except for port fields) in your connection configuration, you'll still need to export configuration files and use them via --database-connection in commands. This usage pattern is ❌ not recommended.
Method 2: Using Vault Variables + Cloud Database Connection Configuration
If you're using environment variable remote values + Vault variables to maintain cloud database connections, and want to use these cloud-saved connections in CLI, follow these steps:
Step-by-Step Implementation:
Configure Vault Variables: In environment management, set database connection Vault variables in the remote values of corresponding variables, keeping local values following remote values. Configure this for each environment you need to use.
Ensure Variable-Based Configuration: Make sure your database connection configuration uses variables completely (except for ports), ensuring it's saved as a cloud database connection.
Verify Test Scenario Configuration: Confirm that all test scenarios you want to run via CLI use "cloud database connection configuration" (i.e., configurations saved with variables).
Configure CI/CD Settings: Navigate to the CI/CD page, select "Use remote values" under Environment/Global Variables, configure according to your actual situation, then copy the CLI command.
Set Vault Variables: On the machine where you need to run CLI, in your pipeline or terminal, first input export APIDOG_VAULT_KEY=VALUE to actually use Vault variables. Separate multiple Vault variables with spaces.
Operating System Specific Syntax:
| Linux & MacOS | Windows |
|---|---|
Set Variables: Use export, separate variables with spaces<br>export APIDOG_VAULT_KEY1=VALUE1 APIDOG_VAULT_KEY2=VALUE2 APIDOG_VAULT_KEY3=VALUE3 |
Set Variables: Use set, separate variables with &<br>set APIDOG_VAULT_KEY1=VALUE1&APIDOG_VAULT_KEY2=VALUE2&APIDOG_VAULT_KEY3=VALUE3 |
Query Variables: Use echo $VARIABLE_NAME<br>echo $APIDOG_VAULT_KEY1 |
Query Variables: Use echo %VARIABLE_NAME%<br>echo %APIDOG_VAULT_KEY1% |
Execute CLI Command: Run your CLI command to start execution.
Verify Results: Upon completion, you can see database connection results in the report, confirming successful database connection and operation execution.
Review Execution Details: If result printing is configured, you can view database connection execution details in the uploaded report details.
Critical Reminders:
⚠️ Pre-execution Requirement: Before executing CLI commands containing Vault variables for database connections, always use export/set to input actual Vault variable values. Otherwise, database connections will fail due to inability to retrieve actual configurations.
⚠️ Temporary Variable Scope: Vault variable actual values input via export/set are only effective for the current execution, functioning like temporary variables. You'll need to re-input them using this method for subsequent runs.
Conclusion
Cloud database connection configuration significantly streamlines the CLI testing workflow by eliminating manual file management and reducing configuration complexity. Whether using local values or Vault variables, this approach provides a more secure, efficient, and maintainable solution for running database-connected test scenarios in CI/CD environments.
Choose the method that best fits your security requirements and operational preferences:
- Local Values: Better for scenarios requiring maximum data security with local file control
- Vault Variables: Ideal for automated CI/CD pipelines with centralized secret management
Both approaches ensure your database connections remain secure while providing the flexibility and efficiency needed for modern testing workflows.
