fix: add mysqlbinlog_path DSN param and LOAD_FILE fallback for remote binlogs

- Allow users to specify mysqlbinlog path via DSN parameter
  (e.g. ?mysqlbinlog_path=C:\mysql\bin\mysqlbinlog.exe)
- Add DownloadBinlogFiles method to MySQLConnector that downloads
  binlog files via LOAD_FILE when mysqlbinlog is not available
- Cascade: explicit path → PATH → basedir → LOAD_FILE download
- All remote binlog reading works without mysqlbinlog installed

Author: Developer

internal/config/config.go

@@ -182,12 +182,17 @@ func ParseDSNToConnConfig(dsn string) (connector.ConnConfig, error) {
 		params["tls"] = cfg.TLSConfig
 	}
 
+	// Extract custom mysqlbinlog_path param before passing to the connector.
+	mysqlbinlogPath := params["mysqlbinlog_path"]
+	delete(params, "mysqlbinlog_path")
+
 	return connector.ConnConfig{
-		Host:     host,
-		Port:     port,
-		User:     cfg.User,
-		Password: cfg.Passwd,
-		Database: cfg.DBName,
-		Params:   params,
+		Host:            host,
+		Port:            port,
+		User:            cfg.User,
+		Password:        cfg.Passwd,
+		Database:        cfg.DBName,
+		Params:          params,
+		MySQLBinlogPath: mysqlbinlogPath,
 	}, nil
 }

internal/connector/mysql.go

