Document Tree
Document Properties
Kbid
29835N
Last Modified
16-Jul-2024
Added to KB
29-Mar-2021
Public Access
Everyone
Status
Online
Doc Type
Concepts
Product
ICM 7.10
Concept - DBPrepare (valid to 7.10)

Introduction

Info

This document is valid from Intershop Commerce Management 7.10.14.0.

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

Glossary

This glossary describes the terms in this concept:

Term

Description

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.

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

dbinit.properties - example snippet of core cartridge
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

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

Use Cases

Operational Use Cases

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


Description

Command

1

Initialization of an empty database

./dbprepare.sh -classic

2

Migration of database

./dbprepare.sh -classic

Developer Use Cases


Description

Command

Example

1

Initialization of a database (does not matter if empty or not)

./dbprepare.sh -classic -cdb=yes


2

Migration of database

./dbprepare.sh -classic


4

Filter execution to specific cartridges (you are able to verify the result)

./dbprepare.sh -classic --cartridges=<CARTRIDGES>

./dbprepare.sh -classic --cartridges=core,bc_foundation

5

Explicit 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

6

Get additional command line options

./dbprepare.sh --help


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
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.
Home
Knowledge Base
Product Releases
Log on to continue
This Knowledge Base document is reserved for registered customers.
Log on with your Intershop Entra ID to continue.
Write an email to supportadmin@intershop.de if you experience login issues,
or if you want to register as customer.