Skip to content

Terms

SQL and C interface

Datum

The general C type that PostgreSQL uses to pass SQL values. A small value can fit in the Datum. A variable-length value normally uses the Datum as a pointer.

fcinfo

The information for one PostgreSQL function call. It contains the arguments, null flags, result information, and other call data. PG_FUNCTION_ARGS declares this value for a C function.

PG_GETARG_POINTER

A macro that returns the raw pointer from a function argument. It does not detoast the value. The extension uses it to inspect the current storage form before it selects a read path.

PG_GETARG_JSONB_P

A macro that returns a usable Jsonb *. PostgreSQL detoasts and decompresses the argument when this is necessary. This can read the complete value.

SQL null

The absence of an SQL value. PostgreSQL does not call a STRICT function when an argument is SQL null.

JSON null

A real JSON value whose JSON type is null. It is different from SQL null.

Variable-length values

varlena

The common PostgreSQL representation for variable-length values, such as text and jsonb. A normal value starts with a four-byte header. A raw varlena pointer can also identify a short value, a compressed value, or an external value.

varlena header

The prefix that identifies the varlena form and its size. PostgreSQL code must use the varlena macros to read it.

Form Prefix before its data
Normal inline value 4 bytes
Short inline value 1 byte
Compressed inline value 8 bytes
On-disk external pointer 2 bytes before the pointer metadata

The compressed form has a four-byte varlena header and a four-byte compression information field. An on-disk TOAST pointer normally has a two-byte prefix and 16 bytes of pointer metadata. It does not contain the value data.

logical data

The uncompressed bytes that form the SQL value. A TOAST slice offset starts in this data, after the original varlena header. For jsonb, offset zero is the root container header.

stored size

The number of bytes in the current stored form. Compression can make the stored size smaller than the logical size.

TOAST storage

TOAST

PostgreSQL's system for values that are too large for normal row storage. It can compress a value or move it to a secondary table in chunks.

inline value

A value that is present in the main table row. It can be uncompressed or compressed.

compressed value

A value whose data uses a PostgreSQL compression method. Compression does not show whether the value is in memory or on disk. A value can be compressed inline or compressed in a TOAST table.

external value

A value that PostgreSQL stores outside the main table row. The table row keeps a small pointer to the value. An external value can be compressed or uncompressed.

TOAST pointer

Metadata that identifies an external value. An on-disk TOAST pointer records the logical size, stored size and compression information, value identifier, and TOAST table identifier. It does not contain the JSONB data.

TOAST chunk

One numbered part of an external value in a TOAST table.

TOAST slice

A requested byte range from a TOAST value. For an external, uncompressed value, PostgreSQL reads the TOAST chunks that cover the range.

detoast

To make the logical value available from its current TOAST form. This can include reading all chunks and decompressing the value.

storage representation

The current form of one stored value: inline, compressed, or external. PostgreSQL macros inspect this form. They do not calculate whether the value could fit in the row.

storage strategy

The column setting that tells TOAST which storage operations it can use.

Strategy Behavior
PLAIN Keep the value inline. Do not compress it.
MAIN Allow compression. Prefer inline storage.
EXTERNAL Allow external storage. Do not compress it.
EXTENDED Allow compression and external storage.

VARATT_IS_EXTERNAL_ONDISK

A macro that reports whether a raw value is an on-disk TOAST pointer. It inspects the current representation. It does not test whether the complete value can fit in a row.

VARATT_EXTERNAL_IS_COMPRESSED

A macro that reports whether the value behind an on-disk TOAST pointer is compressed.

JSONB layout

jsonb

PostgreSQL's binary representation of JSON data. It stores a container directory before the container data.

JSONB container header

The first four bytes of a JSONB container. It records the container type and item count. It is part of the logical JSONB data. It is not the varlena header.

JEntry

A four-byte JSONB directory entry. It records a value type and either a length or an end offset. An object uses one key entry and one value entry for each field.

JSONB object directory

The JEntry array at the start of a JSONB object. The key entries come first. The value entries follow them. The key and value bytes come after the complete directory.

Project structures

SliceSource

The per-call context for partial reads. It keeps the raw external value, the logical read boundary, and the byte counter used by the regression test. It is a local C structure. It is not stored in PostgreSQL.

ValueLocation

The decoded location of one JSONB value. It keeps the JEntry type, absolute slice offset, and requested length. This lets the code validate a location before it fetches and rebuilds the result.