Chapter 16. Frontend/Backend Protocol

PostgreSQL uses a message-based protocol for communication between frontends and backends. The protocol is implemented by default over TCP/IP and is also available on UNIX sockets.

Higher level features built on this protocol (for example, how libpq passes certain environment variables after the connection is established) are covered elsewhere.

Overview

The three major components are the frontend (running on the client), the postmaster and backend (running on the server). The postmaster and backend have different roles but may be implemented by the same executable.

A frontend sends a start-up packet to the postmaster. This includes the names of the user and the database the user wants to connect to. The postmaster then uses this and the information in the pg_hba.conf file to determine what further authentication information it requires the frontend to send (if any) and responds to the frontend accordingly.

The frontend then sends any required authentication information. Once the postmaster validates this, it responds to the frontend that the user is authenticated and hands over the connection to a backend. The backend then sends a message indicating successful start-up (normal case) or failure (for example, an invalid database name).

Subsequent communications consist of query and result packets exchanged between the frontend and the backend. The postmaster takes no further part in ordinary query/result communication. However, the postmaster is involved when the frontend wishes to cancel a query currently being executed by its backend.

When the frontend wishes to disconnect, it sends an appropriate packet and closes the connection without waiting for a response from the backend.

Packets are sent as a data stream. The first byte determines what should be expected in the rest of the packet. The exception is packets sent from a frontend to the postmaster, which consist of a packet length followed by the packet itself. The difference is historical.