Indique le nom de la base à tester. Si elle n'est pas spécifier, la variable d'environnement PGDATABASE est utilisée. Si elle n'est pas configurée, le nom d'utilisateur indiqué pour la connexion est utilisé.

Nécessaire pour passer en mode initialisation.

N'effectue qu'une partie des étapes d'initialisation habituelles. init_steps spécifie les étapes d'initialisation à exécuter, à raison d'un caractère par étape. Chaque étape est appelée dans l'ordre indiqué. La valeur par défaut est dtgvp. Voici la liste des différentes étapes disponibles :

Crée les tables pgbench_accounts, pgbench_tellers et pgbench_branches avec le facteur de remplissage (fillfactor) spécifié. La valeur par défaut est 100.

Ne réalise pas de VACUUM après l'initialisation. (Cette option supprime l'étape d'initialisation v, même si elle était précisée dans -I.)

Passe du mode verbeux au mode silencieux, en n'affichant qu'un message toutes les 5 secondes. Par défaut, on affiche un message toutes les 100 000 lignes, ce qui engendre souvent plusieurs lignes toutes les secondes (particulièrement sur du bon matériel)

Ce paramètre n'a pas d'effet si G est spécifié dans l'option -I.

Multiplie le nombre de lignes générées par le facteur d'échelle (scale factor). Par exemple, -s 100 va créer 10 millions de lignes dans la table pgbench_accounts. La valeur par défaut est 1. Lorsque l'échelle dépasse 20 000, les colonnes utilisées pour contenir les identifiants de compte (colonnes aid) vont être converties en grands entiers (bigint), de manière à être suffisamment grandes pour contenir l'espace des identifiants de compte.

Crée des contraintes de type clé étrangère entre les tables standards. (Cette option ajoute l'étape d'initialisation f, si elle n'est pas déjà présente.)

Crée un index dans le tablespace spécifié plutôt que dans le tablespace par défaut.

Crée une table partitionnée pgbench_accounts par la méthode NOM. Les valeurs attendues sont range ou hash. Cette option nécessite que --partitions soit différente de zéro. Sans précision, le défaut est range.

Crée une table partitionnée pgbench_accounts avec NUM partitions de taille à peu près égale pour le nombre de clients indiqué par l'échelle. Le défaut est 0, ce qui signifie qu'il n'y a pas de partitionnement.

Crée une table dans le tablespace spécifié plutôt que dans le tablespace par défaut.

Crée toutes les tables en tant que tables non journalisées (unlogged tables) plutôt qu'en tant que tables permanentes.

Ajoute le script interne spécifié à la liste des scripts à exécuter. Les scripts internes disponibles sont tpcb-like, simple-update et select-only. L'utilisation des préfixes non ambigus des noms de scripts internes est acceptée. En utilisant le nom spécial list, la commande affiche la liste des scripts internes, puis quitte immédiatement.

En option, il est possible d'écrire un poids en entier après @ pour ajuster la probabilité de sélectionner ce script plutôt que les autres. Le poids par défaut est de 1. Voir ci-dessous pour les détails.

Nombre de clients simulés, c'est-à-dire le nombre de sessions concurrentes sur la base de données. La valeur par défaut est à 1.

Établit une nouvelle connexion pour chaque transaction, plutôt que de ne le faire qu'une seule fois par session cliente. C'est une option très utile pour mesurer la surcharge engendrée par la connexion.

Définit une variable à utiliser pour un script personnalisé Voir ci-dessous pour plus de détails. Il est possible d'utiliser plusieurs fois l'option -D.

Ajoute un script de transactions nommé nom_fichier à la liste des scripts à exécuter.

En option, il est possible d'écrire un poids sous la forme d'un entier après le symbole @ pour ajuster la probabilité de sélectionner ce script plutôt qu'unautre. Le poids par défaut est de 1. (Pour utiliser un nom de fichier incluant un caractère @, ajoutez un poids pour qu'il n'y ait pas d'ambiguité, par exemple filen@me@1.) Voir ci-dessous pour les détails.

Nombre de processus utilisés dans pgbench. Utiliser plus d'un thread peut être utile sur des machines possédant plusieurs cœurs. Les clients sont distribués de la manière la plus uniforme possible parmi les threads. La valeur par défaut est 1.

