In high-performance environments, even milliseconds matter. Whether you’re fine-tuning client connection pools, debugging startup latency, or sizing infrastructure for scale, knowing how long it takes to connect to your YugabyteDB cluster can be a crucial metric.
In this tip, we’ll walk through a flexible, production-ready Bash script that benchmarks connection time to YugabyteDB’s YSQL interface using ysqlsh. It supports both Unix socket and TCP connections, reports summary stats, and is easily customizable.
Why Connection Time Matters
Connection time is the often-ignored “first impression” between your application and your database.
Some reasons you might care:
• Serverless architectures spin up new DB connections frequently
• Microservices may create short-lived DB sessions
• Connection pools may reach limits and start dropping/queuing clients
• Monitoring tools (like Dynatrace, Datadog, New Relic) may attribute client-side latency to the DB when it’s really connection overhead
Measuring this helps validate:
• Network latency
• Authentication or TLS handshake overhead
• Cluster load responsiveness
The Tool: A Bash Script for Benchmarking
This script:
• Uses
ysqlsh(YugabyteDB’s PostgreSQL-compatible CLI)• Measures how long it takes to establish a connection and run
SELECT 1;• Works over both Unix sockets and TCP
• Provides min, max, average, and median latency
• Accepts CLI arguments for user, DB, mode, host, and run count
• Does not require
bc— usesawkfor all timing math
The Script
Save the following as yb_ysqlsh_connect_benchmark.sh:
#!/bin/bash
set -euo pipefail
# --- Defaults ---
YSQLSH="${YSQLSH:-/home/yugabyte/yugabyte-db/bin/ysqlsh}"
USERNAME="yugabyte"
DBNAME="yugabyte"
COUNT=10
MODE="socket"
HOST=""
PORT="5433"
# --- Parse CLI args ---
while [[ $# -gt 0 ]]; do
case "$1" in
--tcp)
MODE="tcp"
shift
;;
--socket)
MODE="socket"
shift
;;
--host)
HOST="$2"
shift 2
;;
-U|--user)
USERNAME="$2"
shift 2
;;
-d|--dbname)
DBNAME="$2"
shift 2
;;
-n|--count)
COUNT="$2"
shift 2
;;
*)
echo "Unknown option: $1"
echo "Usage: $0 [--tcp|--socket] [--host ] [-U user] [-d dbname] [-n count]"
exit 1
;;
esac
done
# --- Validate ysqlsh path ---
if [[ ! -x "$YSQLSH" ]]; then
echo "❌ Error: ysqlsh not found or not executable at: $YSQLSH"
echo "👉 Please set the correct path at the top of the script or use:"
echo " YSQLSH=/path/to/ysqlsh ./yb_ysqlsh_connect_benchmark.sh ..."
exit 1
fi
# --- Determine connection method ---
if [[ "$MODE" == "tcp" ]]; then
HOST="${HOST:-127.0.0.1}"
echo "✅ Using TCP connection to $HOST:$PORT"
else
HOST=$(ps -ef | grep '[t]server' | awk '{for(i=1;i<=NF;i++)if($i~/-k/)print $(i+1)}')
if [[ -z "$HOST" ]]; then
echo "❌ Could not detect YSQL socket path. Is the tserver running?"
exit 1
fi
echo "✅ Detected YSQL socket path: $HOST"
fi
echo "▶ Running $COUNT connections to database '$DBNAME' as user '$USERNAME' using ysqlsh ($MODE mode)..."
# --- Run benchmark ---
TIMINGS=()
for i in $(seq 1 "$COUNT"); do
start_ns=$(date +%s%N)
if [[ "$MODE" == "tcp" ]]; then
output=$(
PGPASSWORD="" "$YSQLSH" --no-password -h "$HOST" -p "$PORT" -U "$USERNAME" -d "$DBNAME" -c "SELECT 1;" 2>&1
)
else
output=$(
PGPASSWORD="" "$YSQLSH" --no-password -h "$HOST" -U "$USERNAME" -d "$DBNAME" -c "SELECT 1;" 2>&1
)
fi
end_ns=$(date +%s%N)
duration=$(awk -v s="$start_ns" -v e="$end_ns" 'BEGIN { printf "%.4f", (e - s)/1000000000 }')
if echo "$output" | grep -q "could not connect"; then
echo "⚠️ [$i] Connection failed:"
echo "$output"
continue
fi
TIMINGS+=("$duration")
printf " [%02d] Connection time: %.4f sec\n" "$i" "$duration"
done
# --- Summary stats ---
if [[ ${#TIMINGS[@]} -eq 0 ]]; then
echo "❌ No successful connections."
exit 1
fi
MIN=$(printf '%s\n' "${TIMINGS[@]}" | sort -n | head -n1)
MAX=$(printf '%s\n' "${TIMINGS[@]}" | sort -n | tail -n1)
AVG=$(printf '%s\n' "${TIMINGS[@]}" | awk '{sum+=$1} END{printf "%.4f", sum/NR}')
MEDIAN=$(printf '%s\n' "${TIMINGS[@]}" | sort -n | awk '
{ a[NR]=$1 }
END {
if (NR % 2 == 1)
printf "%.4f", a[(NR+1)/2]
else
printf "%.4f", (a[NR/2] + a[NR/2+1]) / 2
}')
echo ""
echo "📊 Connection Time Summary:"
echo " Total: ${#TIMINGS[@]} successful connections"
echo " Min: ${MIN} sec"
echo " Max: ${MAX} sec"
echo " Avg: ${AVG} sec"
echo " Median: ${MEDIAN} sec"
Don’t forget to make the script executable!
chmod +x yb_ysqlsh_connect_benchmark.sh
Example Usage
Default (Unix socket):
./yb_ysqlsh_connect_benchmark.sh
TCP to local host:
./yb_ysqlsh_connect_benchmark.sh --tcp
TCP to a remote host:
./yb_ysqlsh_connect_benchmark.sh --tcp --host 10.1.1.45 -U appuser -d appdb -n 50
A view Sample Outputs
[root@localhost ~]# YSQLSH=/root/yugabyte-2.25.2.0/bin/ysqlsh ./yb_ysqlsh_connect_benchmark.sh -n 5
✅ Detected YSQL socket path: /tmp/.yb.127.0.0.1:5433
▶ Running 5 connections to database 'yugabyte' as user 'yugabyte' using ysqlsh (socket mode)...
[01] Connection time: 0.0241 sec
[02] Connection time: 0.0251 sec
[03] Connection time: 0.0250 sec
[04] Connection time: 0.0271 sec
[05] Connection time: 0.0255 sec
📊 Connection Time Summary:
Total: 5 successful connections
Min: 0.0241 sec
Max: 0.0271 sec
Avg: 0.0254 sec
Median: 0.0251 sec
[root@localhost ~]# YSQLSH=/root/yugabyte-2.25.2.0/bin/ysqlsh ./yb_ysqlsh_connect_benchmark.sh --tcp --host 127.0.0.1 -n 5
✅ Using TCP connection to 127.0.0.1:5433
▶ Running 5 connections to database 'yugabyte' as user 'yugabyte' using ysqlsh (tcp mode)...
[01] Connection time: 0.0713 sec
[02] Connection time: 0.0312 sec
[03] Connection time: 0.0305 sec
[04] Connection time: 0.0326 sec
[05] Connection time: 0.0268 sec
📊 Connection Time Summary:
Total: 5 successful connections
Min: 0.0268 sec
Max: 0.0713 sec
Avg: 0.0385 sec
Median: 0.0312 sec
Final Thoughts
Connection time isn’t always a problem, but knowing where your latency comes from is power. This script gives you a fast, repeatable way to measure that very first hop from client to YugabyteDB, over both socket and TCP.
Have Fun!
