Migrations

1. Migration 1: Schema change

With this step the new column gets created:

public function changeSchema(IOutput $output, \Closure $schemaClosure, array $options) {
           /** @var ISchemaWrapper $schema */
           $schema = $schemaClosure();

           $table = $schema->getTable('twofactor_backupcodes');

           $table->addColumn('user_id', \OCP\DB\Types::STRING, [
                   'notnull' => true,
                   'length' => 64,
           ]);

           return $schema;
  }

2. Migration 1: Post schema change

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

public function postSchemaChange(IOutput $output, \Closure $schemaClosure, array $options) {
       $query = $this->db->getQueryBuilder();
       $query->update('twofactor_backupcodes')
               ->set('user_id', 'uid');
       $query->executeStatement();
}

3. Migration 2: Schema change

With this the old column gets removed.

 public function changeSchema(IOutput $output, \Closure $schemaClosure, array $options) {
        /** @var ISchemaWrapper $schema */
        $schema = $schemaClosure();

        $table = $schema->getTable('twofactor_backupcodes');
        $table->dropColumn('uid');

        return $schema;
}

Construction of migration classes

All migration classes are constructed via :ref:`dependency-injection`. So if your migration steps need additional dependencies, these can be defined in the constructor of your migration class.

Example: If your migration needs to execute SQL statements, inject a OCP\IDBConnection instance into your migration class like this:

class Version2404Date20220903071748 extends SimpleMigrationStep {
   public function __construct(
      private IDBConnection $db
   ) {
   }

   public function postSchemaChange(IOutput $output, \Closure $schemaClosure, array $options) {
      $query = $this->db->getQueryBuilder();
      // execute some SQL ...
   }
}

Migrations and Metadata

Since 30, details about migrations are available to administrator as metadata can be attached to your migration class by adding specific PHP Attributes:

List of available Migration Attributes:

• \OCP\Migration\Attributes\AddColumn if your migration implies the creation of a new column

• \OCP\Migration\Attributes\AddIndex if your migration adds a new index

• \OCP\Migration\Attributes\CreateTable if your migration creates a new table

• \OCP\Migration\Attributes\DropColumn if your migration drops a column

• \OCP\Migration\Attributes\DropIndex if your migration drops an index

• \OCP\Migration\Attributes\DropTable if your migration drops a table

• \OCP\Migration\Attributes\ModifyColumn if your migration modifies a column

Console commands

The following occ commands help you create and manage migrations:

migrations
 migrations:execute  execute a single migration version manually
 migrations:generate generate a new migration file for an app
 migrations:migrate  execute migrations to a specified or the latest version
 migrations:preview  preview available DB migrations before an upgrade
 migrations:status   view the status of migrations for an app

sudo -E -u www-data php occ migrations:execute myapp 2404Date20220903071748

sudo -E -u www-data php occ migrations:generate myapp 1000

sudo -E -u www-data php occ migrations:migrate myapp
sudo -E -u www-data php occ migrations:migrate myapp prev

sudo -E -u www-data php occ migrations:preview 30.0.0

sudo -E -u www-data php occ migrations:status myapp

Adding indices

Adding indices to existing tables can take long time, especially on large tables. Therefore it is recommended to not add the indices in the migration itself, but to indicate the index requirement to the server by adding a listener for the AddMissingIndicesEvent. This way the migration can be executed in a separate step and do not block the upgrade process. For new installations the index should still be added to the migration that creates the table.

class AddMissingIndicesListener implements IEventListener {
   public function handle(Event $event): void {
      if (!$event instanceof AddMissingIndicesEvent) {
         return;
      }

      $event->addMissingIndex('my_table', 'my_index', ['column_a', 'column_b']);
   }
}

Replacing indices

Similar to adding an index to an existing table, it could be necessary to replace one or more indices with a new one. To avoid a gap between dropping the old indices in a migration and adding the new one through AddMissingIndicesEvent, it is possible to do both at once in AddMissingIndicesEvent.

If none of the previous indices are found, e.g. because they were optional and not created yet, the replacement index will be treated as missing index.

class ReplaceIndicesListener implements IEventListener {
   public function handle(Event $event): void {
      if (!$event instanceof AddMissingIndicesEvent) {
         return;
      }

      $event->replaceIndex('my_table', ['my_old_index_one', 'my_old_index_two'], 'my_new_index', ['column_a', 'column_b'], false);
   }
}