Chapter 19. Introduction

v.4.1 (4.1.M1)	Chapter 19. Introduction
Prev	Part IV. DB-First Flow	Next

Table of Contents

"DB-first" Flow
Introduction to "cdbimport"

"DB-first" Flow

An ORM system consists of three parts: database, OR mapping and persistent Java classes. These parts always need to be kept in sync with each other for the application to work. "DB-first" flow is a common and practical approach to synchronization that assumes the database to be the master source of the metadata, with other two parts synchronized from the DB as the schema evolves. Cayenne provides a number of tools to automate and control it. Here is how "DB-first" flow is typically implemented:

A SQL migrations framework is used to bring a local DB to a certain version. This is outside of the scope of Cayenne and is done with a third-party tool, such as Liquibase or Flyway.
OR mapping model (Cayenne XML files) are synchronized with the state of the database using "cdbimport" tool provdied by Cayenne.
Object layer of the OR mapping model is customized to the developer liking, usually via CayenneModeler. Subsequent runs of "cdbimport" will not override any customizations that you make.
Java classes are generated using "cgen" tool provided by Cayenne.

"cgen" and "cdbimport" tools can be invoked from Maven or Ant as discussed in the "Including Cayenne in a Project" chapter or run from CayenneModeler. This chapter will mostly focus on "cdbimport".

Here is simple maven configuration to start with:

Introduction to "cdbimport"

Here is a simple Maven configuration of "cdbimport" (for details see cayenne-maven-plugin documentation)

	<plugin>
		<groupId>org.apache.cayenne.plugins</groupId>
		<artifactId>cayenne-maven-plugin</artifactId>
		<version>4.1.M1</version>

		<configuration>
			<map>${project.basedir}/src/main/resources/datamap.map.xml</map>
			<dataSource>
				<url><!-- jdbc url --></url>
				<driver><!-- jdbc driver class --></driver>
				<username>username</username>
				<password>password</password>
			</dataSource>
			<dbimport>
				<defaultPackage>com.example.package</defaultPackage>
			    <includeTable>.*</includeTable>
			</dbimport>
		</configuration>
		<dependencies>
			<!-- jdbc driver dependency -->
		</dependencies>
	</plugin>

In the next chapters we will discuss various filtering and other reverse-engineering options.