pgbench: benchmark y pruebas de carga de PostgreSQL
7 min de lectura
pgbench es el programa de benchmark que viene con PostgreSQL: ejecuta la misma transacción SQL una y otra vez en varias sesiones de base de datos simultáneas e informa de las transacciones por segundo y la latencia. Creas sus tablas de prueba con pgbench -i -s 50 mydb y luego lanzas algo como pgbench -c 10 -j 2 -T 300 mydb para diez clientes en dos hilos durante cinco minutos. Mide solo la base de datos, así que no dice nada de lo que notan los usuarios a través de la aplicación que va delante.
No hemos ejecutado pgbench para esta guía. Los datos salen de la página de pgbench en la documentación de PostgreSQL 18, la versión que postgresql.org marca como actual, comprobados el 31 de octubre de 2026, y las valoraciones son nuestras.
| Opción | Qué hace |
|---|---|
-i / -s | Crear las tablas de prueba / factor de escala (100.000 cuentas por unidad) |
-c | Clientes, es decir, sesiones de base de datos simultáneas (1 por defecto) |
-j | Hilos de trabajo dentro de pgbench (1 por defecto) |
-T / -t | Duración en segundos, o transacciones por cliente (10 por defecto) |
-b / -f | Un script integrado o un archivo tuyo, con un @peso opcional |
-P | Informe de progreso cada N segundos |
-R / -L | Ritmo objetivo en tps / límite de latencia en ms |
-r / -l | Latencias por sentencia / una línea de registro por transacción |
¿Qué mide pgbench?
Ejecuta un script de transacción una y otra vez en un número fijo de sesiones de base de datos e informa de la tasa media de transacciones y de la latencia. El script por defecto se basa de forma libre en el benchmark bancario TPC-B.
Según la documentación de pgbench, el escenario por defecto se inspira en TPC-B sin ser realmente TPC-B, y de ahí su nombre: la salida lo llama TPC-B (sort of) (comprobado el 31 de octubre de 2026).
¿Cómo se prepara una base de datos para pgbench?
Ejecuta pgbench -i contra una base de datos existente, con -s para el factor de escala. El comando crea cuatro tablas y borra cualquier tabla existente con el mismo nombre, así que dale una base de datos propia.
Con factor 1, pgbench_branches tiene una fila, pgbench_tellers 10, pgbench_accounts 100.000 y pgbench_history ninguna, y -s multiplica esas filas: -s 100 da 10.000.000 de filas en pgbench_accounts. La documentación no indica el tamaño en disco, así que mídelo después de inicializar (comprobado el 31 de octubre de 2026).
¿Qué scripts integrados trae pgbench?
Tres: tpcb-like (el predeterminado), simple-update y select-only. Eliges uno con -b o con los atajos -N y -S.
El predeterminado envía siete comandos por transacción: BEGIN, un update y un select sobre una cuenta al azar, updates sobre pgbench_tellers y pgbench_branches, un insert en pgbench_history y END. simple-update quita los dos updates sobre las tablas pequeñas, con lo que evita la contención en ellas y, según la documentación, aleja todavía más la prueba de TPC-B. select-only solo envía el select.
¿Cómo se escribe un script propio de pgbench?
Pon tu SQL en un archivo, define variables con \set y las funciones aleatorias, y pasa el archivo con -f. Cada ejecución del archivo cuenta como una transacción.
\set aid random(1, 100000 * :scale)
\set delta random(-5000, 5000)
BEGIN;
UPDATE pgbench_accounts SET abalance = abalance + :delta
WHERE aid = :aid;
SELECT abalance FROM pgbench_accounts WHERE aid = :aid;
END;Un peso después de @ fija la frecuencia con la que se elige cada script: -f update.sql@9 -b select-only@1 elige el archivo unas nueve de cada diez veces. La documentación también recoge random_exponential, random_gaussian y random_zipfian, con las que puedes concentrar el acceso en unas pocas filas. \sleep añade una pausa, la versión de base de datos del tiempo de reflexión. Si solo ejecutas tus propios archivos, pasa el factor de escala de la base de datos con -s; si no, :scale se queda en 1 y el script de arriba solo toca las primeras 100.000 cuentas. Con tus propias tablas, omite -i y añade -n para que pgbench no haga VACUUM de las tablas estándar (comprobado el 31 de octubre de 2026).
¿Qué opciones convierten pgbench en una prueba de carga?
La concurrencia sale de -c y -j, la duración de -T y la forma de la carga de -R. Sin -R, cada cliente lanza su siguiente transacción en cuanto termina la anterior.
Ese comportamiento por defecto es un modelo de carga cerrado, como explica nuestro artículo sobre el modelo de carga abierto vs cerrado. Con -R, pgbench lanza las transacciones según un calendario con distribución de Poisson que avanza desde el arranque del cliente, pase lo que pase con las transacciones anteriores. La latencia que muestra cuenta entonces desde cada inicio previsto e incluye el retraso sobre el calendario (schedule lag), cuya media y máximo aparecen por separado: es la corrección que describe nuestro artículo sobre coordinated omission. El número de clientes no cambia, así que si el retraso no deja de crecer, el sistema no aguanta ese ritmo con los clientes e hilos elegidos: baja -R o añade clientes.
--latency-limit (-L) cuenta como tardías las transacciones que superan un límite en milisegundos; con -R, pgbench además se salta las transacciones que ya van demasiado retrasadas y las cuenta como omitidas. -M prepared usa sentencias preparadas, más rápidas que los otros modos según la documentación (comprobado el 31 de octubre de 2026).
¿Cómo se lee la salida de pgbench?
El resumen muestra la configuración, las transacciones procesadas y fallidas, la latencia media, el tiempo de conexión inicial y los tps. Esta forma sale de la documentación, sin las cifras:
transaction type: <builtin: TPC-B (sort of)>
number of transactions actually processed: ...
number of failed transactions: ... (...%)
latency average = ... ms
latency stddev = ... ms (only with -P, -R or -L)
initial connection time = ... ms
tps = ... (without initial connection time)Las transacciones fallidas son errores de serialización o deadlocks, que --max-tries puede reintentar. Los demás errores SQL abortan el cliente afectado y dejan un código de salida 2. El resumen no trae percentiles: para la latencia de cola, registra cada transacción con -l, que guarda su duración en microsegundos, y calcula tú el p95 o el p99.
Sin -P, -R ni -L, la latencia media del resumen no se mide: pgbench la deduce a partir de la duración y del número de clientes, es decir, la ley de Little aplicada al revés, con los fallos incluidos. Añade -P cuando importe la latencia.
¿Cómo se consiguen cifras de pgbench fiables?
Haz que cada ejecución dure varios minutos, repítela, mantén el factor de escala al menos igual al número de clientes y vigila el VACUUM. Si el propio pgbench se convierte en el cuello de botella, llévalo a otra máquina.
La primera pauta de la sección «Good Practices» de la documentación advierte que no te fíes de ninguna prueba que dure solo unos segundos, y añade que unas cifras reproducibles pueden requerir horas (comprobado el 31 de octubre de 2026). Con el script por defecto, un factor de escala menor que el número de clientes mide sobre todo la contención de los updates, porque pgbench_branches solo tiene -s filas y cada transacción modifica una. Las filas muertas y el autovacuum cambian los resultados de una ejecución a otra. Con muchas sesiones, pgbench puede saturar su propia máquina: ejecútalo en una máquina aparte con baja latencia de red, o reparte varias instancias entre varias máquinas.
¿Cuándo no es pgbench la herramienta adecuada?
Cuando la pregunta trata de los usuarios, de otra base de datos o de una mezcla OLTP estándar. pgbench mide PostgreSQL a solas, sin tu pool de conexiones, tu ORM, tu caché ni tu capa HTTP.
Para ver lo que notan los usuarios, pon carga en la capa HTTP o API que va delante. LoadFocus, que publica este sitio, no ejecuta pgbench ni puede conectarse directamente a PostgreSQL: ejecuta planes de prueba JMeter y scripts de k6 desde 25 regiones en la nube contra endpoints web y de API.
Elige sysbench para MySQL: su repositorio describe una herramienta de benchmark programable y multihilo con pruebas de base de datos de tipo OLTP. Elige HammerDB para una mezcla al estilo de TPC-C: su documentación describe TPROC-C, una carga derivada de TPC-C, que ejecuta sobre PostgreSQL y otros motores. Elige JMeter con su sampler JDBC Request para mezclar SQL y HTTP en un mismo plan de prueba en tus propias máquinas (todo comprobado el 31 de octubre de 2026).
FAQ
¿Para qué sirve la opción -s de pgbench? Fija el factor de escala al inicializar. Cada unidad añade 100.000 filas a pgbench_accounts, así que -s 100 crea 10.000.000 de filas. Con el script por defecto, mantenlo al menos igual a tu número de clientes.
¿Qué diferencia hay entre -c y -j en pgbench? La opción -c fija el número de clientes simulados, cada uno una sesión de base de datos simultánea. La opción -j fija cuántos hilos de trabajo de pgbench se reparten esos clientes.
¿Puede LoadFocus ejecutar pgbench? No. LoadFocus ejecuta planes de prueba JMeter y scripts de k6 y no tiene conexión directa con PostgreSQL, así que con él pones carga en la capa web o API que va delante de la base de datos.
Lecturas relacionadas
- Coordinated omission: qué es y cómo evitarla
- Modelo de carga abierto vs cerrado: cuál usar y cuándo
- Latencia de cola: qué es y cómo medirla
- Ley de Little en pruebas de carga: dimensionar y comprobar
- Cómo usar sysbench: benchmarks de CPU, disco y MySQL
- YCSB: cargas de trabajo A-F, ejecución y límites
- redis-benchmark: cómo usarlo y leer sus resultados
- TPC-H: qué mide el benchmark y cómo ejecutarlo
Las afirmaciones técnicas de este artículo no se han revisado de forma independiente.