Configuring HCL Traveler for enterprise database

You can configure the HCL Traveler server to use the database created in Deploying and configuring the enterprise database.

Complete the steps in this section to create a High Availability (HA) pool or add a server to an existing HA pool.

The HCL Traveler server application accesses the enterprise database using a Java™ DataBase Connectivity API standard (JDBC), that enables Java™ programs to execute vendor independent SQL statements. The JDBC software drivers, and the detailed documentation on how to configure them, come from the respective database system vendor products: IBM® DB2® , MySQL, or Microsoft™ SQL Server. This section provides examples of how to configure HCL Traveler for commonly used enterprise database options. Links are provided to the more detailed references from each enterprise database product.

CAUTION: When you configure a standalone server to use an enterprise database, the server migrates existing user and security information to the enterprise database. However, if you configure from an enterprise database to another database or back to standalone, no user or security data is migrated. Starting with Traveler 12.0.1, DB2 to MySQL migration is supported. For more information, see DB2 to MySQL Database Migration.

Perform the following procedure for each HCL Traveler server that is part of the pool:

Note: On Linux® or AIX®, run the following commands as the root user.

Note: On Windows™, run the following commands as an administrator.

Prepare the stand-alone database for migration by ensuring the following requirements have been met:
1. Defragment the stand-alone database prior to migration. For more information, refer to Defragmenting the internal database for improved performance.
2. Make sure the network between the stand-alone HCL Traveler database and enterprise database is a lower latency, higher speed network. Avoid running the migration across a slow network from site A to the enterprise database at site B. If necessary, move the HCL Traveler server physically closer to the enterprise database server.
3. Create a backup of the NTSDB folder and the Lotus Traveler.nsf. Make sure Domino is not running when the backup is created.
Ensure that the HCL Traveler DB is created and available.
Download and prepare the JDBC Driver:
- Use a JDBC driver that supports Java™ 8. Domino® 9.0.1 FP8 and later uses Java™ 8.
- JDBC drivers can be stored in any directory. <domino>\Traveler\lib directory is used as an example throughout. If you use this directory for storing the JDBC driver file make sure you only have the version of the JDBC driver you using in the directory.
- For DB2® servers only: Locate the db2jcc4.jar file on the DB2® Server (<db2_install_dir>\sqllib\java). Copy the db2jcc4.jar file from the DB2® server to the <domino>\Traveler\lib directory.
  Note: Use DB2® JDBC Driver V10.5 FP7 (4.19.49) or higher for Java™ 8 . See technote 1983724 for details. The DB2® JDBC Driver can be downloaded directly from Fix Central. See technote 1363866 for download information.
