Managing Database Components Using a Template

Example Structure of a Template with a Database Layer and a Run-time Layer

environments:
  default:
    is.integrationserver.license.key: "*_PIE_10.*_*_*"
    is.instance.name:   default
    is.primary.port:    5555
    is.diagnostic.port: 9999
    is.jmx.port:        8094
    is.fixes:
      - wMFix.IntegrationServer.Core
    db.host:             ${}
    db.version:          10.5    # Specifies the release version of Integration Server.
    db.type:             mysql
    db.port:             3306
    db.admin.username:   ${}
    db.admin.password:   ${}
    db.admin.url:        "jdbc:mysql://${db.host}:${db.port}"
    db.url:              "jdbc:mysql://${db.host}:${db.port}/${db.name}"
    db.name:             webm
    db.username:         ${}
    db.password:         ${}
    db.str.components:          # List the ID of the database storage component.
      - STR
    db.is.components:           # List the IDs of the Integration Server database components,
      - ISInternal              # for which to manage the schemas in the database.
      - ISCoreAudit
      - DistributedLocking
    dbc.scripts:
      - DatabaseComponentConfigurator # List the product ID of Dabase Component Configurator
      - PIEcdc                     # and the IDs of the database scripts for Integration Server.
      - PIEEmbeddedCdc
      - PIEMobileCdc
   dbc.fixes: ALL               # Database Component Configurator fixes to install.
layers:
  db:
    productRepo: ${repo.product}      # Install products from this product repository.
    fixRepo:     ${repo.fix}          # Install fixes from this fix repository.
    templates:   dbc
    databases:
      storage:
        components:  ${db.str.components}
        version:     latest
        db.type:     ${db.type}
        db.url:      ${db.admin.url}
        db.admin.username: ${db.admin.username}
        db.admin.password: ${db.admin.password}
        db.username: ${db.username}
        db.password: ${db.password}
        db.name:     ${db.name}
      schemas:
        products:    ${db.is.components.${version}}
        version:     ${db.version}
        db.type:     ${db.type}
        db.url:      ${db.url}
        db.username: ${db.username}
        db.password: ${db.password}
        db.name: ${db.name}
  runtime:
    productRepo: ${is.repo.product}         
    templates: is-server

templates:
  is-server:
    licenses:
      "IntegrationServer/config/licenseKey.xml": "${is.integrationserver.license.key}"	
    fixes: ${is.fixes}
    products:
      integrationServer:
        ${is.instance.name}:
          primary.port: ${is.primary.port}
          diagnostic.port: ${is.diagnostic.port}
          jmx.port: ${is.jmx.port}
          license.file: IntegrationServer/config/licenseKey.xml
          db.url: jdbc:wm:${db.type}://${db.host}:${db.port};databaseName=${db.name}
          db.username: ${db.username}
          db.password: ${db.password}
          configuration:
            OSGI-IS_${instance.name}:
          ...
  dbc:
    products: ${dbc.scripts}
    fixes: ${dbc.fixes}		   
provision:
  default:
    db: ${nodes}
    runtime: ${nodes}

The layers: section defines a db: layer with the dbc: inline template. To manage a database, you must ensure that Database Component Configurator and the database scripts of the product(s) are installed in the product installation. The dbc: inline template in the example instructs Command Central to install Database Component Configurator and the database scripts for Integration Server, and then update them to the latest fix. The database scripts of the product are listed in environments:default:dbc.scripts:

The name of the database script starts with the product ID and ends with "cdc". You can find a list of the product database scripts in the sample database templates in sagdevops-templates.

The databases: section of the db: layer includes two database action sections:

• storage: creates the database storage for the database components:, listed in the environments:default:db.str.components: parameter. This section includes the database parameters required to manage the storage component.
• schemas: identifies the database components for which Command Central manages the database schemas, and includes the database parameters required to manage the schemas. In the example, the database components for Integration Server are listed in the environments:default:db.is.components: parameter.

You can define a parameter that lists the database components for a product as follows:

environments:
  default:
    db.<productID>.components:
      - dbcomponentA
      - dbcomponentB

The sample database templates in sagdevops-templates include parameters for all products, which you can use as example. For usage notes and other details about the database components supported by Database Component Configurator, see Database Component Descriptions and Installation Requirements in Installing IBM webMethods Products .

In the provision: section of the template, the database layer must map to a local or remote Platform Manager node. The database layer can only map to a remote Platform Manager node of release 9.10 or higher.

How Does Command Central Apply a Template with a Database Layer?

Based on the value of the environment.mode argument that you include in the sagcc exec templates composite apply command, Command Central does the following:

environment.mode=provision

1. Installs Database Component Configurator and the database scripts listed in the dbc.scripts: parameter in the environments:default: section.

   Note that when installing the database script of a product, Command Central installs all of its dependent scripts, even when the dependent scripts are not listed in the dbc.scripts: section.

2. Installs all available fixes for Database Component Configurator.
3. Creates the storage database component. The version of the database storage is always latest.

4. Executes the create action for the database schemas of the database components listed in the db.productID.components: parameter(s). Command Central can create database schemas with version equal or lower than the value of db.version: (which is the release version of the product).

   In the example, Command Central creates the schemas for the database components listed in db.is.components:

5. Installs the product, creates and configures the product instance.

   In the example, Command Central installs Integration Server, creates the is.default instance, updates the instance with the specified fix, and then configures the instance.

environment.mode=migration

1. Installs Database Component Configurator and the database scripts listed in the dbc.scripts: parameter in the environments:default: section.

   Note that when installing the database script of a product, Command Central installs all of its dependent scripts, even when the dependent scripts are not listed in the dbc.scripts: section.

2. Installs all available fixes for Database Component Configurator.
3. Creates the storage database component. The version of the database storage is always latest.

4. Executes the migrate action for the database schemas of the database components listed in the db.productID.components: parameter.

   In the example, Command Central migrates the schemas for the database components listed in db.is.components:

5. Migrates the product instance.

   In the example, Command Central migrates the is.default instance.

environment.mode=maintenance

Use this mode to install a Database Component Configurator fix that contains database schema changes.

If you apply a maintenance template (a template that has a database layer and a run-time layer) in maintenance mode, Command Central does the following:

1. Pauses and then stops the run-time components on all nodes included in the provision: section of the template.

2. Applies only the fixes defined in the database inline template and the run-time template. In the example, when Command Central processes the dbc: inline template, it installs only the dbc.fixes to which the fixes: section refers, but does not install the dbc.scripts to which the products: section refers. When Command Central processes the is-server inline template, it installs only the is.fixes defined in the fixes: section.

   Note that in maintenance mode, Command Central does not create or migrate product instances, or apply configurations.

3. Executes the migrate database action for the database schemas of the database components listed in the db.productID.components: parameter.

   In the example, Command Central migrates the schemas for the database components listed in db.is.components:

If you apply a database template (a template that has only a database layer) in maintenance mode, you must stop the product instances on the nodes manually, before applying the template. Then after applying the database template, you must apply the fixes for the product instances in the installation.

By default, the run-time components in the installation are not started after applying a template with database layer in maintenance mode. If you want to control this behavior, include the maintenance: section in the template definition, as follows:

alias: is-maintenance-dcc
description: Update DCC to the latest fix
maintenance:
  options:
    pause: true | false     # "true" (default) - pause all runtimes, before stopping them
                            # "false" - do not pause the runtimes
    shutdown: true | false  # "true" (default)- stop all runtimes before installing fixes
                            # "false" - do not stop the runtimes