Kodo JDO stores persistent objects in relational database tables. As you add, remove, or modify your persistent classes, these tables must be updated to reflect the current object model.
To facilitate this process, Kodo JDO provides the schematool. This command-line tool can create, refresh, or drop the relational schema for any persistent types, relieving you from database administration tasks. You can invoke the tool through the included schematool script or via its java class, com.solarmetric.kodo.impl.jdbc.schema.SchemaTool . It accepts the standard set of command-line arguments defined by the configuration framework. It also accepts the following flags:
-ignoreErrors <true|false>: Whether the tool should ignore SQL errors that are thrown while it is manipulating the schema. This optional argument defaults to false.
-outfile <filename>: If this optional argument is set, then the schematool will write SQL statements to the specified file rather than perform any modifications to the data store. Use the keyword stdout to print the SQL to standard output.
-action <add|refresh|drop>: This flag is required. It tells the tool what action to perform, where the available actions are:
add: Creates the schema for the given persistent types, if it does not already exist. This action will add tables for new classes, secondary tables for new collection, array, and map fields, or add new columns to existing tables for new simple fields. If the schema is already up-to-date, the tool will detect this and will not perform any additional work. This action will never drop data.
refresh: Similar to add, but also detects columns that are no longer used and drops them from the schema (some databases do not support dropping columns).
drop: Drops all schema components used by the given persistent types. If a subclass is mapped to the same table as its parent class, and only the subclass is included in the list of types to drop, the parent class' table will not be destroyed. If possible, the tool will remove the subclass' columns from the table. Be careful when using this action!
-db <db name>: This option is for users of the deprecated system.prefs configuration mechanism. Use it to specify the symbolic name of the database to connect to.
Any additional arguments to the schematool will be interpreted as persistent types whose schema should be modified. Just as with the appidtool, each of the arguments can be either a full class name, a .class file, or a .jdo file. If no classes are given, the action will be performed on all known persistent types.
 | Important |
|---|---|
When acting on a persistent type, the schematool automatically extends the action to all known subclasses of the type. | |
Example 5.4. Using the Kodo JDO Schematool
Refresh the schema for all known persistent classes:
schematool -action refresh
Drop the schema for the Company and any types listed in the package.jdo file.
schematool -properties hsql.properties -action drop com.solarmetric.examples.Company ../package.jdo
 | Note |
|---|---|
It is possible to bypass the schematool step by specifying the com.solarmetric.kodo.impl.jdbc.SynchronizeSchema Kodo property to true. This should never be used on a production database, since automatic schema migration can result in columns being dropped, and thus in data loss. See the Configuration Framework chapter for more details. | |