Utilities

A handful of "infrastructure" subsystems are used everywhere in the backend but don't fit neatly into the storage / access / executor stack. They live mostly under src/backend/utils/ and are documented here as a single page.

Memory contexts

Source: src/backend/utils/mmgr/.

PostgreSQL never calls malloc from backend code. Instead, every allocation comes from a MemoryContext — a tree-shaped object whose Reset or Delete frees everything allocated under it.

TopMemoryContext
├── ErrorContext               (always reachable, used during ereport)
├── PostmasterContext          (postmaster only)
├── CacheMemoryContext         (relcache, syscache, plancache)
├── MessageContext             (one protocol message)
├── TopTransactionContext      (current top-level transaction)
│   ├── CurTransactionContext  (current sub-transaction)
│   ├── PortalContext          (cursor / active query)
│   │   ├── EState contexts
│   │   │   └── per-tuple memory contexts
│   │   └── ...
│   └── ...
└── ... per-subsystem long-lived contexts

Allocators:

API	Behavior
palloc(size)	Allocate in CurrentMemoryContext.
palloc0(size)	Same, zeroed.
palloc_extended(size, flags)	Variants for "no error on OOM," huge allocations, etc.
repalloc, pfree	Resize, free. pfree is optional — the context's reset frees everything.
MemoryContextAlloc(ctx, size)	Allocate in a specific context.
MemoryContextSwitchTo(ctx)	Set CurrentMemoryContext; returns the previous context.
MemoryContextReset(ctx)	Frees children + all chunks but keeps the context itself.
MemoryContextDelete(ctx)	Frees the context and everything under it.

Three context implementations:

• AllocSet — the default. Power-of-two-bucketed slabs.
• Slab — fixed-size chunks; faster for many same-size allocations.
• Generation — bump-allocator-style; great for "allocate a lot then free all" patterns like the executor's per-tuple memory.

MEMORY_CONTEXT_CHECKING builds add canaries and verification.

Error reporting

Source: src/backend/utils/error/elog.c.

ereport and elog are the universal logging/error mechanisms. Severity ladder:

• DEBUG5..DEBUG1 — server log only, very chatty.
• LOG — informational; client doesn't see by default.
• INFO, NOTICE, WARNING — sent to client.
• ERROR — aborts the current transaction via longjmp to a PG_TRY block.
• FATAL — aborts the backend; postmaster restarts the cluster only if the context demands.
• PANIC — postmaster restarts the cluster.

ereport(ERROR,
        (errcode(ERRCODE_INVALID_PARAMETER_VALUE),
         errmsg("invalid value for parameter \"%s\": \"%s\"", name, value),
         errdetail("Value must be between 0 and 100."),
         errhint("Try setting it to 50.")));

Auxiliary fields like errdetail, errhint, errcontext, errcode_for_file_access, errposition are routed by name. Translation hooks pick errmsg for gettext-style i18n.

The error code list lives in src/backend/utils/errcodes.txt and is converted by generate-errcodes.pl into the constants you see in code (ERRCODE_DIVISION_BY_ZERO, ERRCODE_UNIQUE_VIOLATION, etc.).

GUC: configuration parameters

Source: src/backend/utils/misc/guc.c, guc_tables.c, plus per-subsystem guc_*.c files.

A GUC (Grand Unified Configuration) parameter is anything settable via postgresql.conf, SET, command line, or ALTER SYSTEM. The whole table is in guc_tables.c. Adding a new GUC means:

1. Add a static int|bool|char *|double variable somewhere.
2. Add an entry to the appropriate table in guc_tables.c (ConfigureNamesBool, ConfigureNamesInt, etc.) with: name, GUC context (PGC_POSTMASTER / PGC_BACKEND / PGC_USERSET / ...), category, short and long descriptions, the underlying variable, default, min/max, and optional check/assign hooks.
3. Document it in doc/src/sgml/config.sgml.

The GUC system handles parsing, type conversion, source tracking (file vs. session vs. role default), and RESET ALL / pg_reload_conf() semantics.

Statistics

