migrator

README

pgx-migrator

Simple pgx oriented PostgreSQL schema migration library for Go based on lopezator/migrator.

Features

• Simple code
• Usage as a library, embeddable and extensible on your behalf
• Made to use with jackc/pgx
• Go code migrations, either transactional or transaction-less, using pgx.Tx (migrator.Migration) or pgx.Conn and pgx.Pool (migrator.MigrationNoTx)
• No need to use //go:embed or others, since all migrations are just Go code

Usage

Customize this to your needs by changing the driver and/or connection settings.

QuickStart:

package main

import (

	pgx "github.com/jackc/pgx/v5"
	migrator "github.com/cybertec-postgresql/pgx-migrator"
)

func main() {
    // Configure migrations
    m, err := migrator.New(
        migrator.Migrations(
            &migrator.Migration{
                Name: "Create table foo",
                Func: func(ctx context.Context, tx pgx.Tx) error {
                    _, err := tx.Exec(ctx, "CREATE TABLE foo (id INT PRIMARY KEY)")
                    return err
                },
            },
        ),
    )
    if err != nil {
        panic(err)
    }
   
    // Open database connection
    conn, err := pgx.Connect(context.Background(), os.Getenv("DATABASE_URL"))
    if err != nil {
        panic(err)
    }
    
    // Migrate up
    if err := m.Migrate(conn); err != nil {
        panic(err)
    }
}

Documentation

Index

• type Migration
  • func (m *Migration) String() string
• type MigrationNoTx
  • func (m *MigrationNoTx) String() string
• type Migrator
  • func New(opts ...Option) (*Migrator, error)
  • func (m *Migrator) Migrate(ctx context.Context, db PgxIface) error
  • func (m *Migrator) NeedUpgrade(ctx context.Context, db PgxIface) (bool, error)
  • func (m *Migrator) Pending(ctx context.Context, db PgxIface) ([]interface{}, int, error)
• type Option
  • func Migrations(migrations ...interface{}) Option
  • func SetNotice(noticeFunc func(string)) Option
  • func TableName(tableName string) Option
• type PgxIface

Types

type Migration

type Migration struct {
	Name string
	Func func(context.Context, pgx.Tx) error
}

Migration represents a single migration

func (*Migration) String

func (m *Migration) String() string

String returns a string representation of the migration

type MigrationNoTx

type MigrationNoTx struct {
	Name string
	Func func(context.Context, PgxIface) error
}

MigrationNoTx represents a single not transactional migration

func (*MigrationNoTx) String

func (m *MigrationNoTx) String() string

type Migrator

type Migrator struct {
	TableName string
	// 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 PgxIface) error

Migrate applies all available migrations

func (*Migrator) NeedUpgrade

func (m *Migrator) NeedUpgrade(ctx context.Context, db PgxIface) (bool, error)

NeedUpgrade returns True if database need to be updated with migrations

func (*Migrator) Pending

func (m *Migrator) Pending(ctx context.Context, db PgxIface) ([]interface{}, int, error)

Pending returns all pending (not yet applied) migrations and count of migration applied

type Option

type Option func(*Migrator)

Option sets options such migrations or table name.

func Migrations

func Migrations(migrations ...interface{}) Option

Migrations creates an option with provided migrations

func SetNotice

func SetNotice(noticeFunc func(string)) Option

SetNotice overrides the default standard output function

func TableName

func TableName(tableName string) Option

TableName creates an option to allow overriding the default table name

type PgxIface

type PgxIface interface {
	Begin(ctx context.Context) (pgx.Tx, error)
	Exec(context.Context, string, ...interface{}) (pgconn.CommandTag, error)
	QueryRow(context.Context, string, ...interface{}) pgx.Row
	Query(ctx context.Context, query string, args ...interface{}) (pgx.Rows, error)
}

PgxIface is interface for database connection or transaction