#Міграції (Migration)

Під час розробки та оновлення плагінів NocoBase, структура бази даних або конфігурація плагіна можуть зазнавати несумісних змін. Щоб забезпечити плавне оновлення, NocoBase пропонує механізм міграцій (Migration), який дозволяє обробляти ці зміни шляхом написання файлів міграцій. Цей посібник допоможе вам системно зрозуміти, як використовувати міграції та який процес їх розробки.

#Концепція міграції

Міграція – це скрипт, який автоматично виконується під час оновлення плагінів і використовується для вирішення таких завдань:

• Коригування структури таблиць даних (додавання полів, зміна типів полів тощо)
• Міграція даних (наприклад, пакетне оновлення значень полів)
• Оновлення конфігурації плагіна або внутрішньої логіки

Час виконання міграцій поділяється на три типи:

#Створення файлів міграцій

Файли міграцій слід розміщувати в каталозі плагіна за шляхом src/server/migrations/*.ts. NocoBase надає команду create-migration для швидкого створення файлів міграцій.

yarn nocobase create-migration [options] <name>

Необов'язкові параметри

Приклад

$ yarn nocobase create-migration update-ui --pkg=@nocobase/plugin-client

Згенерований шлях до файлу міграції:

/nocobase/packages/plugins/@nocobase/plugin-client/src/server/migrations/20240107173313-update-ui.ts

Початковий вміст файлу:

import { Migration } from '@nocobase/server';

export default class extends Migration {
  on = 'afterLoad'; // 'beforeLoad' | 'afterSync' | 'afterLoad'
  appVersion = '<0.19.0-alpha.3';

  async up() {
    // Напишіть тут логіку оновлення
  }
}

⚠️ appVersion використовується для ідентифікації версії, на яку спрямоване оновлення. Середовища з версіями, меншими за вказану, виконають цю міграцію.

#Написання міграції

У файлах міграцій ви можете отримати доступ до наступних поширених властивостей та API через this, щоб зручно працювати з базою даних, плагінами та екземплярами застосунків:

Поширені властивості

• this.app
  Поточний екземпляр застосунку NocoBase. Може використовуватися для доступу до глобальних сервісів, плагінів або конфігурації.

  const config = this.app.config.get('database');

• this.db
  Екземпляр сервісу бази даних, надає інтерфейси для роботи з моделями (колекціями).

  const users = await this.db.getRepository('users').findAll();

• this.plugin
  Поточний екземпляр плагіна, може використовуватися для доступу до користувацьких методів плагіна.

  const settings = this.plugin.customMethod();

• this.sequelize
  Екземпляр Sequelize, може безпосередньо виконувати чистий SQL або транзакційні операції.

  await this.sequelize.transaction(async (transaction) => {
    await this.sequelize.query('UPDATE users SET active = 1', { transaction });
  });

• this.queryInterface
  QueryInterface від Sequelize, часто використовується для зміни структури таблиць, наприклад, додавання полів, видалення таблиць тощо.

  await this.queryInterface.addColumn('users', 'age', {
    type: this.sequelize.Sequelize.INTEGER,
    allowNull: true,
  });

Приклад написання міграції

import { Migration } from '@nocobase/server';

export default class extends Migration {
  on = 'afterSync';
  appVersion = '<0.19.0-alpha.3';

  async up() {
    // Використовуйте queryInterface для додавання поля
    await this.queryInterface.addColumn('users', 'nickname', {
      type: this.sequelize.Sequelize.STRING,
      allowNull: true,
    });

    // Використовуйте db для доступу до моделей даних
    const users = await this.db.getRepository('users').findAll();
    for (const user of users) {
      user.nickname = user.username;
      await user.save();
    }

    // Виконайте користувацький метод плагіна
    await this.plugin.customMethod();
  }
}

Окрім перелічених вище поширених властивостей, міграції також надають багатий набір API. Детальну документацію дивіться в Migration API.

#Запуск міграції

Виконання міграції запускається командою nocobase upgrade:

$ yarn nocobase upgrade

Під час оновлення система визначає порядок виконання на основі типу міграції та appVersion.

#Тестування міграції

Під час розробки плагінів рекомендується використовувати Mock Server для перевірки коректності виконання міграції, щоб уникнути пошкодження реальних даних.

import { createMockServer, MockServer } from '@nocobase/test';

describe('Migration Test', () => {
  let app: MockServer;

  beforeEach(async () => {
    app = await createMockServer({
      plugins: ['my-plugin'], // Назва плагіна
      version: '0.18.0-alpha.5', // Версія перед оновленням
    });
  });

  afterEach(async () => {
    await app.destroy();
  });

  test('run upgrade migration', async () => {
    await app.runCommand('upgrade');
    // Напишіть логіку перевірки, наприклад, чи існує поле, чи успішно мігровані дані
  });
});

Порада: Використання Mock Server дозволяє швидко симулювати сценарії оновлення та перевіряти порядок виконання міграцій і зміни даних.

#Рекомендації щодо розробки

1. Розділяйте міграції
   Намагайтеся генерувати один файл міграції для кожного оновлення, щоб зберегти атомарність і спростити виявлення проблем.
2. Вказуйте час виконання
   Вибирайте beforeLoad, afterSync або afterLoad залежно від об'єктів операції, уникаючи залежності від незавантажених модулів.
3. Контролюйте версії
   Використовуйте appVersion для чіткого визначення версії, до якої застосовується міграція, щоб запобігти повторному виконанню.
4. Покриття тестами
   Перевірте міграцію на Mock Server перед виконанням оновлення в реальному середовищі.