mgx

README

mgx

Simple migration system for pgx.

Migrations are defined in code and are executed in order. The migration system keeps track of which migrations have been executed and which have not.

Getting Started

1. Install the dependency

go get -u github.com/z0ne-dev/mgx/v2

1. Import the package and create a new migrator

package main

import "github.com/z0ne-dev/mgx"

func main() {
    migrator, _ := mgx.New(mgx.Migrations(
		// insert migrations here 
    ))
}

1. Run the Migrate(context.TODO(), pgx) method to execute the migrations

Contributing

Contributions are what make the open source community such an amazing place to learn, inspire, and create. Any contributions you make are greatly appreciated.

If you have a suggestion that would make this better, please fork the repo and create a pull request. You can also simply open an issue with the tag "enhancement". Don't forget to give the project a star! Thanks again!

1. Fork the Project
2. Create your Feature Branch (git checkout -b feature/AmazingFeature)
3. Commit your Changes (git commit -m 'Add some AmazingFeature')
4. Push to the Branch (git push origin feature/AmazingFeature)
5. Open a Pull Request

License

Distributed under the Apache-2.0 License. See LICENSE for more information.

Acknowledgments

• lopezator/migrator for inspiration for this package. Lots of inspiration was taken from this package, but it was not used directly. The API was designed to be similar, to reduce refactoring when switching between the two packages.

Documentation

Overview

Package mgx is a simple migration tool for pgx

Index

• Variables
• type Commands
• type Conn
• type Logger
• type LoggerFunc
  • func (f LoggerFunc) Log(msg string, data map[string]any)
• type Migration
  • func NewMigration(name string, fn MigrationFunc) Migration
  • func NewRawMigration(name, sql string) Migration
• type MigrationFunc
• type Migrator
  • func New(opts ...Option) (*Migrator, error)
  • func (m *Migrator) Migrate(ctx context.Context, db Conn) error
  • func (m *Migrator) Pending(ctx context.Context, db Conn) ([]Migration, error)
• type Option
  • func Log(logger Logger) Option
  • func Migrations(migrations ...Migration) Option
  • func TableName(tableName string) Option

Variables

var ErrTooManyAppliedMigrations = errors.New("too many applied migrations")

ErrTooManyAppliedMigrations is returned when more migrations are applied than defined

Types

type Commands

type Commands interface {
	Exec(ctx context.Context, sql string, arguments ...any) (pgconn.CommandTag, error)
	Query(ctx context.Context, sql string, args ...any) (pgx.Rows, error)
	QueryRow(ctx context.Context, sql string, args ...any) pgx.Row
}

Commands is the interface that wraps the basic sql command methods.

type Conn

type Conn interface {
	Commands
	Begin(ctx context.Context) (pgx.Tx, error)
}

Conn is the interface that wraps the basic connection methods.

type Logger

type Logger interface {
	Log(msg string, data map[string]any)
}

Logger interface

type LoggerFunc

type LoggerFunc func(msg string, data map[string]any)

LoggerFunc is a bridge between Logger and any third party logger

func (LoggerFunc) Log

func (f LoggerFunc) Log(msg string, data map[string]any)

Log implements Logger interface

type Migration

type Migration interface {
	fmt.Stringer
	Run(context.Context, Commands) error
}

Migration is the migration interface

func NewMigration

func NewMigration(name string, fn MigrationFunc) Migration

NewMigration creates a migration from a function.

func NewRawMigration

func NewRawMigration(name, sql string) Migration

NewRawMigration creates a migration from a raw SQL string.

type MigrationFunc

type MigrationFunc func(context.Context, Commands) error

MigrationFunc is a wrapper around a function so that it implements the Migration interface.

type Migrator

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

Migrator is the migrator implementation

func New

func New(opts ...Option) (*Migrator, error)

New creates a new migrator instance

func (*Migrator) Migrate

func (m *Migrator) Migrate(ctx context.Context, db Conn) error

Migrate applies all available migrations

func (*Migrator) Pending

func (m *Migrator) Pending(ctx context.Context, db Conn) ([]Migration, error)

Pending returns all pending (not yet applied) migrations

type Option

type Option func(*Migrator)

Option sets options such migrations or table name.

func Log

func Log(logger Logger) Option

Log creates an option to allow overriding the stdout logging

func Migrations

func Migrations(migrations ...Migration) Option

Migrations creates an option with provided migrations

func TableName

func TableName(tableName string) Option

TableName creates an option to allow overriding the default table name