feat(execmode): allow runtime configuration

- introduce `SetExecMode` function to programmatically control execution mode
- make `GODBC_EXEC_MODE` environment variable dynamic, read on every call
- ensure `SetExecMode` takes precedence over the environment variable
- update documentation to reflect new configuration options
- add tests for dynamic and overridden execution modes

Author: flarco

README.md

@@ -349,6 +349,13 @@ GODBC_EXEC_MODE=prepexec ./your-app
 GODBC_EXEC_MODE=directW  ./your-app
 ```
 
+The env var is read on every call, so you can also set it from code before
+your first query, or override it explicitly with `godbc.SetExecMode`:
+
+```go
+godbc.SetExecMode("prepexec") // takes precedence over GODBC_EXEC_MODE
+```
+
 This only affects paramless `db.Exec`/`db.Query`/`db.Ping`; parameterized
 queries already go through the prepare/execute path.
 

odbc.go

@@ -6,6 +6,7 @@ import (
 	"runtime"
 	"strings"
 	"sync"
+	"sync/atomic"
 	"unsafe"
 
 	"github.com/ebitengine/purego"
@@ -269,10 +270,8 @@ const (
 	execModePrepExec                 // SQLPrepare + SQLExecute
 )
 
-var currentExecMode = parseExecMode(os.Getenv("GODBC_EXEC_MODE"))
-
-// parseExecMode maps the GODBC_EXEC_MODE env var to an execMode. Unknown or
-// empty values fall back to execModeDirect.
+// parseExecMode maps a GODBC_EXEC_MODE value to an execMode. Unknown or empty
+// values fall back to execModeDirect.
 func parseExecMode(s string) execMode {
 	switch strings.ToLower(strings.TrimSpace(s)) {
 	case "directa", "direct_a", "a":
@@ -286,15 +285,42 @@ func parseExecMode(s string) execMode {
 	}
 }
 
+// currentExecMode resolves the active execution mode.
+//
+// The GODBC_EXEC_MODE environment variable is read on every call rather than
+// once at init, so a program can set it in code (os.Setenv) before its first
+// query and have it take effect. An explicit override set via SetExecMode
+// takes precedence over the environment variable.
+func currentExecMode() execMode {
+	if m := execModeOverride.Load(); m != 0 {
+		return execMode(m - 1) // stored as mode+1 so 0 means "unset"
+	}
+	return parseExecMode(os.Getenv("GODBC_EXEC_MODE"))
+}
+
+// execModeOverride holds an in-code override of the execution mode. It stores
+// mode+1 so that the zero value means "no override, use GODBC_EXEC_MODE".
+var execModeOverride atomic.Int32
+
+// SetExecMode overrides the statement execution mode in code, taking precedence
+// over the GODBC_EXEC_MODE environment variable. Valid values are the same as
+// the env var: "", "direct", "directA", "directW", "prepexec". It is safe to
+// call concurrently and affects subsequent ExecDirect calls.
+func SetExecMode(mode string) {
+	execModeOverride.Store(int32(parseExecMode(mode)) + 1)
+}
+
 // ExecDirect executes an SQL statement directly.
 //
 // The statement text length is passed explicitly rather than SQL_NTS, and the
 // underlying buffer is NUL-terminated to be robust against Linux drivers that
 // strlen the text regardless. See cStmtText.
 //
-// The ODBC entry point used is selected by GODBC_EXEC_MODE (see execMode).
+// The ODBC entry point used is selected by GODBC_EXEC_MODE (or SetExecMode);
+// see execMode. The mode is resolved here, on every call, so it can be changed
+// at runtime.
 func ExecDirect(stmt SQLHSTMT, query string) SQLRETURN {
-	return execDirectVia(stmt, query, currentExecMode)
+	return execDirectVia(stmt, query, currentExecMode())
 }
 
 // execDirectVia is the testable core of ExecDirect — it dispatches to the

odbc_test.go

@@ -1,6 +1,7 @@
 package godbc
 
 import (
+	"os"
 	"reflect"
 	"testing"
 	"time"
@@ -1772,6 +1773,57 @@ func TestParseExecMode(t *testing.T) {
 	}
 }
 
+// TestCurrentExecMode verifies the execution mode is resolved at call time:
+// the GODBC_EXEC_MODE env var is honored dynamically, and SetExecMode
+// overrides it.
+func TestCurrentExecMode(t *testing.T) {
+	// Save and restore global state.
+	origEnv, hadEnv := os.LookupEnv("GODBC_EXEC_MODE")
+	origOverride := execModeOverride.Load()
+	t.Cleanup(func() {
+		if hadEnv {
+			os.Setenv("GODBC_EXEC_MODE", origEnv)
+		} else {
+			os.Unsetenv("GODBC_EXEC_MODE")
+		}
+		execModeOverride.Store(origOverride)
+	})
+
+	// No env, no override -> default.
+	os.Unsetenv("GODBC_EXEC_MODE")
+	execModeOverride.Store(0)
+	if got := currentExecMode(); got != execModeDirect {
+		t.Errorf("default: got %d, want execModeDirect", got)
+	}
+
+	// Env var is read dynamically (not frozen at init).
+	os.Setenv("GODBC_EXEC_MODE", "prepexec")
+	if got := currentExecMode(); got != execModePrepExec {
+		t.Errorf("env prepexec: got %d, want execModePrepExec", got)
+	}
+	os.Setenv("GODBC_EXEC_MODE", "directW")
+	if got := currentExecMode(); got != execModeDirectW {
+		t.Errorf("env directW: got %d, want execModeDirectW", got)
+	}
+
+	// SetExecMode overrides the env var.
+	SetExecMode("directA")
+	if got := currentExecMode(); got != execModeDirectA {
+		t.Errorf("override directA over env directW: got %d, want execModeDirectA", got)
+	}
+
+	// Clearing the override falls back to the env var again.
+	SetExecMode("")
+	if got := currentExecMode(); got != execModeDirect {
+		t.Errorf("override cleared to direct: got %d, want execModeDirect", got)
+	}
+	// "" parses to execModeDirect, so the override is still active (forcing
+	// direct) — the env var (directW) is not consulted. Verify that.
+	if got := currentExecMode(); got != execModeDirect {
+		t.Errorf("empty override still forces direct: got %d, want execModeDirect", got)
+	}
+}
+
 // TestExecDirectViaDispatch verifies that execDirectVia routes to the correct
 // underlying FFI function pointer based on the mode. The function pointers are
 // stubbed for the test and restored afterwards.