Use MySQL in a Development Environment

Overview

This guide explains how to configure your local Bloomreach Content development environment to use MySQL as the storage backend.

Note: This page covers configuration for projects that use Cargo to run Tomcat and MySQL directly on your development machine. If you use Docker, setup is simpler. For Docker-based instructions, see Run and Develop with Docker.

When to Use

By default, projects created from the Maven archetype use an embedded H2 database. You may want to use MySQL in development to match your production environment or for specific testing scenarios. For production configuration, refer to Configuring Bloomreach Content for MySQL. This page focuses on additional steps required for a Cargo-based local development environment.

Prerequisites

Before you begin, ensure the following:

Your Bloomreach Content project and local development environment are set up as described in the Getting Started tutorial.
MySQL is installed and running.
You have created a MySQL database and a user account with sufficient privileges. For details, see Configuring Bloomreach Content for MySQL.

Add the MySQL Driver Dependency

Add the MySQL JDBC driver to your project's root pom.xml. Insert the following dependency in the /project/dependencies section:

<dependencies>
    <dependency>
      <groupId>com.mysql</groupId>
      <artifactId>mysql-connector-j</artifactId>
      <version>8.0.33</version>
      <scope>provided</scope>
    </dependency>
</dependencies>

Make sure you add this dependency to the /project/dependencies section, not to /project/dependencyManagement/dependencies/.

Add the MySQL Driver to the Cargo Classpath

Locate the Cargo plugin configuration in the cargo.run profile of your root pom.xml. Add the MySQL driver as a container dependency:

<plugin>
  <groupId>org.codehaus.cargo</groupId>
  <artifactId>cargo-maven3-plugin</artifactId>
  <configuration>
    <container>
      <dependencies>
        <dependency>
          <groupId>com.mysql</groupId>
          <artifactId>mysql-connector-j</artifactId>
          <classpath>extra</classpath>
        </dependency>
      </dependencies>
    </container>
  </configuration>
</plugin>

Note: The configuration above omits unrelated settings for clarity.

Register a MySQL DataSource with Tomcat

Add a Resource declaration to conf/context.xml. Use the example from Configuring Bloomreach Content for MySQL and update it with your database connection details. For local development without SSL validation, add useSSL=false to the datasource URL.

Create a Custom `repository.xml`

Add a conf/repository.xml file to your project. Use the example provided in Configuring Bloomreach Content for MySQL.

Configure the Repository to Use the Custom `repository.xml`

In your root pom.xml, find the Cargo plugin configuration in the cargo.run profile. Add the repo.config system property to the container's system properties:

<plugin>
  <groupId>org.codehaus.cargo</groupId>
  <artifactId>cargo-maven3-plugin</artifactId>
  <configuration>
    <container>
      <systemProperties>
        <repo.config>file:${project.basedir}/conf/repository.xml</repo.config>
      </systemProperties>
    </container>
  </configuration>
</plugin>

Note: The configuration above omits unrelated settings for clarity.

Build and Run the Project

Build and run your project as described in the building and running guides.

On first startup, the CMS web application will create all required tables in the MySQL database.