Introduction

DBPrepare is a tool for creating and updating the database schema objects and for preparing required database content of one or more cartridges. The DBPrepare tool recognizes prepared or up-to-date cartridges and their declared preparer steps. As a result of stored execution protocol for each cartridge, DBPrepare only needs to execute new preparer steps, resulting in a significantly reduced execution time. Additionally, DBPrepare 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.

References

• Cookbook - DBPrepare

• Concept - DBMigrate and DBInit (former tooling for initialization and migration)

Glossary

This glossary describes the terms in this concept:

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 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

Class32 = com.intershop.beehive.core.dbinit.preparer.locking.JobResourcePreparer \
    com/intershop/beehive/core/dbinit/data/locking/jobresources.resource

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

Resources

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

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

Use Cases

Operational Use Cases

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

Developer Use Cases

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, s.FAILURECOUNT
from CARTRIDGEINFORMATION C
, PREPARATIONSTEP S
where c.UUID = s.CARTRIDGEUUID
order by c.INTERNALNAME, s.STARTDATE