feat(writer): 🎉 Enhance script execution order and add symlink skipping

* Update script execution to sort by Priority, Sequence, and Name.
* Add functionality to skip symbolic links during directory scanning.
* Improve documentation to reflect changes in execution order and features.
* Add tests for symlink skipping and ensure correct script sorting.

pkg/writers/sqlexec/README.md

@@ -4,7 +4,7 @@ The SQL Executor Writer (`sqlexec`) executes SQL scripts from `models.Script` ob
 
 ## Features
 
-- **Ordered Execution**: Scripts execute in Priority→Sequence order
+- **Ordered Execution**: Scripts execute in Priority→Sequence→Name order
 - **PostgreSQL Support**: Uses `pgx/v5` driver for robust PostgreSQL connectivity
 - **Stop on Error**: Execution halts immediately on first error (default behavior)
 - **Progress Reporting**: Prints execution status to stdout
@@ -103,19 +103,40 @@ Scripts are sorted and executed based on:
 
 1. **Priority** (ascending): Lower priority values execute first
 2. **Sequence** (ascending): Within same priority, lower sequence values execute first
+3. **Name** (ascending): Within same priority and sequence, alphabetical order by name
 
 ### Example Execution Order
 
 Given these scripts:
 ```
-Script A: Priority=2, Sequence=1
-Script B: Priority=1, Sequence=3
-Script C: Priority=1, Sequence=1
-Script D: Priority=1, Sequence=2
-Script E: Priority=3, Sequence=1
+Script A: Priority=2, Sequence=1, Name="zebra"
+Script B: Priority=1, Sequence=3, Name="script"
+Script C: Priority=1, Sequence=1, Name="apple"
+Script D: Priority=1, Sequence=1, Name="beta"
+Script E: Priority=3, Sequence=1, Name="script"
 ```
 
-Execution order: **C → D → B → A → E**
+Execution order: **C (apple) → D (beta) → B → A → E**
+
+### Directory-based Sorting Example
+
+Given these files:
+```
+1_001_create_schema.sql
+1_001_create_users.sql      ← Alphabetically before "drop_tables"
+1_001_drop_tables.sql
+1_002_add_indexes.sql
+2_001_constraints.sql
+```
+
+Execution order (note alphabetical sorting at same priority/sequence):
+```
+1_001_create_schema.sql
+1_001_create_users.sql
+1_001_drop_tables.sql
+1_002_add_indexes.sql
+2_001_constraints.sql
+```
 
 ## Output
 

pkg/writers/sqlexec/writer.go

@@ -86,20 +86,23 @@ func (w *Writer) WriteTable(table *models.Table) error {
 	return fmt.Errorf("WriteTable is not supported for SQL script execution")
 }
 
-// executeScripts executes scripts in Priority then Sequence order
+// executeScripts executes scripts in Priority, Sequence, then Name order
 func (w *Writer) executeScripts(ctx context.Context, conn *pgx.Conn, scripts []*models.Script) error {
 	if len(scripts) == 0 {
 		return nil
 	}
 
-	// Sort scripts by Priority (ascending) then Sequence (ascending)
+	// Sort scripts by Priority (ascending), Sequence (ascending), then Name (ascending)
 	sortedScripts := make([]*models.Script, len(scripts))
 	copy(sortedScripts, scripts)
 	sort.Slice(sortedScripts, func(i, j int) bool {
 		if sortedScripts[i].Priority != sortedScripts[j].Priority {
 			return sortedScripts[i].Priority < sortedScripts[j].Priority
 		}
-		return sortedScripts[i].Sequence < sortedScripts[j].Sequence
+		if sortedScripts[i].Sequence != sortedScripts[j].Sequence {
+			return sortedScripts[i].Sequence < sortedScripts[j].Sequence
+		}
+		return sortedScripts[i].Name < sortedScripts[j].Name
 	})
 
 	// Execute each script in order

pkg/writers/sqlexec/writer_test.go

@@ -99,13 +99,13 @@ func TestWriter_WriteTable(t *testing.T) {
 	}
 }
 
