ProxySQL · ronaldbradford · May 20, 2026 · May 21, 2026 · May 21, 2026 · May 22, 2026
diff --git a/cmd/replication.go b/cmd/replication.go
@@ -20,6 +20,7 @@ import (
 	"os"
 	"path"
 	"strings"
+	"time"
 
 	"github.com/ProxySQL/dbdeployer/common"
 	"github.com/ProxySQL/dbdeployer/defaults"
@@ -73,9 +74,34 @@ func deployReplicationNonMySQL(cmd *cobra.Command, args []string, providerName s
 	}
 	installedPorts = append(installedPorts, primaryPort)
 
-	topologyDir := path.Join(sandboxHome, fmt.Sprintf("%s_repl_%d", providerName, primaryPort))
+	sandboxDirName, _ := flags.GetString(globals.SandboxDirectoryLabel)
+	force, _ := flags.GetBool(globals.ForceLabel)
+
+	var topologyDir string
+	if sandboxDirName != "" {
+		topologyDir = path.Join(sandboxHome, sandboxDirName)
+	} else {
+		topologyDir = path.Join(sandboxHome, fmt.Sprintf("%s_repl_%d", providerName, primaryPort))
+	}
+
 	if common.DirExists(topologyDir) {
-		common.Exitf(1, "sandbox directory %s already exists", topologyDir)
+		if !force {
+			common.Exitf(1, "sandbox directory %s already exists", topologyDir)
+		}
+		common.CondPrintf("Overwriting directory %s\n", topologyDir)
+		entries, err := os.ReadDir(topologyDir)
+		if err == nil {
+			for _, entry := range entries {
+				if !entry.IsDir() {
+					continue
+				}
+				stopScript := path.Join(topologyDir, entry.Name(), "stop")
+				if common.ExecExists(stopScript) {
+					_, _ = common.RunCmd(stopScript)
+				}
+			}
+		}
+		common.RmdirAll(topologyDir)
 	}
 	if err := os.MkdirAll(topologyDir, 0755); err != nil {
 		common.Exitf(1, "error creating topology directory %s: %s", topologyDir, err)
@@ -92,15 +118,21 @@ func deployReplicationNonMySQL(cmd *cobra.Command, args []string, providerName s
 		Options: map[string]string{"replication": "true"},
 	}
 
+	skipStart, _ := flags.GetBool(globals.SkipStartLabel)
+	common.DeployDebugf("creating primary in %s (port %d)\n", primaryDir, primaryPort)
+	primaryCreateStart := time.Now()
 	if _, err := p.CreateSandbox(primaryConfig); err != nil {
 		common.Exitf(1, "error creating primary: %s", err)
 	}
+	common.DeployDebugSince("primary CreateSandbox complete", primaryCreateStart)
 
-	skipStart, _ := flags.GetBool(globals.SkipStartLabel)
 	if !skipStart {
+		common.DeployDebugf("starting primary in %s\n", primaryDir)
+		primaryStart := time.Now()
 		if err := p.StartSandbox(primaryDir); err != nil {
 			common.Exitf(1, "error starting primary: %s", err)
 		}
+		common.DeployDebugSince("primary StartSandbox complete", primaryStart)
 	}
 
 	fmt.Printf("  Primary deployed in %s (port: %d)\n", primaryDir, primaryPort)
@@ -119,6 +151,8 @@ func deployReplicationNonMySQL(cmd *cobra.Command, args []string, providerName s
 		installedPorts = append(installedPorts, replicaPort)
 
 		replicaDir := path.Join(topologyDir, fmt.Sprintf("replica%d", i))
+		common.DeployDebugf("creating replica %d in %s (port %d)\n", i, replicaDir, replicaPort)
+		replicaCreateStart := time.Now()
 		replicaConfig := providers.SandboxConfig{
 			Version: version,
 			Dir:     replicaDir,
@@ -136,6 +170,7 @@ func deployReplicationNonMySQL(cmd *cobra.Command, args []string, providerName s
 			}
 			common.Exitf(1, "error creating replica %d: %s", i, err)
 		}
+		common.DeployDebugSince(fmt.Sprintf("replica %d CreateReplica complete", i), replicaCreateStart)
 
 		replicaPorts = append(replicaPorts, replicaPort)
 		fmt.Printf("  Replica %d deployed in %s (port: %d)\n", i, replicaDir, replicaPort)
@@ -145,12 +180,13 @@ func deployReplicationNonMySQL(cmd *cobra.Command, args []string, providerName s
 	home, _ := os.UserHomeDir()
 	basedir := path.Join(home, "opt", "postgresql", version)
 	binDir := path.Join(basedir, "bin")
-	libDir := path.Join(basedir, "lib")
+	libDir := postgresql.LibraryPath(basedir, version)
 
 	scriptOpts := postgresql.ScriptOptions{
-		BinDir: binDir,
-		LibDir: libDir,
-		Port:   primaryPort,
+		SandboxDir: topologyDir,
+		BinDir:     binDir,
+		LibDir:     libDir,
+		Port:       primaryPort,
 	}
 
 	checkReplScript := postgresql.GenerateCheckReplicationScript(scriptOpts)
@@ -163,16 +199,42 @@ func deployReplicationNonMySQL(cmd *cobra.Command, args []string, providerName s
 		fmt.Printf("WARNING: could not write check_recovery script: %s\n", err)
 	}
 
+	testReplScript, err := postgresql.GenerateTestReplicationScript(postgresql.TestReplicationOptions{
+		SandboxDir: topologyDir,
+		ShellPath:  defaults.Defaults().ShellPath,
+	})
+	if err != nil {
+		common.Exitf(1, "generating test_replication script: %s", err)
+	}
+	if err := os.WriteFile(path.Join(topologyDir, globals.ScriptTestReplication), []byte(testReplScript), 0755); err != nil { //nolint:gosec // scripts must be executable
+		fmt.Printf("WARNING: could not write test_replication script: %s\n", err)
+	}
+
 	// Handle --with-proxysql
 	withProxySQL, _ := flags.GetBool("with-proxysql")
+	proxyPort := 0
 	if withProxySQL {
 		if !providers.ContainsString(providers.CompatibleAddons["proxysql"], providerName) {
 			common.Exitf(1, "--with-proxysql is not compatible with provider %q", providerName)
 		}
+		common.DeployDebugf("deploying ProxySQL in %s\n", topologyDir)
+		proxysqlStart := time.Now()
 		err := sandbox.DeployProxySQLForTopology(topologyDir, primaryPort, replicaPorts, 0, "127.0.0.1", providerName)
 		if err != nil {
 			common.Exitf(1, "ProxySQL deployment failed: %s", err)
 		}
+		common.DeployDebugSince("ProxySQL deployment complete", proxysqlStart)
+		proxyPort = postgresql.ProxySQLAdminPort(primaryPort) + 1
+	}
+
+	benchScript := postgresql.GenerateTopologyBenchScript(postgresql.TopologyBenchOptions{
+		BinDir:      binDir,
+		LibDir:      libDir,
+		PrimaryPort: primaryPort,
+		ProxyPort:   proxyPort,
+	})
+	if err := os.WriteFile(path.Join(topologyDir, "bench"), []byte(benchScript), 0755); err != nil { //nolint:gosec // scripts must be executable
+		fmt.Printf("WARNING: could not write bench script: %s\n", err)
 	}
 
 	// Write a top-level sandbox description so common.GetInstalledPorts()

diff --git a/cmd/single.go b/cmd/single.go
@@ -491,9 +491,26 @@ func deploySingleNonMySQL(cmd *cobra.Command, args []string, providerName string
 	}
 
 	sandboxHome := defaults.Defaults().SandboxHome
-	sandboxDir := path.Join(sandboxHome, fmt.Sprintf("%s_sandbox_%d", providerName, port))
+	sandboxDirName, _ := flags.GetString(globals.SandboxDirectoryLabel)
+	force, _ := flags.GetBool(globals.ForceLabel)
+
+	var sandboxDir string
+	if sandboxDirName != "" {
+		sandboxDir = path.Join(sandboxHome, sandboxDirName)
+	} else {
+		sandboxDir = path.Join(sandboxHome, fmt.Sprintf("%s_sandbox_%d", providerName, port))
+	}
+
 	if common.DirExists(sandboxDir) {
-		common.Exitf(1, "sandbox directory %s already exists", sandboxDir)
+		if !force {
+			common.Exitf(1, "sandbox directory %s already exists", sandboxDir)
+		}
+		common.CondPrintf("Overwriting directory %s\n", sandboxDir)
+		stopScript := path.Join(sandboxDir, "stop")
+		if common.ExecExists(stopScript) {
+			_, _ = common.RunCmd(stopScript)
+		}
+		common.RmdirAll(sandboxDir)
 	}
 
 	skipStart, _ := flags.GetBool(globals.SkipStartLabel)

diff --git a/cmd/unpack.go b/cmd/unpack.go
@@ -42,11 +42,11 @@ func unpackTarball(cmd *cobra.Command, args []string) {
 	Version, _ := flags.GetString(globals.UnpackVersionLabel)
 	providerName, _ := flags.GetString(globals.ProviderLabel)
 	if providerName == "postgresql" {
-		if len(args) < 2 {
-			common.Exitf(1, "PostgreSQL unpack requires both server and client .deb files\n"+
-				"Usage: dbdeployer unpack --provider=postgresql postgresql-16_*.deb postgresql-client-16_*.deb")
+		if len(args) < 3 {
+			common.Exitf(1, "PostgreSQL unpack requires server and client .deb files, plus libpq5\n"+
+				"Usage: dbdeployer unpack --provider=postgresql postgresql-18_*.deb postgresql-client-18_*.deb libpq5_*.deb")
 		}
-		server, client, err := postgresql.ClassifyDebs(args)
+		server, _, err := postgresql.ClassifyDebs(args)
 		if err != nil {
 			common.Exitf(1, "error classifying deb files: %s", err)
 		}
@@ -59,7 +59,7 @@ func unpackTarball(cmd *cobra.Command, args []string) {
 		}
 		home, _ := os.UserHomeDir()
 		targetDir := filepath.Join(home, "opt", "postgresql", version)
-		if err := postgresql.UnpackDebs(server, client, targetDir); err != nil {
+		if err := postgresql.UnpackDebs(args, targetDir); err != nil {
 			common.Exitf(1, "error unpacking PostgreSQL debs: %s", err)
 		}
 		fmt.Printf("PostgreSQL %s unpacked to %s\n", version, targetDir)

diff --git a/common/checks.go b/common/checks.go
@@ -26,6 +26,7 @@ import (
 	"sort"
 	"strconv"
 	"strings"
+	"time"
 
 	"github.com/araddon/dateparse"
 	"github.com/pkg/errors"
@@ -46,6 +47,17 @@ type VersionInfo struct {
 
 var portDebug bool = IsEnvSet("PORT_DEBUG")
 
+func portDebugf(format string, args ...interface{}) {
+	if !portDebug {
+		return
+	}
+	if IsEnvSet("DEPLOY_DEBUG") {
+		CondPrintf("[%s] "+format, append([]interface{}{time.Now().Format("15:04:05")}, args...)...)
+		return
+	}
+	CondPrintf(format, args...)
+}
+
 type PortMap map[int]bool
 
 type SandboxInfoList []SandboxInfo
@@ -721,7 +733,7 @@ func findFreePortSingle(requestedPort int, usedPorts PortMap) (int, error) {
 		_, exists := usedPorts[candidatePort]
 		if exists {
 			if portDebug {
-				CondPrintf("- port %d not free\n", candidatePort)
+				portDebugf("- port %d not free\n", candidatePort)
 			}
 		} else {
 			foundPort = candidatePort
@@ -752,15 +764,15 @@ func findFreePortRange(basePort int, usedPorts PortMap, howMany int) (int, error
 			_, exists := usedPorts[candidatePort+counter]
 			if exists {
 				if portDebug {
-					CondPrintf("- port %d is not free\n", candidatePort+counter)
+					portDebugf("- port %d is not free\n", candidatePort+counter)
 				}
 				candidatePort += 1
 				counter = 0
 				numPorts = 0
 				continue
 			} else {
 				if portDebug {
-					CondPrintf("+ port %d is free\n", candidatePort+counter)
+					portDebugf("+ port %d is free\n", candidatePort+counter)
 				}
 				numPorts += 1
 			}
@@ -789,7 +801,7 @@ func findFreePortRange(basePort int, usedPorts PortMap, howMany int) (int, error
 // Returns the first port of the requested range
 func FindFreePort(basePort int, installedPorts []int, howMany int) (int, error) {
 	if portDebug {
-		CondPrintf("FindFreePort: requested: %d - used: %v - howMany: %d\n", basePort, installedPorts, howMany)
+		portDebugf("FindFreePort: requested: %d - used: %v - howMany: %d\n", basePort, installedPorts, howMany)
 	}
 	usedPorts := make(PortMap)
 

diff --git a/common/strutils.go b/common/strutils.go
@@ -22,6 +22,7 @@ import (
 	"sort"
 	"strconv"
 	"strings"
+	"time"
 
 	"github.com/ProxySQL/dbdeployer/globals"
 )
@@ -41,6 +42,19 @@ func CondPrintf(format string, args ...interface{}) {
 	}
 }
 
+// DeployDebugf prints timestamped deploy tracing when DEPLOY_DEBUG is set.
+func DeployDebugf(format string, args ...interface{}) {
+	if !IsEnvSet("DEPLOY_DEBUG") || !globals.UsingDbDeployer {
+		return
+	}
+	fmt.Printf("[%s] %s", time.Now().Format("15:04:05"), fmt.Sprintf(format, args...))
+}
+
+// DeployDebugSince prints elapsed seconds since start when DEPLOY_DEBUG is set.
+func DeployDebugSince(label string, start time.Time) {
+	DeployDebugf("%s (%.1fs)\n", label, time.Since(start).Seconds())
+}
+
 func CondPrintln(args ...interface{}) {
 	if globals.UsingDbDeployer {
 		fmt.Println(args...)

diff --git a/providers/postgresql/paths.go b/providers/postgresql/paths.go
@@ -0,0 +1,98 @@
+// DBDeployer - The MySQL Sandbox
+// Copyright © 2006-2020 Giuseppe Maxia
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+package postgresql
+
+import (
+	"fmt"
+	"os"
+	"path/filepath"
+	"runtime"
+	"strings"
+)
+
+// LibraryPath returns LD_LIBRARY_PATH entries for a PostgreSQL basedir.
+// Client tools (psql) need libpq from <basedir>/lib; server binaries and
+// extensions need <basedir>/lib/postgresql/<major>/lib on Linux.
+func LibraryPath(basedir, version string) string {
+	flatLib := filepath.Join(basedir, "lib")
+	if runtime.GOOS != "linux" {
+		return flatLib
+	}
+	major := strings.Split(version, ".")[0]
+	pgLib := filepath.Join(basedir, "lib", "postgresql", major, "lib")
+	return flatLib + string(filepath.ListSeparator) + pgLib
+}
+
+// PgBinDir returns the directory containing Debian-packaged PostgreSQL client tools.
+func PgBinDir(basedir, version string) string {
+	if runtime.GOOS != "linux" {
+		return filepath.Join(basedir, "bin")
+	}
+	major := strings.Split(version, ".")[0]
+	return filepath.Join(basedir, "lib", "postgresql", major, "bin")
+}
+
+// ResolvePsqlBinary locates the unpacked psql binary, skipping Debian pg_wrapper scripts.
+func ResolvePsqlBinary(basedir, version string) (string, error) {
+	candidates := []string{
+		filepath.Join(PgBinDir(basedir, version), "psql"),
+		filepath.Join(basedir, "bin", "psql"),
+	}
+	for _, candidate := range candidates {
+		ok, err := validPsqlBinary(candidate)
+		if err != nil {
+			if os.IsNotExist(err) {
+				continue
+			}
+			return "", err
+		}
+		if ok {
+			return candidate, nil
+		}
+	}
+	return "", fmt.Errorf(
+		"bundled psql not found under %s — re-run unpack with server, client, and libpq5 debs:\n"+
+			"    dbdeployer unpack --provider=postgresql postgresql-NN_*.deb postgresql-client-NN_*.deb libpq5_*.deb",
+		basedir,
+	)
+}
+
+func validPsqlBinary(path string) (bool, error) {
+	info, err := os.Stat(path)
+	if err != nil {
+		return false, err
+	}
+	if info.IsDir() {
+		return false, fmt.Errorf("%s is a directory", path)
+	}
+	resolved := path
+	if isShellScript(resolved) {
+		return false, nil
+	}
+	return true, nil
+}
+
+func isShellScript(path string) bool {
+	f, err := os.Open(path)
+	if err != nil {
+		return false
+	}
+	defer f.Close()
+
+	buf := make([]byte, 2)
+	n, _ := f.Read(buf)
+	return n >= 2 && buf[0] == '#' && buf[1] == '!'
+}