Configuring a Database for the Engine

Checkpoint activity and other persistence features require the Engine Persistence Mode (bw.engine.persistenceMode) to be configured for a datastore or group mode. When the Engine Persistence Mode property is configured for datastore or group mode, the engine requires a database configuration.

Procedure
1. Scripts for creating the engine database for various database types are at BW_HOME/config/dbscripts/engine. Based on whether the Engine Persistence Mode property is configured for datastore mode or group mode, complete one of the following steps:
   1. If the Engine Persistence Mode property is set to datastore mode, run the bundled scripts create.sql and create-scp.sql to create the engine database.
   2. If the Engine Persistence Mode property is set to group mode, run the bundled scripts create.sql and create-dcp.sql to create the engine database.
   Note: The create.sql, create-scp.sql, and create-dcp.sql scripts are available for each vendor directory in the {BW_HOME}\config\dbscripts\engine directory.
2. To change the Engine Persistence Mode, run the utility to set the Persistence Mode property, bw.engine.persistenceMode to datastore or group, and then configure the engine database connection details.

   bw.engine.persistenceMode=[datastore | group]

   Note: Before updating the AppSpace configuration, you must stop the AppSpace if it is running.

   The database connection configuration can be specified at the AppSpace or the AppNode level. The database connection details specified at the AppSpace level are applied to all AppNodes within the AppSpace. The configuration specified at the AppNode level takes precedence over the configuration specified at the AppSpace level.

   When the Engine Persistence Mode property is set to group, the database connection configuration must be specified only at the AppSpace level.

   When the Engine Persistence Mode property is set to datastore, the database connection configuration cannot be shared by two or more AppNodes in the same AppSpace. As a result, the database connection configuration can be specified at the AppSpace level only if the AppSpace contains a single AppNode. For an AppSpace that contains two or more AppNodes, each AppNode requires a unique database and the database connection configuration must be specified at the AppNode level.

3. To set database configuration properties at the AppSpace level, follow these steps:
   Note: Ensure you are using a different database instance for each AppSpace. To do this with a single database, create a tablespace or schema for each AppSpace.
   1. Copy the existing AppSpace config.ini file (in the root of the AppSpace folder), or the AppSpace config.ini template file appspace_config.ini_template (in BW_HOME/config/) to a temporary location.
   2. Edit the Engine Persistence Mode property, bw.engine.persistenceMode, and set it to datastore or group.

      bw.engine.persistenceMode=[datastore | group]

   3. Configure the following database connection properties in the BWEngine Database Configuration section of the config.ini file:

      #------------------------------------------------------------------------------
      # Section:  BW Engine Database Configuration.  
      #
      # The properties in this section are applicable to the BW Engine database.  
      # All properties in this section are required when the BW Engine 
      # property "bw.engine.persistenceMode" set to "datastore" or "group".
      # ------------------------------------------------------------------------------
      # BW Engine Database Driver.  
      bw.engine.db.jdbcDriver=org.postgresql.Driver
      
      # BW Engine Database URL.
      bw.engine.db.url=jdbc:postgresql://<servername>:<portnumber>/<dbname>
      
      # BW Engine Database User Name.
      bw.engine.db.userName=user1
      
      # BW Engine Database User Password.
      bw.engine.db.password=
      
      # BW Engine Database Connection Pool Size.  
      bw.engine.db.maxConnections=15

      When setting the password property (bw.engine.db.password), the default format is plain text. Run the command bwadmin obfuscate, or the command bwobfuscator, from the command line to encrypt the password; use the generated encrypted text as the password.

      Note: The BWAdmin bwenginedb command displays BWEngine datastore configuration settings.

4. To set the database for datastore mode at the AppNode level, follow these steps:
   1. Copy the existing AppNode config.ini file (in the root of the AppNode folder) to a temporary location.
   2. Set Engine Persistence Mode property, bw.engine.persistenceMode to datastore and configure the engine database connection details.

      bw.engine.persistenceMode=[datastore]

   3. Configure the engine database connection properties in the BWEngine datastore configuration section of the config.ini file. By default, the AppNode config.ini file does not contain these properties. Copy these properties from the AppSpace config.ini template file, appspace_config.ini_template, in BW_HOME/config to the AppNode config.ini file and provide the database connection details.
5. Use one of the following config admin commands to push the configuration to the AppSpace or the AppNode:
   AppSpace:

   bwadmin[admin] > config -d myDomain -a myAppSpace -cf <temporaryLocation>/config.ini

   AppNode:

   bwadmin[admin]> config –d myDomain –a myAppSpace -n myAppnode –cf <temporaryLocation>/config.ini

6. Restart the AppSpace.
7. Note: Before you clean the engine database, ensure that you have backed up all important data.
   To clean the engine database that is configured for datastore mode, run the drop.sql and drop-scp.sql scripts. If the engine database is configured for group mode, run the drop.sql and drop-dcp.sql scripts.