The PostgreSQL C Dialect - PostgreSQL wiki

Want to edit, but don't see an edit button when logged in? Click here.

The PostgreSQL C Dialect

From PostgreSQL wiki

Jump to navigationJump to search

THIS PAGE IS A WORK IN PROGRESS. DO NOT RELY ON IT FOR DEVELOPMENT UNTIL THIS WARNING IS REMOVED.

This page is an attempt to gather in one place the cross-cutting C conventions and idioms that pervade the PostgreSQL backend — the things behind the common remark that PostgreSQL is written less in C than in a "PostgreSQL C dialect." It is descriptive, not normative , and it is certainly not authoritative: where it disagrees with the source tree or with the official documentation, those win. Corrections, additions, and arguments about where its boundaries should fall are all welcome — please edit freely, or raise points on the talk page or on pgsql‑hackers.

It deliberately does not restate two things that already have canonical homes in the manual: the PostgreSQL Coding Conventions chapter (formatting, error reporting, the error message style guide) and the C‑Language Functions chapter. Those are referenced where relevant rather than copied.

Contents

1 Scope and status

2 What this page does not cover

3 Memory management: contexts and palloc

4 Error handling: ereport, elog, and the exception model

5 The function manager (fmgr) and the version-1 calling convention

6 The node system

7 Common container and utility types

7.1 List

7.2 StringInfo

7.3 Bitmapset

7.4 Hash tables

7.5 Tuplestore

7.6 Intrusive lists

8 Concurrency primitives

9 The frontend/backend split and portability

10 The c.h vocabulary

11 Signals and latches

12 Debugging and assertion aids

13 Open scope questions

14 References

Scope and status

This page covers conventions a reader needs in order to follow backend C code in any subsystem: memory management, error handling, the function‑call interface, the node system, the common container types, the concurrency primitives, the frontend/backend split, and the vocabulary that lives in c.h.

It deliberately stops at the boundary of any single subsystem. Where a convention only matters inside one area — the lock manager's partitioning scheme, the nbtree concurrency protocol, the WAL record format — this page links to that subsystem's own README rather than reproducing it. The working test is: include it if you need it to read code anywhere; link it if it only matters in one place. That boundary is a judgment call, and reasonable contributors will draw it differently; the open cases are collected under #Open scope questions below.

Currency. Everything here is written against the PostgreSQL 18 source tree. The dialect is stable in outline but not frozen in detail, and several pieces below have changed within the span of currently‑supported releases. Those points are flagged inline as Changed in N. If you are reading this well after it was written, treat it as a map and verify against current source; a confidently‑wrong page is worse than none, which is also why the formatting and error‑message conventions are left to the manual, where editing the surrounding code tends to force the documentation to keep pace.

What this page does not cover

Formatting and layout. Tab‑stop indentation, BSD brace style, the 80‑column guideline, comment‑block conventions, and so on: see the manual's Formatting section. The rules are enforced mechanically by src/tools/pgindent (a Perl driver over pg_bsd_indent), so there is little point styling new code by hand.

Error message wording. Capitalisation, punctuation, what belongs in primary vs. detail vs. hint: see the Error Message Style Guide. The mechanics of raising an error are covered below; the wording rules are not.

The SQL‑callable function ABI in full. The tutorial treatment of writing a C function lives in C‑Language Functions; src/backend/utils/fmgr/README is the in‑tree reference. This page summarises only the parts of that interface a reader must recognise to follow backend code.

Subsystem internals. Each major area carries its own README (the planner, the executor, transaction management, the lock manager, access methods, logical replication, and more). Those are the right homes for subsystem‑specific idioms; this page points at them rather than absorbing them.

Memory management: contexts and palloc

Backend code almost never calls malloc/free directly. It allocates with palloc() (and palloc0(), repalloc(), pfree()), which draw from the current memory context.

Memory contexts form a tree rooted at TopMemoryContext. Each allocation belongs to some context; resetting or deleting a context frees everything allocated in it and in its child contexts in one operation . This is the central idea, and it inverts the usual C habit: most code does not pair every palloc with a pfree. Instead, a context is created for a phase of work (a query, a tuple, a transaction), and the whole context is reset or deleted when that phase ends. The rationale, stated...