Migrations

In the past, apps had a appinfo/database.xml-file which holds their database schema for installation and update and was a functional method for installing apps which had some trouble with upgrading apps (e.g. apps were not able to rename columns without losing the data stored in the original column):

  1. <?xml version="1.0" encoding="ISO-8859-1" ?>
  2. <database>
  3.          <name>*dbname*</name>
  4.          <create>true</create>
  5.          <overwrite>false</overwrite>
  6.          <charset>utf8</charset>
  7.          <table>
  8.                  <name>*dbprefix*twofactor_backupcodes</name>
  9.                  <declaration>
  10.                        <field>
  11.                                <name>id</name>
  12.                                <type>integer</type>
  13.                                <autoincrement>1</autoincrement>
  14.                                <default>0</default>
  15.                                <notnull>true</notnull>
  16.                                <length>4</length>
  17.                        </field>
  18.  ...

The limitations of this method will be bypassed with migrations. A migration can consist of 3 different methods:

  • Pre schema changes
  • Actual schema changes
  • Post schema changes

Apps can have multiple migrations, which allows a way more flexible updating process. For example, you can rename a column while copying all the content with 3 steps packed in 2 migrations.

After creating migrations for your current database and installation routine, you need to in order to make use of migrations, is to delete the old appinfo/database.xml file. The Nextcloud updater logic only allows to use one or the other. But as soon as the database.xml file is gone, it will look for your migration files in the apps lib/Migration folder.

Note

While in theory you can run any code in the pre- and post-steps, we recommend not to use actual php classes. With migrations you can update from any old version to any new version as long as the migration steps are retained. Since they are also used for installation, you should keep them anyway. But this also means when you change a php class which you use in your migration, the code may be executed on different database/file/code standings when being ran in an upgrade situation.

Note

Since Nextcloud stores, which migrations have been executed already you must not “update” migrations. The recommendation is to keep them untouched as long as possible. You should only adjust it to make sure it still executes, but additional changes to the database should be done in a new migration.

1. Migration 1: Schema change

With this step the new column gets created:

  1. public function changeSchema(IOutput $output, \Closure $schemaClosure, array $options) {
  2.                    /** @var Schema $schema */
  3.                    $schema = $schemaClosure();
  5.                    $table = $schema->getTable('twofactor_backupcodes');
  7.                    $table->addColumn('user_id', \OCP\DB\Types::STRING, [
  8.                            'notnull' => true,
  9.                            'length' => 64,
  10.                    ]);
  12.                    return $schema;
  13.       }

2. Migration 1: Post schema change

In this step the content gets copied from the old to the new column.

Note

This could also be done as part of the second migration as part of a pre schema change

  1. public function postSchemaChange(IOutput $output, \Closure $schemaClosure, array $options) {
  2.        $query = $this->db->getQueryBuilder();
  3.        $query->update('twofactor_backupcodes')
  4.                ->set('user_id', 'uid');
  5.        $query->execute();
  6. }

3. Migration 2: Schema change

With this the old column gets removed.

  1.  public function changeSchema(IOutput $output, \Closure $schemaClosure, array $options) {
  2.         /** @var Schema $schema */
  3.         $schema = $schemaClosure();
  5.         $table = $schema->getTable('twofactor_backupcodes');
  6.         $table->dropColumn('uid');
  8.         return $schema;
  9. }

Migrate from database.xml

To migrate your app from a database.xml file to migrations run:

  1. php ./occ migrations:generate-from-schema <app_id> <version>

This will create a new file under lib/Migration that results in the same database table(s) as your database.xml file.

For version you should use your app versions. So if you app is at version 1.2.3 use 010203.

Don’t forget to remove your database.xml file.

Console commands

There are some console commands, which should help developers to create or deal with migrations, which are sometimes only available if you are running your Nextcloud in debug mode:

  • migrations:execute: Executes a single migration version manually.
  • migrations:generate: This is needed to create a new migration file. This takes 2 arguments, first one is the appid, the second one should be the version`of your app as an integer. We recommend to use the major and minor digits of your apps version for that. This allows you to introduce a new migration in your branch for a Nextcloud version if there is already a migration path for a newer one in another branch. Since you can’t change this retroactive, we recommend to leave enough space in between and therefore map the numbers to 3 digits: `1.0.x => 1000, 2.34.x => 2034, etc.
  • migrations:generate-from-schema: Create a migration from the old database.xml.
  • migrations:migrate: Execute a migration to a specified or the latest available version.
  • migrations:status: View the status of a set of migrations.