migration

Documentation

Index

• Variables
• func CurrentDatabase(db *gorm.DB) string
• func DeleteAllTables(ctx context.Context, db *gorm.DB) error
• type DBType
  • func DetectDBType(db *gorm.DB) DBType
• type LintIssue
• type LintReport
  • func Lint(dir string) (report LintReport, retErr error)
  • func (r LintReport) ErrorCount() int
  • func (r LintReport) HasErrors() bool
  • func (r LintReport) HasWarnings() bool
  • func (r LintReport) WarningCount() int
• type LintSeverity
• type Logger
  • func DefaultLogger() Logger
• type NopLogger
  • func (l *NopLogger) Error(_ string, _ ...any)
  • func (l *NopLogger) Info(_ string, _ ...any)
  • func (l *NopLogger) Warn(_ string, _ ...any)

Examples

• Lint
• LintReport

Variables

var (
	// ErrInvalidArgument 表示调用方传入了非法参数（nil db、非法版本号等）。
	ErrInvalidArgument = errors.New("migratex: invalid argument")

	// ErrUnsupportedDatabase 表示当前数据库方言不受支持。
	ErrUnsupportedDatabase = errors.New("migratex: unsupported database")

	// ErrLintFailed 表示 lint 发现了至少一个错误级问题。
	ErrLintFailed = errors.New("migratex: migration lint failed")
)

Functions

func CurrentDatabase

func CurrentDatabase(db *gorm.DB) string

CurrentDatabase 获取当前数据库名称.

func DeleteAllTables

func DeleteAllTables(ctx context.Context, db *gorm.DB) error

DeleteAllTables 删除所有用户基表（不含 view），列表查询与 DROP 均受 ctx 控制.

Types

type DBType

type DBType string

DBType 数据库类型.

const (
	DBTypeMySQL    DBType = "mysql"
	DBTypePostgres DBType = "postgres"
	DBTypeSQLite   DBType = "sqlite"
)

func DetectDBType

func DetectDBType(db *gorm.DB) DBType

DetectDBType 从 GORM Dialector 自动检测数据库类型.

type LintIssue

type LintIssue struct {
	Severity LintSeverity
	Code     string
	Name     string
	Message  string
}

LintIssue 表示一条 lint 结果。

type LintReport

type LintReport struct {
	Issues []LintIssue
}

LintReport 是 migration lint 的完整结果。

Example

ExampleLintReport 展示 lint 结果的计数与判定方法.

package main

import (
	"fmt"

	"github.com/gtkit/migratex/migration"
)

func main() {
	report := migration.LintReport{Issues: []migration.LintIssue{
		{Severity: migration.LintSeverityError, Code: "empty_up", Name: "20260713000100_update_users_table.sql", Message: "Up section has no SQL statements"},
		{Severity: migration.LintSeverityWarning, Code: "missing_no_transaction", Name: "20260713000200_add_email_to_users_table.sql", Message: "file contains DDL but lacks NO TRANSACTION"},
	}}
	fmt.Println(report.ErrorCount(), report.WarningCount(), report.HasErrors(), report.HasWarnings())
}

Output:
1 1 true true

func Lint

func Lint(dir string) (report LintReport, retErr error)

Lint 对迁移目录执行纯静态检查（不连接数据库，可在 CI 中运行）。 检查项：文件命名与版本号合法性、版本号重复、Up/Down 注解完整性、 空 Up（未完成迁移）、不支持的 StatementBegin/End 块、DDL 缺事务标注。 目录不存在视为没有迁移，返回空报告。

Example

ExampleLint 展示如何对迁移目录执行静态检查.

package main

import (
	"fmt"
	"log"
	"os"
	"path/filepath"

	"github.com/gtkit/migratex/migration"
)

func main() {
	dir, err := os.MkdirTemp("", "migratex-lint")
	if err != nil {
		log.Fatal(err)
	}
	defer func() { _ = os.RemoveAll(dir) }()

	content := `-- +goose NO TRANSACTION

-- +goose Up
ALTER TABLE users ADD COLUMN email VARCHAR(128);

-- +goose Down
ALTER TABLE users DROP COLUMN email;
`
	if err := os.WriteFile(filepath.Join(dir, "20260713000100_add_email_to_users_table.sql"), []byte(content), 0o644); err != nil {
		log.Fatal(err)
	}

	report, err := migration.Lint(dir)
	if err != nil {
		log.Fatal(err)
	}
	fmt.Println(len(report.Issues), report.HasErrors())
}

Output:
0 false

func (LintReport) ErrorCount

func (r LintReport) ErrorCount() int

ErrorCount 返回 error 级问题数量。

func (LintReport) HasErrors

func (r LintReport) HasErrors() bool

HasErrors 返回是否存在 error 级问题。

func (LintReport) HasWarnings

func (r LintReport) HasWarnings() bool

HasWarnings 返回是否存在 warning 级问题。

func (LintReport) WarningCount

func (r LintReport) WarningCount() int

WarningCount 返回 warning 级问题数量。

type LintSeverity

type LintSeverity string

LintSeverity 表示 lint 问题级别。

const (
	LintSeverityError   LintSeverity = "error"
	LintSeverityWarning LintSeverity = "warning"
)

type Logger

type Logger interface {
	// Info 记录普通信息.
	Info(msg string, keysAndValues ...any)
	// Warn 记录警告信息.
	Warn(msg string, keysAndValues ...any)
	// Error 记录错误信息.
	Error(msg string, keysAndValues ...any)
}

Logger 迁移日志接口. 默认使用 fmt 输出到 stdout，生产环境可注入 zerolog/zap 等结构化日志实现.

func DefaultLogger

func DefaultLogger() Logger

DefaultLogger 返回默认的 stdout 日志实现.

type NopLogger

type NopLogger struct{}

NopLogger 空日志实现，不输出任何内容. 适用于测试或不需要日志的场景.

func (*NopLogger) Error

func (l *NopLogger) Error(_ string, _ ...any)

func (*NopLogger) Info

func (l *NopLogger) Info(_ string, _ ...any)

func (*NopLogger) Warn

func (l *NopLogger) Warn(_ string, _ ...any)