Database Schema Versions

To deal with extensive database schema changes and avoid dropping the schema by hand, Chimera provides a mechanism for this. In the mysql_schema_version.properties file you can find a property called mysql.schema.version. This is the current database schema version. If you make extensive schema changes (e.g. by introducing a lot of newly annotated fields which EclipseLink should write into the database) you simply raise this property. The next time you build chimera, Maven detects that your local database schema version differs from the global schema version (the one specified in mysql.schema.version) and will tell EclipseLink to once drop and recreate your schema and raise your local schema version. After this initial recreation of the schema, your database will not be dropped anymore as long as the database schema version does not change.

If you are interested in how all this works in detail take a look in the pom.xml. In the groovy-maven-plugin section you will find some Groovy code which does all the stuff stated above. The current local schema version is stored in the mysql_schema_version.txt file. This file is part of the .gitignor so that it is local to your Chimera. When this file does not exist during the first build it will be created. Afterward everytime you build Chimera your local version (stored in mysql_schema_version.txt file) is compared to the global version (which is stored in mysql_schema_version.properties and synchronized with github repo through git). If these version numbers are different the eclipselink.ddl-generation property in the persistence.xml file will be set to drop-and-create-tables telling EclipseLink to drop and recreate the schema on startup. If both versions are equal the property will be set to create-or-extend-tables which tells EclipseLink to use the old schema and try to alter this if needed. So for small schema changes (for example when you add a single field of a basic type in an entity tracked by EclipseLink) EclipseLink should be capable to extend the schema so that no version change and no deletion of the schema should be necessary. Nevertheless, if you make an extensive change or you are not sure whether EclipseLink is capable to integrate your changes into the old schema you should raise the version number to force a schema deletion and avoid persistence errrors during startup or runtime of chimera.