Source: src/backend/utils/activity/. Cumulative statistics are now stored entirely in shared memory (since 15) — there is no separate stats collector process. Backends increment counters in their own backend-local view; periodic flushes consolidate into the shared view. Exposed via pg_stat_* views.

Per-column planner statistics (pg_statistic, pg_statistic_ext) are unrelated; they are populated by ANALYZE. Source: src/backend/commands/analyze.c, src/backend/statistics/.

Timekeeping

Source: src/backend/utils/time/snapmgr.c, src/backend/utils/adt/timestamp.c.

PostgreSQL has its own snapshot manager (covered under MVCC) plus the standard date/time machinery. Time zones come from a vendored copy of the IANA tz database (src/timezone/).

Caches

Beyond syscache and relcache (under Catalog), the backend has:

• Plan cache (src/backend/utils/cache/plancache.c) — caches prepared statement plans across executions; revalidated on cache invalidation.
• Catalog index cache — catalog access uses pre-built index descriptors.
• Type cache (src/backend/utils/cache/typcache.c) — composite type, range type, enum type metadata.

Datatypes (adt)

src/backend/utils/adt/ is the largest single subdirectory in utils/. It holds the implementations of every built-in datatype's I/O, comparison, and operator functions: int8.c, numeric.c, varchar.c, timestamp.c, arrayfuncs.c, jsonfuncs.c, jsonb_op.c, geo_ops.c, network.c, tsvector.c, etc.

Each datatype contributes:

• I/O functions (text in, text out, binary in, binary out).
• A comparison function (for types in B-tree opclasses).
• Operator functions (+, -, =, <, etc.).
• Optional support functions for indexing.

These all hook into pg_proc, pg_operator, pg_amproc, pg_amop via the catalog .dat files.

Foreign data wrappers (FDW)

Source: src/backend/foreign/. The FDW API lets a relation's storage live outside the cluster — in another database, a CSV file, or wherever. Pluggable via the SQL-level CREATE FOREIGN DATA WRAPPER / CREATE SERVER / CREATE FOREIGN TABLE plus a shared library implementing the FDW handler.

The built-in postgres_fdw (in contrib/) is the canonical example; it federates queries to remote PostgreSQL servers and pushes down predicates, joins, aggregates, sorts, and DML when safe.

Partitioning

Source: src/backend/partitioning/. Declarative table partitioning (PARTITION BY RANGE/LIST/HASH). Implementation pieces:

• partbounds.c — partition bound descriptors and matching.
• partdesc.c — runtime partition descriptor (children of a partitioned table).
• partprune.c — plan-time and run-time partition pruning.

The executor's execPartition.c handles routing tuples to the right partition during INSERT/UPDATE.

SPI

Source: src/backend/executor/spi.c. The Server Programming Interface lets C extensions and procedural languages run SQL from inside a backend. SPI builds a plan, manages a portal, and delivers tuples. PL/pgSQL is the largest consumer.

Logical decoding (snap building)

Reaching into src/backend/replication/logical/snapbuild.c from this page just to flag it: building a "historic snapshot" — what the database looked like at any given LSN — is logical decoding's hardest internal problem. Source: snapbuild.c and the comments at the top of reorderbuffer.c.

Misc support

A grab bag worth knowing about:

• miscadmin.h — globals like MyProcPid, MyDatabaseId, IsBackgroundWorker, plus the CHECK_FOR_INTERRUPTS() macro.
• pg_locale.c — locale handling, ICU integration.
• pg_lsn.c — pg_lsn type implementation.
• pg_dump_log.c doesn't exist; pg_dump is a frontend tool — see Apps.

Entry points for modification

• New GUC: edit guc_tables.c plus the relevant subsystem's source.
• New built-in datatype: a pg_type.dat entry, I/O functions, operator class. This is a non-trivial patch — start by reading an existing simple type's implementation (e.g., int4.c).
• New error code: append to errcodes.txt.
• New planner/executor hook: see the comments in src/include/utils/plancache.h, src/include/optimizer/*.h. Most hooks are documented at their declaration site.

For datatype-specific work, browse src/backend/utils/adt/. For partitioning specifically, see src/backend/partitioning/. For everything in src/backend/replication/, see Replication.