{"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"}],"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"],"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":"english-manuals:0846f83420f543293f9d9f72c0d575c01dacf7224f309f4c93847181fffc3aa5","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":"english-manuals:0846f83420f543293f9d9f72c0d575c01dacf7224f309f4c93847181fffc3aa5","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.","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","unit":null,"vartype":"integer"},"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":"pgweb","Version":"18","Locale":"zh-Hans","Title":"max_pred_locks_per_relation","Summary":"","BodyHTML":"\u003cp\u003e这个参数控制在谓词锁被提升为覆盖整个关系之前，可以对单个关系中的多少页面或元组加谓词锁。大于等于零的值表示一种绝对限制，而负值表示用\u003ca href=\"/docs/18/runtime-config-locks.html#GUC-MAX-PRED-LOCKS-PER-TRANSACTION\" rel=\"nofollow\"\u003emax_pred_locks_per_transaction\u003c/a\u003e除以这个设置的绝对值。默认值为-2，它将保持以往版本的\u003cspan\u003ePostgreSQL\u003c/span\u003e中的行为。这个参数只能在\u003ccode\u003epostgresql.conf\u003c/code\u003e文件中或者服务器命令行上设置。\u003c/p\u003e","SourceRevision":"2026-09-11@29c86d9","ContentHash":"404814f42c08c5a9cafbe6e55b1a9ebc38995d19f523d835801d0ea098fc91ab","Payload":{"carried_from":"","carry_reason":"","doc_html":"\u003cp\u003e这个参数控制在谓词锁被提升为覆盖整个关系之前，可以对单个关系中的多少页面或元组加谓词锁。大于等于零的值表示一种绝对限制，而负值表示用\u003ca href=\"/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文件中或者服务器命令行上设置。\u003c/p\u003e","doc_same_as":""}},"RequestedLocale":"zh-Hans","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}