Managing Database

Liquibase is an open source (Apache License), database-independent management library with a database-backed version control system.

Liquibase tracks all database changes in one or more changelogs. Each changelog contains one or more changesets. Each changeset describes the changes that need to be applied to the database in a database independent manner. As Liquibase applies the changeset to your database, it writes a row in a DATABASECHANGELOG table indicating the changeset is applied. On subsequent executions, Liquibase compares the changesets in the changelog with the ones stored in DATABASECHANGELOG. If a changeset has already been applied, Liquibase will not reapply the change and will not add a new entry in DATABASECHANGELOG.

Liquibase creates a checksum for each changeset. Once you have applied a changeset to a database, it must not be edited in the changelog or Liquibase will require you to resolve the checksum mismatch.

For more information, see the Liquibase Manual.

Data Population with Liquibase

Elastic Path projects use a combination of Liquibase scripts and Import/Export data to populate the commerce database.

The Data Population Tool provides a unified mechanism to create new databases or update existing databases. It uses Liquibase to manage the execution of both Liquibase scripts and Import/Export data by wrapping each Import/Export data set in a Liquibase change set. This has a number of benefits:

• Import/Export updates are applied only once to the database, unless configured otherwise.

• Using Liquibase contexts, Import/Export data sets can be applied only to specific environments.

  For example, the test data that shouldn’t go to production.

• Property placeholders can be defined in both Liquibase and Import/Export data.

  These placeholders are filtered at run time using an external properties file to support populating environment-specific values.

Liquibase Changelog Files

When Data Population is executed, the following Liquibase changelog files are processed:

• extensions/database/ext-data/src/main/resources/schema/schema-initializer-changelog.xml
  • commerce-engine/liquibase/core-schema/src/main/resources/elasticpath-db-changelog.xml
    • commerce-engine/liquibase/core-schema/src/main/resources/core-changelog-master.xml
      • All platform changelog files plus custom changelog injection points (schema-customizations-changelog-<version>.xml)
• extensions/database/ext-data/src/main/resources/schema/schema-customizations-changelog.xml (deprecated)

To make custom database schema changes, add changeset entries to the extensions/database/ext-data/src/main/resources/schema/schema-customizations-changelog-<version>.xml changelog file, where <version> is set to your current Self Managed Commerce version, without any dots (i.e. 830).

Adding your changesets within this version-specific file ensures that if Elastic Path modifies the schema in the future, your changesets will not fail because they will execute against a schema in a known state. If you later upgrade to a new version of Self Managed Commerce, your existing changesets should stay in that file, but any new changesets should be added to the schema file for your new version. Platform changesets for each version will be executed before each corresponding schema-customizations-changelog-<version>.xml file, and platform changesets for future versions will be executed after the schema customizations file.

Generating Database Schema Documents

Using SchemaSpy, a Java-based command-line interface tool, you can generate database schema documents from your database.

Before you start

You must have Graphviz installed on your machine. Graphviz is required in the generation of the table/view relationships graph.

To generate your database schema documents:

1. Open the command prompt and navigate to extensions/database/ext-schema-documentation

2. Execute the command below to run Maven’s site plugin and generate the documentation.

   mvn site
   

3. Navigate to extensions/database/ext-schema-documentation/target/site/schemaspy

4. Open index.html in a web browser to view the schema documents