migrate

type AppliedMigration struct {
	ID         int64
	Version    string
	Name       string
	Group      string
	MigratedAt string // ISO 8601 timestamp
}

type Executor interface {
	// Exec executes a SQL statement that does not return rows.
	Exec(ctx context.Context, query string, args ...any) (driver.Result, error)

	// Query executes a SQL statement that returns rows.
	Query(ctx context.Context, query string, args ...any) (driver.Rows, error)

	// EnsureMigrationTable creates the migration tracking table if it doesn't exist.
	EnsureMigrationTable(ctx context.Context) error

	// EnsureLockTable creates the migration lock table if it doesn't exist.
	EnsureLockTable(ctx context.Context) error

	// AcquireLock attempts to acquire the distributed migration lock.
	// Returns an error if the lock is held by another process.
	AcquireLock(ctx context.Context, lockedBy string) error

	// ReleaseLock releases the distributed migration lock.
	ReleaseLock(ctx context.Context) error

	// ListApplied returns all migrations that have been applied.
	ListApplied(ctx context.Context) ([]*AppliedMigration, error)

	// RecordApplied records that a migration was successfully applied.
	RecordApplied(ctx context.Context, m *Migration) error

	// RemoveApplied removes the record of an applied migration (for rollback).
	RemoveApplied(ctx context.Context, m *Migration) error
}

type ExecutorFactory func(drv any) Executor

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

type GroupOption func(*Group)

type GroupStatus struct {
	Name    string
	Applied []*MigrationStatus
	Pending []*MigrationStatus
}

type LockInfo struct {
	Held     bool
	LockedBy string
	LockedAt string
}

type LockInspector interface {
	LockInfo(ctx context.Context) (*LockInfo, error)
}

type MigrateFunc func(ctx context.Context, exec Executor) error //nolint:revive // MigrateFunc is the established public API name

type MigrateResult struct {
	Applied  []*Migration // Migrations that were applied
	Rollback []*Migration // Migrations that were rolled back (for Rollback only)
}

type Migration struct {
	// Name is a human-readable identifier (e.g., "create_users").
	Name string

	// Version is a timestamp-based version string (e.g., "20240115120000").
	// Migrations run in version order within dependency constraints.
	Version string

	// Group identifies the module/extension that owns this migration.
	// Set automatically when registered with a Group.
	Group string

	// Up runs the forward migration.
	Up MigrateFunc

	// Down runs the rollback.
	Down MigrateFunc

	// Comment is an optional description.
	Comment string
}

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

type MigrationStatus struct {
	Migration *Migration
	Applied   bool
	AppliedAt string // empty if not applied
}

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