feat: refactor migration system with improved execution flow (#15)

This PR refactors the migration system to improve code organization and
reliability:

- Consolidates Up/Down operations into a single `execute.go` file
- Refactors runner logic for better maintainability and testability
- Improves error handling and transaction management
- Enhances migration file naming and metadata management
- Adds proper support for respecting migration count limits
- Optimizes database operations and query organization
- Implements proper topological sorting with ascending/descending
options

These changes make the migration system more robust while preserving
backward compatibility.

Author: BolajiOlajide

cmd/kat/command.go

@@ -29,7 +29,7 @@ func addExec(c *cli.Context) error {
 	return migration.Add(c, args[0])
 }
 
-func up(c *cli.Context) error {
+func upExec(c *cli.Context) error {
 	cfg, err := config.GetKatConfigFromCtx(c)
 	if err != nil {
 		return err
@@ -39,14 +39,14 @@ func up(c *cli.Context) error {
 	dryRun := c.Bool("dry-run")
 
 	if dryRun {
-		fmt.Fprintf(os.Stdout, "%sDRY RUN: Migrations will not be applied%s\n", output.StyleInfo, output.StyleReset)
+		fmt.Printf("%sDRY RUN: Migrations will not be applied%s\n", output.StyleInfo, output.StyleReset)
 	}
 
 	// Note: Retry is not used for migrations, only for the ping command
 	return migration.Up(c, cfg, dryRun)
 }
 
-func down(c *cli.Context) error {
+func downExec(c *cli.Context) error {
 	cfg, err := config.GetKatConfigFromCtx(c)
 	if err != nil {
 		return err
@@ -56,7 +56,7 @@ func down(c *cli.Context) error {
 	dryRun := c.Bool("dry-run")
 
 	if dryRun {
-		fmt.Fprintf(os.Stdout, "%sDRY RUN: Migrations will not be rolled back%s\n", output.StyleInfo, output.StyleReset)
+		fmt.Printf("%sDRY RUN: Migrations will not be rolled back%s\n", output.StyleInfo, output.StyleReset)
 	}
 
 	// Note: Retry is not used for migrations, only for the ping command
@@ -68,7 +68,7 @@ func initialize(c *cli.Context) error {
 }
 
 func getVersion(c *cli.Context) error {
-	fmt.Fprintf(os.Stdout, "%sVersion: %s%s\n", output.StyleInfo, version.Version(), output.StyleReset)
+	fmt.Printf("%sVersion: %s%s\n", output.StyleInfo, version.Version(), output.StyleReset)
 	return nil
 }
 

cmd/kat/main.go

@@ -192,26 +192,29 @@ var kat = &cli.App{
 			Name:        "up",
 			Usage:       "Run migrations",
 			Description: "Apply migrations",
-			Action:      up,
+			Action:      upExec,
 			Before:      config.ParseConfig,
-			Flags:       []cli.Flag{configFlag, dryRunFlag},
+			Flags: []cli.Flag{
+				&cli.IntFlag{
+					Name:    "count",
+					Aliases: []string{"n"},
+					Usage:   "number of migrations to apply (default: 0)",
+					Value:   0,
+				}, configFlag, dryRunFlag},
 		},
 		{
 			Name:        "down",
 			Usage:       "Rollback migrations",
 			Description: "Rollback the most recent migration or specify a count with --count flag",
-			Action:      down,
+			Action:      downExec,
 			Before:      config.ParseConfig,
 			Flags: []cli.Flag{
 				&cli.IntFlag{
 					Name:    "count",
 					Aliases: []string{"n"},
 					Usage:   "number of migrations to roll back (default: 1)",
 					Value:   1,
-				},
-				configFlag,
-				dryRunFlag,
-			},
+				}, configFlag, dryRunFlag},
 		},
 		{
 			Name:        "ping",
@@ -237,12 +240,12 @@ var kat = &cli.App{
 
 		errMsg := err.Error()
 		if errMsg != "" {
-			f := fmt.Sprintf("%s%s%s", output.StyleFailure, errMsg, output.StyleReset)
-			fmt.Fprintln(os.Stderr, f)
+			fmt.Fprintln(os.Stderr, fmt.Sprintf("%s%s%s", output.StyleFailure, errMsg, output.StyleReset))
 		}
 
 		// Determine exit code
-		if exitErr, ok := err.(cli.ExitCoder); ok {
+		var exitErr cli.ExitCoder
+		if errors.As(err, &exitErr) {
 			os.Exit(exitErr.ExitCode())
 		}
 		os.Exit(1)

doc/migration.md

@@ -126,17 +126,18 @@ kat up
 When you run `kat up`, the following process occurs:
 
 1. Kat scans your migrations directory for all migration folders
-2. Kat builds a directed acyclic graph (DAG) based on migration dependencies
-3. Kat sorts migrations using topological ordering to respect dependencies
-4. Kat connects to your database using your configuration
-5. If needed, Kat creates a tracking table (specified by `tablename` in your config)
-6. Kat reads the tracking table to determine which migrations have already been applied
-7. For each pending migration:
+2. Kat computes migration definitions, converting files into executable SQL queries
+3. Kat builds a directed acyclic graph (DAG) based on migration dependencies
+4. Kat sorts migrations using topological ordering to respect dependencies
+5. Kat connects to your database using your configuration
+6. If needed, Kat creates a tracking table (specified by `tablename` in your config)
+7. Kat reads the tracking table to determine which migrations have already been applied
+8. For each pending migration:
    - Kat begins a transaction
-   - Kat executes the SQL in the up.sql file
+   - Kat executes the SQL queries from the migration Definition
    - Kat records the migration in the tracking table
    - Kat commits the transaction
-8. Kat provides a summary of the applied migrations
+9. Kat provides a summary of the applied migrations
 
 ### Up Command Options
 
@@ -180,14 +181,15 @@ kat down
 
 When you run `kat down`, the following process occurs:
 
-1. Kat connects to your database using your configuration
-2. Kat reads the tracking table to identify applied migrations
-3. By default, Kat selects the most recent migration for rollback
-4. Kat begins a transaction
-5. Kat executes the SQL in the down.sql file
-6. Kat removes the migration record from the tracking table
-7. Kat commits the transaction
-8. Kat provides a summary of the rolled back migrations
+1. Kat scans your migrations directory and computes migration definitions
+2. Kat connects to your database using your configuration
+3. Kat reads the tracking table to identify applied migrations
+4. By default, Kat selects the most recent migration for rollback
+5. Kat begins a transaction
+6. Kat executes the SQL queries from the migration Definition's DownQuery
+7. Kat removes the migration record from the tracking table
+8. Kat commits the transaction
+9. Kat provides a summary of the rolled back migrations
 
 ### Down Command Options
 

internal/graph/graph.go

@@ -31,7 +31,7 @@ type Graph struct {
 }
 
 func (g *Graph) AddDefinition(def types.Definition) error {
-	if err := g.graph.AddVertex(def); err != nil {
+	if err := g.graph.AddVertex(def, graphlib.VertexAttribute("name", def.FileName())); err != nil {
 		return errors.Wrap(err, "error adding vertex")
 	}
 
@@ -80,9 +80,16 @@ func (g *Graph) GetDefinition(timestamp int64) (types.Definition, error) {
 	return g.graph.Vertex(timestamp)
 }
 
+// TopologicalSort returns a valid topological ordering of all the vertices in the graph.
+// It uses StableTopologicalSort from the graph library to ensure that elements with
+// valid topological ordering are consistently returned in order of their timestamps (i < j),
+// making the results deterministic and predictable.
 func (g *Graph) TopologicalSort() ([]int64, error) {
-	return graphlib.TopologicalSort(g.graph)
+	return graphlib.StableTopologicalSort(g.graph, func(i, j int64) bool {
+		return i < j
+	})
 }
+
 func (g *Graph) Order() (int, error) {
 	return g.graph.Order()
 }

internal/migration/add.go

@@ -33,7 +33,7 @@ func Add(c *cli.Context, name string) error {
 	)
 	migrationDirName := fmt.Sprintf("%d_%s", timestamp, sanitizedName)
 
-	m := types.Migration{
+	m := types.TemporaryMigrationInfo{
 		Up:        filepath.Join(cfg.Migration.Directory, migrationDirName, "up.sql"),
 		Down:      filepath.Join(cfg.Migration.Directory, migrationDirName, "down.sql"),
 		Metadata:  filepath.Join(cfg.Migration.Directory, migrationDirName, "metadata.yaml"),