go_migrator

README

Описание

Библиотека осуществляет управление миграциями базы данных.
В качестве базы данных используется Postgresql. В качестве ORM используется GORM.
Интерфейс миграций подразумевает возможность отката текущей миграции.
Управление текущей версией бд и статусом миграций осуществляется по таблицам version и migrations.

Сущности

Migrator - интерфейс, описывающий миграцию
MigrationManager - фасад для управления миграциями

Пример работы

см. examples

Documentation

Index

• Variables
• type ManagerOption
  • func WithLogFlags(flags int) ManagerOption
  • func WithLogWriter(w io.Writer) ManagerOption
• type Migration
  • func NewBaselineMigration(migrator Migrator) *Migration
  • func NewRepeatableMigration(migrator RepeatableMigrator, opts ...RepeatableMigratorOption) *Migration
  • func NewVersionedMigration(migrator VersionedMigrator) *Migration
• type MigrationManager
  • func NewMigrationsManager(db *gorm.DB, targetVersion string, opts ...ManagerOption) (*MigrationManager, error)
  • func (m *MigrationManager) CheckFulfillment() (reasonErr error, ok bool, err error)
  • func (m *MigrationManager) Downgrade() (err error)
  • func (m *MigrationManager) HasFailedMigrations() (bool, error)
  • func (m *MigrationManager) HasForthcomingMigrations() (bool, error)
  • func (m *MigrationManager) Migrate() error
  • func (m *MigrationManager) RegisterMigration(migration *Migration, opts ...MigrationOption)
  • func (m *MigrationManager) TargetVersionNotLatest() (bool, error)
• type MigrationOption
  • func WithTransaction(useTransaction bool) MigrationOption
• type MigrationType
• type Migrator
• type RepeatableMigrator
• type RepeatableMigratorOption
  • func WithRepeatUnconditional() RepeatableMigratorOption
• type Version
  • func (v Version) Equals(version Version) bool
  • func (v Version) LessOrEqual(version Version) bool
  • func (v Version) LessThan(version Version) bool
  • func (v Version) MoreOrEqual(version Version) bool
  • func (v Version) MoreThan(version Version) bool
  • func (v Version) String() string
• type VersionedMigrator

Variables

var (
	ErrNoSuccessfulBaseline     = errors.New("no baseline migration was found, consider migrating")
	ErrHasForthcomingMigrations = errors.New("found not completed forthcoming migrations, consider migrating")
	ErrHasFailedMigrations      = errors.New("found failed migrations, consider fixing your db")
	ErrTargetVersionNotLatest   = errors.New("target version falls behind migrations, consider raising target version")
)

Types

type ManagerOption

type ManagerOption func(*MigrationManager)

func WithLogFlags

func WithLogFlags(flags int) ManagerOption

func WithLogWriter

func WithLogWriter(w io.Writer) ManagerOption

type Migration

type Migration struct {
	// contains filtered or unexported fields
}

func NewBaselineMigration

func NewBaselineMigration(migrator Migrator) *Migration

func NewRepeatableMigration

func NewRepeatableMigration(migrator RepeatableMigrator, opts ...RepeatableMigratorOption) *Migration

func NewVersionedMigration

func NewVersionedMigration(migrator VersionedMigrator) *Migration

type MigrationManager

type MigrationManager struct {
	// contains filtered or unexported fields
}

func NewMigrationsManager

func NewMigrationsManager(db *gorm.DB, targetVersion string, opts ...ManagerOption) (*MigrationManager, error)

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

func (*MigrationManager) CheckFulfillment

func (m *MigrationManager) CheckFulfillment() (reasonErr error, ok bool, err error)

CheckFulfillment проверяет корректность установки всех миграций. Проверяется, что нет миграций со статусом models.StateFailure, затем проверяется, что все зарегистрированные миграции выше послденей сохраненной версии сохранены и выполнены успешно, затем проверяется, что target версия установлена выше или равной последней найденной миграции.

func (*MigrationManager) Downgrade

func (m *MigrationManager) Downgrade() (err error)

Downgrade осуществляет отмену успешно выполненных или пропущенных миграций в обратном порядке. Миграции типа TypeRepeatable и TypeBaseline не отменяются. Новые миграции при вызове Downgrade не сохраняются.

Паникует в случае, если какая-либо из миграций не была найдена.

func (*MigrationManager) HasFailedMigrations

func (m *MigrationManager) HasFailedMigrations() (bool, error)

HasFailedMigrations определяет есть ли миграции, не выполненные из-за ошибки.

func (*MigrationManager) HasForthcomingMigrations

func (m *MigrationManager) HasForthcomingMigrations() (bool, error)

HasForthcomingMigrations проверяет, есть ли зарегистрированные или сохраненные невыполненные миграции, выше текущей сохраненной версии.

func (*MigrationManager) Migrate

func (m *MigrationManager) Migrate() error

Migrate сохраняет и выполняет миграции в нужном порядке. Для этого на первом шаге создаются системные таблицы version и migrations, затем определяется необходимость проведения миграции типа TypeBaseline, после чего выполняются миграции типов TypeVersioned. Миграции типа TypeRepeatable выполняются в последнюю очередь. Все зарегистрированные миграции сохраняются в таблицу migrations. Миграции считаются новыми по инедтификатору f(версия, тип миграции).

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

func (*MigrationManager) RegisterMigration

func (m *MigrationManager) RegisterMigration(migration *Migration, opts ...MigrationOption)

RegisterMigration сохраняет миграции в память. По умолчанию миграции осуществляются внутри транзакции.

Паникует при регистрации миграций с одинаковымм версией и типом.

func (*MigrationManager) TargetVersionNotLatest

func (m *MigrationManager) TargetVersionNotLatest() (bool, error)

TargetVersionNotLatest проверяет, является ли target версия выше или равной максимальной версии зарегистрированной или сохраненной миграции.

type MigrationOption

type MigrationOption func(*Migration)

func WithTransaction

func WithTransaction(useTransaction bool) MigrationOption

WithTransaction позволяет выполнить текущую миграцию внутри транзации. По умолчанию равен true. При выполнении группы миграций внутри транзакции, что конфигурируется в MigrationManager с помощью опции WithGroupTransaction, вложенная транзакция для данной миграции не создается.

type MigrationType

type MigrationType string

const (
	TypeBaseline   MigrationType = "baseline"
	TypeVersioned  MigrationType = "versioned"
	TypeRepeatable MigrationType = "repeatable"
)

type Migrator

type Migrator interface {
	Migrate(db *gorm.DB) error
	Description() string
	Version() Version
}

type RepeatableMigrator

type RepeatableMigrator interface {
	Migrator
	Checksum() string
}

type RepeatableMigratorOption

type RepeatableMigratorOption func(*Migration)

func WithRepeatUnconditional

func WithRepeatUnconditional() RepeatableMigratorOption

WithRepeatUnconditional позволяет игнорировать значение checksum для миграции типа TypeRepeatable и выполнять ее при каждом запуске Migrate.

type Version

type Version struct {
	Major      int
	Minor      int
	Patch      int
	PreRelease int
}

func (Version) Equals

func (v Version) Equals(version Version) bool

func (Version) LessOrEqual

func (v Version) LessOrEqual(version Version) bool

func (Version) LessThan

func (v Version) LessThan(version Version) bool

func (Version) MoreOrEqual

func (v Version) MoreOrEqual(version Version) bool

func (Version) MoreThan

func (v Version) MoreThan(version Version) bool

func (Version) String

func (v Version) String() string

type VersionedMigrator

type VersionedMigrator interface {
	Migrator
	Downgrade(db *gorm.DB) error
}