Naming, layout and comments: descriptive full-word names, one item per line in wrapped calls and literals, and doc comments on exported names

Short and single-letter names in application code become full words (tests
keep theirs). Wrapped calls, signatures and composite literals put one item
per line, and one-line function bodies are expanded. Exported names and
groups of constants get doc comments, and comments refer to the renamed
identifiers.

internal/store/migrate.go

@@ -46,8 +46,8 @@ func NewMigrator(db *sql.DB) (*goose.Provider, error) {
 }
 
 // LatestVersion is the highest migration version in this build.
-func LatestVersion(p *goose.Provider) int64 {
-	sources := p.ListSources() // sorted ascending
+func LatestVersion(provider *goose.Provider) int64 {
+	sources := provider.ListSources() // sorted ascending
 	if len(sources) == 0 {
 		return 0
 	}
@@ -56,26 +56,34 @@ func LatestVersion(p *goose.Provider) int64 {
 
 // checkVersion returns ErrNeedsMigration or ErrSchemaTooNew unless the
 // database is exactly at this build's schema.
-func checkVersion(ctx context.Context, p *goose.Provider) error {
-	current, err := p.GetDBVersion(ctx)
+func checkVersion(ctx context.Context, provider *goose.Provider) error {
+	current, err := provider.GetDBVersion(ctx)
 	if err != nil {
 		return err
 	}
 
-	latest := LatestVersion(p)
+	latest := LatestVersion(provider)
 	if current > latest {
-		return fmt.Errorf("%w (database is at version %d, this build knows up to %d)",
-			ErrSchemaTooNew, current, latest)
+		return fmt.Errorf(
+			"%w (database is at version %d, this build knows up to %d)",
+			ErrSchemaTooNew,
+			current,
+			latest,
+		)
 	}
 
-	pending, err := p.HasPending(ctx)
+	pending, err := provider.HasPending(ctx)
 	if err != nil {
 		return err
 	}
 
 	if pending {
-		return fmt.Errorf("%w (database is at version %d, latest is %d)",
-			ErrNeedsMigration, current, latest)
+		return fmt.Errorf(
+			"%w (database is at version %d, latest is %d)",
+			ErrNeedsMigration,
+			current,
+			latest,
+		)
 	}
 
 	return nil
@@ -83,53 +91,55 @@ func checkVersion(ctx context.Context, p *goose.Provider) error {
 
 // checkNotNewer refuses to work on a database migrated by a newer build:
 // this build has neither the newer migrations nor their down steps.
-func checkNotNewer(ctx context.Context, m *goose.Provider) error {
-	current, err := m.GetDBVersion(ctx)
+func checkNotNewer(ctx context.Context, provider *goose.Provider) error {
+	current, err := provider.GetDBVersion(ctx)
 	if err != nil {
 		return err
 	}
-	if latest := LatestVersion(m); current > latest {
+	if latest := LatestVersion(provider); current > latest {
 		return fmt.Errorf(
 			"database is at version %d but this build only knows up to %d; use a newer build",
-			current, latest)
+			current,
+			latest,
+		)
 	}
 	return nil
 }
 
 // prepareSchema migrates (with WithAutoMigrate) or verifies the schema
 // version.
-func prepareSchema(ctx context.Context, db *sql.DB, o options) error {
-	p, err := NewMigrator(db)
+func prepareSchema(ctx context.Context, db *sql.DB, opts options) error {
+	provider, err := NewMigrator(db)
 	if err != nil {
 		return err
 	}
 
-	if o.autoMigrate {
-		if _, err := p.Up(ctx); err != nil {
+	if opts.autoMigrate {
+		if _, err := provider.Up(ctx); err != nil {
 			return fmt.Errorf("store: migrating database: %w", err)
 		}
 	}
 
-	return checkVersion(ctx, p)
+	return checkVersion(ctx, provider)
 }
 
 // StepUp applies steps pending migrations, or all of them when steps is 0.
 func StepUp(
-	ctx context.Context, m *goose.Provider, steps int,
+	ctx context.Context, provider *goose.Provider, steps int,
 ) ([]*goose.MigrationResult, error) {
 	var results []*goose.MigrationResult
 
-	if err := checkNotNewer(ctx, m); err != nil {
+	if err := checkNotNewer(ctx, provider); err != nil {
 		return results, err
 	}
 
 	var err error
 	if steps == 0 {
-		results, err = m.Up(ctx)
+		results, err = provider.Up(ctx)
 	} else {
 		for range steps {
-			var r *goose.MigrationResult
-			r, err = m.UpByOne(ctx)
+			var result *goose.MigrationResult
+			result, err = provider.UpByOne(ctx)
 			if errors.Is(err, goose.ErrNoNextVersion) {
 				err = nil
 				break
@@ -137,7 +147,7 @@ func StepUp(
 			if err != nil {
 				break
 			}
-			results = append(results, r)
+			results = append(results, result)
 		}
 	}
 
@@ -148,15 +158,15 @@ func StepUp(
 // is 0. Rolling everything back deletes all data, so confirmDrop is checked
 // first in that case.
 func StepDown(
-	ctx context.Context, m *goose.Provider, steps int, confirmDrop bool,
+	ctx context.Context, provider *goose.Provider, steps int, confirmDrop bool,
 ) ([]*goose.MigrationResult, error) {
 	var results []*goose.MigrationResult
 
-	if err := checkNotNewer(ctx, m); err != nil {
+	if err := checkNotNewer(ctx, provider); err != nil {
 		return results, err
 	}
 
-	current, err := m.GetDBVersion(ctx)
+	current, err := provider.GetDBVersion(ctx)
 	if err != nil {
 		return results, err
 	}
@@ -164,13 +174,13 @@ func StepDown(
 		return results, nil
 	}
 
-	statuses, err := m.Status(ctx)
+	statuses, err := provider.Status(ctx)
 	if err != nil {
 		return results, err
 	}
 	applied := 0
-	for _, s := range statuses {
-		if s.State == goose.StateApplied {
+	for _, status := range statuses {
+		if status.State == goose.StateApplied {
 			applied++
 		}
 	}
@@ -180,11 +190,11 @@ func StepDown(
 	}
 
 	if all {
-		results, err = m.DownTo(ctx, 0)
+		results, err = provider.DownTo(ctx, 0)
 	} else {
 		for range steps {
-			var r *goose.MigrationResult
-			r, err = m.Down(ctx)
+			var result *goose.MigrationResult
+			result, err = provider.Down(ctx)
 			if errors.Is(err, goose.ErrNoNextVersion) {
 				err = nil
 				break
@@ -192,7 +202,7 @@ func StepDown(
 			if err != nil {
 				break
 			}
-			results = append(results, r)
+			results = append(results, result)
 		}
 	}