Rapporte les informations sur chaque transaction dans un fichier journal. Voir ci-dessous pour plus de détails.

Les transactions durant plus de limite millisecondes sont comptabilisée et rapportées séparément en tant que late.

Lorsqu'un bridage est spécifié (--rate=... ), les transactions accusant un retard sur la planification supérieur à limite millisecondes, et donc sans aucune chance de respecter la limite de latence, ne sont pas du tout envoyées au serveur. Elles sont comptabilisées et rapportées séparément en tant que skipped (ignorées).

Avec l'option --max-tries, une transaction échouée à cause d'une anomalie de sérialisation ou d'un deadlock ne sera pas retentée si le temps cumulé de ses tentatives dépasse limit ms. Pour ne limiter que la durée des tentatives et non leur nombre, utiliser --max-tries=0. Par défaut, --max-tries vaut 1, et les transactions en erreur à cause de la sérialisation ou d'un deadlock ne sont pas retentées. Voir Failures and Serialization/Deadlock Retries pour plus de détails sur comment retenter de telles transactions.

Protocole à utiliser pour soumettre des requêtes au serveur :

Comme dans le mode prepared, pgbench réutilise le résultat de l'analyse pour la deuxième itération et les suivantes, pgbench s'exécute plus rapidement dans le mode prepared que dans les autres modes.