-// TestScriptSorting verifies that scripts are sorted correctly by Priority then Sequence
+// TestScriptSorting verifies that scripts are sorted correctly by Priority, Sequence, then Name
 func TestScriptSorting(t *testing.T) {
 	scripts := []*models.Script{
-		{Name: "script1", Priority: 2, Sequence: 1, SQL: "SELECT 1;"},
+		{Name: "z_script1", Priority: 2, Sequence: 1, SQL: "SELECT 1;"},
 		{Name: "script2", Priority: 1, Sequence: 3, SQL: "SELECT 2;"},
-		{Name: "script3", Priority: 1, Sequence: 1, SQL: "SELECT 3;"},
-		{Name: "script4", Priority: 1, Sequence: 2, SQL: "SELECT 4;"},
+		{Name: "a_script3", Priority: 1, Sequence: 1, SQL: "SELECT 3;"},
+		{Name: "b_script4", Priority: 1, Sequence: 1, SQL: "SELECT 4;"},
 		{Name: "script5", Priority: 3, Sequence: 1, SQL: "SELECT 5;"},
 		{Name: "script6", Priority: 2, Sequence: 2, SQL: "SELECT 6;"},
 	}
@@ -114,25 +114,35 @@ func TestScriptSorting(t *testing.T) {
 	sortedScripts := make([]*models.Script, len(scripts))
 	copy(sortedScripts, scripts)
 
-	// Use the same sorting logic from executeScripts
+	// Sort by Priority, Sequence, then Name (matching executeScripts logic)
 	for i := 0; i < len(sortedScripts)-1; i++ {
 		for j := i + 1; j < len(sortedScripts); j++ {
-			if sortedScripts[i].Priority > sortedScripts[j].Priority ||
-				(sortedScripts[i].Priority == sortedScripts[j].Priority &&
-					sortedScripts[i].Sequence > sortedScripts[j].Sequence) {
+			si, sj := sortedScripts[i], sortedScripts[j]
+			// Compare by priority first
+			if si.Priority > sj.Priority {
 				sortedScripts[i], sortedScripts[j] = sortedScripts[j], sortedScripts[i]
+			} else if si.Priority == sj.Priority {
+				// If same priority, compare by sequence
+				if si.Sequence > sj.Sequence {
+					sortedScripts[i], sortedScripts[j] = sortedScripts[j], sortedScripts[i]
+				} else if si.Sequence == sj.Sequence {
+					// If same sequence, compare by name
+					if si.Name > sj.Name {
+						sortedScripts[i], sortedScripts[j] = sortedScripts[j], sortedScripts[i]
+					}
+				}
 			}
 		}
 	}
 
-	// Expected order after sorting
+	// Expected order after sorting (Priority -> Sequence -> Name)
 	expectedOrder := []string{
-		"script3", // Priority 1, Sequence 1
-		"script4", // Priority 1, Sequence 2
-		"script2", // Priority 1, Sequence 3
-		"script1", // Priority 2, Sequence 1
-		"script6", // Priority 2, Sequence 2
-		"script5", // Priority 3, Sequence 1
+		"a_script3", // Priority 1, Sequence 1, Name a_script3
+		"b_script4", // Priority 1, Sequence 1, Name b_script4
+		"script2",   // Priority 1, Sequence 3
+		"z_script1", // Priority 2, Sequence 1
+		"script6",   // Priority 2, Sequence 2
+		"script5",   // Priority 3, Sequence 1
 	}
 
 	for i, expected := range expectedOrder {
@@ -153,6 +163,13 @@ func TestScriptSorting(t *testing.T) {
 			t.Errorf("Sequence not ascending at position %d with same priority %d: %d > %d",
 				i, sortedScripts[i].Priority, sortedScripts[i].Sequence, sortedScripts[i+1].Sequence)
 		}
+		// Within same priority and sequence, names should be ascending
+		if sortedScripts[i].Priority == sortedScripts[i+1].Priority &&
+			sortedScripts[i].Sequence == sortedScripts[i+1].Sequence &&
+			sortedScripts[i].Name > sortedScripts[i+1].Name {
+			t.Errorf("Name not ascending at position %d with same priority/sequence: %s > %s",
+				i, sortedScripts[i].Name, sortedScripts[i+1].Name)
+		}
 	}
 }