@@ -4,6 +4,7 @@ import (
 	"context"
 	"database/sql"
 	"fmt"
+	"os"
 	"path/filepath"
 	"strings"
 	"time"
@@ -187,6 +188,8 @@ func (m *MySQLConnector) GetBinlogDir(ctx context.Context) (string, error) {
 // GetBasedir
 // ---------------------------------------------------------------------------
 
+// GetBasedir returns the MySQL installation base directory by querying
+// SHOW VARIABLES LIKE 'basedir'.
 func (m *MySQLConnector) GetBasedir(ctx context.Context) (string, error) {
 	if m.db == nil {
 		return "", fmt.Errorf("connector: not connected")
@@ -200,6 +203,113 @@ func (m *MySQLConnector) GetBasedir(ctx context.Context) (string, error) {
 	}
 	return basedir, nil
 }
+
+// ---------------------------------------------------------------------------
+// DownloadBinlogFiles
+// ---------------------------------------------------------------------------
+
+// DownloadBinlogFiles reads binlog files from the MySQL server via LOAD_FILE()
+// and writes them to a local temporary directory. Returns the local file paths.
+// This is used as a fallback when mysqlbinlog is not available and binlog files
+// are not accessible on the local filesystem.
+//
+// Conditions for success:
+//   - The MySQL user must have the FILE privilege.
+//   - The MySQL server variable secure_file_priv must be empty ("") or include
+//     the binlog directory so LOAD_FILE() can read the files.
+//   - Binlog files must be world-readable on the MySQL server.
+func (m *MySQLConnector) DownloadBinlogFiles(ctx context.Context, binlogDir string, binlogNames []string) ([]string, error) {
+	if m.db == nil {
+		return nil, fmt.Errorf("connector: not connected")
+	}
+	if len(binlogNames) == 0 {
+		return nil, fmt.Errorf("connector: no binlog files specified")
+	}
+
+	// Check secure_file_priv.
+	var sfpName, secureFilePriv string
+	if err := m.db.QueryRowContext(ctx, "SHOW VARIABLES LIKE 'secure_file_priv'").Scan(&sfpName, &secureFilePriv); err != nil {
+		return nil, fmt.Errorf("connector: query secure_file_priv: %w", err)
+	}
+	if secureFilePriv != "" && !strings.HasPrefix(binlogDir, secureFilePriv) {
+		return nil, fmt.Errorf(
+			"MySQL secure_file_priv (%s) restricts LOAD_FILE() to that directory; "+
+				"binlog files are in %s. To fix, either: (1) add --secure-file-priv= \"\" "+
+				"to the MySQL startup command, or (2) install mysql-client and specify "+
+				"mysqlbinlog_path in the DSN (e.g. ?mysqlbinlog_path=C:\\mysql\\bin\\mysqlbinlog.exe)",
+			secureFilePriv, binlogDir)
+	}
+
+	tmpDir, err := os.MkdirTemp("", "pitr-binlog-*")
+	if err != nil {
+		return nil, fmt.Errorf("connector: create temp dir: %w", err)
+	}
+
+	var localPaths []string
+	for _, name := range binlogNames {
+		fullPath := filepath.Join(binlogDir, name)
+
+		// Load the file into a session variable. This avoids re-reading the file
+		// from disk for each chunk.
+		_, err := m.db.ExecContext(ctx, "SET @_pitr_binlog = LOAD_FILE(?)", fullPath)
+		if err != nil {
+			// Cleanup on failure.
+			os.RemoveAll(tmpDir)
+			return nil, fmt.Errorf("connector: LOAD_FILE(%s) failed: %w (check FILE privilege)", fullPath, err)
+		}
+
+		// Check whether LOAD_FILE returned NULL (file not found, no privilege, or
+		// secure_file_priv restriction).
+		var isNull bool
+		if err := m.db.QueryRowContext(ctx, "SELECT @_pitr_binlog IS NULL").Scan(&isNull); err != nil {
+			os.RemoveAll(tmpDir)
+			return nil, fmt.Errorf("connector: verify LOAD_FILE(%s): %w", fullPath, err)
+		}
+		if isNull {
+			os.RemoveAll(tmpDir)
+			return nil, fmt.Errorf(
+				"connector: LOAD_FILE(%s) returned NULL; the file may not exist, "+
+					"is not world-readable, or the MySQL user lacks the FILE privilege", fullPath)
+		}
+
+		// Get file size.
+		var size int64
+		if err := m.db.QueryRowContext(ctx, "SELECT LENGTH(@_pitr_binlog)").Scan(&size); err != nil {
+			os.RemoveAll(tmpDir)
+			return nil, fmt.Errorf("connector: get size of %s: %w", fullPath, err)
+		}
+
+		// Read chunks and write to local file.
+		localPath := filepath.Join(tmpDir, name)
+		f, err := os.Create(localPath)
+		if err != nil {
+			os.RemoveAll(tmpDir)
+			return nil, fmt.Errorf("connector: create local file %s: %w", localPath, err)
+		}
+
+		const chunkSize = 64 * 1024 * 1024 // 64 MB per chunk
+		for pos := int64(1); pos <= size; pos += chunkSize {
+			var chunk []byte
+			err := m.db.QueryRowContext(ctx, "SELECT SUBSTRING(@_pitr_binlog, ?, ?)", pos, chunkSize).Scan(&chunk)
+			if err != nil {
+				f.Close()
+				os.RemoveAll(tmpDir)
+				return nil, fmt.Errorf("connector: read chunk at pos %d of %s: %w", pos, fullPath, err)
+			}
+			if _, err := f.Write(chunk); err != nil {
+				f.Close()
+				os.RemoveAll(tmpDir)
+				return nil, fmt.Errorf("connector: write chunk of %s: %w", localPath, err)
+			}
+		}
+		f.Close()
+
+		localPaths = append(localPaths, localPath)
+	}
+
+	return localPaths, nil
+}
+
 // ---------------------------------------------------------------------------
 // ParseBinlog verifies that the requested binlog files exist and returns any
 // parse errors. Actual event-level parsing is delegated to the parser package

internal/connector/types.go

@@ -11,6 +11,10 @@ type ConnConfig struct {
 	Database string
 	// Params holds additional DSN parameters (e.g., TLS config, timeouts).
 	Params map[string]string
+	// MySQLBinlogPath is an optional explicit path to the mysqlbinlog binary.
+	// If empty, the system auto-discovers it from PATH, MySQL basedir, and
+	// common installation paths.
+	MySQLBinlogPath string
 }
 
 // DSN returns the MySQL Data Source Name string derived from the config.

internal/server/pitr/handler.go

@@ -497,22 +497,35 @@ func (h *Handler) Progress(w http.ResponseWriter, r *http.Request) {
 	})
 }
 
-// findMySQLBinlog locates the mysqlbinlog binary by checking PATH first, then
-// querying MySQL's basedir, and finally checking common installation paths.
-func findMySQLBinlog(ctx context.Context, conn *connector.MySQLConnector) (string, error) {
+// findMySQLBinlog locates the mysqlbinlog binary. If mysqlbinlogPath is
+// non-empty it is validated and returned directly. Otherwise the function
+// checks PATH, queries MySQL basedir (if conn is non-nil), and finally
+// common installation paths.
+func findMySQLBinlog(mysqlbinlogPath string, ctx context.Context, conn *connector.MySQLConnector) (string, error) {
+	// 0. Explicit path from config.
+	if mysqlbinlogPath != "" {
+		if fi, err := os.Stat(mysqlbinlogPath); err == nil && fi.Mode().IsRegular() {
+			abs, _ := filepath.Abs(mysqlbinlogPath)
+			return abs, nil
+		}
+		return "", fmt.Errorf("specified mysqlbinlog path %q does not exist", mysqlbinlogPath)
+	}
+
 	// 1. Try PATH first.
 	if path, err := exec.LookPath("mysqlbinlog"); err == nil {
 		return path, nil
 	}
 
 	// 2. Try MySQL basedir (SHOW VARIABLES LIKE 'basedir').
-	basedir, err := conn.GetBasedir(ctx)
-	if err == nil && basedir != "" {
-		for _, name := range []string{"mysqlbinlog", "mysqlbinlog.exe"} {
-			candidate := filepath.Join(basedir, "bin", name)
-			if fi, statErr := os.Stat(candidate); statErr == nil && fi.Mode().IsRegular() {
-				abs, _ := filepath.Abs(candidate)
-				return abs, nil
+	if conn != nil {
+		basedir, err := conn.GetBasedir(ctx)
+		if err == nil && basedir != "" {
+			for _, name := range []string{"mysqlbinlog", "mysqlbinlog.exe"} {
+				candidate := filepath.Join(basedir, "bin", name)
+				if fi, statErr := os.Stat(candidate); statErr == nil && fi.Mode().IsRegular() {
+					abs, _ := filepath.Abs(candidate)
+					return abs, nil
+				}
 			}
 		}
 	}
@@ -533,7 +546,7 @@ func findMySQLBinlog(ctx context.Context, conn *connector.MySQLConnector) (strin
 		}
 	}
 
-	return "", fmt.Errorf("mysqlbinlog not found in $PATH, MySQL basedir, or common installation paths; install mysql-client or add mysqlbinlog to your PATH")
+	return "", fmt.Errorf("mysqlbinlog not found; install mysql-client or specify the path via DSN parameter mysqlbinlog_path (e.g. ?mysqlbinlog_path=C:\\mysql\\bin\\mysqlbinlog.exe)")
 }
 
 // parseBinlogRemote uses mysqlbinlog --read-from-remote-server to parse binlog
@@ -792,20 +805,32 @@ func (h *Handler) runOperation(op *Operation, operator string) {
 	}
 
 	var parseRes *connector.ParseResult
+	var downloadCleanup string // temp dir to clean up if LOAD_FILE was used
 
-	// Check if binlog files are accessible locally; if not, try mysqlbinlog remote.
+	// Check if binlog files are accessible locally; if not, try alternatives.
 	if len(paths) > 0 {
 		if _, statErr := os.Stat(paths[0]); os.IsNotExist(statErr) {
-			log.Printf("pitr: binlog files not accessible locally, trying mysqlbinlog remote for op %s", op.ID)
-			mysqlbinlogPath, findErr := findMySQLBinlog(ctx, conn)
-			if findErr != nil {
-				h.failOperation(op, "parse binlogs (remote): %v", findErr)
-				return
-			}
-			parseRes, err = h.parseBinlogRemote(mysqlbinlogPath, connCfg, binlogNames, op.TargetTable, op.RecoveryTime)
-			if err != nil {
-				h.failOperation(op, "parse binlogs (remote): %v", err)
-				return
+			// Binlog files are not on the local filesystem.
+			// Try mysqlbinlog --read-from-remote-server first.
+			mysqlbinlogPath, findErr := findMySQLBinlog(connCfg.MySQLBinlogPath, ctx, conn)
+			if findErr == nil {
+				log.Printf("pitr: trying mysqlbinlog remote for op %s", op.ID)
+				parseRes, err = h.parseBinlogRemote(mysqlbinlogPath, connCfg, binlogNames, op.TargetTable, op.RecoveryTime)
+				if err != nil {
+					h.failOperation(op, "parse binlogs (remote): %v", err)
+					return
+				}
+			} else {
+				// mysqlbinlog not available. Try downloading binlog files via
+				// MySQL LOAD_FILE() and parsing them with the Go-native parser.
+				log.Printf("pitr: mysqlbinlog not found (%v), trying LOAD_FILE download for op %s", findErr, op.ID)
+				downloaded, dlErr := conn.DownloadBinlogFiles(ctx, binlogDir, binlogNames)
+				if dlErr != nil {
+					h.failOperation(op, "cannot parse binlogs: mysqlbinlog not found and LOAD_FILE download failed: %v", dlErr)
+					return
+				}
+				downloadCleanup = filepath.Dir(downloaded[0])
+				paths = downloaded
 			}
 		}
 	}
@@ -824,6 +849,11 @@ func (h *Handler) runOperation(op *Operation, operator string) {
 		}
 	}
 
+	// Clean up downloaded binlog files.
+	if downloadCleanup != "" {
+		os.RemoveAll(downloadCleanup)
+	}
+
 	reverseSqls, err := parser.ReverseSQLBatch(parseRes.Events, nil)
 	if err != nil {
 		h.failOperation(op, "generate reverse SQL: %v", err)