Par défaut, le protocole de requête standard est utilisé (voir Chapitre 53 pour plus d'informations).

Ne réalise pas de VACUUM avant de lancer le test. Cette option est nécessaire si vous lancez un scénario de test personnalisé qui n'utilise pas les tables standards pgbench_accounts, pgbench_branches, pgbench_history et pgbench_tellers .

Exécute le script interne simple-update. Raccourci pour -b simple-update.

Affiche un rapport de progression toutes les sec secondes. Ce rapport inclut la durée du test, le nombre de transactions par seconde depuis le dernier rapport et la latence moyenne des transactions, ainsi que la déviation et le nombre de transactions échouées depuis le dernier rapport. Avec le bridage (option -R), la latence est calculée en fonction de la date de démarrage ordonnancée de la transaction et non de son temps de démarrage réel, donc elle inclut aussi la latence moyenne du temps d'ordonnancement. Si --max-tries est utilisée pour autoriser de nouvelles tentatives après des erreurs de sérialisation ou des deadlocks, le rapport inclut le nombre de transactions retentées et la somme de tous les nouveaux essais.

Affiche les statistiques suivantes pour chaque commande après la fin du benchmark : latence moyenne par requête (temps d'exécution du point de vue du client), nombre d'échecs après des erreurs de sérialisation ou des deadlocks, et le nombre de nouvelles tentatives après cela. Le rapport affiche les statistiques sur les nouveaux essais uniquement si --max-tries n'est pas égal à 1.

Exécute les transactions en visant le débit spécifié, au lieu d'aller le plus vite possible (le défaut). Le débit est donné en transactions par seconde. Si le débit visé est supérieur au maximum possible, la limite de débit n'aura aucune influence sur le résultat.

Pour atteindre ce débit, les transactions sont ordonnancées avec une distribution suivant une loi de Poisson. La date de démarrage prévue se calcule depuis le moment où le client a démarré et pas depuis le moment où la dernière transaction s'est achevée. Cette approche signifie que, si une transaction dépasse sa date de fin prévue, un rattrapage est encore possible pour les suivantes.

Lorsque le bridage est actif, la latence de la transaction rapportée en fin de test est calculée à partir des dates de démarrage ordonnancées, c'est-à-dire qu'elle inclut le temps où chaque transaction attend que la précédente se termine. Le temps d'attente est appelé temps de latence d'ordonnancement, et ses valeurs moyenne et maximum sont rapportées séparément. La latence de transaction par rapport au temps de démarrage réel, c'est-à-dire le temps d'exécution de la transaction dans la base, peut être récupérée en soustrayant le temps de latence d'ordonnancement à la latence précisée dans les journaux.

Si l'option --latency-limit est utilisée avec l'option --rate, une transaction peut avoir une telle latence qu'elle serait déjà supérieure à limite de latence lorsque la transaction précédente se termine, car la latence est calculée au moment de la date de démarrage planifiée. Les transactions concernées ne sont pas envoyées à l'instance, elles sont complètement ignorées et comptabilisées séparément.

Une latence de planification élevée est une indication que le système n'arrive pas à traiter les transactions à la vitesse demandée, avec les nombres de clients et threads indiqués. Lorsque le temps moyen d'exécution est plus important que l'intervalle prévu entre chaque transaction, les transactions vont prendre du retard une-à-une, et la latence de planification va continuer de croître tout le long de la durée du test. Si cela se produit, vous devrez réduire le taux de transaction que vous avez spécifié.

Affiche le facteur d'échelle dans la sortie de pgbench. Avec les tests internes, ce n'est pas nécessaire ; le facteur d'échelle approprié sera détecté en comptant le nombre de lignes dans la table pgbench_branches. Toutefois, lors de l'utilisation d'un benchmark avec un scénario personnalisé (option -f), le facteur d'échelle sera affiché à 1 à moins que cette option soit utilisée.

Exécute le script interne select-only. Raccourci pour -b select-only.

Nombre de transactions lancées par chaque client. La valeur par défaut est 10.

Lance le test pour la durée spécifiée en secondes, plutôt que pour un nombre fixe de transactions par client. Les options -t et -T ne sont pas compatibles.

Réalise un VACUUM sur les quatre tables standards avant de lancer le test. Sans l'option -n ou -v, pgbench lancera un VACUUM sur les tables pgbench_tellers et pgbench_branches, puis tronquera pgbench_history.

Taille de l'intervalle d'agrégation (en secondes). Ne peut être utilisée qu'avec l'option -l. Avec cette option, le journal contiendra des résumés par intervalle, comme décrit ci-dessous.

Quitte imméditament quand un client abandonne à cause d'une erreur. Sans cette option, quand un client est abandonné, les autres clients continuent leur exécution comme indiqué par les options -t ou -T, et pgbench affichera un résultat incomplet dans ce cas.

Notez que les échecs de sérialisation et de deadlock ne provoquent pas l'abandon du client, donc ils ne sont pas affectés par cette option. Voir Failures and Serialization/Deadlock Retries pour plus d'informations.

Dans les traces, par transaction et agrégées, et les rapports manuels et par script, affiche les erreurs regroupées selon les types suivants :

Voir Failures and Serialization/Deadlock Retries pour plus d'informations.

Définit le préfixe des fichiers logs créés par --log. Le défaut est pgbench_log.

Autorise de nouvelles tentatives dans les transactions avec des erreurs de sérialisation ou de verrous mortels, et définit le nombre maximum de ces tentatives. Cette option peut être combinée avec --latency-limit, qui limite le temps total de toutes les tentatives de transactions ; cependant vous ne pouvez définir un nombre illimité de tentatives (--max-tries=0) sans définir --latency-limit ou --time. La valeur par défaut est 1, et les transactions avec des erreurs de sérialisation ou des deadlocks ne sont donc pas retentées. Voir Failures and Serialization/Deadlock Retries pour plus de détails sur les nouvelles tentatives sur de telles transactions.

Lorsque la progression est affichée (option -P), utilise un horodatage de type timestamp (epoch Unix) au lieu d'un nombre de secondes depuis le début de l'exécution. L'unité est la seconde avec une précision en millisecondes après le point. Ceci aide à comparer les traces générées par différents outils.

Fournit la graine du générateur de nombres aléatoires, qui produira alors une séquence d'états initiaux du générateur, un pour chaque thread. Les valeurs pour graine peuvent être time (par défaut, la graine est basée sur l'heure en cours), rand (utilise une source fortement aléatoire, et tombe en échec si aucune n'est disponible), ou une valeur entière non signée. Le générateur aléatoire est appelé depuis un script pgbench explicitement (fonctions random...) ou implicitement (par exemple l'option --rate l'utilise pour planifier les transactions). Si elle est mise en place explicitement, la valeur utilisée comme graine est affichée sur le terminal. N'importe quelle valeur autorisée pour graine peut aussi être fournie par la variable d'environnement PGBENCH_RANDOM_SEED. Pour garantir que la graine fournie couvre tous les cas d'usage possibles, mettez cette fonction en premier ou utilisez la variable d'environnement.

Placer cette variable explicitement permet de reproduire un run pgbench exactement identique, du moins en ce qui concerne les nombres aléatoires. Comme l'état du générateur aléatoire est géré par thread, pgbench s'exécutera à l'identique s'il y a un client par thread et pas de dépendance externe ou par rapport aux données. D'un point de vue statistique, reproduire des runs est une mauvaise idée, car cela peut masquer la variabilité des performances ou améliorer les performances excessivement, par exemple en appelant les mêmes pages qu'un run précédent. Cependant, ce peut être d'une grande aide pour déboguer, par exemple pour reproduire un cas tordu provoquant une erreur. À utiliser judicieusement.

Taux d'échantillonnage utilisé lors de l'écriture des données dans les journaux, afin d'en réduire la quantité. Si cette option est utilisée, n'y sera écrite que la proportion indiquée des transactions. 1.0 signifie que toutes les transactions seront journalisées, 0.05 signifie que 5 % de toutes les transactions le seront.

Pensez à prendre le taux d'échantillonnage en compte en consultant le journal. Par exemple, lorsque vous évaluez le nombre de transactions par seconde, vous devrez multiplier les nombres en conséquence. (Par exemple, avec un taux d'échantillonnage de 0,01, vous n'obtiendrez que 1/100è du débit réel).

Affiche le code réel du script intégré scriptname sur stderr, et quitte immédiatement.

Affiche des messages sur toutes les erreurs et échecs (les erreurs sans nouvelles tentatives), et mentionne quelle limite a été dépassée, et de combien, pour les échecs lors d'erreurs de sérialisation ou des deadlocks. (Notez que dans ce cas le débit peut être significativement amélioré.) Voir Failures and Serialization/Deadlock Retries pour plus d'informations.

Affiche les informations de debug.

Le nom du serveur de base de données

Le port d'écoute de l'instance sur le serveur de base de données

Le nom de l'utilisateur avec lequel on se connecte

Affiche la version de pgbench puis quitte.

Affiche l'aide sur les arguments en ligne de commande de pgbench puis quitte.

Cette commande peut être utilisée pour marquer la fin de requêtes SQL, prenant ainsi la place du point-virgule final (;).

Quand la commande \gset est utilisée, la requête SQL précédente doit renvoyer une ligne. Les valeurs de ses colonnes sont enregistrées dans des variables nommées d'après les noms de colonnes, préfixées avec prefix, si ce dernier est fourni.

Quand la commande \aset est utilisée, toutes les requêtes (séparées par \;) voient leurs colonnes stockées dans des variables nommées d'après elles, préfixées de prefix s'il est fourni. Si une requête ne retourne aucune ligne, aucune affectation n'est faite. On peut tester l'existence de la variable pour détecter ce cas. Si une requête retourne plus d'une ligne, la dernière valeur est conservée.

\gset et \aset ne peuvent être utilisées en mode pipeline, puisque les résultats des requêtes ne sont pas encore disponibles au moment où la commande en a besoin.

L'exemple suivant place la balance finale du compte provenant de la première requête dans la variable abalance, et remplit les variables p_two et p_three avec les entiers provenant de la troisième requête. Le résultat de la deuxième requête est ignoré. Les résultats des deux dernières requêtes combinées sont stockés dans les variables four et five.

UPDATE pgbench_accounts
  SET abalance = abalance + :delta
  WHERE aid = :aid
  RETURNING abalance \gset
-- compound of two queries
SELECT 1 \;
SELECT 2 AS two, 3 AS three \gset p_
SELECT 4 AS four \; SELECT 5 AS five \aset
       

Ce groupe de commandes implémente des blocs conditionnels imbriquables, de manière similaire au \if expression de psql. Les expressions conditionnelles sont identiques à celles avec \set, les valeurs autres que zéro valant true.

Définit la variable nom_variable à une valeur définie par expression. L'expression peut contenir la constante NULL, les constantes booléennes TRUE et FALSE, des constantes entières comme 5432, des constantes double précision comme 3.14159, des références à des variables :nomvariable, des opérateurs avec leur priorité et leur associativité habituelles en SQL, des appels de fonction, des expressions conditionnelles génériques SQL avec CASE et des parenthèses.

Les fonctions et la plupart des opérateurs retournent NULL en cas d'entrée à NULL.

En ce qui concerne les conditions, les valeurs numériques différentes de zéro valent TRUE, les valeurs numériques à zéro et NULL sont FALSE.

Des constantes entières ou à virgule flottante ainsi que des opérateurs arithmétiques entiers (+, -, * et /), trop larges ou trop petites, renvoient des erreurs de dépassement.

Quand aucune clause finale ELSE n'est fournie à un CASE, la valeur par défaut est NULL.

Exemples :

\set ntellers 10 * :scale
\set aid (1021 * random(1, 100000 * :scale)) % \
           (100000 * :scale) + 1
\set divx CASE WHEN :x <> 0 THEN :y/:x ELSE NULL END
       

Entraîne la suspension de l'exécution du script pendant la durée spécifiée en microsecondes (us), millisecondes (ms) ou secondes (s). Si l'unité n'est pas définie, l'unité par défaut est la seconde. Ce peut être soit un entier constant, soit une référence :nom_variable vers une variable retournant un entier.

Exemple :

\sleep 10 ms
       

Définit la variable nom_variable comme le résultat d'une commande shell nommée commande aves le(s) argument(s) donné(s). La commande doit retourner un entier sur la sortie standard.

commande et chaque argument peuvent être soit une constante de type text, soit une référence :nom_variable à une variable. Si vous voulez utiliser un argument commençant avec un symbole deux-points, écrivez un deux-points supplémentaire au début de l'argument.

Exemple :

\setshell variable_à_utiliser commande argument_litéral :variable
::literal_commencant_avec_deux_points
       

Identique à \setshell, mais le résultat de la commande sera ignoré.

Exemple :

\shell command literal_argument :variable ::literal_starting_with_colon
       

Ce groupe de commandes implémente un pipeline de requêtes SQL. Un pipeline doit commencer avec \startpipeline et terminer avec \endpipeline. Entre les deux, il peut y avoir plusieurs commandes \syncpipeline qui envoie un message de synchronisation sans terminer le pipeline en cours et sans vide le buffer d'envoi. Dans le mode pipeline, les requêtes sont envoyées au serveur sans attendre le résultat des requêtes précédentes. Voir Section 32.5 pour plus de détails. Le mode pipeline impose l'utilisation du protocole de requête étendu.

identifie la session client qui a exécuté la transaction

décompte les transactions exécutées par cette session

temps déroulé pour la transaction, en microsecondes

identifie le fichier script utilisé par la transaction (utile quand plusieurs scripts ont été fournis avec -f ou -b)

horodatage de la fin de la transaction (époque Unix)

fraction de seconde de la durée de la transaction, en microsecondes

délai au démarrage de de la transaction, c'est-à-dire la différence entre le moment prévu du démarrage et le moment où elle a réellement démarré, en microsecondes (n'est présent que si --rate est précisé)

nombre des nouvelles tentatives après des erreurs de sérialisation et des deadlocks pendant la transaction (n'est présent que si --max-tries n'est pas à 1)

horodatage du démarrage de l'intervalle (époque Unix)

nombre de transactions au sein de l'intervalle

somme des latences de transaction

somme des carrés des latences de transaction

minimum des latences de transaction

maximum des latences de transaction

somme des délais de démarrage des transactions (zéro, à moins que --rate soit renseigné)

somme des carrés des délais de démarrage des transactions (zéro, à moins que --rate soit renseigné)

minimum des délais de démarrage des transactions (zéro, à moins que --rate soit renseigné)

maximum des délais de démarrage des transactions (zéro, à moins que --rate soit renseigné)

nombre de transactions passées car elles auraient démarré trop tard (zéro, à moins que --rate et --latency-limit soient renseignés)

nombre de transactions retentées (zéro, à moins que --max-tries soit différent de 1)

nombre de transactions retentées après des erreurs de sérialisation ou des deadlocks (zéro, à moins que --max-tries soit différent de 1)

nombre de transactions ayant obtenu une erreur de sérialisation et non retentées ensuite (zéro, à moins que --failures-detailed soit précisé)

nombre de transactions ayant obtenu une erreur à cause d'un deadlock et non retentées ensuite (zéro, à moins que --failures-detailed soit précisé)