Migrations¶
There are two types of migrations, schema and data migrations. Schema migrations are responsible for applying changes to your schema, data migrations are responsible for updating data when you found some kind of error in data.
For better visibility all migrations are stored as part of manifest YAML files. All migrations of a model can be found in the same model YAML file.
Model YAML file is a multi-document file and documents are organized this way:
---
# Current model schema
---
# Initial model version
---
# Second model version
---
...
First document in YAML file is the latest schema version. In YAML files, first document is usually used to change model schema. Once first document is updated in-place, you need to freeze those changes, no create a new schema version.
Migrations always use freezed schema versions. So if you have a modified first YAML fiel document, then changes will not be used in migrations untill they are not freezed.
Creating new model¶
When you want to add a new model, you need to start by writing schema like this:
---
type: model
name: country
properties:
name:
type: string
Currently this model is in draft mode, it will not be used and will not be visible. To make this model available for use you need to freeze it:
spinta freeze
freeze
command will freeze all drafts and creates new schema version. You can
freeze only one model:
spinta freeze country
After freezing, YAML file is updated and now looks like this:
---
type: model
name: country
version: aee17c1f-f16c-4d7c-ac45-d7ed9c7ac771
properties:
name:
type: string
---
version:
id: aee17c1f-f16c-4d7c-ac45-d7ed9c7ac771
date: 2020-02-12 07:14
changes:
- {op: add, path: /type, value: model}
- {op: add, path: /name, value: country}
- {op: add, path: /version, value: aee17c1f-f16c-4d7c-ac45-d7ed9c7ac771}
- {op: add, path: /properties, value: {name: string}}
migrate:
- type: schema
backend: default
upgrade: >-
create_table(
country,
column(_id, uuid4(), primary_key: true),
column(_revision, string(), unique: true),
column(name, string(), nullable: true),
)
downgrade: >-
drop_table(country)
Current model schema was updated with a new version and now model is ready to be used.
In the new version we see all the information aboult changes. In changes
parameter we see what exactly was changed in schema document and in migrate
we see all the steps that will be performed on database.
migrate
parameter contains migration actions specific to a specific backend
instance (see Configuring backends).
Different backends might generate different migration steps. For example Mongo backend will not have any steps, because Mongo is schemaless database.
Running migrations¶
But before using this model we need to apply migrations:
spinta migrate
This command will run migration steps and finally will register new schema
version in the internal _schema
table.