Description
GenRocket Runtime must be connected to a database before a query or data insertion can be performed during test data generation.
Primary Reasons to Connect to a Database
There are three primary reasons for making a connection to a database (e.g., MySQL, MS SQL, Oracle) with GenRocket:
- Retrieve Data from a Database (Query Data)
- Data is retrieved from the database during test data generation using GenRocket Runtime.
- This is done using Generators (e.g., ListQueryGen, QueryBeforeLoopGen, etc.) or through the Self Service Platform using G-Queries.
- Populate Database Tables (Insert Data)
- Populate tables with test data generated using GenRocket Runtime.
- This is done using Receivers like GenericSQLInsertReceiver, MySQLInsertReceiver, etc.
- Migrate a Subset of Data (Masked or Unmasked) from a Source to a Target Database
- This is done using G-Migration+.
GenRocket leverages JDBC to connect to a database and query, populate, or perform data subsetting and masking.
Database Connection Steps
- Step 1 - Create a JDBC Config File (config.properties)
- Step 2 - (Optional) Encrypt the JDBC Config file
- Step 3 - Update Your JDBC Organization Resource Value
- Step 4 - Update your Profile in the .genrocket Folder
- Step 5 - Download and place the JDBC connector Jar file in the $GENROCKET_HOME/lib/ folder
- Step 6 - Test the JDBC Connection (SQL Databases Only)
- Step 7 - Reference the JDBC Resource as Needed
Step 1 - Create a JDBC Config File (config.properties)
A config.properties file is needed for GenRocket to connect to a database via JDBC. GenRocket can connect to a database via JDBC by reading a JDBC Config file that contains the following information.
- driver - Defines the name of the specific database driver to use to access the given database. The actual driver file must be placed in the $GEN_ROCKET_HOME/lib folder on your local computer. Please note that the required driver varies per database.
- user - Defines the Username used to access the database.
- password - Defines the password used to access the database.
- url - Defines the specific URL to access the database. Please note that this will vary per database.
- batchCount - Defines the number of SQL statements that are batched together and sent to the database for execution. This property is only mandatory for GenRocket Receivers.
driver=<JDBCDriverClassName>
user=<userToConnectToDatabase>
password=<passwordToConnectToDatabase>
url=<URL>/<databaseName>
batchCount=1000
Note: If you are connecting to a different type of database, your configuration file will look different and may require additional information. To learn more and see troubleshooting tips, please see these articles:
Example config.properties for MySQL database
GenRocket will read this config file and connect to the employee database on localhost using username root and password root.
driver=com.mysql.jdbc.Driver
user=root
password=root
url=jdbc:mysql://localhost:3306/employee?rewriteBatchedStatements=true
batchCount=1000
Note: It is possible to have more than one config.properties file for different database connections. This requires a little planning and organization, which is further explained here.
Step 2 - (Optional) Encrypt the JDBC Config file
You can encrypt this file for additional security. Click here to learn more.
Step 3 - Update Your JDBC Organization Resource Value
The resource.jdbc.config Organization Resource specifies the location of the JDBC Config file on the logged in user's local machine. This resource value should contain the full directory path (e.g., /home/user/dev). Click here to see step-by-step instructions.
Step 4 - Update your Profile in the .genrocket Folder
Each user has a profile stored in the .genrocket folder on their local machine. You must download and replace your profile (in ~/.genrocket folder). GenRocket will read this resource value from your profile on your system to make a connection with the database. Click here for more information.
Step 5 - Download and place the JDBC connector Jar file in the $GENROCKET_HOME/lib/ folder
Download and place the appropriate JDBC connector Jar file in your genrocket/lib folder. The location of the genrocket/lib folder will depend on where GenRocket Runtime has been installed: a local user machine, a shared machine, or a server.
Links are provided below for the following database JDBC connector jar files:
Database | Link |
MySQL | You can download the JDBC Connect for MySQL at this link. |
Oracle | You can download the JDBC connector for Oracle at this link. |
MS SQL | Microsoft provides the JDBC driver for free. You can download the one that works for your version of SQL Server from one of these links:
For information about system requirements and detailed information about each of the drivers listed above, please go to https://docs.microsoft.com/en-us/sql/connect/jdbc/system-requirements-for-the-jdbc-driver. |
Step 6 - Test the JDBC Connection (SQL Databases Only)
You can test the JDBC connection for SQL databases before referencing the resource in GenRocket. Click here to learn more.
Step 7 - Reference the JDBC Resource as Needed
When you create a Scenario containing a Generator or Receiver that references your jdbc.config resource, it will connect directly to your database. GenRocket feature that uses a database connection will also need to reference this file.