{"Entry":{"collection":"guc","key":"max_pred_locks_per_relation","name":"max_pred_locks_per_relation","aliases":[],"metadata":{"baseline":false,"boot_human":"Not specified","boot_val":null,"category":"Lock Management","category_zh":"","changed_in":[],"changes":[{"documentation_changed":false,"fields":{},"from":"9.6","status":"added","to":"10"}],"content_hash":"1b58bad054ef5d8fd3d95dc9e3b6181d9d4f00f7a72c7ea3e25030fba19153c9","context":"","default_changed_in":[],"default_history":[{"from":"10","to":"19","value":"-2"}],"derived_content_hash":"8f71156bad5e75578bdce0898a3224ce554d416143bd6be6fc58d34fb4e61ae1","editorial":{"advice":{"olap":"Partitioned queries, bulk DDL, and SERIALIZABLE reports may touch many objects; test the worst plan, not only an average transaction.","oltp":"Calibrate max_pred_locks_per_relation from lock-wait logs, objects touched, and the concurrency bound. Fix long transactions and access ordering before adding shared memory or changing detection granularity.","small":"Defaults are usually sufficient. If raising a startup lock-table setting, account for max_connections, prepared transactions, and standby consistency together."},"mechanism":["Sets the maximum number of predicate-locked pages and tuples per relation. A configuration reload applies a new value; existing work already in flight is not retroactively changed.","SSI promotes page/tuple predicate locks to one relation-level lock at this threshold. A negative value means max_pred_locks_per_transaction divided by its absolute value; promotion changes granularity, not SQL lock strength.","Monitor and change max_pred_locks_per_relation together with max_pred_locks_per_transaction, max_pred_locks_per_page, default_transaction_isolation. Validate on the relevant server role and real workload, then use its sighup context to choose session change, reload, or restart; a historical boot default is not the current effective value."],"pitfalls":["Reading an average shared-memory sizing value as a hard per-transaction limit.","Raising it without the multiplier from connections and prepared transactions.","Expanding lock memory instead of fixing long transactions, access order, or partition explosion.","Ignoring compatible startup lock capacity on standbys."],"references":[{"title":"PostgreSQL 19 Beta 4: max_pred_locks_per_relation","url":"https://www.postgresql.org/docs/19/runtime-config-locks.html#GUC-MAX-PRED-LOCKS-PER-RELATION"},{"title":"PostgreSQL 19 release notes","url":"https://www.postgresql.org/docs/19/release-19.html"}],"related":["max_pred_locks_per_transaction","max_pred_locks_per_page","default_transaction_isolation","max_locks_per_transaction","deadlock_timeout"],"summary":"max_pred_locks_per_relation — Sets the maximum number of predicate-locked pages and tuples per relation. Observed in PG10–19 Beta 4; its last measured boot default is -2 in PG19 Beta 4, with sighup context. This is a beta-snapshot fact and can change before PostgreSQL 19 GA."},"enumvals":[],"first_version":"10","group":"Lock Management","group_slug":"locks","imported_at":"2026-09-27T17:57:31.723144+08:00","intro_commit":{"authored_at":"2017-04-07T21:38:05-05:00","discussion":[],"hash":"c63172d60f242ad3581c83723a5b315bbe547a0e","subject":"Add GUCs for predicate lock promotion thresholds.","url":"https://git.postgresql.org/gitweb/?p=postgresql.git;a=commit;h=c63172d60f242ad3581c83723a5b315bbe547a0e"},"key":"max_pred_locks_per_relation","last_version":"20","max_val":"","min_val":"","name":"max_pred_locks_per_relation","position":278,"present_in":["10","11","12","13","14","15","16","17","18","19","20"],"repair_provenance":{"original_source_revision":"english-manuals:0846f83420f543293f9d9f72c0d575c01dacf7224f309f4c93847181fffc3aa5","receipt_sha256":"5a4e899c285e4152c99b60f71bd87b0e25e229eae7473f6eaa073d7281e2b315","repair":"wiki-repair-20261023"},"short_desc":"This controls how many pages or tuples of a single relation can be predicate-locked before the lock is promoted to covering the whole relation.","short_desc_zh":"","source_rev":"wiki-repair-20261023:49b4a3952757dffa03d9b3b485a11e1450698b8c06c3dda33b885764811d68d1","unit":"","vartype":"integer"}},"Definition":{"Collection":"guc","Key":"max_pred_locks_per_relation","SourceDatabase":"center","Version":"18","SourceTable":"guc","SourceKey":"max_pred_locks_per_relation","SourceRevision":"wiki-repair-20261023:49b4a3952757dffa03d9b3b485a11e1450698b8c06c3dda33b885764811d68d1","Facts":{"boot_val":"-2","category":"Lock Management","context":"sighup","description":"This controls how many pages or tuples of a single relation can be predicate-locked before the lock is promoted to covering the whole relation. Values greater than or equal to zero mean an absolute limit, while negative values mean max_pred_locks_per_transaction divided by the absolute value of this setting. The default is -2, which keeps the behavior from previous versions of PostgreSQL. This parameter can only be set in the postgresql.conf file or on the server command line.","description_zh":"这个参数控制在谓词锁被提升为覆盖整个关系之前，可以对单个关系中的多少页面或元组加谓词锁。大于等于零的值表示一种绝对限制，而负值表示用 max_pred_locks_per_transaction 除以这个设置的绝对值。默认值为-2，它将保持以往版本的 PostgreSQL 中的行为。这个参数只能在 postgresql.conf 文件中或者服务器命令行上设置。","description_zh_html":"\u003cp\u003e\n        这个参数控制在谓词锁被提升为覆盖整个关系之前，可以对单个关系中的多少页面或元组加谓词锁。大于等于零的值表示一种绝对限制，而负值表示用 \u003ca class=\"xref\" href=\"/zh/docs/18/runtime-config-locks.html#GUC-MAX-PRED-LOCKS-PER-TRANSACTION\"\u003emax_pred_locks_per_transaction\u003c/a\u003e 除以这个设置的绝对值。默认值为-2，它将保持以往版本的 \u003cspan class=\"productname\"\u003ePostgreSQL\u003c/span\u003e 中的行为。这个参数只能在 \u003ccode class=\"filename\"\u003epostgresql.conf\u003c/code\u003e 文件中或者服务器命令行上设置。\n       \u003c/p\u003e","doc":{"anchor":"GUC-MAX-PRED-LOCKS-PER-RELATION","file":"runtime-config-locks.html","lang":"en","sha256":"5faab37986a9ca9ff362569c12b8c63e8df57c76c9aea6e40d06e44e9abee87b","slug":"18"},"documented":true,"enumvals":null,"extra_desc":"If more than this total of pages and tuples in the same relation are locked by a connection, those locks are replaced by a relation-level lock.","lang":"en","max_val":"2147483647","metadata_version":"18","min_val":"-2147483648","name":"max_pred_locks_per_relation","short_desc":"Sets the maximum number of predicate-locked pages and tuples per relation.","source":"pg-settings-source-snapshot","translation_provenance":{"inputs":[{"kind":"current-pgdoc-translation","path":"/Users/vonng/pgsty/pgdoc/zh/18/html/runtime-config-locks.html","sha256":"57e70ce1a9664a1043a2a4b3489f8fe2ca9fb65ddd7f71cb527c8fb1c1035b1f"}],"kind":"same-version-pgdoc","locale":"zh-Hans","source_revision":"b1b500221dbe5437cfca004d6b04d3f6e422765d","version":"18"},"unit":null,"vartype":"integer","zh_from":"same-version-pgdoc"},"ManualEvidence":{"doc":{"anchor":"GUC-MAX-PRED-LOCKS-PER-RELATION","file":"runtime-config-locks.html","lang":"en","sha256":"5faab37986a9ca9ff362569c12b8c63e8df57c76c9aea6e40d06e44e9abee87b","slug":"18"}},"MeasuredEvidence":{"metadata_version":"18"}},"Text":{"Collection":"guc","Key":"max_pred_locks_per_relation","SourceDatabase":"center","Version":"18","Locale":"en","Title":"max_pred_locks_per_relation","Summary":"This controls how many pages or tuples of a single relation can be predicate-locked before the lock is promoted to covering the whole relation. Values greater than or equal to zero mean an absolute limit, while negative values mean max_pred_locks_per_transaction divided by the absolute value of this setting. The default is -2, which keeps the behavior from previous versions of PostgreSQL. This parameter can only be set in the postgresql.conf file or on the server command line.","BodyHTML":"\u003cp\u003eThis controls how many pages or tuples of a single relation can be predicate-locked before the lock is promoted to covering the whole relation. Values greater than or equal to zero mean an absolute limit, while negative values mean max_pred_locks_per_transaction divided by the absolute value of this setting. The default is -2, which keeps the behavior from previous versions of PostgreSQL. This parameter can only be set in the postgresql.conf file or on the server command line.\u003c/p\u003e","SourceRevision":"wiki-repair-20261023:49b4a3952757dffa03d9b3b485a11e1450698b8c06c3dda33b885764811d68d1","ContentHash":"f53d369ac074ebbad482a052cf0d402d39b9bcadc901e888562d25f9d44bbde4","Payload":{"description":"This controls how many pages or tuples of a single relation can be predicate-locked before the lock is promoted to covering the whole relation. Values greater than or equal to zero mean an absolute limit, while negative values mean max_pred_locks_per_transaction divided by the absolute value of this setting. The default is -2, which keeps the behavior from previous versions of PostgreSQL. This parameter can only be set in the postgresql.conf file or on the server command line."}},"RequestedLocale":"en","Fallback":false,"Versions":["10","11","12","13","14","15","16","17","18","19","20"],"Locales":["en","zh-Hans"],"Signatures":null,"Spellings":null,"SQLState":null,"Evidence":null}