h1. Liquibase Module

bq. You never develop code without version control, why do you develop your database without it ?™

p. Liquibase (http://www.liquibase.org) is a simple, reliable and elegant solution for database refactoring management. It comes with main features :

* multi dabase support (SGBDR)
* structural / data changeset 
* safety check (on md5sum basis)
* safety database upgrade process (cluster is liquibase friend) 
* contexts execution filter (you Player know what I'm talking about)
* automation tooling provided (ant / servlet, and now PlayFramework !)

Liquibase module differs from Migrate module for the main following reason :

h3. Database changes follow application changes just the same way code source does

h2. Getting started

Bundle changelog files within your Play application (see example),

Add liquibase dependency to your Play application

pre. # Additional modules
# ~~~~~
# A module is another play! application. Add a line for each module you want
# to add to your application. Module paths are either absolutes or relative to
# the application root.
module.liquibase=${play.path}/modules/liquibase
 


h2. Configuration

First version configuration options are the following :

pre. liquibase.active=true/false
liquibase.actions=status|update|validate|sync|listlocks|releaselocks|clearchecksums [actions can be sequenced with coma]
liquibase.changelog=changelog_path (classpath loaded)
liquibase.properties=properties_path (classpath loaded)
liquibase.contexts=ctxt1[,ctx2]
liquibase.scanner=jar|src

h2. Example

p. Locate your xml changeset file within your models folder, or in external 3rd party jar. You only need to remember relative path to root xml file.
At configuration level, Turn jpa.ddl to validate or none within your application.conf file. Simply start your play app and see the changelog information output

h4. Sample configuration entries for liquibase module

pre. %staging.liquibase.active=true
%staging.liquibase.actions=status,update
%staging.liquibase.changelog=models/myapp/mainchangelog.xml
%staging.liquibase.properties=models/myapp/database.properties
%staging.liquibase.scanner=jar

h4. Usage

Set your action(s) sequence using the corresponding tag, use the active flag to apply - or not - changesets, and simply start your app. That's it, you can now handle Model development with structural projection in parallel. Keep the jpa.ddl flag to validate in order to prevent asynchronous evolution, and you're done. Underlying db keeps track of changes performed (structural, performances, data, custom SQL).

h4. Database Properties Injection 

Properties are then injected within changeset xml file

pre. #naming convention
db.schema=public
pkprefix=pk_
ukprefix=uk_
fkprefix=fk_
idxprefix=idx_
tableprefix=snsr
#types
type.pk=bigint
type.integer=integer
type.long=bigint
type.binary=bytea
type.timestamp=timestamp without time zone
type.boolean=boolean
type.short_text=varchar(50)
type.long_text=varchar(255)
type.very_long_text=text


p. Changeset files / properties can be jared and integrated - thus versioned - as 3rd party libs, at module / application level, just the same way jdbc drivers are.

p. One may also handle changeset at the same level as domainmodel declaration - that's what we do at GdTeam -, within dedicated module/application, using play module dependency mechanism to create modular app.
Modules archives are still built and maintained against 3rd party repository such as nexus / archiva / artifactory, and then released agains private / public play module repository (see http://code.google.com/p/play-repo/ for more information)