- For SQL servers only: Copy the mssql-jdbc-<version>.jre8.jar file to the <domino>\Traveler\lib directory. Download the latest jre8 Microsoft SQL Server JDBC Driver from this article. For detailed system requirements for the SQL Server JDBC driver, see System requirements for the JDBC driver. MS SQL 10.2.0 and later JDBC drivers have connections enabled with TLS encryption by default. If the target SQL Server is not using SSL TLS encryption either use the encrypt=false parameter to disable TLS encryption (i.e. jdbc:sqlserver://<yoursqlserver>.com:1433;databaseName=traveler;encrypt=false) or use the MS SQL 9.2.1 JDBC driver. SSL can also enabled on the database server if the version of MS SQL Server supports it.
- For MySQL servers only: Locate the latest MySQL connector for your appropriate operating system from this page. Copy the mysql-connector-j-<version>.jar to <domino>\Traveler\lib. A complete list of JDBC connection properties for MySQL can be found here.
  Note: MySQL JDBC support requires Domino 11 as it needs the openJDK 1.8. Prior Domino versions with IBM JDK do not work with the MSQL Connector/J jdbc driver.
Open a command prompt.
Change directory to <domino data>\traveler\util.
Run travelerUtil to configure HCL Traveler. Make sure the user=<db login user> has the proper permissions as specified in the Database permissions.
Note: The utility validates the DB information and configures HCL Traveler to use the target Enterprise DB instead of the default derby database. The credentials are encrypted and stored in the LotusTraveler.nsf. If you do not specify any parameters for travelerUtil db set, it prompts you for all required parameters (the database URL, the database login id, the database login password, and the full JDBC path). To validate what you configured, use the travelerUtil db show command (this will not show the password) or the travelerUtil db check command to verify that the configuration allows database connections to be made. Use the same utility to update the password.
Note: travelerUtil operations require the Traveler task not to be running. Certain travelerUtil operations may also require the Domino server to not be running. For more information on the travelerUtil tool, see travelerUtil commands.
- For DB2® servers only: Run travelerUtil to configure HCL Traveler in the following format:
```
travelerUtil db set url=jdbc:db2://<db2server hostname>:<db port>/
<traveler db name> user=<db login user> pw=<db login password> path=<libPath>
```
  Important: There are many different URL formats allowed for DB2®. See the IBM® DB2® product Information Center for all possible variations.
  One common variation is to use an IBM® DB2® High Availability (HADR) configuration with a primary and alternate server and exploit a capability called Automatic Client Reroute. For DB2® for Linux®, UNIX®, and Windows™, the JDBC URL to utilize automatic client reroute in the travelerUtil db set command would look like the following:
```
travelerUtil db set url=jdbc:db2://primaryDBbserver.yourco.com:50000/TRAVELER:
clientRerouteAlternateServerName=alternateDBserver.yourco.com;clientRerouteAlternatePortNumber=50000;
retryIntervalForClientReroute=10;maxRetriesForClientReroute=3; user=LNTUSER pw=passw0rd path=<domino>\Traveler\lib\db2jcc4.jar
```
  Note: Automatic Client Reroute is not supported by the DB2® JDBC driver for IBM® i.
  The URL for connecting to a single DB2® server consists of the fully qualified hostname of the database server, the port for the database instance (the default value is 50000), and the database name. For example:
```
travelerUtil db set url=jdbc:db2://dbserver.yourco.com:50000/traveler 
user=LNTUSER pw=passw0rd path=<domino>\Traveler\lib\db2jcc4.jar
```
  Upon execution, the utility validates the DB2® information and configures HCL Traveler to use the DB2® instance instead of the default derby database. The credentials are encrypted and stored in the LotusTraveler.nsf. If you do not specify any parameters for travelerUtil db set, it will prompt you for all required parameters (the DB2® URL, the database admin id, and the database admin password).
  To validate what you just configured, use the travelerUtil db show command (this will not show the password) or the travelerUtil db check command to verify that the configuration allows database connections to be made.
  You will use the same utility to update the password in the event that becomes necessary.
- For HCL Traveler servers running on Windows™ connecting to SQL servers: Run travelerUtil to configure HCL Traveler in the following format:
```
travelerUtil db set url=jdbc:sqlserver://<sqlserver hostname>:<db port>;
databasename=<traveler db name> user=<db login user> pw=<db login password>
path=<libPath>
```
  For example:
```
travelerUtil db set url=jdbc:sqlserver://dbserver.yourco.com:1433;databasename=TRAVELER 
user=LNTUSER pw=passw0rd path=<domino>\Traveler\lib\mssql-jdbc-<version>.jre8.jar
```
  Note:
  
  Note: travelerUtil operations require the Traveler task not to be running. Certain travelerUtil operations may also require the Domino server to not be running. For more information on the travelerUtil tool, see travelerUtil commands.
  Important: There are many different URL formats allowed for SQL server. See the Microsoft™ SQL Server documentation for all possible variations. Depending on the JDBC driver used and MS Server SSL configuration you may need to use ;encrypt=false in the URL. See the note in Step 3 for SQL Server only above for more information.
  Another common variation is using a database mirror. If you are using a mirror, add ;failoverPartner=hostname to the end of the previous URL. The Microsoft™ documentation for building the JDBC Connection URL can be found here, while the description of the connection properties can be found here.
  For example:
```
travelerUtil db set url=jdbc:sqlserver://dbserver.yourco.com:1433;databasename=TRAVELER;failoverPartner=altdbserver.yourco.com 		
   user=LNTUSER pw=passw0rd path=<domino>\Traveler\lib\mssql-jdbc-<version>.jre8.jar
```
- For HCL Traveler servers running on Linux® or AIX connecting to SQL servers:
  Run ./travelerUtil in the following format:
```
travelerUtil db set user=<db login user> pw=<db login password>
```
  For example:
```
./travelerUtil db set user=LNTUSER pw=passw0rd 
```
  Note: The url command line parameter for SQL Server on Linux® or AIX will not work because of the required semicolon.
  You will be prompted for your database URL. The following example shows a sample database URL for an SQL server:
```
jdbc:sqlserver://dbserver.yourco.com:1433;databasename=TRAVELER
```
  Upon execution of steps 7 or 8, the utility validates the SQL Server DB information and configures HCL Traveler to use the SQL Server DB instance instead of the default derby database. The credentials are encrypted and stored in the LotusTraveler.nsf. If you do not specify any parameters for travelerUtil db set, it will prompt you for all required parameters (the database URL, the database admin id, and the database admin password).
  To validate what you just configured, use the travelerUtil db show command (this will not show the password) or the travelerUtil db check command to verify that the configuration allows database connections to be made.
  Important: Depending on the JDBC driver used and MS Server SSL configuration you may need to use ;encrypt=false in the URL. See the note in Step 3 for SQL Server only above for more information. Another common variation is using a database mirror. If you are using a mirror, add ;failoverPartner=hostname to the end of the previous URL.
- If connecting to a SQL Server Always On Availability Groups configuration, the following additional configuration may be needed for the Traveler environment to successfully connect to the Always On configuration.
  - The Traveler server may hang if trying to configure an Always On database to allow Snapshot Isolation and Read Committed Snapshots. To prevent hanging, disable the Traveler feature that sets these values then ensure they are properly configured on your SQL Server Database, as follows.
    Set this notes.ini parameter on all Traveler servers that will connect to the Always On configuration. A restart of the Traveler server is required for the change to take effect.
```
NTS_DB_FORCE_SNAP_ISO=false
```
    Configure the SQL Server Always On database to allow Read Committed Snapshot Isolation. This can be done through the MS SQL Server Management Studio or by running the following SQL Commands:
```
ALTER DATABASE <databasename> SET ALLOW_SNAPSHOT_ISOLATION ON
ALTER DATABASE <databasename> SET READ_COMMITTED_SNAPSHOT ON
```
    For more information about Snapshot Isolation, the MS SQL documentation.
  - The JDBC URL for a SQL Server Always On configuration may vary based on your setup, but in general you should add the multiSubnetFailover property to the URL instead of using the failoverPartner property. For example:
```
jdbc:sqlserver://dbserver.yourco.com:1433;databasename=TRAVELER;multiSubnetFailover=true
```
    For a complete list of JDBC Properties and accepted values see the MS SQL documentation.
  - Currently the Traveler server does not support Windows based authentication for use with the SQL Server Always On configuration. To workaround this limitation, enable the SQL Servers to allow both SQL Server Authentication and Windows Authentication. You may need to create a user on each SQL Server with proper access to the Traveler database if one is not already configured. Note each SQL Server should use the same username and password as you can only configure the Traveler server with one value.
    For more information, see the MS SQL documentation.
  - The SQL Server Always On Availability Groups should be configured for failover and availability but NOT LOAD BALANCING. All traffic for the Traveler database should be handled by the same physical SQL Server. Failover is supported, but all connections should failover to the same SQL Server. For more information about configuring SQL Server Always On, see the MS SQL documentation.
- For MySQL servers only:
  Run travelerUtil to configure HCL Traveler in the following format:
```
travelerUtil db set url=jdbc:mysql://<Server Name>:3306<database name> user=<db login user> pw=<db login password> path=<libPath>
```
  For example:
```
./travelerUtil db set url=jdbc:mysql://dbserver.yourco.com:3306/TRAVELER user=LNTUSER pw=passw0rd path=<domino>\Traveler\lib\mysql-connector-j-<version>.jar
```
  Important: There are many different URL formats allowed for MySQL. For all possible variations, see the MySQL product documentation.
  The following error may arise:
```
Unable to connect to database: The server time zone value 'EDT' is unrecognized or represents more than one time zone. 
You must configure either the server or JDBC driver (via the 'serverTimezone' configuration property) to use a more 
specific time zone value if you want to utilize time zone support. Database configuration was not saved.
```
  In order to work around this issue, the user must enter an additional parameter - ?serverTimezone=<Your server timezone> - onto the connection string to specify a more specific timezone value. Check the Servers Timezone settings and determine the specific timezone value for your configuration. For further information regarding this issue, see this article.
```
travelerUtil command ./travelerUtil db set url=jdbc:mysql://dbserver.yourco.com:3306/TRAVELER?serverTimezone=EST5EDT user=LNTUSER pw=passw0rd path=<domino>\Traveler\lib\mysql-connector-j-<version>.jar
```
  It is common to use database replication and URL failover. When using URL failover, add the alternate database to the end of primary server database behind a comma. Be sure to specify failOverReadOnly is equal to false. For example:
```
travelerUtil db set url=jdbc:mysql://dbserver.yourco.com:3306,altdbserver.yourco.com:3306/TRAVELER?failOverReadOnly=false user=LNTUSER pw=passw0rd path=<domino>\Traveler\lib\mysql-connector-j-<version>.jar
```
  For the full list of failover URL configuration options, see the MySQL Configuring Server Failover for Connections Using JDBC documentation. For more information about database replication, see MySQL's Replication documentation.
Configure HCL Traveler to skip creating the database schema (optional).
By Default, HCL Traveler will automatically create the database schema and database objects needed by HCL Traveler if they do not exist during startup. If you created the HCL Traveler database using the database wizard and want HCL Traveler to automatically handle creating and altering the database schema, you can skip this step. However, If you configured the HCL Traveler database using the DDL and want to handle the database schema manually, then add the following entry to the notes.ini to ensure HCL Traveler does not alter the database schema.
```
NTS_AUTO_DBSCHEMA=false
```
If you changed the schema name in the DDL files, you must set the following property in the notes.ini, where <schemaname> is the schema name used in the DDL files:
```
NTS_DB2_SCHEMA=<schemaname>
```
Start HCL Traveler. If this HCL Traveler server was an existing stand-alone server, the existing user data will be automatically transferred into the HA pool. The status of the transfer process will display in the console, and upon completion, the HCL Traveler server will automatically start and begin servicing client requests.
Validate Traveler Server and Database server times are the same.
1. Issue a tell traveler systemdump command from the Domino Console on the Traveler Server.
2. Review the generated systemdump file and check that there is little to no time difference between the Current Time and the Database Time and the servers are conifgured for the same timezone.
```
Current Time (Local): Wed Oct 07 11:51:34 EDT 2020 (1602085894175)
Current Time (GMT): Wed Oct 07 15:51:34 GMT 2020 (1602085894175)
Java Time Zone Data version: {2019c=ZoneRules[currentStandardOffset=Z]}
Database Time (Local): Wed Oct 07 11:51:33 EDT 2020 (1602085893247)
```
  For further regarding this issue, see this article.

Alternatives to the travelerUtil application

If you experience problems with the travelerUtil application, the same settings can be set using the equivalent notes.ini parameters. If you are using notes.ini parameters, however, you will bypass the check connection phase and the HCL Traveler server may not function if it is unable to connect to the database server. When setting the notes.ini parameters, shutdown the Traveler server, set the parameters, then restart the server.

For parameter details, see the values for NTS_DB* in Notes.ini settings.