1、pgbench 文法參數解釋
1.1、基礎文法
pgbench --help
pgbench is a benchmarking tool for PostgreSQL.
Usage:
pgbench [OPTION]... [DBNAME]
Initialization options:
-i, --initialize invokes initialization mode
-I, --init-steps=[dtgvpf]+ (default "dtgvp")
run selected initialization steps
-F, --fillfactor=NUM set fill factor
-n, --no-vacuum do not run VACUUM during initialization
-q, --quiet quiet logging (one message each 5 seconds)
-s, --scale=NUM scaling factor
--foreign-keys create foreign key constraints between tables
--index-tablespace=TABLESPACE
create indexes in the specified tablespace
--tablespace=TABLESPACE create tables in the specified tablespace
--unlogged-tables create tables as unlogged tables
Options to select what to run:
-b, --builtin=NAME[@W] add builtin script NAME weighted at W (default: 1)
(use "-b list" to list available scripts)
-f, --file=FILENAME[@W] add script FILENAME weighted at W (default: 1)
-N, --skip-some-updates skip updates of pgbench_tellers and pgbench_branches
(same as "-b simple-update")
-S, --select-only perform SELECT-only transactions
(same as "-b select-only")
Benchmarking options:
-c, --client=NUM number of concurrent database clients (default: 1)
-C, --connect establish new connection for each transaction
-D, --define=VARNAME=VALUE
define variable for use by custom script
-j, --jobs=NUM number of threads (default: 1)
-l, --log write transaction times to log file
-L, --latency-limit=NUM count transactions lasting more than NUM ms as late
-M, --protocol=simple|extended|prepared
protocol for submitting queries (default: simple)
-n, --no-vacuum do not run VACUUM before tests
-P, --progress=NUM show thread progress report every NUM seconds
-r, --report-latencies report average latency per command
-R, --rate=NUM target rate in transactions per second
-s, --scale=NUM report this scale factor in output
-t, --transactions=NUM number of transactions each client runs (default: 10)
-T, --time=NUM duration of benchmark test in seconds
-v, --vacuum-all vacuum all four standard tables before tests
--aggregate-interval=NUM aggregate data over NUM seconds
--log-prefix=PREFIX prefix for transaction time log file
(default: "pgbench_log")
--progress-timestamp use Unix epoch timestamps for progress
--random-seed=SEED set random seed ("time", "rand", integer)
--sampling-rate=NUM fraction of transactions to log (e.g., 0.01 for 1%)
Common options:
-d, --debug print debugging output
-h, --host=HOSTNAME database server host or socket directory
-p, --port=PORT database server port number
-U, --username=USERNAME connect as specified database user
-V, --version output version information, then exit
-?, --help show this help, then exit
1.2、初始化選項
pgbench接受下列指令行初始化參數:
-i
--initialize
要求調用初始化模式。
-I init_steps
--init-steps=init_steps
隻執行選出的一組普通初始化步驟。init_steps指定要被執行的初始化步驟,每一個步驟使用一個字元代表。每一個步驟都以指定的順序被調用。預設是dtgvp。可用的步驟是:
d(删除)
删除任何已有的pgbench表。
t(建立表)
建立标準pgbench場景使用的表,即pgbench_accounts、pgbench_branches、pgbench_history以及pgbench_tellers。
g(生成資料)
生成資料并且裝入到标準的表中,替換掉已經存在的任何資料。
v(清理)
在标準的表上調用VACUUM。
p(建立主鍵)
在标準的表上建立主鍵索引。
f(建立外鍵)
在标準的表之間建立外鍵限制(注意這一步預設不會被執行)。
-F fillfactor
--fillfactor=fillfactor
用給定的填充因子建立表pgbench_accounts、pgbench_tellers以及pgbench_branches。預設是100。
-n
--no-vacuum
在初始化期間不執行清理(這個選項會抑制v初始化步驟,即便在-I中指定了該步驟)。
-q
--quiet
把記錄切換到安靜模式,隻是每 5 秒産生一個進度消息。預設的記錄會每 100000 行列印一個消息,這經常會在每秒鐘輸出很多行(特别是在好的硬體上)。
-s scale_factor
--scale=scale_factor
将生成的行數乘以比例因子。例如,-s 100将在pgbench_accounts表中建立 10,000,000 行。預設為 1。當比例為 20,000 或更高時,用來儲存賬号辨別符的列(aid列)将切換到使用更大的整數(bigint),這樣才能足以儲存賬号辨別符。
--foreign-keys
在标準的表之間建立外鍵限制(如果f在初始化步驟序列中不存在,這個選項會把它加入)。
--index-tablespace=index_tablespace
在指定的表空間而不是預設表空間中建立索引。
--tablespace=tablespace
在指定的表空間而不是預設表空間中建立表。
--unlogged-tables
把所有的表建立為非日志記錄表而不是永久表。
1.3、基準選項
pgbench接受下列指令行基準參數:
-b scriptname[@weight]
--builtin=scriptname[@weight]
把指定的内建腳本加入到要執行的腳本清單中。@之後是一個可選的整數權重,它允許調節抽取該腳本的可能性。如果沒有指定,它會被設定為 1。可用的内建腳本有:tpcb-like、simple-update和select-only。這裡也接受内建名稱無歧義的字首縮寫。如果用上特殊的名字list,将會顯示内建腳本的清單并且立刻退出。
-c clients
--client=clients
模拟的用戶端數量,也就是并發資料庫會話數量。預設為 1。
-C
--connect
為每一個事務建立一個新連接配接,而不是隻為每個用戶端會話建立一個連接配接。這對于度量連接配接開銷有用。
-d
--debug
列印調試輸出。
-D varname=value
--define=varname=value
定義一個由自定義腳本(見下文)使用的變量。允許多個-D選項。
-f filename[@weight]
--file=filename[@weight]
把一個從filename讀到的事務腳本加入到被執行的腳本清單中。@後面是一個可選的整數權重,它允許調節抽取該測試的可能性。詳見下文。
-j threads
--jobs=threads
pgbench中的工作者線程數量。在多 CPU 機器上使用多于一個線程會有用。用戶端會盡可能均勻地分布到可用的線程上。預設為 1。
-l
--log
把與每一個事務相關的資訊寫到一個日志檔案中。詳見下文。
-L limit
--latency-limit=limit
對持續超過limit毫秒的事務進行獨立的計數和報告, 這些事務被認為是遲到(late)了的事務。
在使用限流措施時(--rate=...),滞後于計劃超過 limit毫秒并且是以沒有希望滿足延遲限制的事務根本 不會被發送給伺服器。這些事務被認為是被跳過(skipped) 的事務,它們會被單獨計數并且報告。
-M querymode
--protocol=querymode
要用來送出查詢到伺服器的協定:
simple:使用簡單查詢協定。
extended使用擴充查詢協定。
prepared:使用帶預備語句的擴充查詢語句。
在prepared模式中,pgbench重用從第二次查詢疊代開始的文法分析結果,是以pgbench運作速度比其他模式快。
預設是簡單查詢協定(詳見第 52 章)。
在運作測試前不進行清理。如果你在運作一個不包括标準的表pgbench_accounts、 pgbench_branches、pgbench_history和 pgbench_tellers的自定義測試場景時,這個選項是必需的。
-N
--skip-some-updates
運作内建的簡單更新腳本。這是-b simple-update的簡寫。
-P sec
--progress=sec
每sec秒顯示進度報告。該報告包括運作了多長時間、從上次報告以來的 tps 以及從上次報告以來事務延遲的平均值和标準偏差。如果低于限流值(-R),延遲會相對于事務預定的開始時間(而不是實際的事務開始時間)計算,是以其中也包括了平均排程延遲時間。
-r
--report-latencies
在基準結束後,報告平均的每個指令的每語句等待時間(從用戶端的角度來說是執行時間)。詳見下文。
-R rate
--rate=rate
按照指定的速率執行事務而不是盡可能快地執行(預設行為)。該速率 以 tps(每秒事務數)形式給定。如果目标速率高于最大可能速率,則 該速率限制不會影響結果。
該速率的目标是按照一條泊松分布的排程時間線開始事務。期望的開始 時間表會基于用戶端第一次開始的時間(而不是上一個事務結束的時 間)前移。這種方法意味着當事務超過它們的原定結束時間時,更遲的 那些有機會再次追趕上來。
當限流措施被激活時,運作結束時報告的事務延遲是從預訂的開始時間計 算而來的,是以它包括每一個事務不得不等待前一個事務結束所花的時 間。該等待時間被稱作排程延遲時間,并且它的平均值和最大值也會被 單獨報告。關于實際事務開始時間的事務延遲(即在資料庫中執行事務 所花的時間)可以用報告的延遲減去排程延遲時間計算得到。
如果把--latency-limit和--rate一起使用, 當一個事務在前一個事務結束時已經超過了延遲限制時,它可能會滞後 非常多,因為延遲是從計劃的開始時間計算得來。這類事務不會被發送 給伺服器,而是一起被跳過并且被單獨計數。
一個高的排程延遲時間表示系統無法用標明的用戶端和線程數按照指定 的速率處理事務。當平均的事務執行時間超過每個事務之間的排程間隔 時,每一個後續事務将會落後更多,并且随着測試運作時間越長,排程 延遲時間将持續增加。發生這種情況時,你将不得不降低指定的事務速率。
在pgbench的輸出中報告指定的比例因子。對于内建測試,這并非必需;正确的比例因子将通過對pgbench_branches表中的行計數來檢測。不過,當隻測試自定義基準(-f選項)時,比例因子将被報告為 1(除非使用了這個選項)。
-S
--select-only
執行内建的隻有選擇的腳本。是-b select-only簡寫形式。
-t transactions
--transactions=transactions
每個用戶端運作的事務數量。預設為 10。
-T seconds
--time=seconds
運作測試這麼多秒,而不是為每個用戶端運作固定數量的事務。-t和-T是互斥的。
-v
--vacuum-all
在運作測試前清理所有四個标準的表。在沒有用-n以及-v時, pgbench将清理pgbench_tellers 和pgbench_branches表,并且截斷pgbench_history。
--aggregate-interval=seconds
聚集區間的長度(機關是秒)。僅可以與-l選項一起使用。通過這個選項,日志會包含針對每個區間的概要資料,如下文所述。
--log-prefix=prefix
設定--log建立的日志檔案的檔案名字首。預設是pgbench_log。
--progress-timestamp
當顯示進度(選項-P)時,使用一個時間戳(Unix 時間)取代從運作開始的秒數。機關是秒,在小數點後是毫秒精度。這可以有助于比較多種工具生成的日志。
--random-seed=SEED
設定随機數生成器種子。為系統的随機數生成器提供種子,然後随機數生成器會産生一個初始生成器狀态序列,每一個線程一個狀态。SEED的值可以是:time(預設值,種子基于目前時間)、rand(使用一種強随機源,如果沒有可用的源則失敗)或者一個無符号十進制整數值。一個pgbench腳本中會顯式(random...函數)地或者隐式地(如--rate使用随機數生成器排程事務)調用随機數生成器。在被明确設定時,用作種子的值會顯示在終端上。 還可以通過環境變量PGBENCH_RANDOM_SEED提供用于SEED的值。為了確定所提供的種子影響所有可能的使用,把這個選項放在第一位或者使用環境變量。
明确地設定種子允許準确地再生一個pgbench運作,對随機數而言。因為随機狀态是針對每個線程管理,這意味着如果每一個線程有一個用戶端并且沒有外部或者資料依賴,則對于一個相同的調用就會有完全相同的pgbench運作。從一種統計的角度來看,再生運作不是什麼好主意,因為它能隐藏性能可變性或者不正當地改進性能,即通過命中前一次運作的相同頁面來改進性能。不過,它也可以對調試起到很大幫助作用,例如重新運作一種導緻錯誤的棘手用例。請善用。
--sampling-rate=rate
采樣率,在寫入資料到日志時被用來減少日志産生的數量。如果給出這個選項,隻有指定比例的事務被記錄。1.0 表示所有事務都将被記錄,0.05 表示隻有 5% 的事務會被記錄。
在處理日志檔案時,記得要考慮這個采樣率。例如,當計算TPS值時,你需要相應地乘以這個數字(例如,采樣率是 0.01,你将隻能得到實際TPS的 1/100)。
1.4、普通選項
pgbench接受下列指令行普通參數:
-h hostname
--host=hostname
資料庫伺服器的主機名
-p port
--port=port
資料庫伺服器的端口号
-U login
--username=login
要作為哪個使用者連接配接
-V
--version
列印pgbench版本并退出。
-?
--help
顯示有關pgbench指令行參數的資訊,并且退出。
1.5、在pgbench中實際執行的事務
pgbench執行從指定清單中随機選中的測試腳本。它們包括帶有-b的内建腳本和帶有-f的使用者提供的自定義腳本。每一個腳本可以在其後用@指定一個相對權重,這樣可以更改該腳本的抽取機率。預設權重是1。權重為0的腳本會被忽略。
預設的内建事務腳本(也會被-b tpcb-like調用)會在每個事務上發出七個從aid、tid、bid和delta中随機選擇的指令。該場景來自于 TPC-B 基準,但并不是真正的 TPC-B,隻是名字像而已。
BEGIN;
UPDATE pgbench_accounts SET abalance = abalance + :delta WHERE aid = :aid;
SELECT abalance FROM pgbench_accounts WHERE aid = :aid;
UPDATE pgbench_tellers SET tbalance = tbalance + :delta WHERE tid = :tid;
UPDATE pgbench_branches SET bbalance = bbalance + :delta WHERE bid = :bid;
INSERT INTO pgbench_history (tid, bid, aid, delta, mtime) VALUES (:tid, :bid, :aid, :delta, CURRENT_TIMESTAMP);
END;
如果選擇simple-update内建腳本(還有-N),第 4 和 5 步不會被包括在事務中。這将避免更新那些表中的内容,但是它會讓該測試用例更不像 TPC-B。
如果選擇select-only内建腳本(還有-S),隻會發出SELECT。