Concept - DBPrepare

1 Introduction

Info

This document is valid from Intershop Commerce Management 7.10.14.0.

DBPreprare is a tool for creating and updating the database schema objects and for preparing required database content of one or more cartridges. The DBPreprare tool recognizes prepared or up-to-date cartridges and their declared preparer steps. As a result of stored execution protocol for each cartridge, DBPreprare only needs to execute new preparer steps, resulting in a significantly reduced execution time. Additionally, DBPreprare initializes new cartridges, so explicit initialization of new cartridge is no longer required.

DBPrepare uses the declaration files of DBinit and DBmigrate and replaces the functionality of DBInit and DBMigrate.

1.1 Documentation

2 Glossary

This glossary describes the terms in this concept:

TermDescription

Cartridge

From a developer's perspective, a code container for implementation artifacts like templates, pipelines, Java code etc. that provide business logic or technical functionality to Intershop 7.

From a system administrator's perspective, a type of deployment component for implementation artifacts that provide business logic or technical functionality to Intershop 7.

Preparer

A preparer implements a database initialization or migration processor. Both preparers are processed by DBPrepare to prepare the database content of one or more cartridges.

3 General Processing

There are three processing phases in the DBPrepare tools with the following processing order:

  1. Pre-processing
  2. Main-processing
  3. Post-processing

Each phase loops through the list of cartridges (the property cartridges.dbinit within cartridgelist.properties).

DBPrepare Process

3.1 DBPrepare Cartridge Initialization

In case the initialization of a cartridge was not done before, the initialization process of the cartridge starts.

Each cartridge can contain an initialization declaration in:

  • Configuration file:
    • dbinit.properties
  • Each property in this file has the format:[pre.|post.]ClassN = Preparer [params]
    • N - floating point number support, >= 0
dbinit.properties - example snippet of core cartridge
pre.Class1   = com.intershop.beehive.core.dbinit.preparer.database.DatabaseTablesPreparer
...
Class1       = com.intershop.beehive.core.dbinit.preparer.database.SQLScriptPreparer \
               resources/core/dbinit/scripts/utctimestamp.sql
...
post.Class50 = com.intershop.beehive.core.dbinit.preparer.locking.RemoveAllProcesses

3.2 DBPrepare Cartridge Migration

In case the cartridge initialization is registered, the migration process of a cartridge starts.

Cartridge-specific preparer:

  • Configuration files:

    • Version-independent: migration.properties

    • Version-dependent: migration-to-<version>.properties

  • Property: [pre.|post.]ClassN = Preparer [params]

    • N - floating point number support , >= 0

Migration Path:

  • The migration version path is calculated for each cartridge based on the migration-to-<version>.properties files.

The order of the migration files is calculated from the version part of the file name:

  • Version_1 , Version_2 , ... Version_n string should map to the corresponding file name

    • migration-to- Version_1.properties ,

    • migration-to- Version_2.properties ...

    • migration-to- Version_N.properties

4 Resources

4.1 Resource Files

Initialization and migration preparer can use the same resources and classes as the application server. To avoid resource conflicts, we recommend using the folder with the cartridge name under resources.

  • IS_SOURCE/<cartridge>/src/main/resources/<cartridge>/dbinit/data/<type_of_data>

SQL scripts:

  • IS_SOURCE/<cartridge>/src/main/resources/<cartridge>/dbinit/scripts

4.2 UUIDs

UUIDs are used to identify persistent objects inside a database table. In case DBPrepare creates new objects in the database, we recommend to use a predefined set of UUIDs to avoid conflicts or duplicated data during the replication process

The data replication feature requires the same UUID for the same object on edit and live system.

5 Use Cases

5.1 Operational Use Cases

It is highly recommended to avoid additional parameters for the DBprepare command.


DescriptionCommand
1Initialization of an empty database./dbprepare.sh -classic
2Migration of database./dbprepare.sh -classic

5.2 Developer Use Cases


DescriptionCommandExample
1Initialization of a database (does not matter if empty or not)./dbprepare.sh -classic -cdb=yes
2Migration of database./dbprepare.sh -classic
4Filter execution to specific cartridges (you are able to verify the result)./dbprepare.sh -classic --cartridges=<CARTRIDGES>./dbprepare.sh -classic --cartridges=core,bc_foundation
5Explicit run of a specific preparer (you are able to debug and restart already registered steps)./dbprepare.sh -classic --force-exec-id=<IDs>./dbprepare.sh -classic --force-exec-id=core:pre.Class1,xcs:Class1
6Get additional command line options./dbprepare.sh --help

6 Registration and Protocol of DBPrepare Steps

Each execution step of DBPrepare is protocolized at PREPARATIONSTEP table. The following statement provides good insights into former executions:

select c.INTERNALNAME, s.ID, s.STARTDATE, s.ENDDATE, s.version, s.type, s.PHASE, s.RUNSTATUS
from CARTRIDGEINFORMATION C
, PREPARATIONSTEP S
where c.UUID = s.CARTRIDGEUUID
order by c.INTERNALNAME, s.STARTDATE

Disclaimer

The information provided in the Knowledge Base may not be applicable to all systems and situations. Intershop Communications will not be liable to any party for any direct or indirect damages resulting from the use of the Customer Support section of the Intershop Corporate Web site, including, without limitation, any lost profits, business interruption, loss of programs or other data on your information handling system.

Customer Support
Knowledge Base
Product Resources
Tickets