Persisting Data With Models
Let's use the example to see exactly what is happening at each stage of Model Schema definition life cycle.
Step 1: Requirements
I want to store my "todo list" in platformOS
Todo list:
| Task | Priority |
|---|---|
| Clean the apartment | Low |
| Do the homework | High |
Step 2: Model Schema File
Create definition file in your project repository that will describe my Model Schema:
touch app/model_schemas/todo.yml
Step 3: Definition of Model Schema
Using the editor of choice, add the definition of Model Schema.
The code below is the description of properties that Model will accept and the name of Model Schema object that is used to identify the object.
For full list of Types that can be used see CustomAttribute Types
name: todo
properties:
- name: task
type: string
- name: priority
type: string
Step 4: Sync/Deploy Model Schema definition.
At the moment of deploy pos-cli is asking platformOS if Model Schema object with name todo already exists, if so it will be updated with given definition otherwise new object is created.
You can verify this step with GraphQL query:
{
admin_model_schemas {
results {
name
properties {
name
}
}
}
}
the result for that query depending on your instance state should be similar to:
{
"data": {
"admin_model_schemas": {
"results": [
{
"name": "todo",
"properties": [
{
"name": "task"
},
{
"name": "priority"
}
]
}
]
}
}
}
Step 5: Model Creation
In Building Contact Form With Model tutorial you will learn in details how to create Models.
Step 6: Model Schema change
As you know by now Models and Model Schema objects are strictly related as the definition of properties allows for storing the data in platformOS backend systems.
Once you have data persisted within Model you need to be aware of how changes in Model Schema affect your Model objects:
-
Model Schema definition delete - you can only delete your Model Schema object if there is no related Model object. Use models_delete_all mutation to delete all related Model objects.
If you try to deploy with orphaned Model, you will see the following message:
Cannot delete record because of dependent model of type: todo Use the mutation below to remove dependent objects: mutation { models_delete_all(model_schema_name: "todo") { count } } -
name change - as platformOS detects Model Schema definition by its name, if you change it is equal with adding new Model Schema, please note that Model objects are not automatically migrated and will be treated as orphaned with next deploy attempt, see error message above.
-
add new Model Schema property - adding new properties is a valid change that does not need additional actions, the data remains untouched.
-
delete of Model Schema property - deletion of the property is a valid change, data stored in related Model properties will remain saved but will not be accessible. Use migration to remove the data prior to the change.
-
property edition - is a valid change and is equal to the removal of property with old name and creation of new property, data is not migrated.
Step 7: Mutations
What you have done in steps 2, 3 and 4 can be done with admin_model_schema_create mutation.
In your platformOS instance, the result would be exactly the same, but you can now create CMS system where the user can define their own models with a few clicks in the user interface.
Please note that the same rules apply for Model Schema deletion as when you delete it with pos-cli