1. Topics:
  2. Zero Resource Model quick start tutorial
  3. |
  4. Configuring the Zero Resource Model
  1. Modules:
  2. Getting started with database access
  3. |
  4. Client programming with Dojo

Zero Resource Model CLI Tasks

The zero.resource component contributes several Command Line Interface (CLI) tasks for the lifecycle development of Zero Resource Model (ZRM) data models.

Through these tasks you can create necessary database artifacts, load data into the database, and reset the database to a predictable state.

Because ZRM using embedded Derby as a convenience to quickly get started developing your RESTful applications, you must stop and start your application if you need to run ZRM's CLI tasks. This limitation imposed by Derby is not an issue when connecting to any of the other supported databases, including DB2, Oracle, MySQL, and network Derby.

Using the ZRM CLI in your development workflow

The typical workflow involves:

  1. Create one or more models
  2. Create database artifacts and load initial data with the model sync CLI task
  3. Test
  4. Modify and iterate on model declaration (i.e. add/change fields)
  5. Revert data to a predictable state and alter database artifacts as needed with the model reset CLI task
  6. Dump data with model dumpdata
  7. Load data with model loaddata

If you add new models, simply call model sync. If you change models during development and can tolerate reverting all data base to an initial state, execute model reset. If you cannot tolerate loosing data, you must modify the table by yourself. You can also use a combination of model dumpdata and model loaddata.

Details

The model sync task generates a database table for each resource using a top down mapping scheme. By default, the name of the model file maps to the name of the database table and the field names map to column names. Each table also has a special field, id, that is the unique identifier for that resource.

In order to create required database artifacts, first run the model sync task from the command line. This task will read the model declarations, determine what required database artifacts are missing, and create them for you. Requisite artifacts are determined on a per model basis. Thus, the model sync task will leave previously generated artifacts intact. However, if you modify a model file and want the table be recreated, you can use model reset if reverting data back to its initial state is tolerable. If not, then you must manually alter the database artifacts.

The model sync command line task will never alter any existing tables. See the complete ZRM documentation for more details. Because of this limitation, any changes you make to your ZRM declaration will need to manually changed. To do this, create a file with the table altering SQL and execute it using the runsql command line task from the zero.data module.

An Example

For instance, if the following person resource model definition evolves from:

{
    "fields" : {
        "first_name": {"type": "string"}
    }
}

and adds a birth_date field as follows:

{
    "fields" : {
        "first_name": {"type": "string"},
        "birth_date": {"type": "date"}
    }
}

When these model changes happen, you to create a file (alter_table.sql in the application root, for instance) with the necessary changes for your selected database vendor dialect:

ALTER TABLE person {
    ADD COLUMN birth_date birth_date DATE
}

and execute with the following runsql cli task:

zero runsql alter_table.sql

The zero.data documentation has more information on the runsql task.

Loading initial data fixtures

In addition to creating the database tables at application initialization, ZRM searches for initial_data.json files across all dependencies in /app/models/fixtures directories and loads its data into the database.

The virtualized directory concepts are ignored in this case.

If the database has already been initialized, the data is not loaded until the database is deleted or the table is manually dropped. Your initial_data.json files can populate multiple resource model types from the same file.

More details on the JSON format can be found in ZRM's complete documentation.

model sync

Usage:

zero model sync

Details

Creates necessary database artifacts and loads data from the application's initial_data.json file.

model reset

Usage:

zero model reset

Details

Reset by restoring the ZRM database to the state just after the model sync. The model reset task is the equivalent of dropping the ZRM database artifacts and executing the model sync task.

model loaddata

Usage:

zero model loaddata filename [filename]*

Summary

Loads data from specified files into the ZRM database.

Details

The model loaddata task reads data in from JSON from one or more files in the /app/models/fixtures folder of your application. For instance, to import data into the ZRM database from a file at /app/models/fixtures/exporteddata.json, execute the task as follows:

zero model loaddata exporteddata.json

To load data from more than one file, add as many file names as desired.

model dumpdata

Usage:

zero model dumpdata [--model={model_name}] filename
zero model dumpdata --split [--prefix={file_prefix}]

Summary

The model dumpdata task writes data out as JSON to one or more files in the /app/models/fixtures folder of your application. For instance, to export all data found in the ZRM database out to a file at /app/models/fixtures/exporteddata.json, execute the task as follows:

zero model dumpdata exporteddata.json

You can target just the instances of one model type by providing a value for the optional --model argument:

zero model dumpdata --model=persons personsdata.json

You can also split instances in the ZRM database of each model type into its own file as follows:

zero model dumpdata --split app/models/fixtures

Using the --split argument as show above will place member instances of model types into their own file with the default prefix of dump. For instance, an application with model types of persons and addresses will dump data for both types into dump_persons.json and dump_addresses.json, respectively, into the /app/models/fixtures folder.

You can also provide an optional prefix value to override the default dump prefix:

zero model dumpdata --split --prefix=export app/models/fixtures

model sql

Usage:

zero model sql {sync|drop|reset} filename

Summary

The model sql task outputs generated statements to create and drop database tables to support the resource declarations made in your application's /app/models folder. You can view model sql somewhat as a "dry run". Rather executing the generated statements as model sync and model reset do, model sql simply generates and outputs to a file.

There are three modifiers that affect the output of model sql based on use cases. These are sync, drop, and reset. The sync modifier outputs the statements that are executed when the model sync is used. The drop modifier outputs database "DROP" statements to destroy ZRM database artifacts. Finally, the reset modifier outputs statements that are executed when the model reset task is used. reset is also the equivalent of the combination of both drop and sync output concatenated together.

zero model sql sync create_only.sql
zero model sql drop drop_only.sql
zero model sql reset create_and_drop.sql
model sql is only for creating and dropping tables and will not output statements for manipulating data in these artifacts. To work with instance data, use the model dumpdata and model loaddata tasks.

Version 1.1.0.0.21442