Wiki / Protocol Messages / Backend messages

BackendKeyData

BackendKeyData is a backend protocol message. Identifies the message as cancellation key data. The frontend must save these values if it wishes to be able to issue CancelRequest messages later.

Reading PostgreSQL 18.6.

Description

BackendKeyData is a backend protocol message. Identifies the message as cancellation key data. The frontend must save these values if it wishes to be able to issue CancelRequest messages later.

Direction: Backend → frontend
First wire field: Byte1('K')
Field entries: 4
Documented flow contexts: Start-up

Usage

BackendKeyData (B)

Framing and repetition

The complete definition below retains repetition, counts and conditional fields. A numbered table row is a documented field definition, not a fixed byte offset. Integer encodings and flow rules follow the same-version protocol chapter.

Wire fields in documented order

Position	Format	Meaning
1	Byte1('K')	Identifies the message as cancellation key data. The frontend must save these values if it wishes to be able to issue CancelRequest messages later.
2	Int32	Length of message contents in bytes, including self.
3	Int32	The process ID of this backend.
4	Byte n	The secret key of this backend. This field extends to the end of the message, indicated by the length field. The minimum and maximum key length are 4 and 256 bytes, respectively. The PostgreSQL server only sends keys up to 32 bytes, but the larger maximum size allows for future server versions, as well as connection poolers and other middleware, to use longer keys. One possible use case is augmenting the server's key with extra information. Middleware is therefore also encouraged to not use up all of the bytes, in case multiple middleware applications are layered on top of each other, each of which may wrap the key with extra data.

Manual definition

Byte1('K')

Identifies the message as cancellation key data. The frontend must save these values if it wishes to be able to issue CancelRequest messages later.

Int32

Length of message contents in bytes, including self.

Int32

The process ID of this backend.

Byten

The secret key of this backend. This field extends to the end of the message, indicated by the length field.

The minimum and maximum key length are 4 and 256 bytes, respectively. The PostgreSQL server only sends keys up to 32 bytes, but the larger maximum size allows for future server versions, as well as connection poolers and other middleware, to use longer keys. One possible use case is augmenting the server's key with extra information. Middleware is therefore also encouraged to not use up all of the bytes, in case multiple middleware applications are layered on top of each other, each of which may wrap the key with extra data.

Before protocol version 3.2, the secret key was always 4 bytes long.

Related entries

Documentation and source

PostgreSQL 18 English manual

Source build

Version: 18.6
Build: https://ftp.postgresql.org/pub/source/v18.6/postgresql-18.6.tar.bz2
Source fingerprint: 555610c24d53e4316da5b7d3fc25c279d96856d5e0e23ee308c328c5fa881d9f

Compare versions

PostgreSQL 17 → 18: changed.

--- PostgreSQL 17
+++ PostgreSQL 18
@@ -7,15 +7,15 @@
     },
     {
       "description": "Length of message contents in bytes, including self.",
-      "format": "Int32(12)"
+      "format": "Int32"
     },
     {
       "description": "The process ID of this backend.",
       "format": "Int32"
     },
     {
-      "description": "The secret key of this backend.",
-      "format": "Int32"
+      "description": "The secret key of this backend. This field extends to the end of the message, indicated by the length field. The minimum and maximum key length are 4 and 256 bytes, respectively. The PostgreSQL server only sends keys up to 32 bytes, but the larger maximum size allows for future server versions, as well as connection poolers and other middleware, to use longer keys. One possible use case is augmenting the server's key with extra information. Middleware is therefore also encouraged to not use up all of the bytes, in case multiple middleware applications are layered on top of each other, each of which may wrap the key with extra data.",
+      "format": "Byte n"
     }
   ]
 }

Compares recorded interfaces and attributes. Source fingerprints and build metadata are excluded; an absent sample is not proof of the introduction or removal release.

Related entries

Export JSON · Back to Protocol Messages · Recorded in PostgreSQL 10 through 20; the first sample is not necessarily its introduction.