Datastore Schema

Java persistence tools often add various types of information to the tables for persisted classes, such as special columns, or meta information. DataNucleus is very unobtrusive as far as the datastore schema is concerned. It minimises the addition of any implementation artifacts to the datastore, and adds nothing (other than any datastore identities, and version columns where requested) to any schema tables. The only thing that DataNucleus could add to the schema is a single table that stores information about the classes being persisted (the "auto start mechanism" SchemaTable which is optional).

DataNucleus can persist to a datastore that already contains a schema, or alternatively can create the datastore schema for you. It can exist alongside existing tables leaving them untouched. It is not necessary to have a datastore schema specifically for DataNucleus.

When having DataNucleus generate the schema for you, it is advisable to run the DataNucleus SchemaTool before running your application. This can be used to ensure that the correct datastore schema is present (a schema that matches your metadata), and so the persistence layer of your application is ready to use.

Schema Creation

DataNucleus can generate the schema for the developer as it encounters classes in the persistence process. Alternatively you can use the SchemaTool application before starting your application.

If you want to create the schema (tables+columns+constraints) during the persistence process, the property datanucleus.autoCreateSchema provides a way of telling DataNucleus to do this. It's a shortcut to setting the other 3 properties to true. Thereafter, during calls to DataNucleus to persist classes or perform queries of persisted data, whenever it encounters a new class to persist that it has no information about, it will use the MetaData to check the datastore for presence of the table, and if it doesn't exist, will create it. In addition it will validate the correctness of the table (compared to the JDO Meta-Data for the class), and any foreign key constraints that it requires (to manage any relationships). If any foreign key constraints are missing it will create them.

If you wanted to only create the tables required, and none of the constraints the property datanucleus.autoCreateTables provides this, simply performing the tables part of the above.

If you want to create any missing columns that are required, the property datanucleus.autoCreateColumns provides this, validating and adding any missing columns.

If you wanted to only create the constraints required, and none of the tables the property datanucleus.autoCreateConstraints provides this, simply performing the constraints part of the above.

Schema Validation

DataNucleus can check any existing schema against what is implied by the JDO Meta-Data.

The property datanucleus.validateTables provides a way of telling DataNucleus to validate any tables that it needs against their current definition in the datastore. If the user already has a schema, and want to make sure that their tables match what DataNucleus requires (from the JDO Meta-Data definition) they would set this property to true . This can be useful for example where you are trying to map to an existing schema and want to verify that you've got the correct JDO Meta-Data definition.

The property datanucleus.validateColumns provides a way of telling DataNucleus to validate any columns of the tables that it needs against their current definition in the datastore. If the user already has a schema, and want to make sure that their tables match what DataNucleus requires (from the JDO Meta-Data definition) they would set this property to true . This will validate the precise column types and widths etc, including defaultability/nullability settings. Please be aware that many JDBC drivers contain bugs that return incorrect column detail information and so having this turned off is sometimes the only option (dependent on the JDBC driver quality).

The property datanucleus.validateConstraints provides a way of telling DataNucleus to validate any constraints (primary keys, foreign keys, indexes) that it needs against their current definition in the datastore. If the user already has a schema, and want to make sure that their table constraints match what DataNucleus requires (from the JDO metadata definition) they would set this property to true .

Schema Naming Issues

DataNucleus will, by default, use the default database schema for the Connection URL and user supplied. This may cause issues where the user has been set up and in some databases (e.g Oracle) you want to write to a different schema (which that user has access to). To achieve this in DataNucleus you would set the runtime properties

javax.jdo.mapping.Catalog={the_catalog_name}
javax.jdo.mapping.Schema={the_schema_name}

This will mean that all RDBMS DDL and SQL statements will prefix table names with the necessary catalog and schema names (specify which ones your datastore supports).

Schema Generation and Column Ordering

By default all tables are generated with columns in alphabetical order, starting with root class fields followed by subclass fields (if present in the same table) etc. There is a DataNucleus extension that allows you to specify the order of columns for schema generation. This is achieved by specifying the metadata extension index against the column.

<column>
    <extension vendor-name="datanucleus" key="index" value="1"/>
</column>

Note that the values of index start at 0, and should be specified completely for all columns of all fields.