5.5. Schema Manipulation
Prev | Chapter 5. JDBC Configuration | Next

## 5.5. Schema Manipulation

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.

Prev | Up | Next
5.4. Large Result Sets | Home | Chapter 6. Standard Features