iciql/docs/02_table_versioning.mkd

Database & Table Versioning

Iciql supports an optional, simple versioning mechanism. There are two parts to the mechanism.

1. You must supply an implementation of com.iciql.DbUpgrader to your com.iciql.Db instance.
2. One or more of your table model classes must set the version field of the com.iciql.IQTable annotation
   AND/OR
   Your com.iciql.DbUpgrader implementation must set the version field of the com.iciql.IQDatabase annotation

How does it work?

If you choose to use versioning, iciql will maintain a table within your database named _iq_versions which is defined as:

CREATE TABLE _IQ_VERSIONS(SCHEMANAME TEXT NOT NULL, TABLENAME TEXT NOT NULL, VERSION INT NOT NULL)

This database table is automatically created if and only if at least one of your model classes specifies a version > 0.

When you generate a statement, iciql will compare the annotated version field of your model class to its last known value in the _iq_versions table. If _iq_versions lags behind the model annotation, iciql will immediately call the registered com.iciql.DbUpgrader implementation before generating and executing the current statement.

When an upgrade scenario is identified, the current version and the annotated version information is passed to either:

• DbUpgrader.upgradeDatabase(db, fromVersion, toVersion)
• DbUpgrader.upgradeTable(db, schema, table, fromVersion, toVersion)

both of which allow for non-linear upgrades. If the upgrade method call is successful and returns true, iciql will update the _iq_versions table with the annotated version number.

The actual upgrade procedure is beyond the scope of iciql and is your responsibility to implement. This is simply a mechanism to automatically identify when an upgrade is necessary.

NOTE:
The database entry of the _iq_versions table is specified as SCHEMANAME=” and TABLENAME=“.