YugabyteDB Cluster Sizing Calculator

Size a YugabyteDB cluster from workload inputs: node count, vCPU, memory, storage, IOPS, disk throughput, network and failure resilience, targeting ≤65% CPU. Always run the bundled script (scripts/sizing_calc.py) — never compute by hand.

Rules:

• RF must be 1, 3, 5 or 7 (the script rejects others). Never recommend RF=1 for production.
• Always state that the sizing is indicative and that the user should test with their actual

workload to fine-tune production sizing.

• CPU comes from measured CPU cost per operation (transactional, point-select and YCQL key-value benchmarks), not

from latency. Details: references/cpu-model.md.

Workflow

1. Pick the API. --api ysql (default) or --api ycql. Cassandra, CQL, port 9042, partition

keys or TTL → YCQL; PostgreSQL, SQL, joins or port 5433 → YSQL. Ask if unclear.

1. Gather inputs (table below). Ask for the required ones; use defaults for the rest.
2. Choose the CPU basis, best first:
3. Calibration — if the user has a running cluster or PoC with a similar mix, ask for its QPS

and average CPU% (--observed-qps, --observed-cpu-pct; plus --observed-nodes / --observed-vcpu-per-node if its shape differs from the target).

1. Workload profile — pick --workload from the user's description of their queries.
2. Only if neither is available, let the script auto-select a profile from the read/write mix,

and say so in the answer.

1. Run the script. For production, add --size-for zone. When the node size is open, use

--compare 8,16,32 instead of --vcpu-per-node.

1. Present the result (see Presenting results), including every ⚠️ warning the script prints.

Inputs

All other parameters and their defaults: references/defaults.md.

Running the script

# Typical YSQL sizing
python3 scripts/sizing_calc.py --qps 10000 --write-pct 30 --read-pct 70 --workload oltp \
  --vcpu-per-node 16 --rf 3 --table-size-gb 500 --size-for zone

# YCQL
python3 scripts/sizing_calc.py --api ycql --qps 100000 --write-pct 30 --read-pct 70 \
  --workload point --vcpu-per-node 16 --rf 3 --table-size-gb 500

# Calibrated from a running cluster (observed shape defaults to RF nodes × target vCPU)
python3 scripts/sizing_calc.py ... --observed-qps 8000 --observed-cpu-pct 40 \
  [--observed-nodes 6 --observed-vcpu-per-node 8]

# Compare node sizes (replaces --vcpu-per-node; with --compare, pass --observed-vcpu-per-node too)
python3 scripts/sizing_calc.py ... --compare 8,16,32 --size-for zone

# NVMe / io2 instead of gp3
python3 scripts/sizing_calc.py ... --disk-iops 200000 --disk-mibps 4000

# Single AZ, Graviton, previous-gen hardware, Connection Manager, xCluster
python3 scripts/sizing_calc.py ... --zones 1 --cpu-arch arm --cpu-cost-scale 1.15 \
  --connection-manager --xcluster

# YCQL with TTL
python3 scripts/sizing_calc.py --api ycql ... --ttl-days 30

# Transactions: 3,000 TPS of 6-statement transactions (QPS = 18,000; distributed by default)
python3 scripts/sizing_calc.py --tps 3000 --statements-per-txn 6 --write-pct 30 --read-pct 70 --workload kv ...

# Multi-region (3 regions, one replica each), leaders pinned to the app's region, 40% follower reads
python3 scripts/sizing_calc.py ... --regions 3 --preferred-region --region-rtt-ms 40 --follower-read-pct 40

# Same, with write pipelining (multi-statement transactions across regions)
python3 scripts/sizing_calc.py ... --regions 3 --preferred-region --write-pipelining

# HTAP: OLTP plus 5 analytical queries/s scanning ~2M rows each, isolated on a read replica
python3 scripts/sizing_calc.py --qps 20000 --write-pct 30 --read-pct 70 --workload htap \
  --analytics-qps 5 --analytics-rows 2000000 --analytics-target read-replica ...

# Read-replica cluster for 30% of reads (e.g. remote-region reporting)
python3 scripts/sizing_calc.py ... --read-replica-read-pct 30 --read-replica-rf 1

