dsync

README

dsync

Getting Started

go get github.com/SharkFourSix/dsync

Usage

1. Choose a data source (check in sources) or implement your own.
2. Create a Migrator and pass the data source to the migrator

import (
	"embed"
	"testing"

	"github.com/SharkFourSix/dsync"
	"github.com/SharkFourSix/dsync/sources/postgresql"
)

//go:embed resources/migrations
var efs embed.FS

func DoMigrate(){
    dsn := "postgres://postgres:toor@localhost:5433/test-db"
    
    // Create a migrator
    var migrator dsync.Migrator

    // Configure a data source
	ds, err := postgresql.New(dsn, &dsync.Config{
		FileSystem: efs,
		Basepath:   BASEPATH,
		TableName:  "dsync_schema_migration",
	})

	if err != nil {
        panic(err)
	}

    // Migrate
	err = migrator.Migrate(ds)
	if err != nil {
		panic(err)
		return
	}
}

Things To Know

• File names must use the following convention to be included when scanning:

  \d+__\w+.sql.

• An error will be returned otherwise when the version part of the file name does not contain a number.

• A migration script will not be included if it does not end with .sql extension

• Migrations are only recorded in the database when successfull

• Custom migration table name to allow different migrations for difference DB clients.

• Supports out of order migrations

Database sources

Database	Data source	Status
Postgres	github.com/SharkFourSix/dsync/sources/postgresql	Done
MySQL	github.com/SharkFourSix/dsync/sources/mysql	Done
SQLite	github.com/SharkFourSix/dsync/sources/sqlite	Done

TODO

• Add logging and configuration

Documentation

Index

• Constants
• func ExtractVersion(filename string) (version int64, err error)
• func HashFile(_fs fs.FS, filename string) (int64, error)
• func Migrate(ds DataSource, outOfOrder bool) error
• func SortDirectoryEntries(entries []fs.DirEntry) (status error)
• func ValidateConfig(cfg *Config) error
• type Config
  • func (cfg *Config) TableNameOrDefault() string
• type DataSource
• type Migration
  • func ParseMigration(filename string) (*Migration, error)
• type MigrationError
  • func (e MigrationError) Error() string
• type MigrationInfo
• type Migrator
  • func (migrator Migrator) Migrate(ds DataSource) error

Constants

const DefaultTableName = "dsync_migration_info"

Functions

func ExtractVersion

func ExtractVersion(filename string) (version int64, err error)

ExtractVersion Extract version from a migration changeset file

func HashFile

func HashFile(_fs fs.FS, filename string) (int64, error)

HashFile Calculate file content checksum using CRC32(IEEE)

func Migrate

func Migrate(ds DataSource, outOfOrder bool) error

Migrate Perform a quick migration

func SortDirectoryEntries

func SortDirectoryEntries(entries []fs.DirEntry) (status error)

SortDirectoryEntries Sorts the slice in place using the library's naming scheme.

NOTE: This function should not be treated as a validation function.

func ValidateConfig

func ValidateConfig(cfg *Config) error

Types

type Config

type Config struct {
	FileSystem fs.FS
	Basepath   string
	TableName  string
}

func (*Config) TableNameOrDefault

func (cfg *Config) TableNameOrDefault() string

type DataSource

type DataSource interface {
	// GetMigrationInfo Returns table name and other information
	GetMigrationInfo() (*MigrationInfo, error)

	// GetChangeSetFileSystem returns the source file system where migration changeset files are stored
	GetChangeSetFileSystem() (fs.FS, error)

	// GetPath Returns the base path within the file system where to
	GetPath() string

	// BeginTransaction Start transaction
	BeginTransaction() error

	// SetTransactionSuccessful notify the data source whether to commit or rollback when EndTransaction is called
	SetTransactionSuccessful(s bool)

	// ApplyMigration Applies the given migration
	ApplyMigration(migration *Migration) error

	// EndTransaction Commit or rollback the active transaction
	EndTransaction()

	// Handle Return the underlying database handle
	Handle() *sql.DB
}

type Migration

type Migration struct {
	Id        uint32
	Name      string
	File      string
	Version   int64
	CreatedAt time.Time
	Checksum  int64
	Success   bool
}

func ParseMigration

func ParseMigration(filename string) (*Migration, error)

ParseMigration Parse migration information from file name

type MigrationError

type MigrationError struct {
	Err       error
	Migration *Migration
}

func (MigrationError) Error

func (e MigrationError) Error() string

type MigrationInfo

type MigrationInfo struct {
	TableName  string
	Migrations []Migration
	Version    int64
}

type Migrator

type Migrator struct {
	OutOfOrder bool
}

func (Migrator) Migrate

func (migrator Migrator) Migrate(ds DataSource) error