The file is checked on every startup of the module. The child diff tags are iterated over in a top down fashion. The earliest diff should be at the top and the most recent diff should be at the bottom. Each "diff" element is executed one at a time. As each one runs, the "version" is stored in a Global Property in the user's database: moduleid.database_version. The next time the module is started, ONLY "diff"s that have a "version" GREATER THAN the version stored in the moduleid.database_version will be run. This allows for easy upgrading for module users and module devs don't need to worry about who has what version.
It is very bad practice to edit "diff" elements. You should always add new ones. This is especially true after you release your module.
However, while developing your module you are free to edit the sql in the diffs. Before reinstalling the module though, you need to make sure your moduleid.database_version is LESS THAN the "version" of the diffs you want to run.
Put this at the top of your sqldiff.xml file for autocompletion help (this dtd isn't required by openmrs):
(The sqldiff file contains 0 to n diff tags)
The "diff" element contains:
- version: String referring to the unique extension point labeled the same in the code
- author: Any string referring to the person that created this. Usually use for openmrs id username.
- date: Only used for convenience. Should be the date the sql was added to the file
- description: Text describing what the sql diff is doing. Only used for convenience when reading through sqldiff file later
- sql: Contains the sql statements. Separate statements should be delimited by semi colons: ";"
example sqldiff.xml file:
Notice that a SECOND "diff" element was appended instead of modifying the first one!
If you really want it, the viewable contents of http://resources.openmrs.org/doctype/sqldiff-1.0.dtd made available here: