Управление версиями базы данных Atlas

1. Введение в Atlas

atlas

Atlas - это инструмент, независимый от языка программирования, специально разработанный для управления и миграции схем баз данных с использованием современных принципов DevOps. Он предоставляет два варианта рабочего процесса:

Декларативный: Аналогично Terraform, Atlas сравнивает текущее состояние базы данных с желаемым состоянием, определенным с использованием HCL, SQL или схемой ORM. На основе этого сравнения он генерирует и выполняет план миграции для перехода базы данных к желаемому состоянию.
Версионный: В отличие от других инструментов, Atlas автоматически планирует миграции схем для вас. Пользователи могут описать желаемую схему базы данных с использованием HCL, SQL или выбранной ими ORM, и с помощью Atlas планировать, проверять и применять необходимые миграции к базе данных.

Одним из ключевых преимуществ Atlas является упрощение управления сложностью баз данных, что делает процессы контроля версий, совместной работы и реализации более легкими.

2. Установка Atlas

Перед использованием Atlas для управления версиями баз данных необходимо установить его. Ниже приведены инструкции по установке на различных платформах.

2.1 Установка на macOS + Linux

На системах macOS или Linux вы можете загрузить и установить последнюю версию Atlas с помощью следующей команды:

curl -sSf https://atlasgo.sh | sh

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

2.2 Установка через Homebrew

Если вы используете macOS и уже установили менеджер пакетов Homebrew, установка Atlas будет столь же проста, как выполнение команды:

brew install ariga/tap/atlas

Это позволит получить последнюю версию Atlas из репозитория Homebrew и установить ее.

2.3 Установка через Docker

Установка и запуск Atlas через Docker является быстрым и удобным методом, особенно для временного тестирования или для пользователей, предпочитающих не устанавливать дополнительное программное обеспечение на своей системе.

Сначала загрузите образ Docker для Atlas:

docker pull arigaio/atlas

Затем вы можете выполнить команду для подтверждения успешной установки:

docker run --rm arigaio/atlas --help

Если контейнеру требуется доступ к сети хоста или к локальным каталогам, используйте флаг --net=host и подключите необходимые каталоги:

docker run --rm --net=host \
  -v $(pwd)/migrations:/migrations \
  arigaio/atlas migrate apply \
  --url "mysql://root:pass@:3306/test"

2.4 Установка на Windows

Загрузите двоичный файл по ссылке https://release.ariga.io/atlas/atlas-windows-amd64-latest.exe и добавьте путь установки в переменную среды PATH системы.

3. Экспорт структуры существующей таблицы базы данных с помощью Atlas

Atlas предоставляет команду atlas schema inspect, которая может использоваться для экспорта структуры существующей базы данных. Эта команда поддерживает чтение описаний базы данных из URL базы данных и выводит их в три различных формата: формат Atlas HCL по умолчанию, формат SQL и формат JSON. В этом руководстве мы покажем, как использовать форматы Atlas HCL и SQL, поскольку формат JSON обычно используется для обработки вывода с помощью jq.

Чтобы осмотреть локально запущенный экземпляр MySQL и записать вывод в файл с именем schema.hcl, используйте следующую команду:

atlas schema inspect -u "mysql://root:pass@localhost:3306/example" > schema.hcl

Откройте файл schema.hcl, чтобы просмотреть описание структуры таблицы Atlas, описывающее базу данных (HCL - это независимый от базы данных формат конфигурации структуры таблиц, определенный Atlas). Например, этот файл будет содержать следующее содержимое:

table "users" {
  schema = schema.example
  column "id" {
    null = false
    type = int
  }
  column "name" {
    null = true
    type = varchar(100)
  }
  primary_key {
    columns = [column.id]
  }
}

Этот блок кода представляет структуру таблицы с колонками id и name. Поле schema ссылается на определение модели example, определенной в другом месте в этом документе. Кроме того, подблок primary_key указывает колонку id как первичный ключ для таблицы. Atlas стремится имитировать синтаксис базы данных, с которой работает. В этом примере колонка id имеет тип int, а колонка name имеет тип varchar(100).

Аналогично, для экспорта SQL-определения модели базы данных вы можете использовать следующую команду:

atlas schema inspect -u "mysql://root:pass@localhost:3306/example" --format '{{ sql . }}' > schema.sql

Откройте файл schema.sql, чтобы просмотреть SQL-описание базы данных, обычно содержащее некоторые операторы CREATE TABLE.

Этот подход упрощает понимание деталей структуры существующей таблицы базы данных и предоставляет точное описание для последующих версионных миграций.

4.1 Декларативный рабочий процесс

Декларативный рабочий процесс Atlas позволяет пользователям декларативно определять желаемое конечное состояние базы данных. Пользователям нужно только описать, каким должно быть конечное состояние схемы базы данных, и инструмент Atlas автоматически сгенерирует и выполнит планы миграции для безопасного перехода схемы базы данных от текущего состояния к этому ожидаемому состоянию.

Ниже приведено, как использовать декларативный рабочий процесс для определения и достижения желаемого состояния базы данных:

4.1.1 Определение структуры целевой таблицы

Сначала вам нужно создать файл, определяющий ожидаемую структуру базы данных, который может быть в формате HCL, SQL или ORM (Object-Relational Mapping).

Возьмем формат HCL в качестве примера и определим новую таблицу blog_posts:

table "blog_posts" {
  schema = schema.example
  column "id" {
    null = false
    type = int
  }
  column "title" {
    null = true
    type = varchar(100)
  }
  column "body" {
    null = true
    type = text
  }
  column "author_id" {
    null = true
    type = int
  }
  primary_key {
    columns = [column.id]
  }
  foreign_key "author_fk" {
    columns     = [column.author_id]
    ref_columns = [table.users.column.id]
  }
}

