Benchmarking YSQL Connection Time in YugabyteDB with ysqlsh

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 — uses awk for 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 <hostname>] [-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!

My daughter’s engagement party was held at Queen City Exchange in Cincinnati, OH, a very cool venue where beer prices are displayed like stock tickers and update every 15 minutes. If you “play the market” right, you can score drinks at a steep discount. Pretty clever (and dangerous) concept!