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/readers/sqldir/README.md

@@ -93,6 +93,7 @@ fmt.Printf("Found %d scripts\n", len(schema.Scripts))
 ## Features
 
 - **Recursive Directory Scanning**: Automatically scans all subdirectories
+- **Symlink Skipping**: Symbolic links are automatically skipped (prevents loops and duplicates)
 - **Multiple Extensions**: Supports both `.sql` and `.pgsql` files
 - **Flexible Naming**: Extract metadata from filename patterns
 - **Error Handling**: Validates directory existence and file accessibility
@@ -153,8 +154,9 @@ go test ./pkg/readers/sqldir/
 ```
 
 Tests include:
-- Valid file parsing
+- Valid file parsing (underscore and hyphen formats)
 - Recursive directory scanning
+- Symlink skipping
 - Invalid filename handling
 - Empty directory handling
 - Error conditions

pkg/readers/sqldir/reader.go

@@ -107,11 +107,20 @@ func (r *Reader) readScripts() ([]*models.Script, error) {
 			return err
 		}
 
-		// Skip directories
+		// Don't process directories as files (WalkDir still descends into them recursively)
 		if d.IsDir() {
 			return nil
 		}
 
+		// Skip symlinks
+		info, err := d.Info()
+		if err != nil {
+			return err
+		}
+		if info.Mode()&os.ModeSymlink != 0 {
+			return nil
+		}
+
 		// Get filename
 		filename := d.Name()
 

pkg/readers/sqldir/reader_test.go

@@ -373,3 +373,65 @@ func TestReader_MixedFormat(t *testing.T) {
 		}
 	}
 }
+
+func TestReader_SkipSymlinks(t *testing.T) {
+	// Create temporary test directory
+	tempDir, err := os.MkdirTemp("", "sqldir-test-symlink-*")
+	if err != nil {
+		t.Fatalf("Failed to create temp directory: %v", err)
+	}
+	defer os.RemoveAll(tempDir)
+
+	// Create a real SQL file
+	realFile := filepath.Join(tempDir, "1_001_real_file.sql")
+	if err := os.WriteFile(realFile, []byte("SELECT 1;"), 0644); err != nil {
+		t.Fatalf("Failed to create real file: %v", err)
+	}
+
+	// Create another file to link to
+	targetFile := filepath.Join(tempDir, "2_001_target.sql")
+	if err := os.WriteFile(targetFile, []byte("SELECT 2;"), 0644); err != nil {
+		t.Fatalf("Failed to create target file: %v", err)
+	}
+
+	// Create a symlink to the target file (this should be skipped)
+	symlinkFile := filepath.Join(tempDir, "3_001_symlink.sql")
+	if err := os.Symlink(targetFile, symlinkFile); err != nil {
+		// Skip test on systems that don't support symlinks (e.g., Windows without admin)
+		t.Skipf("Symlink creation not supported: %v", err)
+	}
+
+	// Create reader
+	reader := NewReader(&readers.ReaderOptions{
+		FilePath: tempDir,
+	})
+
+	// Read database
+	db, err := reader.ReadDatabase()
+	if err != nil {
+		t.Fatalf("ReadDatabase failed: %v", err)
+	}
+
+	schema := db.Schemas[0]
+
+	// Should only have 2 scripts (real_file and target), symlink should be skipped
+	if len(schema.Scripts) != 2 {
+		t.Errorf("Expected 2 scripts (symlink should be skipped), got %d", len(schema.Scripts))
+	}
+
+	// Verify the scripts are the real files, not the symlink
+	scriptNames := make(map[string]bool)
+	for _, script := range schema.Scripts {
+		scriptNames[script.Name] = true
+	}
+
+	if !scriptNames["real_file"] {
+		t.Error("Expected 'real_file' script to be present")
+	}
+	if !scriptNames["target"] {
+		t.Error("Expected 'target' script to be present")
+	}
+	if scriptNames["symlink"] {
+		t.Error("Symlink script should have been skipped but was found")
+	}
+}