infi.clickhouse_orm/docs/schema_migrations.md

112 lines
3.7 KiB
Markdown
Raw Normal View History

2017-04-26 15:47:02 +03:00
Schema Migrations
=================
Over time, the ORM models in your application may change. Migrations provide a way to modify the database tables according to the changes in your models, without writing raw SQL.
The migrations that were applied to the database are recorded in the `infi_clickhouse_orm_migrations` table, so migrating the database will only apply any missing migrations.
Writing Migrations
------------------
2017-05-11 05:30:17 +03:00
To write migrations, create a Python package. Then create a python file for the initial migration. The migration files must begin with a four-digit number, and will be applied in sequence. For example:
2017-04-26 15:47:02 +03:00
analytics
|
+-- analytics_migrations
|
+-- __init__.py
|
+-- 0001_initial.py
|
+-- 0002_add_user_agents_table.py
2017-05-11 05:30:17 +03:00
Each migration file is expected to contain a list of `operations`, for example:
2017-04-26 15:47:02 +03:00
from infi.clickhouse_orm import migrations
from analytics import models
operations = [
migrations.CreateTable(models.Visits),
migrations.CreateTable(models.Visitors)
]
The following operations are supported:
2017-10-30 16:15:12 +03:00
2020-06-06 11:07:01 +03:00
### CreateTable
2017-04-26 15:47:02 +03:00
A migration operation that creates a table for a given model class. If the table already exists, the operation does nothing.
In case the model class is a `BufferModel`, the operation first creates the underlying on-disk table, and then creates the buffer table.
2017-04-26 15:47:02 +03:00
2017-10-30 16:15:12 +03:00
2020-06-06 11:07:01 +03:00
### DropTable
2017-04-26 15:47:02 +03:00
A migration operation that drops the table of a given model class. If the table does not exist, the operation does nothing.
2017-04-26 15:47:02 +03:00
2017-10-30 16:15:12 +03:00
2020-06-06 11:07:01 +03:00
### AlterTable
2017-04-26 15:47:02 +03:00
A migration operation that compares the table of a given model class to the models fields, and alters the table to match the model. The operation can:
- add new columns
- drop obsolete columns
- modify column types
Default values are not altered by this operation.
2017-10-30 16:15:12 +03:00
2020-06-06 11:07:01 +03:00
### AlterTableWithBuffer
A compound migration operation for altering a buffer table and its underlying on-disk table. The buffer table is dropped, the on-disk table is altered, and then the buffer table is re-created. This is the procedure recommended in the ClickHouse documentation for handling scenarios in which the underlying table needs to be modified.
Applying this migration operation to a regular table has the same effect as an `AlterTable` operation.
2020-06-06 11:07:01 +03:00
### AlterConstraints
A migration operation that adds new constraints from the model to the database table, and drops obsolete ones. Constraints are identified by their names, so a change in an existing constraint will not be detected unless its name was changed too. ClickHouse does not check that the constraints hold for existing data in the table.
### RunPython
2017-10-30 16:15:12 +03:00
A migration operation that runs a Python function. The function receives the `Database` instance to operate on.
def forward(database):
database.insert([
TestModel(field=1)
])
2017-10-30 16:15:12 +03:00
operations = [
2017-10-30 16:15:12 +03:00
migrations.RunPython(forward),
]
2020-06-06 11:07:01 +03:00
### RunSQL
2020-06-06 11:07:01 +03:00
A migration operation that runs raw SQL statements. It expects a string containing an SQL statements, or a list of statements.
2017-10-30 16:15:12 +03:00
Example:
2017-10-30 16:15:12 +03:00
operations = [
RunSQL('INSERT INTO `test_table` (field) VALUES (1)'),
RunSQL([
'INSERT INTO `test_table` (field) VALUES (2)',
'INSERT INTO `test_table` (field) VALUES (3)'
])
]
2017-04-26 15:47:02 +03:00
Running Migrations
------------------
2017-05-11 05:30:17 +03:00
To migrate a database, create a `Database` instance and call its `migrate` method with the package name containing your migrations:
2017-04-26 15:47:02 +03:00
Database('analytics_db').migrate('analytics.analytics_migrations')
2017-04-28 13:44:45 +03:00
Note that you may have more than one migrations package.
---
[<< Table Engines](table_engines.md) | [Table of Contents](toc.md) | [System Models >>](system_models.md)