XOS-Migrations

xos-migrations.md

XOS Migrations

NOTE this feature is not implemented yet

This document describes how to use the XOS toolchain to generate basic migrations for service models. The autogenerated migrations can later be extended with custom logic to support more complex scenarios.

NOTE from now on we assume you have obtained the code as described in this guide and the entire tree is now available in ~/cord

Install the XOS Toolchain

The XOS toolchain consists of a set of python libraries. There is an helper script to install the toolchain in the XOS repo, so just execute:

cd ~/cord/orchestration/xos
bash scripts/setup_venv.sh

Generate the migrations

Once the toolchain is available, enter you service (we'll use olt-service as an example).

cd ~/cord/orchestration/xos_services/olt-service
xos-migrate xos/synchronizer/models/olt.xproto [--app ~/cord/orchestration/xos]

--core app is an optional parameter to include additional apps in case they are needed because of external relations. By default it includes the core (assuming everything has been cloned with repo)

If no migrations were present for your service you'll see a new folder migrations that is a sibling of models containing a file 0001-initial.py. If the service already had migrations you'll see a new file in that folder, for example: 0002-xosgenerated.py

NOTE that all the migration files needs to be committed together with the code as they'll be loaded into the core together with the models.

Customize the migrations

The autogenerated migrations only operates on the database altering tables, they won't make any modifications to the data. You can write custom code to do that, following this example.

We assume you already have a model called MyModel that has two properties: first_name and last_name.

As part of your changes you want to add a third property called full_name that is defined as first_name + last_name.

This is the migration code that the tool will generate:

class Migration(migrations.Migration):

    dependencies = [
        ('myapp', '0001_initial_data'),
    ]

    operations = [
        migrations.AddField(
            model_name='MyModel',
            name='full_name',
            field=models.TextField(blank=True, null=True),
        )
    ]

To migrate the data, you need to add a custom operation in your migration. This can be done defining a custom method forwards as:

def forwards(apps, schema_editor):
  MyModel = apps.get_model('myapp', 'MyModel')
    for row in MyModel.objects.all():
        row.full_name = "%s %s" = (first_name, last_name)
        row.save(update_fields=['full_name'])

and adding it to the operations list.

Here is a complete example of the customized migration:

class Migration(migrations.Migration):

	def forwards(apps, schema_editor):
	  MyModel = apps.get_model('myapp', 'MyModel')
	    for row in MyModel.objects.all():
	        row.full_name = "%s %s" = (first_name, last_name)
	        row.save(update_fields=['full_name'])

    dependencies = [
        ('myapp', '0001_initial_data'),
    ]

    operations = [
        migrations.AddField(
            model_name='MyModel',
            name='full_name',
            field=models.TextField(blank=True, null=True),
        ),
        migrations.RunPython(forwards),
    ]

For more informations about migrations you can refer to the official Django guide.

Here are some good reads about migrations:

• https://realpython.com/django-migrations-a-primer/#creating-migrations
• https://realpython.com/data-migrations/