Output format: --format text (default) for the answer; --format html > sizing.html when the user wants a shareable report (self-contained page — write it to a file and give the path); --format json for programmatic use.

Comparison logic (--compare): among node sizes that meet the CPU target and survive a zone loss, take those within 10% of the lowest total vCPU and pick the one with the fewest nodes.

Presenting results

Lead with the recommendation (nodes × vCPU, RAM and storage per node), then:

• CPU basis: calibrated, or which workload profile was used — and if it was auto-selected,

say so and ask the user to confirm.

• Failure resilience: CPU after losing a node and a zone. If a zone loss exceeds 65%,

recommend --size-for zone (or show its result).

• What constrains the size: CPU, storage cap, disk limits or failure headroom. When disk adds

nodes, present the choice of more gp3 nodes vs fewer NVMe/io2 nodes.

• Disk and network: IOPS and MiB/s to provision per node; cross-AZ traffic and its monthly

cost for multi-AZ clusters.

• Concurrency: if latency was given and the workload is connection-bound, recommend more

nodes or Connection Manager. In multi-region layouts the effective latency includes the cross-region round trips the script adds.

• Multi-region: added latency per statement; with --preferred-region, the leader-region vs

follower-region CPU and the fact that every region is sized to take over leadership. For YSQL the report also shows the latency with write pipelining — recommend ysql_enable_write_pipelining=true (2026.1.2+, set on every yb-master and yb-tserver) when multi-statement write transactions cross regions or the workload is connection-bound.

• Transactions and read offload: distributed-transaction CPU, and the read-replica cluster

(nodes, RAM, storage) as a separate line item.

• HTAP: scan CPU and scan disk reads, and where analytics run. On the primary, scans compete

with OLTP for CPU and evict its cache — recommend isolating them on a read replica (or follower reads if staleness is fine, noting that followers widen each node's cached data). Present the primary and the read-replica cluster as separate line items.

• Storage growth: 1- and 2-year storage per node.
• Deployment notes the script prints (YCQL memory flags, Connection Manager flags).
• The indicative-sizing disclaimer.

Edge cases

• Minimum cluster: RF nodes. Scale out in multiples of RF.
• Read-heavy or remote-region reads: if reads tolerate bounded staleness (30 s default),

model follower reads (--follower-read-pct) or a read-replica cluster (--read-replica-read-pct). Both need read-only transactions with yb_read_from_followers (YSQL) or consistency ONE (YCQL).

• Multi-region choices: a synchronous stretch cluster (--regions) pays a cross-region round

trip on every write; for active-active with async replication, size each xCluster universe separately with --xcluster; for geo-partitioned data, size each region's partition separately.

• Transactions: single-statement writes use the fast path; any BEGIN … COMMIT block with

writes is a distributed transaction (--statements-per-txn > 1 assumes so). The oltp profile already includes distributed-transaction cost, so the overhead is added only to the fast-path profiles (YSQL kv, YCQL point/range).

• Bursty workloads: size for peak QPS; add headroom or plan for horizontal scaling.
• YCQL secondary indexes: each index is a table (--num-objects) and requires

transactions = {'enabled': true} — use --workload lwt.

• YSQL + YCQL on one cluster: size each workload separately and add the vCPUs; keep

use_memory_defaults_optimized_for_ysql=true if YSQL is used.

• Connection Manager client count: if the user states expected client connections per node,

pass --cm-client-ratio ≈ clients ÷ backends (e.g. 2,000 ÷ 160 → 13); it sets reported capacity only — CPU and RAM follow the backend pool.

• Kubernetes: StatefulSets, one pod per node; match pod requests to the per-node figures.
• Large nodes: use the latency-performance tuned profile on 32/64-core machines.
• Managed / cloud instances: match to available shapes (e.g. r6g.4xlarge = 16 vCPU / 128 GB).
• Data sources: the YSQL costs come from single-AZ runs; the YCQL costs from older hardware

scaled ×0.6. Calibrate from the user's own cluster whenever one exists.

References

• references/cpu-model.md — CPU cost model, measured sources, workload

profiles, calibration, capacity per node

• references/methodology.md — step-by-step formulas for every output
• references/defaults.md — every default and its flag
• references/examples.md — worked YSQL and YCQL examples