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 запроса;
- нарушена целостность файлов миграций;
- другие причины;
====