live-migrations

Миграции баз данных для Node.js

Автоматическое обновление состояния базы даных проекта путем последовательного выполнения sql-комманд, прописанных в файлах миграций.

Когда использовать модуль

Если вы хотите параллельно с изменением кода вашего проекта обновлять структуру БД без потери данных или необходимости создавать все таблицы с нуля.

Поддерживаемые БД

• MySQL
• SQLite
• PostgreSQL

Установка

$ npm install live-migration

Пример:

# ./migrations/v1_user.sql

CREATE TABLE users (
    id int primary key,
    email varchar(100) not null
);

# ./migrations/v2_comments.sql

CREATE TABLE comments (
    id int primary key,
    user_id int not null,
    text varchar(255) not null,
    FOREIGN KEY (user_id) users(id)
);

# ./migrations/v3_alter_user.sql

ALTER TABLE users ADD COLUMN name varchar(100);

# ./app.js

    var config = {
        type: "mysql",
        host: "127.0.0.1",
        port: "3306",
        name: "mysql_db",
        user: "mysql_user",
        password: "mysql_user_pswd",
        migrations_dir: "./migrations"
    }

    var module = require("live-migration")(config);

    module.on("ready",function(){
        // Utilize database here ...

    }).on("error",function(err){
        console.error(err);
        process.exit(1);
    });

Важно

• Перед любыми операциями, связанными с изменением структуры БД, настоятельно рекомендуется сделать резервную копию данных.

• На событие "error" должен быть повешен обработчик (особенность Node.js Events).

• Файлы миграций выполняются в порядке возрастания имен. Учитывайте это при создании новых миграций.

• Добавьте в список игнорируемых файлов вашей VCS (Version Control System, например GitHub):

    *.corrupted
    .migrationsrc.json

Как это работает

[Пример работы с локальными БД] (https://docs.google.com/document/d/1bG9SKJGhQzbaRrFIlmrLljNmxwTA9Cwjtjd-7YieFjI/edit?usp=sharing)

• новая миграция

  Для проведения новой миграции пользователь создает *.sql файлы в директории миграций, в которых прописывает алгоритм изменения таблиц на SQL языке. При запуске модуль обнаруживает новые файлы и пошагово выполняет их. Каждый файл - это один шаг миграции. После успешного выполнения команд к имени файла добавляется таймштамп, а в историю текущей базы данных записывается соответствующая версия миграции. Таким образом шаг миграции становится выполненным, а соответствующий ему файл - учтённым.

• обновление

  Обновление возможно при наличии ранее выполненных миграций в проекте. При запуске модуль обнаруживает новые учтённые миграций, по отношению к текущей версии мигрируемой БД, и выполняет её пошаговое обновление. Если при этом присутствуют новые файлы миграций (не учтённые), то после обновления до последней версии миграций они будут выполнены как новая миграция и учтены в проекте.

config

    var config = {
        type: "mysql", // String, "mysql", "sqlite", "postgres"
        host: "127.0.0.1", // String
        port: 3306, // Number
        path: "./sqlite_database.db", // String, SQLite БД;
        name: "mysql_db", // String, имя БД;
        user: "mysql_user", // String, имя пользователя для подключения к БД;
        password: "mysql_user_pswd", // String, пароль пользователя;
        vcs: false, // Boolean, по умолчанию = false, история миграций текущей БД не подлежит контролю VCS.
        migrations_dir: "./migrations" // String - путь к директории миграций относительно корня проекта.
        history_path: "./history" // String - путь к директории, в которой будут храниться файлы с текущим состоянием БД, дублирует migrations_dir, если не задан явно
    }

config.vcs

default: false

Данный флаг имеет значение если вы пользуетесь VCS (например GitHub).

Если разработчики проекта используют физически общую БД то установите флаг vcs = true. Тогда текущая версия миграции такой БД будет храниться в VCS - это обеспечит правильную работу модуля. Так же убедитесь, что в список игнорируемых файлов добавлено:

 .migrationsrc.json

Проверка целостности данных

При успешном выполнении новой миграции содержимое соответствующего ей файла хэшируется.

При запуске модуля происходит проверка целостности данных в учтённых файлах миграции. Если содержимое нарушено к имени файла добавляется суффикс ".corrupt": "timestamp_filename.sql.corrupt".

Файлы с индексом ".corrupt" игнорируются модулем. Чтобы не засорять проект, убедитесь, что в список игнорируемых файлов добавлено:

 *.corrupt

error event

Ввиду особенностей реализации событий в Node.js на событие "error" должен быть повешен обработчик, иначе при запуске модуль вывалится с ошибкой.

Модуль высылает сигнал error в случае:

• не заданы: тип, имя или хост БД (путь к файлу для SQlite);
• невозможно установить соединение с базой данных;
• в файловой системе отсутствует директория миграций;
• ошибка при выполнении sql запроса;
• нарушена целостность файлов миграций;
• другие причины;

====