Skip to content

Instantly share code, notes, and snippets.



Last active Jun 27, 2018
What would you like to do?
Handling Migrations In EE [RFC]

Handling migrations in EE,

Migration Classes & file structure

Migrations will be used to make changes(db/file/containers) to existing ee installation. Migrations will be stored in /migrations folder in EE root. Each migration will be stored in seperate file. Name would be like 'timestamp_migration_title.php' i.e '1530101102_migrate_to_beta2.php'

Each of them will have a class that will extend a base abstract class. The abstract class will have one method - migrate(). The class that implements it can create more methods to group different types of changes.

I'm anticipating migration code for each release to be not more than 300-500 lines. Hence IMO filesystem, database and docker changes should be in single file, but in different functions. i.e.

function migrate() {

Files would pile up fast in migration if we create 3 files for each migration( if we put db, fs, container changes in seperate files ).

Also we can have up() and down() methods. Something in up() goes wrong and it throws exception, we can safely call down() and it would revert the changes done by up().

Migration logic

We'll have a table in DB to track which migrations have been executed. We'll store name of migration in a 'migration' table. We could also have 2nd column to store timestamp of when migration was executed(might be helpful for debugging).

When migration will be triggered, we'll get all migrations from filesystem and check their corrosponding entries in DB. If they do not exist, we'll execute the migration and add it in DB.

Triggering migration

First of all let's understand how EE updates. This help us better think about this topic. After you select stable/nightly update, EE will fetch PHAR from github and store it in /tmp/(initialy). Then we run php /tmp/ee-temp.phar cli info and check it's return code to check if new phar runs correctly. Then EE replaces currect phar with phar in /tmp/.

There are two ways of triggering migrations.

1. Public Command

We can create a public command ee cli migrate. This will trigger migration as described byabove logic.

After we fetching the phar, we can run php /tmp/ee-temp.phar cli migrate after fetching it. This will run migrations from the new phar.

2. (Mostly correct) Guesswork

Since we run ee cli info each time after downloading phar, in that function we can check if the cwd of phar is /tmp, we'll trigger migration.

In both cases, we don't have to worry about migration getting triggered twice. Because each time the function will only run migrations which havn't previousy ran.

The benifit I see of #2 is that we won't have to expose a public command for something that is internal to ee.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment