db_migrator

README

Описание

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

Сущности

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

Пример использования

см. migrate_test.go

Documentation

Index

• Variables
• type DbDependency
• type ManagerOption
  • func WithLogger(logger *slog.Logger) ManagerOption
• type Migration
• type MigrationManager
  • func NewMigrationsManager(opts ...ManagerOption) (*MigrationManager, error)
  • func (m *MigrationManager) CheckFulfillment(serviceName string) (reasonErr error, ok bool, err error)
  • func (m *MigrationManager) Downgrade(serviceName string) (err error)
  • func (m *MigrationManager) GetServiceInfoUnsafe(name string) (*ServiceInfo, bool)
  • func (m *MigrationManager) Migrate(serviceName string) error
  • func (m *MigrationManager) Register(serviceName string, migrationsStruct ...Migration) error
  • func (m *MigrationManager) RegisterService(name string, connectFunc func() *gorm.DB, disconnectFunc func(db *gorm.DB), ...) error
• type MigrationOption
  • func WithTransaction(useTransaction bool) MigrationOption
• type MigrationType
• type RepeatableMigratorOption
  • func WithRepeatUnconditional() RepeatableMigratorOption
• type ServiceInfo

Variables

var (
	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 DbDependency

type DbDependency struct {
	Name    string
	Version string
	Strict  bool
}

type ManagerOption

type ManagerOption func(*MigrationManager)

func WithLogger

func WithLogger(logger *slog.Logger) ManagerOption

type Migration

type Migration struct {
	MigrationType MigrationType
	Version       string
	Description   string

	IsTransactional bool
	IsAllowFailure  bool

	Up   string
	Down string

	UpF   func(selfDb *gorm.DB, depsDb map[string]*gorm.DB) error
	DownF func(selfDb *gorm.DB, depsDb map[string]*gorm.DB) error

	CheckSum            func(selfDb *gorm.DB) string
	Identifier          uint32
	RepeatUnconditional bool

	Dependency []DbDependency
}

type MigrationManager

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

func NewMigrationsManager

func NewMigrationsManager(opts ...ManagerOption) (*MigrationManager, error)

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

func (*MigrationManager) CheckFulfillment

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

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

func (*MigrationManager) Downgrade

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

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

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

func (*MigrationManager) GetServiceInfoUnsafe

func (m *MigrationManager) GetServiceInfoUnsafe(name string) (*ServiceInfo, bool)

func (*MigrationManager) Migrate

func (m *MigrationManager) Migrate(serviceName string) error

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

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

func (*MigrationManager) Register

func (m *MigrationManager) Register(serviceName string, migrationsStruct ...Migration) error

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

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

func (*MigrationManager) RegisterService

func (m *MigrationManager) RegisterService(name string, connectFunc func() *gorm.DB, disconnectFunc func(db *gorm.DB), targetVersion string) error

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 RepeatableMigratorOption

type RepeatableMigratorOption func(*Migration)

func WithRepeatUnconditional

func WithRepeatUnconditional() RepeatableMigratorOption

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

type ServiceInfo

type ServiceInfo struct {
	Db             *gorm.DB
	ConnectFunc    func() *gorm.DB
	DisconnectFunc func(db *gorm.DB)
	TargetVersion  models.Version
	// contains filtered or unexported fields
}