Command-line interface for the Zero Resource Model
zero.resource component contributes several commands for the
lifecycle development of Zero Resource Model (ZRM) data models.
Through these commands you can create necessary database artifacts, load data into the database, and reset the database to a predictable state.
model sync
Creates necessary database artifacts and loads data from the application's
initial_data.json file.
Usage:
zero model sync
model reset
Reset by restoring the ZRM database to the state just after the model sync. The
model reset command is the equivalent of dropping the ZRM database artifacts
and executing the model sync command.
Usage:
zero model reset
model loaddata
Loads data from specified files into the ZRM database.
Usage:
zero model loaddata filename [filename]*
The model loaddata command reads data in from JSON from one or more files. To
load data from more than one file, add as many file names as desired as
command arguments.
If the specified file name is not found, model loaddata will then look in
the app/models/fixtures folder. Thus the following two commands produce the
same result if there is no exporteddata.json file in the current working
directory:
zero model loaddata exporteddata.json zero model loaddata app/models/fixtures/exporteddata.json
Note: The file in the current working directory wins if there is a conflict.
model dumpdata
The model dumpdata command writes data out as JSON to one or more files.
Usage:
zero model dumpdata [--model={model_name}] filename
zero model dumpdata --split [--prefix={file_prefix}]
To export all data found in the ZRM database out to a file at
app/models/fixtures/exporteddata.json, execute the command 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
Further, 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
The model sql command outputs generated statements to create and drop database
tables to support the resource declarations made in your application's
app/models folder.
Usage:
zero model sql {sync|drop|reset} filename
You can view model sql commands somewhat as a "dry run". Rather than executing
the statements as model sync and model reset do, model sql
generates statements and outputs them 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 command 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 commands.
Using the model commands
The model sync command 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
command from the command-line. This command will read the model declarations,
determine what required database artifacts are missing, and create them for you.
Note that requisite artifacts are determined on a per model basis. Thus, the
model sync command 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.
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.
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.
Manually altering database tables
Under normal circumstances, developing with ZRM should use the
initial_data.json file to get to a predictable data state. For instance,
unit testing often requires putting the database into a state where tests can
make assumptions about the data.
Thus, model sync combined with model reset when the model changes should
be sufficient to develop your application rapidly. However, there are advanced
scenarios in which manually altering the database is needed.
The model sync command-line command will never alter any existing tables and
the model reset command is destructive, dropping all model tables and contained
data. See the ZRM documentation on model declaration for more details. Thus,
some changes you make to your ZRM models will need to manually alter the backing
database tables. To do this, create a file with the table altering SQL and
execute it using the runsql command-line command from the zero.data module.
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 command:
zero runsql alter_table.sql
The zero.data documentation has more information on the runsql command.
