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<br>
AND/OR<br/>
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:**<br/>
The database entry of the *_iq_versions* table is specified as SCHEMANAME='' and TABLENAME=''.