svc

README

svc

svc stands for schema version control, a simple tool to manage schema migration.

How svc works

svc first tries to create a table to maintain the scripts it executed:

CREATE TABLE IF NOT EXISTS schema_version (
    id BIGINT(20) UNSIGNED NOT NULL AUTO_INCREMENT,
    app VARCHAR(50) NOT NULL DEFAULT '',
    created_at TIMESTAMP NOT NULL DEFAULT CURRENT_TIMESTAMP,
    script VARCHAR(256) NOT NULL DEFAULT '',
    success TINYINT(1) NOT NULL DEFAULT 1,
    remark VARCHAR(256) NOT NULL DEFAULT '',
    PRIMARY KEY (id),
    KEY app_idx (app)
);

Everytime svc runs, it queries the last execution log from the schema_version table. If the last execution was failed (success=0), svc returns error until the error and the record is fixed manually.

e.g.,

UPDATE schema_version SET success=1 WHERE id = ?;

If last execution was success, it loads all scripts files from the provided Fs object. The scripts files are sorted and executed one by one only if svc considers the script file belongs to a version that is after the last execution.

For example, the last executed file is 'v0.0.2.sql'. From the provided FS, svc found following files:

- v0.0.1.sql
- v0.0.2.sql
- v0.0.3.sql

svc recognizes that both v0.0.1.sql and v0.0.2.sql belong to a version that is before 0.0.2. These two files are simply ignored. Then only the v0.0.3.sql file is executed.

The entry point of svc is:

func MigrateSchema(db *gorm.DB, log Logger, c MigrateConfig) error {
    // ...
}

e.g., we may write code like the following

//go:embed schema/*.sql
var schemaFs embed.FS

conf := MigrateConfig{
    App:     "test",
    Fs:      schemaFs,
    BaseDir: "schema/svc",
}
err = MigrateSchema(conn.Debug(), PrintLogger{}, conf)

// ...

Then in database:

> select * from schema_version;

+----+------+---------------------+------------+---------+--------+
| id | app  | created_at          | script     | success | remark |
+----+------+---------------------+------------+---------+--------+
| 30 | test | 2024-03-02 18:45:46 | v0.0.1.sql |       1 |        |
| 31 | test | 2024-03-02 18:45:46 | v0.0.2.sql |       1 |        |
+----+------+---------------------+------------+---------+--------+

Documentation

Index

• Constants
• func ExcludeFile(name string)
• func MigrateSchema(db *gorm.DB, log Logger, c MigrateConfig) error
• func PadVer(ver1 []string, s int) []string
• func PadVers(ver1 []string, ver2 []string) ([]string, []string)
• func SplitVer(ver string) []string
• func VerAfter(ver1 string, ver2 string) bool
• type Logger
• type MigrateConfig
• type PrintLogger
  • func (pl PrintLogger) Error(args ...any)
  • func (pl PrintLogger) Errorf(pat string, args ...any)
  • func (pl PrintLogger) Info(args ...any)
  • func (pl PrintLogger) Infof(pat string, args ...any)
• type ReadFS

Constants

const (
	VerSep = "."
)

Functions

func ExcludeFile

func ExcludeFile(name string)

func MigrateSchema

func MigrateSchema(db *gorm.DB, log Logger, c MigrateConfig) error

func PadVer

func PadVer(ver1 []string, s int) []string

func PadVers

func PadVers(ver1 []string, ver2 []string) ([]string, []string)

v1, v2.1 => v1.0, v2.1; v2, v1.2 => v2.0, v1.2

func SplitVer

func SplitVer(ver string) []string

func VerAfter

func VerAfter(ver1 string, ver2 string) bool

Check if ver1 is after ver2.

Types

type Logger

type Logger interface {
	Info(args ...any)
	Infof(pat string, args ...any)
	Error(args ...any)
	Errorf(pat string, args ...any)
}

type MigrateConfig

type MigrateConfig struct {
	App     string
	Fs      ReadFS
	BaseDir string

	// Starting version, it's optional. If provided, svc tries to start with the provided version.
	// If absent, svc follows the previous version.
	StartingVersion string
}

type PrintLogger

type PrintLogger struct {
}

func (PrintLogger) Error

func (pl PrintLogger) Error(args ...any)

func (PrintLogger) Errorf

func (pl PrintLogger) Errorf(pat string, args ...any)

func (PrintLogger) Info

func (pl PrintLogger) Info(args ...any)

func (PrintLogger) Infof

func (pl PrintLogger) Infof(pat string, args ...any)

type ReadFS

type ReadFS interface {
	fs.ReadFileFS
	fs.ReadDirFS
}

Interface that impls both fs.ReadFileFS and fs.ReadDirFS

e.g.,

//go:embed schema/svc/*.sql
var schemaFs embed.FS