- Implementation Owner: @torstendittmann
- Start Date: (today's date, 13-01-2021)
- Target Date: (expected date of completion, 13-01-2021)
- Appwrite Issue: Is this RFC inspired by an issue in appwrite
Add a migration script to handle internal changes when upgrading to a new version with breaking changes.
What problem are you trying to solve?
During development, internal breaking changes are often introduced, which must be incorporated when upgrading to a new version. Also, the current migration script is not ready for easy extension of upcoming versions.
What is the context or background in which this problem exists?
Since Appwrite is still in early development, breaking change will most likely be introduced with each release. We will face a similar problem with major releases in the future.
Once the proposal is implemented, how will the system change?
Not much for the user, only for the developer. The concept of object-oriented programming is introduced to the migration script. Object Inheritance and Polymorphism via Interfaces will ensure easy and safe introduction of upcoming migrations of versions.
Initial situation is as follows, the current migration script serves its purpose - but is very inflexible and offers little basis for upcoming additions. To improve this, a main parent class and an interface is to be created, which is extended and implemented by the individual migrations. Significant refactoring is performed for the previous migrations.
A new class will be introduced to src/Appwrite/Migration. The class will inherit instances ($register, $projectDB & co) and methods to the individual migrations, which are needed regardless of the version. Also, abstract functions are introduced which enforces certain methods that have to be custom to the migration. The main class will not be instantiable.
It will look something like this:
abstract class Migration {
private function __construct() { }
public function setProject($project, $projectDB) { /* ... */ }
public function forEachDocument($callback) { /* ... */ }
abstract protected function execute();
}
class V07 extends Migration {
public function execute() { /* ... */ }
}Following functions are gonna be added the the main Appwrite\Migration\Migration class:
Sets the current project for migration. Will be used by the migration script run from the CLI.
Iterates through every document. A method is passed that takes and returns a Document. The returned Document will be overwritten in the set project. This will be called by the individual migration class (childs of Appwrite\Migration\Migration) to adjust document structure.
There is no reference to the version right now, before we run the migration script and after we finished setting up the new version. If we have a reference in the future, we can move to a dynamic migration that can migrate over different versions.
In addition, only one version is migrated at the moment and a migration of 2 versions could be possible.
If a version was skipped, 2 migrations are carried out. For example, if you want to migrate from 0.5 to 0.7, you will first migrate to 0.6 and then to 0.7. This is done automatically in a single operation. For this we would need a reference to the used version number after setting up the new one.