Совет: Синтаксис формата HCL будет рассмотрен в следующем разделе.

4.1.2 Выполнение миграции с помощью инструмента Atlas

После завершения определения структуры таблицы базы данных вы можете использовать команду schema apply Atlas для выполнения миграции.

atlas schema apply \
  -u "mysql://root:pass@localhost:3306/example" \
  --to file://schema.hcl

После выполнения этой команды Atlas сравнит существующую схему базы данных с схемой, определенной в файле, сгенерирует план миграции и запросит подтверждение пользователя для выполнения. Как только пользователь подтвердит план выполнения, Atlas выполнит миграцию базы данных и обновит ее до желаемого состояния.

4.2 Версионный рабочий процесс

Версионный рабочий процесс - это еще один поддерживаемый режим использования Atlas, иногда называемый "миграцией на основе изменений". Он подходит для сценариев, где изменения схемы базы данных должны быть контролируемыми по версиям и рассматриваться в процессе кодового обзора.

Этапы версионного рабочего процесса включают:

4.2.1 Расчет различий

Перед началом миграции необходимо сравнить текущую структуру базы данных с желаемым состоянием и определить различия между ними. Это можно сделать, запустив команду atlas migrate diff.

atlas migrate diff create_blog_posts \
  --dir "file://migrations" \
  --to "file://schema.hcl" \
  --dev-url "docker://mysql/8/example"

Параметр --dir указывает URL папки миграции, по умолчанию устанавливается как file://migrations. Параметр --to задает URL желаемого состояния (например, базы данных в вашей среде разработки), а --dev-url предоставляет URL для разработочной базы данных, используемой для вычисления различий (обратите внимание, что параметр --dev-url должен указывать на пустую базу данных, которую Atlas использует для расчета различий).

Подсказка: Если вам нужно сгенерировать файлы SQL, обратитесь к предыдущему разделу для установки формата с помощью параметра --format.

4.2.2 Применение изменений миграции

После завершения расчета различий, Atlas сгенерирует два файлы миграции, сохраненных в папке migrations. Например, если выбран формат SQL, то файлы, сгенерированные командой diff, будут содержать команды миграции для создания новой таблицы:

-- создание таблицы "blog_posts"
CREATE TABLE `blog_posts` (
  `id` int NOT NULL,
  `title` varchar(100) DEFAULT NULL,
  `body` text DEFAULT NULL,
  `author_id` int NULL REFERENCES `users`(id),
  PRIMARY KEY (`id`)
);

После генерации файлов миграции можно использовать инструменты контроля версий (например, Git) для управления этими изменениями. Такой подход позволяет вносить множество изменений в структуру таблицы базы данных в среде разработки и при выпуске сравнить среду разработки и среду UAT, используя команды Atlas для генерации файлов миграции структуры таблиц баз данных. Затем эти файлы миграции могут быть применены к среде UAT и продукционной среде для обновления базы данных.

Эти два рабочих процесса, Декларативный и С версиями, обеспечивают гибкость для различных режимов разработки и развертывания, позволяя командам выбирать метод, который лучше всего подходит для управления изменениями схемы базы данных их проекта.

5. Описание формата HCL

5.1 Введение

HCL - это декларативный язык, используемый для описания определений структуры таблиц баз данных. Atlas использует формат HCL для записи схем баз данных, обеспечивая богатую структуру для описания различных аспектов базы данных. Преимущество HCL заключается в его читаемости, легкости обслуживания и поддержке функций, таких как внедрение переменных и дополнительные аннотации.

Подсказка: Если ваш проект должен адаптироваться к нескольким базам данных, описание структуры таблиц в базе-независимом формате с использованием HCL может быть очень удобным.

5.2 Объект `schema`

Объект schema используется для описания схемы базы данных. В MySQL и SQLite он представляет DATABASE, а в PostgreSQL - SCHEMA. Файл HCL может содержать один или несколько объектов schema.

schema "public" {
  comment = "Комментарий к схеме"
}

schema "private" {}

5.3 Объект `table`

Объект table используется для описания таблицы в SQL-базе данных, включая столбцы, индексы, ограничения и различные дополнительные свойства, поддерживаемые различными драйверами баз данных.

table "users" {
  schema = schema.public
  column "id" {
    type = int
  }
  column "name" {
    type = varchar(255)
  }
  column "manager_id" {
    type = int
  }
  primary_key {
    columns = [
      column.id
    ]
  }
  index "idx_name" {
    columns = [
      column.name
    ]
    unique = true
  }
  foreign_key "manager_fk" {
    columns     = [column.manager_id]
    ref_columns = [table.users.column.id]
    on_delete   = CASCADE
    on_update   = NO_ACTION
  }
}

5.4 Объект `column`

Объект column является подресурсом объекта table, используемым для определения столбцов в таблице.

column "name" {
  type = text
  null = false
}

column "age" {
  type = integer
  default = 42
}

column "active" {
  type = tinyint(1)
  default = true
}

5.5 Объект `primary_key`

primary_key - это дополнительный ресурс table, который определяет первичный ключ таблицы.

primary_key {
  columns = [column.id]
}

5.6 Объект `foreign_key`

foreign_key - это дополнительный ресурс table, который определяет столбцы, ссылающиеся на столбцы в других таблицах.

table "orders" {
  schema = schema.market
  // ...
  column "owner_id" {
    type = integer
  }
  foreign_key "owner_id" {
    columns     = [column.owner_id]
    ref_columns = [table.users.column.id]
    on_update   = NO_ACTION
    on_delete   = NO_ACTION
  }
}

5.7 Объект `index`

Объект index представляет индекс в таблице.

index "idx_name" {
  columns = [
    column.name
  ]
  unique = true
}