diff options
| author | James Moger <james.moger@gmail.com> | 2011-08-03 22:01:42 -0400 |
|---|---|---|
| committer | James Moger <james.moger@gmail.com> | 2011-08-03 22:01:42 -0400 |
| commit | 538ba78ac1dc2e9670380329ad989c9df0ab546b (patch) | |
| tree | 505694283fe116a274f0b388953e329333263847 /docs/02_table_versioning.mkd | |
| download | iciql-538ba78ac1dc2e9670380329ad989c9df0ab546b.tar.gz iciql-538ba78ac1dc2e9670380329ad989c9df0ab546b.zip | |
Initial commit of iciql.
Diffstat (limited to 'docs/02_table_versioning.mkd')
| -rw-r--r-- | docs/02_table_versioning.mkd | 29 |
1 files changed, 29 insertions, 0 deletions
diff --git a/docs/02_table_versioning.mkd b/docs/02_table_versioning.mkd new file mode 100644 index 0000000..0c778cb --- /dev/null +++ b/docs/02_table_versioning.mkd @@ -0,0 +1,29 @@ +## 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=''.
\ No newline at end of file |