Introduction Migrations

 Introduction Migrations

What are migrations?

- A migration is a file that keeps track of changes to our database schema (structure of our database).

- Offers version control on our schema.

- Migrations deal with how we manage modifications to our data schema, over time.

Benefits of migrations in our app:

- Mistakes to our database schema are very expensive to make. 

- The entire app can go down, so we want to quickly roll back changes, and test changes before we make them.

- Encapsulate a set of changes to our database schema, made over time.

- Are uniquely named.

- Are usually stored as local files in our project repo, e.g. a migrations/ folder.

- There should be a one-to-one mapping between the changes made to our database, and the migration files that exist in our migrations/ folder.

- Our migrations files set up the tables for our database.

- All changes made to our db should exist physically as part of migration files in our repository.

Upgrades and rollbacks:

- Migrations stack together in order to form the latest version of our database schema.

- We can upgrade our database schema by applying migrations. 

- We can roll back our database schema to a former version by reverting the migrations that we applied. 

Migration command-line scripts:

There are generally 3 scripts needed, for:

- migrate: creating a migration script template to fill out; generating a migration file based on changes to be made

- upgrade: applying migrations that hadn't been applied yet ("upgrading" our database)

- downgrade: rolling back applied migrations that were problematic ("downgrading" our database)

Why use migrations?

Without migrations:

- We do heavy-handed work, creating and recreating the same tables in our database even for minor changes.

- We can lose existing data in older tables we dropped.

With migrations:

- Auto-detects changes from the old version & new version of the SQLAlchemy models. 

- Creates a migration script that resolves differences between the old & new versions. 

- Gives fine-grain control to change existing tables.

This is much better, because:

- We can keep existing schema structures, only modifying what needs to be modified. 

- We can keep existing data.

- We isolate units of change in migration scripts that we can roll back to a “safe” db state. 

Flask-Migrate-cheat-sheet

Flask-Migrate commands:

pip install Flask-Migrate

flask db --help

flask db init 

- Create initial migrations directory structure. 

flask db migrate 

- Detects the model changes to be made and creates a migration file with an upgrade and downgrade logic set up. 

(replaces use of db.create_all()).

flask db upgrade 

- Runs the upgrade command in the migration file, to apply the migration. 

flask db downgrade

- Runs the downgrade command in the migration file, to roll back in migration.