Today, we turn our focus to query itself that is dissecting its internal anatomy to understand how PostgreSQL transforms a raw SQL string into a structured in-memory representation: the Query tree.

The Query Pipeline

Before diving into the Query struct and how PostgreSQL represents SQL internally, let’s recap the pipeline that a query traverses after reaching the backend.

As discussed in PostgreSQL Internals: Query Pipeline, query processing can be viewed as a five-stage assembly line, where the output of one stage becomes the input to the next:

1. Parser (gram.y)
   Performs syntactic analysis using the Flex lexer and Bison-generated parser. It verifies that the SQL conforms to PostgreSQL's grammar and produces a parse tree containing nodes such as RawStmt, SelectStmt, RangeVar, and ResTarget.

   At this stage, PostgreSQL understands the shape of the statement, but it does not yet resolve whether a referenced table or column actually exists.

2. Analyzer / Transformer
   Performs semantic analysis. It resolves names against PostgreSQL's system catalogs (pg_class, pg_attribute, pg_type, etc.), determines data types, establishes namespaces and scopes, resolves operators and functions, and converts the raw parse tree into an annotated Query tree.

3. Rewriter
   Applies PostgreSQL rewrite rules, including rules associated with views and other rewrite mechanisms. It can also add security-related qualifications where applicable.

   Importantly, the output of this stage is not necessarily one query. A single Query can be transformed into a list of Query trees.

4. Planner / Optimizer
   Takes the rewritten Query tree and determines how the query should execute. It considers possible access paths, join orders, join strategies, indexes, sorting, aggregation, and other execution alternatives using statistics and cost estimates.

   The result is a PlannedStmt containing a physical Plan tree.

5. Executor
   Executes the physical plan tree produced by the planner. It initializes the required executor nodes and recursively drives them to produce result tuples.

A simplified view is therefore:

SQL Statement → Parser (returns Parse Tree) → Analyzer (returns Query Tree) → Rewriter applies Rules, Views (returns a list of Query Tree) → Planner (return Plan Tree) → Executor → Result Rows

The important point for this article is the transition:

Raw SQL
   ↓
RawStmt / raw parse tree
   ↓
Query

The Query struct is where PostgreSQL has moved beyond simply understanding SQL syntax and has started building a semantic representation of what the query means.

The Query Struct

The Query node is defined in:

src/include/nodes/parsenodes.h

A simplified view of the structure looks like this:

typedef struct Query
{
    NodeTag         type;
    CmdType         commandType;
    QuerySource     querySource;
    uint64          queryId;
    bool            canSetTag;

    Node           *utilityStmt;

    int             resultRelation;

    bool            hasAggs;
    bool            hasWindowFuncs;
    bool            hasTargetSRFs;
    bool            hasSubLinks;
    bool            hasDistinctOn;
    bool            hasRecursive;
    bool            hasModifyingCTE;
    bool            hasForUpdate;
    bool            hasRowSecurity;
    bool            hasGroupRTE;
    bool            isReturn;

    List           *cteList;
    List           *rtable;
    List           *rteperminfos;

    FromExpr       *jointree;

    List           *mergeActionList;
    int             mergeTargetRelation;
    Node            *mergeJoinCondition;

    List           *targetList;

    OverridingKind  override;
    OnConflictExpr *onConflict;

    char           *returningOldAlias;
    char           *returningNewAlias;
    List           *returningList;

    List           *groupClause;
    bool            groupDistinct;
    List           *groupingSets;

    Node           *havingQual;

    List           *windowClause;
    List           *distinctClause;
    List           *sortClause;

    Node           *limitOffset;
    Node           *limitCount;
    LimitOption    limitOption;

    List           *rowMarks;

    Node           *setOperations;

    List           *constraintDeps;
    List           *withCheckOptions;

    ParseLoc        stmt_location;
    ParseLoc        stmt_len;
} Query;

Anatomy of the Query Struct

Once a statement passes through parsing and analysis, PostgreSQL has a much richer representation of it.

The parser primarily answers:

“Is this valid PostgreSQL syntax?”

The analyzer answers a much more interesting question:

“What does this statement actually refer to?”

For example, consider:

SELECT c.id
FROM companies c
WHERE c.revenue > 1000000;

After analysis, PostgreSQL needs to know:

• Which relation does companies refer to?

• What OID identifies that relation?

• Which attribute does c.id refer to?

• What data type does c.id have?

• What operator implements >?

• What type does 1000000 have in this expression?

• Which table does c refer to?

• Which expressions belong to the target list?

• Which expression represents the WHERE qualification?

The Query tree contains the information necessary for later stages to reason about those semantics.

1. Command Metadata

The first group of fields describes what kind of statement this is and which SQL features are present.

commandType

CmdType commandType;

commandType identifies the broad command represented by the Query:

CMD_SELECT
CMD_UPDATE
CMD_INSERT
CMD_DELETE
CMD_MERGE
CMD_UTILITY

For example:

SELECT * FROM companies;

will produce a Query whose commandType is:

CMD_SELECT

Whereas:

UPDATE companies
SET revenue = revenue * 1.1;

will have:

CMD_UPDATE

This gives later stages an immediate indication of the statement's nature.

querySource

QuerySource querySource;

This describes where the query came from.

A query may originate directly from the user, or it may have been generated as part of PostgreSQL's rewrite processing.

This distinction becomes particularly useful when PostgreSQL is dealing with rewritten queries.

queryId

uint64 queryId;

queryId represents a query identifier associated with the analyzed query.

It is important not to confuse this with the query ID displayed or used by pg_stat_statements as though Query.queryId itself were the statistics extension.

The query identifier is assigned as part of PostgreSQL's query-identification infrastructure and can be used by extensions such as pg_stat_statements to associate execution statistics with a normalized query identity.

The important distinction is:

Query.queryId
      │
      └── Query identification
              │
              └── Used by infrastructure/extensions
                  such as pg_stat_statements

It is not a transaction ID, object OID, or plan identifier.

2. Feature Flags

The Query node also contains several boolean fields:

bool hasAggs;
bool hasWindowFuncs;
bool hasTargetSRFs;
bool hasSubLinks;
bool hasDistinctOn;
bool hasRecursive;
bool hasModifyingCTE;
bool hasForUpdate;
bool hasRowSecurity;
bool hasGroupRTE;

These flags summarise important properties discovered during analysis.

For example:

SELECT department_id, count(*)
FROM employees
GROUP BY department_id;

contains an aggregate function.

Therefore:

hasAggs = true

Similarly:

SELECT name,
       row_number() OVER (ORDER BY salary)
FROM employees;

contains a window function, so:

hasWindowFuncs = true

These flags allow later processing stages to quickly determine whether particular query-processing features are involved without having to rediscover them from scratch.

3. Relations, Scope and the Range Table

One of the most important fields in Query is:

List *rtable;

This is the range table.

The range table contains RangeTblEntry structures representing the relations and other range-table items referenced by the query.

A simplified RangeTblEntry looks like:

typedef struct RangeTblEntry
{
    NodeTag type;
    RTEKind rtekind;

    Oid relid;

    Alias *alias;
    Alias *eref;

    Query *subquery;

    JoinType jointype;

    /* ... additional fields ... */
} RangeTblEntry;

The actual PostgreSQL structure contains considerably more information.

For a normal table reference:

SELECT *
FROM companies;

the corresponding RangeTblEntry contains information identifying the relation.

For example:

companies
    │
    ▼
RangeTblEntry
    │
    ├── rtekind = RTE_RELATION
    ├── relid   = <companies OID>
    └── ...

The important transformation is:

"companies"
     ↓
catalog lookup
     ↓
relation OID
     ↓
RangeTblEntry

This is one of the key differences between the raw parse tree and the analyzed Query tree.

4. Range Table Indexes

The range table is also important because other nodes refer to its entries by range-table index (rtindex).

For example:

typedef struct RangeTblRef
{
    NodeTag type;
    int rtindex;
} RangeTblRef;

If:

rtable[1] → companies
rtable[2] → employees

then a RangeTblRef with:

rtindex = 1

refers to the first range-table entry.

This gives PostgreSQL an internal relationship like:

Query
 │
 ├── rtable
 │    │
 │    ├── [1] → companies
 │    └── [2] → employees
 │
 └── jointree
      │
      ├── RangeTblRef(1)
      └── RangeTblRef(2)

The tree nodes don't need to repeatedly store the complete relation information. They can refer back to the appropriate RangeTblEntry.

5. TargetList: What Should the Query Produce?

Another critical field is:

List *targetList;

The target list represents the expressions that the query is interested in producing.

For:

SELECT c.id, c.name
FROM companies c;

the target list contains two TargetEntry nodes.

Conceptually:

targetList
   │
   ├── TargetEntry
   │      └── Var → c.id
   │
   └── TargetEntry
          └── Var → c.name

A simplified TargetEntry looks like:

typedef struct TargetEntry
{
    Expr       *expr;
    AttrNumber  resno;
    char       *resname;
    Index       ressortgroupref;
    bool        resjunk;
} TargetEntry;

6. The Var Node

The expr field can contain an expression node such as Var.

A simplified Var looks like:

typedef struct Var
{
    Expr        xpr;

    Index       varno;
    AttrNumber  varattno;
    Oid         vartype;

    /* ... additional properties ... */
} Var;

The important fields are:

varno

Identifies the range-table entry from which the value comes.

Conceptually:

varno = 1
     ↓
rtable[1]
     ↓
companies

varattno

Identifies the attribute within that relation.

For example:

varattno = 1

might correspond to the first user attribute of the relation.

vartype

Contains the PostgreSQL type OID.

For example:

23 → int4
25 → text

Therefore, an expression such as:

c.id

can eventually be represented conceptually as:

Var
 ├── varno    → companies
 ├── varattno → id
 └── vartype  → int4

This is a major semantic transformation.

The parser sees:

c.id

The analyzer turns that name into a structured reference to:

Range table entry
        +
attribute number
        +
data type

7. ResultRelation: Which Relation Is Being Modified?

For DML statements, PostgreSQL needs to identify the relation being modified.

This is represented by:

int resultRelation;

For example:

UPDATE companies
SET revenue = revenue * 1.1;

the resultRelation identifies the appropriate entry in the query's range table.

Conceptually:

rtable
 ├── [1] → companies
 │
 └── ...

resultRelation = 1

So:

resultRelation
      │
     ▼
rtable entry
      │
     ▼
companies

This allows later stages to determine which relation is the target of the modification.

8. CteList: Common Table Expressions

The Query also contains:

List *cteList;

This stores the query's Common Table Expressions (WITH clauses).

For example:

WITH high_value AS
(
    SELECT *
    FROM companies
    WHERE revenue > 1000000
)
SELECT *
FROM high_value;

The CTE is represented internally as a CommonTableExpr node in cteList.

Conceptually:

Query
 │
 ├── cteList
 │      │
 │      └── CommonTableExpr
 │              │
 │              └── Query
 │
 └── ...

A CTE therefore introduces another query representation nested inside the surrounding query structure.

9. JoinTree: FROM + WHERE Structure

One of the most interesting fields in Query is:

FromExpr *jointree;

The jointree represents the query's FROM/WHERE structure.

A simplified FromExpr is:

typedef struct FromExpr
{
    NodeTag type;

    List *fromlist;

    Node *quals;
} FromExpr;

It contains two important pieces:

fromlist

The relations and joins appearing in the FROM clause.

quals

The qualification expression, which generally corresponds to the WHERE condition.

For example:

SELECT *
FROM companies
WHERE revenue > 1000000;

can be visualized as:

FromExpr
 │
 ├── fromlist
 │      │
 │      └── RangeTblRef
 │              │
 │              └── companies
 │
 └── quals
        │
        └── 
            ├── Var → companies.revenue
            └── Const → 1000000

Notice that the WHERE expression is not represented as a separate "WHERE node."

It is stored as the quals expression tree.

10. Representing JOINs

For a query such as:

SELECT *
FROM companies c
JOIN employees e
    ON c.id = e.company_id;

the FROM structure contains a JoinExpr.

A simplified representation is:

typedef struct JoinExpr
{
    JoinType jointype;

    Node *larg;
    Node *rarg;

    List *usingClause;

    Node *quals;

    Alias *join_using_alias;
    int rtindex;
} JoinExpr;

Conceptually:

JoinExpr
 │
 ├── jointype = JOIN_INNER
 │
 ├── larg
 │     └── RangeTblRef → companies
 │
 ├── rarg
 │     └── RangeTblRef → employees
 │
 └── quals
       └── =
           ├── Var → companies.id
           └── Var → employees.company_id

So the query's relational structure can be represented as a tree:

                 JoinExpr
                /        \
               /          \
       companies        employees
              \            /
               \          /
                join condition

This representation gives later stages a structured description of the query's relational topology.

11. GroupClause and Aggregation

Consider:

SELECT company_id, count(*)
FROM employees
GROUP BY company_id;

The Query contains:

List *groupClause;

which represents the grouping specification.

The aggregate itself contributes to the expression tree in the target list.

Conceptually:

Query
 │
 ├── targetList
 │      ├── Var → company_id
 │      └── Aggref
 │             └── count(*)
 │
 └── groupClause
        └── company_id

This separation is useful because PostgreSQL needs to reason independently about:

• what values are produced,

• what expressions are aggregated,

• and what expressions define the grouping.

12. HavingQual

HAVING is different from WHERE.

Consider:

SELECT company_id, count(*)
FROM employees
GROUP BY company_id
HAVING count(*) > 10;

The HAVING condition is represented by:

Node *havingQual;

Conceptually:

GROUP BY
    ↓
Aggregation
    ↓
HAVING
    ↓
Result

Whereas a WHERE condition generally belongs to:

jointree->quals

This distinction is important because the two predicates operate at different logical stages.

13. Window Functions

Window specifications are represented using:

List *windowClause;

For example:

SELECT
    name,
    salary,
    row_number() OVER (ORDER BY salary DESC)
FROM employees;

The query contains information describing the window specification:

windowClause
    │
    └── Window specification
            │
            └── ORDER BY salary DESC

The window function itself appears in the relevant expression tree.

14. SortClause

ORDER BY information is represented through:

List *sortClause;

For:

SELECT *
FROM employees
ORDER BY salary DESC;

the query representation records the expression being sorted and the associated sort semantics.

Conceptually:

sortClause
    │
    └── salary
          │
          └── DESC

The important distinction is that the Query describes what ordering is required.

It is the planner that later decides how to achieve that ordering.

For example, the planner might determine that an index can provide the required ordering, or that an explicit sort operation is necessary.

15. LimitOffset and LimitCount

LIMIT and OFFSET are represented using:

Node *limitOffset;
Node *limitCount;
LimitOption limitOption;

For:

SELECT *
FROM employees
LIMIT 10
OFFSET 20;

the query representation contains expressions corresponding to:

limitOffset → 20
limitCount  → 10

Again, the Query describes the semantic requirement.

The planner and executor determine how that requirement is physically implemented.

16. SetOperation

PostgreSQL also needs to represent set operations such as:

SELECT id FROM companies
UNION
SELECT id FROM employees;

The relevant information is stored through:

Node *setOperations;

This can represent operations such as:

UNION
INTERSECT
EXCEPT

and their associated query structures.

Conceptually:

SetOperation
      │
      ├── left query
      │
      └── right query

17. RowMarks

Queries involving row-level locking, such as:

SELECT *
FROM employees
FOR UPDATE;

carry locking information through:

List *rowMarks;

This allows PostgreSQL to preserve the semantic requirement that selected rows must be locked.

The planner later translates this requirement into an appropriate execution strategy.

18. rteperminfos: Separating Permissions from Range Table Entries

Alongside rtable, the Query struct also carries:

List *rteperminfos;

This list holds RTEPermissionInfo structures, one per relation that actually needs an access-control check – which is a smaller set than rtable itself, since not every range table entry represents a checkable relation (a subquery RTE or join RTE doesn't need its own permission check, for instance).

A simplified RTEPermissionInfo looks like:

typedef struct RTEPermissionInfo
{
    NodeTag     type;

    Oid         relid;
    bool        inh;

    AclMode     requiredPerms;
    Oid         checkAsUser;

    Bitmapset  *selectedCols;
    Bitmapset  *insertedCols;
    Bitmapset  *updatedCols;
} RTEPermissionInfo;

Each RangeTblEntry that needs checking stores an index (perminfoindex) back into rteperminfos, rather than embedding the permission fields directly on itself:

rtable
 ├── [1] companies  ──── perminfoindex ────┐
 └── [2] employees  ──── perminfoindex ──┐ │
                                          ▼ ▼
                                   rteperminfos
                                    ├── [1] companies: requiredPerms, selectedCols...
                                    └── [2] employees: requiredPerms, selectedCols...

Why split it out at all? Because permission checking and range-table membership are logically different concerns. A view expands into multiple RTEs during rewriting, but the permission check should still apply to the view as the user wrote it, not to each underlying table separately. Keeping RTEPermissionInfo as its own list lets PostgreSQL track who needs to be allowed to do what independently of which relations the plan will actually touch – the two lists can diverge as the query tree is rewritten and expanded, without one bloating or corrupting the other.

19. Tracking the Original SQL Location

Finally, the Query structure contains:

ParseLoc stmt_location;
ParseLoc stmt_len;

These fields record the location and length of the statement within the original query text.

This is useful because PostgreSQL does not need to duplicate the complete SQL text inside every parse-tree node merely to remember where something originated.

Instead, nodes can retain source-location information that points back into the original query string.

Conceptually:

Original query buffer

SELECT c.id, count(*)
FROM companies c
...

^
|
stmt_location

<-------- stmt_len -------->

This source-location information is also useful for producing accurate error messages and other diagnostics.

Putting Everything Together

Let's take a concrete example:

SELECT c.id, count(*)
FROM companies c
JOIN employees e
    ON c.id = e.company_id
GROUP BY c.id;

At the SQL level, we can think about the query as:

SELECT
    c.id,
    count(*)

FROM
    companies c
    JOIN employees e
        ON c.id = e.company_id

GROUP BY
    c.id

After analysis, PostgreSQL has enough information to construct a semantic representation roughly like:

Query
│
├── commandType
│     └── CMD_SELECT
│
├── rtable
│     ├── [1] → companies
│     └── [2] → employees
│
├── targetList
│     ├── TargetEntry
│     │      └── Var
│     │           ├── varno → 1
│     │           ├── varattno → id
│     │           └── vartype → int4
│     │
│     └── TargetEntry
│            └── Aggref
│                 └── count(*)
│
├── jointree
│     └── FromExpr
│           │
│           └── JoinExpr
│               ├── larg → RangeTblRef(1)
│               ├── rarg → RangeTblRef(2)
│               └── quals
│                     └── c.id = e.company_id
│
└── groupClause
      └── c.id

This is the important conceptual leap:

SQL text

c.id

becomes something closer to:

Var
 ├── varno
 ├── varattno
 └── vartype

And:

SQL relation

companies

becomes:

RangeTblEntry
 └── relid → relation OID

And:

SQL JOIN

companies c
JOIN employees e
ON c.id = e.company_id

becomes a structured tree:

JoinExpr
├── left relation
├── right relation
└── join qualification

PostgreSQL has therefore transformed human-readable SQL names into a graph/tree of strongly typed internal nodes.

Conclusion

A Query is PostgreSQL's answer to what does this SQL actually mean – names resolved to Vars and RangeTblEntrys, structure captured in jointree, intent captured in fields like groupClause, sortClause, and rteperminfos. It describes the query fully, but not how to run it – that's the planner's job, and where we'll head next.

And for me, that place is Zoho – the company that gave me my first job, helped me take that first step on the ladder I always wanted to climb, and brought me closer to the dreams I had always carried with me.

Now, it’s time for me to take that second step.

After an incredible journey of nearly four years (3 years and 8 months), I am finally saying goodbye to Zoho.

January 2023

I joined Zoho on January 18th, 2023.

I still remember feeling equally thrilled and overwhelmed by the sheer size of the workplace and its unique working culture. Everything felt new, unfamiliar, and exciting at the same time.

And, of course, I couldn’t leave out one of the perks that made Zoho even more memorable – the free food!

With three meals provided for employees every day, I inevitably put on a few extra kilos along the way. Back then, I didn’t even know what calories were. Now, well... I’ve got them under control! 😄

Friendships

When I joined, my only goals were simple: work hard, clear my probation, and hopefully make some friends as I stepped into this brand-new stage of my life.

Somehow, I managed to do both.

A Full-Stack Developer (I assumed through my college projects) slowly transitioned into a Database enthusiast.

And along the way, I found a wonderful set of friends with whom I loved spending most of my time – spending time chitchatting in pantries, having evening snacks, watch movies in conference rooms (not that many though), going out, or simply hanging around and doing absolutely nothing.

Even today I randomly remembers the conversations we had in Tower pantries, watching series while having lunch at the South Plaza tent, the food the guys bought from the home, and all those random conversations over the evening snacks.
Those seemingly ordinary moments are the memories I’ll carry with me!! ❤️

The Engineer I Became

At some point, I realised I needed to take my work more seriously – thanks to the gentle nudge from my manager about not taking work seriously enough. 😄

From that moment until this very day, I have worked hard, made meaningful contributions to the product and the projects I was part of, and learned so much about databases, especially PostgreSQL. I learned from my mentors, my teammates, and, at times, from my own mistakes.

I also got the opportunity to mentor two juniors. Looking back, I think I handled that responsibility better than I would have expected from myself – or at least, that’s what I’d like to believe.

They’re probably the ones who can tell whether that's actually true.. :)

And somewhere along the way, my interests started changing too. Instead of thinking about building full-stack web applications, I found myself increasing interested in building tools and projects that could make working with databases easier and better.

It eventually went so far that I started writing blogs and posting them like it was a war. 😅

Personal Growth

But, as life usually does, things started changing along the way.

Some friendships slowly faded – some because of my own mistakes, and some simply because we stopped being able to keep in touch. There wasn’t always a dramatic ending or maybe there is. Sometimes, people just slowly became a little more distant.

And somewhere in between all of that, I entered what I now call my solo-life phase. I started going to movies alone, sitting in cafés by myself, reading books, and, most importantly, learning to enjoy my own company.

Looking back, that phase helped me grow in ways I didn’t realise at the time. I became more comfortable with myself, more independent, and perhaps a little more mature. Ironically, learning to be comfortable alone also helped me find new people, make new friends, and, most importantly, feel secure in my own company.

Games

Zoho introduced me to games I had barely played before – Foosball and Table Tennis – and somehow made me fall a little more in love with Badminton.

I still remember the first time, I played foosball, the only thing I know is to rotate the player in full circle and hit the ball with complete randomness. 😂

What started as something to do during breaks slowly became one of the ways I spent a lot of my time at Zoho – enough to make me sweat even with the A/C running throughout the building. 😄

Interestingly, many of the friends I made during the later part of my journey came through these games. Some started as people I played with, some gradually became closer friends, and some became people I genuinely enjoyed spending time with outside the game as well.

Looking back, the games were never just about winning or losing. Well, sorry, in my case, it was definitely about winning! 😄

But more than anything, they gave me a reason to meet people, spend time together, laugh at each other’s terrible shots, and, somewhere between all of that, build friendships.

Things I Didn't Know I Had to Learn

When I first started, I thought being a developer was mostly about writing code. I slowly realised that writing code was only a small part of it.

There were hours spent debugging issues in the source code, trying to understand why something that looked perfectly fine on the surface was behaving completely differently underneath.

There were production issues that needed to be analysed, countless lines of source code to go through, and documentation that had to be written and maintained – things I probably didn't think much about when I first imagined what being a developer would be like.

And then came the never-ending meetings and discussions. 😄 Some were about solving problems, some were about understanding problems, and some somehow led to discussions about other problems we didn't even know existed!

But somewhere in all of this, I learned that being an engineer isn't just about writing code.

It's about understanding a problem before trying to solve it, asking the right questions, digging deeper when the obvious answer isn't the right one, documenting what you learn, and being able to explain your thinking to others.

Those were things I didn't know I had to learn when I joined Zoho. Looking back, they probably shaped me just as much as the code I wrote.

And finally, I want to thank everyone who has been a part of this incredible journey.

To my mentors and teammates who helped me grow.

To my friends who made ordinary days memorable.

To everyone I crossed paths with along the way.

Thank you.

I may not remember every project, meeting, or line of code, but I’ll always remember the people, the conversations, the laughter, the games, the lessons, and the moments that made these nearly four years special.

And heads up – even after saying all this, I won’t be the one to ping first. 🤪

GOOD BYE, ZOHO!! ❤️

• An UPDATE inserts a brand-new tuple version and sets the xmax on the old one; the old version stays on disk so that concurrent transactions with an older snapshot can still see it.

• A DELETE sets the xmax to the transaction ID that deleted the row, but the row itself is not cleared from disk either. Transactions that started before the deleting transaction can still see this row.

Once no active transaction or snapshot can possibly need a tuple version anymore, it becomes dead – wasted space that nothing will ever look at again. That's the debt VACUUM exists to collect.

Part 1: Why VACUUM Exists?

Every write operation i.e., UPDATE or DELETE in PostgreSQL creates a debt that must eventually be paid. For example:

INSERT → writes 1 new tuple
       → debt: none (yet)

UPDATE → writes 1 new tuple version
       → marks old tuple dead (xmax set)
       → writes 1 new index entry per index (assume N indexes)
       → marks old index entries dead
       → debt: 1 dead heap tuple + N dead index entries

DELETE → marks tuple dead (xmax set)
       → marks index entries dead
       → debt: 1 dead heap tuple + N dead index entries

This debt accumulates on every page, and dead tuples cause:

• Wasted space: pages fill with unreachable data

• Slower scans: every scan reads and discards dead tuples

• Blocked index-only scans: the all_visible bit cannot be set while dead tuples exist

• Wraparound risk: old xmin values must be frozen before the XID space/range is exhausted

Part 2: What VACUUM Does?

VACUUM is the debt collector, whose responsibility is to clear all the debt created above:

• Reclaims space occupied by dead tuples (and their index entries) so that space can be reused by future inserts/updates.

• Freezes old transaction IDs so PostgreSQL doesn't run into transaction ID wraparound. XIDs are 32-bit and comparisons are circular, so an unfrozen tuple can appear to be "from the future" once wraparound occurs.

• Updates the visibility map and free space map so future scans/vacuums can skip work.

• Optionally truncates trailing empty pages and updates planner statistics.

Part 3: How VACUUM Works – The Three-Phase Design

We can divide the process into three phases:

• Scan, Prune, and Freeze

• Index Vacuuming

• Heap Vacuuming

Phase 0 below covers the entry point into the heap access method – it sits before the three phases proper, which are Phase 1 through Phase 3.

Phase 0: Entry – from the VACUUM Command Down to the Heap AM (Access Method)

When a VACUUM command is executed, PostgreSQL calls ExecVacuum(), which is the primary entry point for ANALYZE as well.

Code flow:

void ExecVacuum(ParseState *pstate, VacuumStmt *vacstmt, bool isTopLevel) {
   // ..... parse options into VacuumParams

   vacuum(newrels, &params, bstrategy, ...); => {

      // ..... loop over relations
      vacuum_rel(vrel->oid, vrel->relation, &params, bstrategy); => {
         Relation rel;

         // ..... open/lock relation, permission checks
         if (params->options & VACOPT_PROCESS_MAIN) {
            if (params->options & VACOPT_FULL) {
               cluster_rel(rel, InvalidOid, &cluster_params); // VACUUM FULL: different path entirely (cluster.c)
               rel = NULL;
            }
            else {
               // OUR AREA OF INTEREST — plain/lazy VACUUM
               table_relation_vacuum(rel, params, bstrategy); => {
                  // src/include/access/tableam.h:1674
                  rel->rd_tableam->relation_vacuum(rel, params, bstrategy);

                  // ======================================
                  // rel->rd_tableam->relation_vacuum is a function pointer to the table access method's vacuum implementation.
                  // heap AM wires this straight to heap_vacuum_rel:
                  //   .relation_vacuum = heap_vacuum_rel  (heapam_handler.c:2656)
                  heap_vacuum_rel(rel, params, bstrategy); => {
                     LVRelState *vacrel = palloc0(sizeof(LVRelState));
                     
                     // ..... set up error callback, open indexes, copy names
                     vacrel->aggressive = vacuum_get_cutoffs(rel, params, &vacrel->cutoffs); // computes OldestXmin/FreezeLimit/MultiXactCutoff
                     vacrel->rel_pages = RelationGetNumberOfBlocks(rel);
                     vacrel->vistest = GlobalVisTestFor(rel);
                     dead_items_alloc(vacrel, params->nworkers); // TID store, bounded by maintenance_work_mem

                     lazy_scan_heap(vacrel);        // === STAGE 1 ===
                     // (lazy_scan_heap internally calls lazy_vacuum() === STAGE 2+3 === when TID store fills or scan ends)

                     // ..... final index cleanup, truncate, update relfrozenxid/relminmxid, pgstat report
                     return;
                  }
               }
            }
         }
         // ..... close relation
      }
   }
}

Phase 1: Scan, Prune, and Freeze

Entry point: lazy_scan_heap()

The driver loop reads blocks via a ReadStream, and for each block:

• heap_vac_scan_next_block() decides whether a block can be skipped using the visibility map. Pages that are already all-visible (or all-frozen) don't need scanning, unless this is an aggressive vacuum or eager scanning wants to freeze them anyway.

• It takes a cleanup lock and calls lazy_scan_prune, which delegates the real work to heap_page_prune_and_freeze.

• heap_page_prune_and_freeze walks every line pointer on the page. For each tuple, it calls HeapTupleSatisfiesVacuumHorizon, which returns one of the following:

  • HEAPTUPLE_DEAD – deletable now

  • HEAPTUPLE_RECENTLY_DEAD – dead, but some snapshots might still see it, so it's kept

  • HEAPTUPLE_LIVE

  • HEAPTUPLE_INSERT_IN_PROGRESS / HEAPTUPLE_DELETE_IN_PROGRESS

• HOT-chain pruning: Heap-Only Tuple chains are collapsed i.e., intermediate dead tuple versions are removed. The root tuple's line pointer is turned into LP_REDIRECT, pointing straight to the latest live version. This way, index entries pointing at the root stay valid without needing an index update.

• Freezing: if a tuple's xmin is older than FreezeLimit, it's rewritten with a frozen XID so it's permanently visible without needing to look up the CLOG. Here, FreezeLimit = nextXID - vacuum_freeze_min_age.

• Dead item pointers (LP_DEAD) whose tuples were removed are recorded into the TID store – a memory-efficient, radix-tree-like structure capped at maintenance_work_mem, which will be used later for index cleanup.

• If the entire page ends up fully visible/frozen, the relevant bit(s) are set in the visibility map.

lazy_scan_heap(LVRelState *vacrel) { 
   ReadStream *stream = read_stream_begin_relation(READ_STREAM_MAINTENANCE, vacrel->bstrategy,
                                                    vacrel->rel, MAIN_FORKNUM,
                                                    heap_vac_scan_next_block, vacrel, sizeof(uint8)); => {
      // called back per block: decides skip vs scan using the Visibility Map
      // OUR AREA OF INTEREST — this is what lets normal vacuums skip all-visible/all-frozen pages
   }

   while (true) {
      // ..... check TID-store fullness -> if full, call lazy_vacuum() (Stage 2+3) mid-scan, then resume
      Buffer buf = read_stream_next_buffer(stream, &per_buffer_data);
      if (!BufferIsValid(buf)) break;

      blkno = BufferGetBlockNumber(buf);
      vacrel->scanned_pages++;
      visibilitymap_pin(vacrel->rel, blkno, &vmbuffer);

      got_cleanup_lock = ConditionalLockBufferForCleanup(buf);
      // ..... lazy_scan_new_or_empty() short-circuit for new/empty pages

      // OUR AREA OF INTEREST
      lazy_scan_prune(vacrel, buf, blkno, page, vmbuffer,
                       all_visible_according_to_vm, &has_lpdead_items, &vm_page_frozen); => {
         PruneFreezeResult presult;
         int prune_options = HEAP_PAGE_PRUNE_FREEZE;
         if (vacrel->nindexes == 0)
            prune_options |= HEAP_PAGE_PRUNE_MARK_UNUSED_NOW;

         // OUR AREA OF INTEREST — the real per-page workhorse
         heap_page_prune_and_freeze(rel, buf, vacrel->vistest, prune_options,
                                     &vacrel->cutoffs, &presult, PRUNE_VACUUM_SCAN,
                                     &vacrel->offnum,
                                     &vacrel->NewRelfrozenXid, &vacrel->NewRelminMxid); => {
            for (offnum = maxoff; offnum >= FirstOffsetNumber; offnum = OffsetNumberPrev(offnum)) {
               ItemId itemid = PageGetItemId(page, offnum);
               // ..... LP_UNUSED / LP_DEAD / LP_REDIRECT items handled directly

               // classify each normal tuple:
               prstate.htsv[offnum] = heap_prune_satisfies_vacuum(&prstate, &tup, buffer); => {
                  //  calls HeapTupleSatisfiesVacuumHorizon()
                  // returns HEAPTUPLE_DEAD / RECENTLY_DEAD / LIVE / INSERT_IN_PROGRESS / DELETE_IN_PROGRESS
               }

               if (!HeapTupleHeaderIsHeapOnly(htup))
                  prstate.root_items[prstate.nroot_items++] = offnum;
               else
                  prstate.heaponly_items[prstate.nheaponly_items++] = offnum; // HOT chain member
            }

            // ..... walk HOT chains: collapse dead intermediate versions,
            //       rewrite root line pointer as LP_REDIRECT to the surviving tuple

            // for each surviving tuple, consider freezing:
            if (prstate->freeze) {
               // OUR AREA OF INTEREST
               heap_prepare_freeze_tuple(htup, prstate->cutoffs, &prstate->pagefrz,
                                          &prstate->frozen[prstate->nfrozen],
                                          &totally_frozen); => {
                  // heapam.c — decides if xmin/xmax older than FreezeLimit/MultiXactCutoff
                  // must be rewritten frozen; feeds presult.all_frozen for the VM bit
               }
               prstate->frozen[prstate->nfrozen++].offset = offnum;
            }

            // ..... apply all changes (redirect/dead/unused/frozen arrays) to the page,
            //       WAL-log via log_heap_prune_and_freeze(), set presult.all_visible/all_frozen
         }

         if (presult.lpdead_items > 0) {
            qsort(presult.deadoffsets, presult.lpdead_items, sizeof(OffsetNumber), cmpOffsetNumbers);
            // OUR AREA OF INTEREST — feeds Stage 2/3
            dead_items_add(vacrel, blkno, presult.deadoffsets, presult.lpdead_items); => {
               // vacuumlazy.c:3538 — inserts TIDs into the bounded TidStore
            }
         }

         // ..... if presult.all_visible, set VM bit(s) via visibilitymap_set()
      }
   }
}

Phase 2: Index Vacuuming

Once the TID store fills up (or the heap scan finishes), lazy_vacuum calls each index's bulk-delete routine (e.g., btree's btbulkdelete) with the TID store, so all index entries pointing at now-dead heap tuples are removed. This can run in parallel across indexes.

lazy_vacuum(LVRelState *vacrel) { 
   // ..... bypass-optimization check (skip index vacuuming if lpdead_item_pages is near zero)

   else if (lazy_vacuum_all_indexes(vacrel)) => {
      
      for (int idx = 0; idx < vacrel->nindexes; idx++) {
         Relation indrel = vacrel->indrels[idx];
         IndexBulkDeleteResult *istat = vacrel->indstats[idx];

         // OUR AREA OF INTEREST
         vacrel->indstats[idx] = lazy_vacuum_one_index(indrel, istat, old_live_tuples, vacrel); => {
            IndexVacuumInfo ivinfo = { .index = indrel, .heaprel = vacrel->rel, /* ..... */ };

            istat = vac_bulkdel_one_index(&ivinfo, istat, vacrel->dead_items,
                                           vacrel->dead_items_info); => {
               // OUR AREA OF INTEREST — calls into the *index* AM, e.g. btree's btbulkdelete
               istat = index_bulk_delete(ivinfo, istat, vac_tid_reaped, dead_items); => {
                  // indrel->rd_indam->ambulkdelete(...)
                  // walks the index, for each entry asks vac_tid_reaped(TID)
                  // whether that TID is in vacrel->dead_items (the TidStore from Stage 1),
                  // and deletes the matching index tuples
               }
            }
            return istat;
         }
      }
   }
   // ..... on success, proceeds straight into Stage 3 below
}

Phase 3: Heap Vacuuming

lazy_vacuum_heap_rel / lazy_vacuum_heap_page revisit each page recorded in the TID store and finally flip LP_DEAD line pointers to LP_UNUSED, actually freeing the slot for reuse. This can only happen after Phase 2 guarantees no index still references those TIDs – otherwise you'd get index entries pointing at garbage or reused tuples, a classic corruption bug.

lazy_vacuum_heap_rel(vacrel) { 
   // ..... TidStoreIterate over every blkno recorded in Stage 1's dead_items

   lazy_vacuum_heap_page(vacrel, blkno, buffer, deadoffsets, num_offsets, vmbuffer); => {
     
      Page page = BufferGetPage(buffer);
      START_CRIT_SECTION();

      for (int i = 0; i < num_offsets; i++) {
         ItemId itemid = PageGetItemId(page, deadoffsets[i]);
         Assert(ItemIdIsDead(itemid) && !ItemIdHasStorage(itemid));
         // OUR AREA OF INTEREST — the actual space reclamation
         ItemIdSetUnused(itemid);   // slot is now free for reuse by future inserts
         unused[nunused++] = deadoffsets[i];
      }

      PageTruncateLinePointerArray(page);   // shrink the line-pointer array if possible
      MarkBufferDirty(buffer);

      if (RelationNeedsWAL(vacrel->rel))
         log_heap_prune_and_freeze(vacrel->rel, buffer, InvalidTransactionId, false,
                                    PRUNE_VACUUM_CLEANUP, /* ..... */
                                    unused, nunused);
      END_CRIT_SECTION();

      // ..... recheck heap_page_is_all_visible() now that dead items are gone,
      //       set VM bit if so
   }
   // ..... FreeSpaceMapVacuumRange() makes the freed space visible to future inserters
}

Phase 4: Finishing Up

• FreeSpaceMapVacuumRange propagates newly freed space up the FSM tree.

• If trailing pages are entirely empty, the relation is truncated.

• relfrozenxid/relminmxid in pg_class are advanced to vacrel->NewRelfrozenXid/NewRelminMxid, and stats (pg_stat_user_tables, pg_class.reltuples) are updated.

Conclusion

MVCC is what makes PostgreSQL's concurrency model work – readers never block writers, and writers never block readers – but that guarantee isn't free. Every UPDATE and DELETE leaves behind a dead tuple, a set of stale index entries, and eventually an unfrozen XID, and none of that debt clears itself.

VACUUM is the mechanism that pays it down, and the three-phase design exists specifically so that payoff can happen safely and efficiently:

• Scan, Prune, and Freeze finds what's dead and rewrites what's old enough to freeze, using the visibility map to skip pages that don't need the work.

• Index Vacuuming clears every index's references to those dead tuples first — this ordering is what keeps the next phase safe.

• Heap Vacuuming only then flips the now-unreferenced line pointers to LP_UNUSED, actually handing the space back for reuse.

That ordering – indexes before heap – is the detail worth remembering above all else. Reclaim heap space before indexes are cleaned up, and you get index entries pointing at tuples that no longer mean what they used to: exactly the class of corruption bug the two-phase split (Phase 2 then Phase 3) is built to prevent.

The freezing work matters just as much as the space reclamation, if not more — it's not an optimization, it's what keeps the 32-bit XID counter from wrapping around and making old, unfrozen rows look like they were written in the future. Skip VACUUM long enough, and that's the failure mode you eventually hit, not just table bloat.

So many genres, right? When I bought it, I thought it was a crime mystery. But once I finished, I felt the other two genres fit just as well.

Plot

What is intended to be a bank robbery turns into a hostage situation when the robber fails to rob the bank and enters an apartment to escape the police.

This story is about the group of hostages and the robber – in other words, idiots (sorry, I'm not calling them that – the author did). It's about how the hostage situation brings them closer, and what happens to the robber in the end.

My Thoughts

This book isn't really about the robbery or hostage situation. It's about how quickly people judge others, their quirks, and who they become in the present. It also touches on the private battles everyone in that room is fighting, and the empathy that helps them through it. And that's what stuck with me long after I finished it.

My favourite quote from the book goes:

They say that a person's personality is the sum of their experiences. But that isn't true, at least not entirely, because if our past was all that defined us, we'd never be able to put up with ourselves. We need to be allowed to convince ourselves that we're more than the mistakes we made yesterday. That we are all our next choices, too, all of our tomorrows – Fredrik Backman, Anxious People

My Ratings: 4.5/5

In this blog, we are going to discuss about the "Replication" and how it helps the PostgreSQL to keep the data safe across multiple machines. A single server in a system is always a single point of failure and replication is what turns PostgreSQL into a high-availability system. In this we are going to discuss that exact mechanics of replication: how WAL bytes flow from primary to standby, how logical decoding transforms those bytes into row-level changes, how replication slots prevent data loss, and what happens at every layer when you commit a transaction on a synchronous replica setup.

Part 1: Replication Fundamentals

PostgreSQL supports two fundamentally different replication approaches:

1. Physical/Streaming Replication

2. Logical Replication

Physical Replication

Ships raw WAL bytes from primary to standby. The standby replays the exact same WAL records the primary wrote - byte for byte. The result is a binary-identical copy of the primary.

Primary                           Standby
  │                                  │
  │─ WAL record (INSERT, page  X) ─>│
  │─ WAL record (UPDATE, page  Y) ─>│─ replay → apply to data files
  │─ WAL record (COMMIT, xid=5001)─>│
  │<─ acknowledgement (LSN) ─────│

Characteristics:

• Replicates everything: all databases, all tables, system catalogs

• Standby is identical at the block level: cannot have different indexes or schema

• Standby can serve read-only queries (hot standby)

Logical Replication

Decodes WAL records into SQL-level row changes (INSERT/UPDATE/DELETE) and ships those instead. The subscriber applies the changes to its own tables.

Primary                              Subscriber
  │                                     │
  │── WAL record (heap INSERT) ─>     │
  │   logical decoding  ────────>  │
  │   row: {id=42, name='alice'}  ───>│── apply INSERT
  │<── confirmation  ───────────│

Characteristics:

• Replicates specific tables or publications, not the whole cluster

• Subscriber can have different schema, indexes, additional columns

• Can replicate between different PostgreSQL major versions

• Powers CDC (change data capture) pipelines

• Cannot replicate DDL automatically

Part 2: Physical Replication - Deep Internals

Setting up streaming replication

-- On Primary: postgresql.conf
wal_level = replica    -- minimum for replication
max_wal_senders = 5    -- max concurrent WAL sender processes
wal_keep_size = 1GB    -- Keep at-least 1GB of WAL for lagging standbys

-- Create replication role
CREATE ROLE replicator WITH REPLICATION LOGIN PASSWORD 'secret';

-- pg_hba.conf
host replication replicator standby_ip/32 scram-sha-256

-- On Standby: create base-backup
pg_basebackup -h primary_ip -U replicator -D /var/lib/postgresql/data \
     -P -Xs -R

-- -Xs = stream WAL during backup
-- -R = create standby.signal and postgresql.auto.conf automatically

The WAL sender: WAL receiver pipeline

Primary process tree:

• Postmaster

  • WAL Sender (one per standby connection)

    • reads WAL from pg_wal/

    • sends to standby over TCP

    • tracks standby's replay position

Standby process treee:

• Postmaster

  • Startup process (replays WAL in recovery mode)

  • WAL receiver (receives WAL from primary)

    • writes to pg_wal/

    • signals startup process: new WAL available

The Replication Protocol - Exact Sequence

Standby → Primary:  START_REPLICATION LSN timeline
Primary → Standby:  XLogData (WAL bytes, starting_lsn, current_lsn, send_time)
Standby → Primary:  Standby Status Update (every wal_receiver_status_interval)
         write_lsn   — written to pg_wal on standby
         flush_lsn   — fsynced on standby
         replay_lsn  — applied to data files on standby
         reply_time

Hot Standby: Read queries on standy

The standby's startup process replays WAL while simultaneously serving read-only queries. This works because:

Standby maintains its own:

• shared buffer pool

• MVCC snapshot (based on replayed transactions)

• pg_stat_activity for its own connections

• local lock table

Standby does NOT have:

• writable data files (read-only replay)

• its own transaction IDs (read use primary's XIDs)

• ability to run VACUUM independently

-- On standy: read-only queries work fine
SELECT count(*) FROM orders; -- OK

-- Writes are rejected:
INSERT INTO orders VALUES (...);
-- ERROR: cannot execute INSERT in a read-only transaction

Part 3: Replication Slots

Replication slots solve a critical problem: What if the standby falls behind?

Without replication slots, if a standby disconnects, the primary might delete WAL files the standby still needs. When the standby reconnects, it cannot continue - it has to do a full base backup again.

How replication slots work

-- Create a physical replication slot:
SELECT pg_create_physical_replication_slot('standby_slot');

-- The slot records:
-- restart_lsn: the oldest WAL position the standby still needs
-- confirmed_flush_lsn: the latest position the standby confirmed

-- Primary will NOT delete WAL files before restart_lsn
-- even if the standby is disconnected for days/weeks

-- Monitor replication slots:
SELECT
    slot_name,
    slot_type,              -- physical or logical
    active,                 -- is a consumer currently connected?
    restart_lsn,            -- oldest WAL the slot needs
    confirmed_flush_lsn,    -- last position confirmed by consumer
    pg_wal_lsn_diff(
        pg_current_wal_lsn(),
        restart_lsn
    ) AS retained_wal_bytes,
    pg_size_pretty(pg_wal_lsn_diff(
        pg_current_wal_lsn(),
        restart_lsn
    )) AS retained_wal
FROM pg_replication_slots;

The replication slot danger

If a replication slot's consumer goes offline and never comes back, the slot continues to hold WAL. pg_wal/ grows indefinitely. When the disk fills: PRIMARY CRASHES.

Real scenario:

• Day 1: slot created for subscriber

• Day 3: subscriber host dies

• Day 10: primary disk is full

• Day 10: primary crashes: could not write to file pg_wal/...

Monitoring

-- CRITICAL monitoring query — run this every 5 minutes:
SELECT
    slot_name,
    active,
    pg_size_pretty(
        pg_wal_lsn_diff(pg_current_wal_lsn(), restart_lsn)
    ) AS wal_retained,
    pg_wal_lsn_diff(pg_current_wal_lsn(), restart_lsn) AS retained_bytes
FROM pg_replication_slots
ORDER BY retained_bytes DESC;

-- Alert if retained_bytes > 10GB
-- Drop dead slots immediately:
SELECT pg_drop_replication_slot('dead_slot');

Part 4: Synchronous v/s Asynchronous Replication

Asynchronous replication (default)

Primary: COMMIT → WAL written + fsynced locally → SUCCESS returned to client

Standby: receives WAL asynchronously (milliseconds to seconds later)

Risk: if primary crashes immediately after COMMIT, standby may not have received that WAL yet means data loss of committed transactions

Synchronous replication

-- postgresql.conf on primary:
synchronous_standby_names = 'standby1'

-- or for multiple:
synchronous_standby_names = 'FIRST 1 (standby1, standby2)'  -- any one of them
synchronous_standby_names = 'ALL (standby1, standby2)'      -- all of them

Primary: when COMMIT, it follows:

• write WAL locally

• send WAL to standby

• WAIT for acknowledgement from standby

• standby confirms flush_lsn >= commit_lsn

• SUCCESS returned to client

Guarantee: no committed transaction can be lost (both primary and standby must fail simultaneously)

Cost: COMMIT latency += network round trip to standby (~0.5ms on LAN, ~5ms on WAN, ~50ms cross-region)

synchronous_commit levels

-- Per-transaction control:
SET synchronous_commit = on;           -- wait for standby flush (default)
SET synchronous_commit = remote_apply; -- wait for standby to replay
SET synchronous_commit = remote_write; -- wait for standby OS write (no fsync)
SET synchronous_commit = local;        -- only wait for local fsync
SET synchronous_commit = off;          -- don't wait for anything

-- Use off for bulk loads where some data loss is acceptable:
BEGIN;
SET LOCAL synchronous_commit = off;
INSERT INTO events SELECT * FROM staging_events;
COMMIT;  -- returns immediately, standby catches up later

Part 5: Logical Replication - Deep Internals

The logical decoding pipeline

WAL stream
  │
  V
Output Plugin (pgoutput, wal2json, decoderbufs...)
  │  reads WAL records
  │  filters by publication tables
  │  reconstructs row images from before/after
  │  emits logical change messages:
  │    BEGIN xid=5001
  │    INSERT relation=orders tuple=(42,'alice',100.00)
  │    UPDATE relation=orders old=(42,'alice',100.00) new=(42,'alice',150.00)
  │    COMMIT xid=5001 lsn=0/1A3F058
  V
Replication Protocol
  │
  V
Subscriber (apply worker)
  applies changes to subscriber tables

Publications and subscription

On publisher (primary)

-- Publish all tables:
CREATE PUBLICATION my_pub FOR ALL TABLES;

-- Publish specific tables:
CREATE PUBLICATION orders_pub FOR TABLE orders, customers;

-- Publish specific operations:
CREATE PUBLICATION insert_only_pub FOR TABLE events
    WITH (publish = 'insert');  -- only INSERT, not UPDATE/DELETE

-- See what's published:
SELECT * FROM pg_publication;
SELECT * FROM pg_publication_tables;

On subscriber

-- Create subscription:
CREATE SUBSCRIPTION my_sub
    CONNECTION 'host=primary_ip dbname=mydb user=replicator password=secret'
    PUBLICATION my_pub;

-- PostgreSQL automatically:
-- 1. Creates a replication slot on the publisher
-- 2. Takes a snapshot of current data
-- 3. Copies existing table data (initial sync)
-- 4. Starts streaming new changes

-- Detailed per-table sync status:
SELECT * FROM pg_subscription_rel;
-- srsubstate: i=initializing, d=data copy, s=synchronized, r=ready

REPLICA IDENTITY - how UPDATE/DELETE know what changed

For UPDATE and DELETE, the subscriber needs to identify which row to modify. This requires a REPLICA IDENTITY:

-- Default: REPLICA IDENTITY DEFAULT
-- Uses primary key columns as identifier
-- If no PK: cannot replicate UPDATE/DELETE

-- FULL: send entire old row (expensive, no PK needed)
ALTER TABLE orders REPLICA IDENTITY FULL;

-- USING INDEX: use a unique index
ALTER TABLE orders REPLICA IDENTITY USING INDEX idx_orders_uuid;

-- Check:
SELECT relname, relreplident FROM pg_class WHERE relname = 'orders';
-- d = default (PK), f = full, i = index, n = nothing

Part 6: Logical Replication Slots - The Decoding Engine

A logical replication slot is more complex than a physical one:

-- Create a logical slot manually (for CDC, not subscription):
SELECT pg_create_logical_replication_slot('my_slot', 'pgoutput');
SELECT pg_create_logical_replication_slot('cdc_slot', 'wal2json');

-- Peek at decoded changes without consuming:
SELECT * FROM pg_logical_slot_peek_changes('my_slot', NULL, NULL);

-- Consume changes (advances the slot):
SELECT * FROM pg_logical_slot_get_changes('my_slot', NULL, NULL);

-- Output with wal2json (JSON format for CDC pipelines):
SELECT * FROM pg_logical_slot_get_changes(
    'cdc_slot', NULL, NULL,
    'pretty-print', '1',
    'include-timestamp', '1'
);

The logical slot stores:

• restart_lsn : WAL must be kept from here (same as physical)

• confirmed_flush_lsn : last change confirmed consumed by client

• catalog_xmin : oldest XID needed for catalog lookups during decoding

The catalog_xmin is a second wraparound risk specific to logical slots - it prevents VACUUM from cleaning system catalog dead tuples. Monitor it:

SELECT slot_name, catalog_xmin, age(catalog_xmin)
FROM pg_replication_slots
WHERE slot_type = 'logical';
-- age > 500M is dangerous

Part 7: Cascading Replication and Standby Promotion

Cascading Replication

A standby can itself have standbys - WAL flows from primary → standby 1 → standby 2:

Primary ── WAL──> Standby 1 ──WAL──> Standby 2
                       │                    │
                   (hot standby)        (hot standby)
                    reads OK             reads OK

-- On Standby 1: allow WAL senders to Standby 2
-- postgresql.conf:
max_wal_senders = 3
hot_standby = on

-- Standby 2 connects to Standby 1 as its upstream
-- primary_conninfo = 'host=standby1_ip ...'

Standby promotion

When the primary fails, a standby is promoted to become the new primary:

# Promote standby to primary:
pg_ctl promote -D /var/lib/postgresql/data

# Or create a trigger file (older method):
touch /var/lib/postgresql/data/failover.trigger

What happens internally:

• Startup process stops replaying WAL

• Standby completes any in-progress WAL record

• Writes a new timeline history files to pg_wal/

• Increments timeline ID (e.g., timeline 1 -> timeline 2)

• Opens for read-write connections

• Other standbys detect timeline change

  • reconnect to new primary

  • start replicating from the divergence point

Part 8: pg_basebackup and Point-in-Time Recovery (PITR)

Base backup

# Full base backup:
pg_basebackup \
    -h primary_ip \
    -U replicator \
    -D /backup/basebackup_$(date +%Y%m%d) \
    -Ft \          # tar format
    -z \           # gzip compress
    -Xs \          # stream WAL
    -P             # show progress

# Backup manifest (PG 13+): verifies backup integrity
pg_verifybackup /backup/basebackup_20240115/

WAL archiving for PITR

-- postgresql.conf:
archive_mode = on
archive_command = 'aws s3 cp %p s3://my-wal-archive/%f'
-- %p = full path to WAL file
-- %f = filename only

-- Monitor archiving:
SELECT archived_count, failed_count,
       last_archived_wal, last_archived_time,
       last_failed_wal, last_failed_time
FROM pg_stat_archiver;

Point-in-time recovery

# recovery.conf (or postgresql.conf in PG 12+):
restore_command = 'aws s3 cp s3://my-wal-archive/%f %p'
recovery_target_time = '2024-01-15 14:30:00 UTC'
recovery_target_action = 'promote'   # open for writes after reaching target

# PostgreSQL replays WAL until the target time
# Stops at the first commit after target_time
# Then promotes (or pauses for inspection)

-- During recovery, monitor progress:
SELECT pg_last_xact_replay_timestamp();
-- Watch this advance toward your target time

-- After recovery: verify you're at the right point
SELECT max(created_at) FROM orders;  -- did you recover enough?

Part 9: Hands-On Lab

-- ═══ 1. Set up logical replication locally ═══

-- Publisher database (run in psql -d publisher_db):
CREATE TABLE products (
    id bigserial primary key,
    name text,
    price numeric,
    updated_at timestamptz default now()
);
INSERT INTO products(name, price)
VALUES ('Widget A', 9.99), ('Widget B', 19.99), ('Widget C', 4.99);

CREATE PUBLICATION products_pub FOR TABLE products;

SELECT * FROM pg_publication;
SELECT * FROM pg_publication_tables;

-- ═══ 2. Create subscriber ═══

-- Subscriber database (run in psql -d subscriber_db):
CREATE TABLE products (
    id bigint primary key,
    name text,
    price numeric,
    updated_at timestamptz
    -- note: no serial, subscriber doesn't generate IDs
);

CREATE SUBSCRIPTION products_sub
    CONNECTION 'host=localhost dbname=publisher_db user=replicator'
    PUBLICATION products_pub;

-- Check initial sync:
SELECT * FROM products;
-- Should have 3 rows copied from publisher

-- ═══ 3. Watch changes replicate ═══

-- Publisher:
INSERT INTO products(name, price) VALUES ('Widget D', 29.99);
UPDATE products SET price = 11.99 WHERE name = 'Widget A';
DELETE FROM products WHERE name = 'Widget C';

-- Subscriber (immediately after):
SELECT * FROM products;
-- Should reflect all three changes

-- ═══ 4. Monitor the logical slot ═══

-- Publisher:
SELECT slot_name, confirmed_flush_lsn, restart_lsn,
       pg_size_pretty(
           pg_wal_lsn_diff(pg_current_wal_lsn(), restart_lsn)
       ) AS retained_wal
FROM pg_replication_slots;

-- ═══ 5. Peek at raw logical changes ═══

SELECT pg_create_logical_replication_slot('inspect_slot', 'pgoutput');

-- Make some changes:
INSERT INTO products(name, price) VALUES ('Widget E', 39.99);

-- Peek at the decoded stream:
SELECT lsn, xid, data
FROM pg_logical_slot_peek_binary_changes(
    'inspect_slot', NULL, NULL,
    'proto_version', '1',
    'publication_names', 'products_pub'
);

-- Clean up:
SELECT pg_drop_replication_slot('inspect_slot');

-- ═══ 6. Simulate replication lag ═══

-- Pause WAL replay on standby:
SELECT pg_wal_replay_pause();

-- Make changes on primary...
INSERT INTO products(name, price)
SELECT 'Lag test ' || g, g FROM generate_series(1,1000) g;

-- Check lag:
SELECT
    pg_wal_lsn_diff(
        pg_last_wal_receive_lsn(),
        pg_last_wal_replay_lsn()
    ) AS lag_bytes;

-- Resume replay:
SELECT pg_wal_replay_resume();

-- Watch lag decrease:
SELECT pg_wal_lsn_diff(
    pg_last_wal_receive_lsn(),
    pg_last_wal_replay_lsn()
) AS lag_bytes;

-- ═══ 7. PITR practice ═══

-- Record a restore target:
SELECT now() AS restore_target, pg_current_wal_lsn() AS restore_lsn;
-- Save these values

-- Make destructive change:
DELETE FROM products WHERE price < 10;

-- Recover to saved LSN:
-- recovery_target_lsn = '0/1A3F058'  (your saved LSN)
-- recovery_target_action = 'promote'

Conclusion

This is the final module of the PostgreSQL Internals series. We have now traced the complete lifecycle of data in PostgreSQL from the moment SQL text arrives over the wire, through the parser, analyzer, rewriter, planner, and executor; through MVCC visibility checks reading xmin and xmax on heap pages; through WAL records being written and fsynced on COMMIT; through VACUUM reclaiming dead tuples and setting visibility map bits; through lock acquisition and deadlock detection and now through WAL bytes flowing across the network to replicas, being decoded into row-level changes, and powering high-availability and CDC pipelines.

1. Norwegian Wood - by Haruki Murakami

2. The Devotion of Suspect X - by Keigo Higashino

Norwegian Wood

A semi-autobiographical novel disclosing a portion of the author's life. I bought this book after coming across a fair share of posts about it on Instagram. But when I started reading, I just couldn't connect with the storytelling. I tried hard pushed through 50 pages - but it didn't click, so I discontinued it.

So this isn't a review or an opinion - others might love it, it just wasn't for me this time.

The Devotion of Suspect X

At this point, a month never goes by without me reading a crime thriller or suspense novel. The same happened in June, and this time it was The Devotion of Suspect X , a crime thriller revolving around a man's murder.

The Setup

Yasuko lives a quiet life, working in a Tokyo bento shop, a good mother to her only child. But when her ex-husband appears at her door without warning one day, her comfortable world is shattered. When Detective Kusanagi of the Tokyo Police tries to piece together the events of that day, and finds himself confronted by the most puzzling, mysterious circumstances he has ever investigated. Nothing quite makes sense, and it will take a genius to understand the genius behind this particular crime...

My Take

What I like about this book is that it never moves in one straight line i.e., crime, investigation, and capture. It has small, emotional subplots, each with its own significance, adding value to the main plot. Every character involved in this story has a part to play.

Also, this book isn't really a typical who did it, you already know more than the detective does at certain points. And that changes the whole feel of it. It's less about who did it and more about how far someone would go for a person they love. Higashino doesn't rush to a clever twist just for the sake of it, the emotion stays right there with the mystery throughout.

My Ratings: 4.2/5

In today's blog, we'll explore PostgreSQL's table statistics - when, where, and how they get calculated - and finally, take a brief look at how these stats actually help our queries.

Part 1: What are Table Statistics & Why they are important?

Table statistics are estimates about the data that lives inside a table - things like the most common values in a column and their frequencies, the number of distinct values that exist in a column, correlation between columns, and so on.

When you run a query, it enters the PostgreSQL planner, which has to find an efficient and optimised way - in terms of memory usage and data access, to produce the required result. But on what basis does the planner decide whether a generated plan is actually optimised and efficient? That's exactly what statistics tell it.

If the stats are stale, they can easily mislead the planner into generating a bad plan - and a bad plan means bad query performance.

Part 2: Where Do These Statistics Live?

Usually, statistics are stored in two distinct layers: in-memory during ANALYZE, then persisted across three system catalogs.

Layer-1: In-Memory - VacAttrStats

Reference: vacuum.h

During the ANALYZE operation, each column's computed stats live in a VacAttrStats struct:

typedef struct VacAttrStats {
    // Set by ANALYZE before calling typanalyze:
    int         attstattarget;      // sample size target
    Oid         attrtypid;          // column's type OID
    Form_pg_type attrtype;          // pg_type row
    Oid         attrcollid;

    // Set by typanalyze (e.g. std_typanalyze):
    AnalyzeAttrComputeStatsFunc compute_stats;  // fn pointer
    int         minrows;
    void       *extra_data;   // e.g. StdAnalyzeData (eq/lt operators)

    // Filled by compute_stats:
    bool        stats_valid;
    float4      stanullfrac;
    int32       stawidth;
    float4      stadistinct;
    int16       stakind[5];         // slot type codes
    Oid         staop[5];           // operator OIDs per slot
    Oid         stacoll[5];
    float4     *stanumbers[5];      // numeric arrays (frequencies, correlation)
    Datum      *stavalues[5];       // value arrays (MCV values, histogram bounds)
} VacAttrStats;

This is a transient structure - it exists only during ANALYZE and is freed once the stats are flushed to disk.

Layer-2: On-Disk - Three System Catalogs

Once the stats are computed, those stats are flushed into the PostgreSQL catalog tables namely:

• pg_class

• pg_statistic

• pg_statistic_ext + pg_statistic_ext_data - Extended stats

pg_class

pg_class catalog table holds the table-level stats. Like:

pg_statistic

pg_statistic catalog table holds per-column stats. One row per (table, column, stainherit) triple.

Reference: update_attstats()

The kind codes defined in pg_statistic.h determine what each slot means:

pg_statistic_ext + pg_statistic_ext_data - Extended stats

Created by CREATE STATISTICS, populated by ANALYZE. split across two tables by design:

pg_statistic_ext (OID 3381) - the definition (created once, survives until DROP STATISTICS):

pg_statistic_ext_data(OID 3429) — the computed data (overwritten each ANALYZE):

Part 3: When Is ANALYZE Called

There are two distinct ways ANALYZE gets triggered: manually, by you running the command yourself, and automatically, via autovacuum's analyze sub-process.

Trigger 1: Manual ANALYZE

We can invoke it directly:

ANALYZE table_name;            -- single table
ANALYZE table_name(col1, col2); -- specific columns only
ANALYZE;                        -- entire database

This runs synchronously, in our session, immediately recomputing stats for the target relation(s).

Trigger 2: Autoanalyze - The Threshold Formula

PostgreSQL's autovacuum launcher doesn't just watch for dead tuples (which trigger VACUUM) - it separately tracks how many rows have been inserted, updated, or deleted since the last ANALYZE, and compares that against a computed threshold:

analyze threshold = autovacuum_analyze_threshold + (autovacuum_analyze_scale_factor * reltuples)

Where:

• autovacuum_analyze_threshold : a flat minimum, default 50 rows

• autovacuum_analyze_scale_factor : a fraction of table size, default 0.1 (10%)

• reltuples : the table's estimated row count, read from pg_class

So for a table with 100,000 rows, using defaults: the analyze threshold equals the analyze base threshold plus the analyze scale factor multiplied by the number of tuples, giving 50 + (0.1 × 100,000) = 10,050. Once 10,050+ rows have changed since the last ANALYZE, the table becomes a candidate for autoanalyze.

Part 4: How Are They Actually Computed? - The ANALYZE Call Tree

Here's the full execution path, from the moment we run ANALYZE to the moment stats land in pg_statistic:

ANALYZE command => {
    analyze_rel() => {
        do_analyze_rel() => {
            // examine_attribute() is called once per column to analyze
            // Builds VacAttrStats per column
            examine_attribute() => {
                std_typanalyze(); // sets the compute_stats fn pointer
            }

            // acquire_sample_rows() is called once per column to sample rows
            // samples ~300 × target rows using reservoir sampling
            acquire_sample_rows() => {
                BlockSampler_Init(); // picks random blocks to read
                reservoir sampling; // keeps a uniform random subset
            }

            // compute_stats() is called once per column to compute statistics
            // computes scalar, distinct, and trivial statistics
            compute_stats() => {
                compute_scalar_stats(); // computes scalar statistics 
                compute_distinct_stats(); // computes distinct statistics
                compute_trivial_stats(); // computes trivial statistics
            }
            
            update_attstats() => {
                INSERT/UPDATE into pg_statistic
            }
        }
    }
}

Part 5: Why Any of This Matters - Stats and the Query Planner

Everything we've covered so far - pg_statistic, the ANALYZE call tree, the sampling - exists for one reason: so that when the planner sees a query, it can guess how many rows will come out of each step, before actually running it. Those row estimates are what decide whether you get a fast index scan or a slow sequential scan.

Let's see this directly, with a table simple enough to set up in seconds:

CREATE TABLE sample (id INT PRIMARY KEY, col1 TEXT);
INSERT INTO sample SELECT i, 'col' || i FROM generate_series(1, 1000000) i;
ANALYZE sample;

A million rows, one indexed integer column, one text column. Now:

EXPLAIN ANALYZE SELECT * FROM sample WHERE id = 50042;

Output:

Index Scan using sample_pkey on sample  (cost=0.42..8.44 rows=1 width=13) (actual time=0.012..0.012 rows=1.00 loops=1)
  Index Cond: (id = 50042)
  Index Searches: 1
  Buffers: shared hit=4
Planning:
  Buffers: shared hit=17
Planning Time: 0.290 ms
Execution Time: 0.028 ms

Look at rows=1 in the planner's estimate, and then rows=1.00 in the actual execution result right next to it. The planner predicted exactly one row and it was right.

Why? Because id is the primary key, which means it's backed by a unique index. When ANALYZE ran, it stored n_distinct = 1,000,000 for this column (every value distinct), with no MCV list at all - no value is any more common than another. So when the planner sees id = 50042, it doesn't need a histogram or anything fuzzy: it knows there's exactly one matching value, period. That's why it confidently chose an Index Scan instead of scanning the whole table - cost=0.42..8.44 is tiny, because the estimate told it there's almost nothing to fetch.

This is the entire point of everything in Parts 1 through 5. The planner never touched all 1,000,000 rows to make this decision. It looked at the statistics - built from a sample, stored in pg_statistic, computed back when ANALYZE ran - and used them to predict the outcome before running anything.

Part 6: Putting It All Together

We started this post asking a simple question: when, where, and how does PostgreSQL calculate the statistics that its planner depends on?

We've now traced the entire lifecycle:

• What stats are and why a planner can't make good decisions without them

• Where they live: transiently in VacAttrStats during ANALYZE, and permanently across pg_class, pg_statistic, and the extended-stats catalogs

• When they get triggered : manually, or automatically once autovacuum's analyze threshold formula is crossed

• How they're actually computed : the full call tree from analyze_rel() down through sampling and per-column stat computation, to being written back via update_attstats()

• And finally, why it all matters - watching the planner use exactly these numbers, live, in a real EXPLAIN ANALYZE, to confidently pick an index scan over a sequential scan

"Will you ever go out?"

Well. That is really a tough question for me to answer, to be honest.

And yes. I go out.

FYI, I am not talking about BTech - because I was a big NOO! guy for every single invitation I got from friends to go out, and eventually they stopped asking me anyway- even I would have stopped asking, if someone says NO always. Honestly, not much of a difference - and since my sister was in the same city, it didn't bother me much either then, though it stings a little now. Current working days are not very different either, but I will say - I did go out and hang out with my office friends for a bit (not a bit, maybe some good 1 year), before the NOO! guy in me woke up again. And you can guess what follows.

Fast forward to present - 3 years of work experience. I said I go out, and I also said the NOO! guy returned after 1 year. So what happened in the remaining 2 years?

Learnt PostgreSQL and got deep expertise in my domain - oh! Sorry, wrong blog. Back to the topic.

I worked on myself (not at 100%, but still), got better state of mind, and then one day, my Instagram feed showed a "solo date" reel, which stuck me in mind.

Experimental Day Out

On one fine day - not a weak day, mind you; dressed up, wore new shoes, went to a cafe ~20KM from where I stay, sat by myself and ordered coffee and pasta.

There were friends, families and couples sitting around me, eating, chatting and laughing. And there was me - sitting all by myself, sipping coffee and playing that one feel-good romantic song on Spotify.

You think awkward right? of course it was, but I sat there through it all to complete the very last bite of the food I ordered. But I kinda liked it, be it taking small length videos, some random pics of random places and food.

So, the catch is - yes, I go out. But alone.

The Tradition

Since then, I went to movies, restaurants, cafes and even a cricket match - all by myself. Sitting at a table, earphones in, eating. Watching a movie in a theatre, no earphones there, FYI. Sitting in a stadium surrounded by groups cheering together. And then me, just me, in the middle of all of it.

I won't say I didn't miss going out with people, but at the same time I enjoyed my company after a very very long time, after a series of really bad years.

The only downside of this tradition is "It is costly" and only my wallet is suffering for it :)

To Anyone Reading This

It is not like, I would love always go out all by myself, I do love going trips, outings, some gossips and enjoying with friends, even I had some of the great memories in my previous trips, and memories don't have to be so expensive or expressive, a 10-20 minute conversation will do.

So if any of you have plans to include me, just ping me. I would love to come. Fair warning, there is NOO! guy still in me, so I might say No, but don't take it to heart.

See Yaa!!

Part 1: What is TableAmRoutine?

TableAmRoutine is the Table Access Method (AM) API - a vtable (struct of function pointers) that defines the complete interface between the PostgreSQL executor/planner and a storage engine. This is a core extensibility feature that lets change how PostgreSQL store and retrieve the data without changing the planner and executor layer.

Every table in PostgreSQL has a pg_am catalog entry. When the executor needs to do anything with a table be it scan, insert, vacuum. It goes through rel->rd_tableam , which points to the registered TableAmRoutine for that table.

Part 2: Some understanding with an Example

CREATE TABLE sample (id int primary key, col1 int);

SELECT * FROM pg_am;
 oid  | amname |      amhandler       | amtype
------+--------+----------------------+--------
    2 | heap   | heap_tableam_handler | t
  403 | btree  | bthandler            | i
  405 | hash   | hashhandler          | i
  783 | gist   | gisthandler          | i
 2742 | gin    | ginhandler           | i
 4000 | spgist | spghandler           | i
 3580 | brin   | brinhandler          | i
(7 rows)

SELECT relname, relam FROM pg_class WHERE oid = 'sample'::regclass;
 relname | relam
---------+-------
 sample  |     2
(1 row)

Now if you see the example provided, relam of "sample" table points to 2 i.e, heap in pg_am. Now when we ran a query on the top of the table "sample", now postgresql calls the handler function i.e heap_tableam_handler which returns the TableAmRoutine containing all the necessary function definitions can be used to perform the operations like SELECT, DMLs, VACUUM etc..

Reference: heapam_methods is the Heap's TableAmRoutine exists at access/heap/heapam_handler.c

Part 3: The Core Design

TableAmRoutine

An API struct for a table AM (Access Methods), which should be allocated in a server-lifetime, typically as a static const struct .

typedef struct TableAmRoutine {
    NodeTag type;        // must be T_TableAmRoutine

    // ~30 function pointers grouped by category
    const TupleTableSlotOps *(*slot_callbacks)(Relation rel);
    TableScanDesc (*scan_begin)(...);
    bool (*tuple_insert)(...);
    // ...
} TableAmRoutine;

Reference: tableam.h

Now whatever the custom storage engine we are writing should define the respective function definitions and map to the respective pointers in the TableAmRoutine. To explain this further, we are going to use existing Heap Access Methods.

Heap AM Vtable

The heap AM implements its own TableAmRoutine vtable as a static const struct as explained above in the heapam_handler.c

static const TableAmRoutine heapam_methods = {
    .type = T_TableAmRoutine,
    .slot_callbacks       = heapam_slot_callbacks,
    .scan_begin           = heap_beginscan,
    .tuple_insert         = heapam_tuple_insert,
    .tuple_update         = heapam_tuple_update,
    .relation_vacuum      = heap_vacuum_rel,
    // ...
};

The Handler Function

This is the entry point which PostgreSQL calls to get the particular custom AM's TableAmRoutine. In heap case, it is defined in the file heapam_handler.c as:

Datum
heap_tableam_handler(PG_FUNCTION_ARGS)
{
	PG_RETURN_POINTER(&heapam_methods);
}

If you observe the name of the handler function heap_tableam_handler . It is the same name stored in the pg_am 's amhandler shown in the part 2.

Register the Access Method

CREATE ACCESS METHOD heap TYPE TABLE HANDLER heap_tableam_handler;

This triggers CreateAccessMethod() in amcmds.c, which:

1. Resolves heap_tableam_handler and validates it returns TABLE_AM_HANDLEROID

2. Inserts one row into pg_am with amtype = 't' (t for table, i for index)

3. Records a dependency: dropping the handler function also drops the AM

Usage

-- New table:
CREATE TABLE my_table (id int, data text) USING heap; -- default is heap anyway, used just for example

-- Existing table (rewrites data):
ALTER TABLE existing_table SET ACCESS METHOD heap;

-- Make it the default for the session:
SET default_table_access_method = heap;

Part 4: How PostgreSQL accesses this when querying?

Every time PostgreSQL tries to open a Relation/Table, it usually loads all the required information into the struct Relation (alias of RelationData ) be it the tuple descriptor, table's OID, PK information etc. In those, there are two properties related to access methods i.e, oid rd_amhandler the OID of the access method (like heap) using by this table and TableAmRoutine *rd_tableam containing the vtable given by the amhandler , in our case methods defined in heapam_methods.

Code flow path in case of relation_open()

Now let's see what is the path of the code which populates the access methods when a relation/table is opened using the function relation_open() .

Note: The nested => { } style below is simplified pseudocode showing the call chain - see relation.c , relcache.c for the actual C source.

Entry Point: relation_open() in the file common/relation.c

Relation relation_open(oid relationId) {
   Relation r;
   // .....
   r = RelationIdGetRelation(relationId); => {
      Relation rd;
      // ..... Here looks into cache, if hit return that, else build Relation

      // Cache Miss: Building from scratch
      rd = RelationBuildDesc(relationId, true); => {
          // Here all the necessary information will be populated
          Relation	relation;

          // ......
          else if (RELKIND_HAS_TABLE_AM(relation->rd_rel->relkind) ||
                   relation->rd_rel->relkind == RELKIND_SEQUENCE) {
                    // OUR AREA OF INTEREST
                    RelationInitTableAccessMethod(relation); => {
                      // Here, the cache lookup will be done to get
                      // the OID of Access method using by this relation
                      tuple = SearchSysCache1(AMOID,
                               ObjectIdGetDatum(relation->rd_rel->relam));
                      aform = (Form_pg_am) GETSTRUCT(tuple);
                      relation->rd_amhandler = aform->amhandler; //OID saved here

                      /*
                       * Now we can fetch the table AM's API struct
                       */
                      InitTableAmRoutine(relation); => {
                         relation->rd_tableam = GetTableAmRoutine(relation->rd_amhandler); => {
                             datum = OidFunctionCall0(amhandler);
                             routine = (TableAmRoutine *) DatumGetPointer(datum);
                             // Some checks will be done here
                             return routine; // THIS IS OUR TABLEAMROUTINE
                         }
                      }
                  }
          }
          // ......
          return relation;
      }
      // .....
      return rd;
   }
   // .....
   return r;
}

Part 5: Callback Groups

Below table summarizing the callback pointer functions declared in TableAmRoutine

Part 6: Example - How executor uses it?

Let's see the case of Executor, how it uses the access methods. The executor never calls these function pointers directly. Instead it uses table_* wrapper functions (tableam.h) which dispatch through rd_tableam :

static inline TableScanDesc
table_beginscan(Relation rel, Snapshot snapshot, int nkeys, ScanKeyData *key)
{
    uint32 flags = SO_TYPE_SEQSCAN | SO_ALLOW_STRAT | SO_ALLOW_SYNC | SO_ALLOW_PAGEMODE;
    return rel->rd_tableam->scan_begin(rel, snapshot, nkeys, key, NULL, flags);
    //          ^^^^^^^^^^^^ vtable dispatch which calls "heap_beginscan" internally
}

Part 7: Why TableAmRoutine Matters

1. Pluggable storage - You can write a custom AM (columnar, in-memory, compressed, etc.) without touching the core executor. Just implement the ~30 callbacks and register with CREATE ACCESS METHOD.

2. Separation of concerns - MVCC visibility, tuple format, physical layout, and vacuum strategy are all encapsulated inside the AM. The executor only sees slots and TIDs.

3. Real-world uses - Citus's columnar AM, Zedstore (experimental), and third-party AMs like Orioledb all use this interface. The default heap AM (DEFAULT_TABLE_ACCESS_METHOD = "heap", tableam.h:29) is just one implementation.

4. TOAST delegation - relation_needs_toast_table, relation_toast_am, and relation_fetch_toast_slice let each AM decide its own large-value storage strategy.

Closing notes

This post covered the interface, the wiring, and how PostgreSQL loads your AM at runtime. What it didn't cover is which callbacks are mandatory versus stubbable, TOAST integration, and the visibility/snapshot contract your AM needs to honour, those deserve their own deep dives. For now, heapam_handler.c and the Orioledb source are the best two codebases to have open while you build.

I wanted something better: a setup where I could ask natural language questions about PostgreSQL source code and get answers grounded in the actual C files on my machine - not from some LLM's training data. And I wanted it free, local, and integrated into my editor.

This post walks through exactly that.

What We're Building

A three-layer stack:

ctags + cscope          → deterministic symbol navigation
pgvector on PG 18       → semantic search over indexed source chunks
Ollama (local LLM)      → natural language reasoning over retrieved context
MCP server              → exposes all of this as tools inside Zed / VSCode

The key insight: these layers answer different types of questions.

• ctags/cscope: "Where is ReadBuffer defined? Who calls it?" - deterministic, instant

• pgvector: "Find code related to buffer eviction clock sweep" - semantic, fuzzy

• LLM: "Explain what this function does in context of buffer management" - reasoning

No single tool does all three well. Together, they cover the full range of questions you ask when reading unfamiliar source code.

Prerequisites

• PostgreSQL running locally with pgvector extension

• PostgreSQL Source code

• Zed or VSCode with GitHub Copilot / Agent Panel

Step 1: Install Ollama

# Install via official installer (not Homebrew — the brew version
# may be missing the llama-server binary)
curl -fsSL https://ollama.com/install.sh | sh

Pull two models — one for embeddings, one for chat:

# Lightweight code reasoning model (~4.5GB, runs well on 16GB M-series)
ollama pull qwen2.5-coder:7b

# Embedding model (~500MB)
ollama pull nomic-embed-text

A note on RAM: qwen2.5-coder:7b uses ~4.5GB when loaded. Models only load into RAM when a request comes in and unload after ~5 minutes of idle. So the server itself (ollama serve) is just ~50MB - start it when you need it, kill it when done.

# Start manually
ollama serve

# Stop (Ctrl+C, or from another terminal)
pkill ollama

Step 2: Set Up pgvector

brew install pgvector
(or) 
make PG_CONFIG=$pg_config install

Connect to your PostgreSQL cluster and set up the schema:

CREATE DATABASE pg_source_index;
\c pg_source_index

CREATE EXTENSION vector;

CREATE TABLE code_chunks (
    id            SERIAL PRIMARY KEY,
    file_path     TEXT NOT NULL,
    function_name TEXT,
    chunk_text    TEXT NOT NULL,
    embedding     vector(768),
    start_line    INT,
    end_line      INT,
    subsystem     TEXT
);

-- HNSW index for fast cosine similarity search
CREATE INDEX ON code_chunks
USING hnsw (embedding vector_cosine_ops);

I set it up on PostgreSQL 18, the table ends up at ~297MB for the full PostgreSQL source (33,734 chunks).

Step 3: Build cscope + ctags Index

brew install cscope universal-ctags

From your PostgreSQL source root:

# ctags — jump-to-definition, call hierarchies
ctags -R --languages=C --fields=+iaS --extras=+q .

# cscope — cross-reference index (who calls what, where defined)
find . -name "*.c" -o -name "*.h" | xargs ls 2>/dev/null > cscope.files
cscope -b -q -k

You'll get a tags file and three cscope.out files. These are deterministic and fast — no LLM involved.

Note: You may see warnings about missing generated files (fmgroids.h, nodetags.h, etc.). These are build-time generated files. The index still builds correctly for all existing source files.

Step 4: Index PG Source into pgvector

Create a Python virtual environment:

python3 -m venv ~/pg-tools-env
source ~/pg-tools-env/bin/activate
pip install psycopg2-binary requests mcp

Save this as index_pg_source.py:

import os
import re
import psycopg2
import requests

PG_CONN   = "dbname=pg_source_index"
PG_SRC    = "/path/to/postgresql"       # your PG source root
OLLAMA    = "http://localhost:11434"
EMB_MODEL = "nomic-embed-text"

SUBSYSTEMS = {
    "storage/buffer": "buffer",
    "storage/smgr":   "storage",
    "access/heap":    "heap",
    "executor":       "executor",
    "storage/lmgr":   "locking",
    "access/transam": "mvcc",
    "replication/walreceiver": "wal",
    "access/rmgrdesc": "wal",
}

def get_subsystem(path):
    for pattern, name in SUBSYSTEMS.items():
        if pattern in path:
            return name
    return "other"

def extract_functions(content):
    chunks = []
    lines = content.split('\n')
    current_chunk = []
    current_start = 1
    brace_depth = 0
    in_function = False

    for i, line in enumerate(lines, 1):
        current_chunk.append(line)
        brace_depth += line.count('{') - line.count('}')
        if brace_depth == 0 and in_function:
            chunk_text = '\n'.join(current_chunk)
            if len(chunk_text.strip()) > 50:
                chunks.append((chunk_text, current_start, i))
            current_chunk = []
            current_start = i + 1
            in_function = False
        elif brace_depth > 0:
            in_function = True

    return chunks

def embed(text):
    resp = requests.post(f"{OLLAMA}/api/embeddings", json={
        "model": EMB_MODEL,
        "prompt": text[:2000]
    })
    return resp.json()["embedding"]

def index_file(cur, filepath):
    with open(filepath, 'r', errors='ignore') as f:
        content = f.read()

    subsystem = get_subsystem(filepath)
    chunks = extract_functions(content)

    for chunk_text, start, end in chunks:
        match = re.search(r'^(\w+)\s*\(', chunk_text, re.MULTILINE)
        fn_name = match.group(1) if match else None
        embedding = embed(chunk_text)
        cur.execute("""
            INSERT INTO code_chunks
                (file_path, function_name, chunk_text, embedding,
                 start_line, end_line, subsystem)
            VALUES (%s, %s, %s, %s, %s, %s, %s)
        """, (filepath, fn_name, chunk_text, embedding, start, end, subsystem))

def main():
    conn = psycopg2.connect(PG_CONN)
    conn.autocommit = True
    cur = conn.cursor()

    c_files = []
    for root, _, files in os.walk(PG_SRC):
        for f in files:
            if f.endswith('.c') or f.endswith('.h'):
                c_files.append(os.path.join(root, f))

    print(f"Indexing {len(c_files)} files...")
    for i, fp in enumerate(c_files):
        print(f"[{i+1}/{len(c_files)}] {fp}")
        try:
            index_file(cur, fp)
        except Exception as e:
            print(f"  ERROR: {e}")

    print("Done.")

if __name__ == "__main__":
    main()

Run it (takes 15–30 minutes, one-time):

ollama serve &
python index_pg_source.py

Verify:

SELECT COUNT(*) FROM code_chunks;

Step 5: The MCP Server

This is where it comes together. Instead of switching to a terminal to query the index, we expose it as MCP tools directly inside the editor.

Save as pg_mcp_server.py:

import subprocess
import psycopg2
import requests
from mcp.server.fastmcp import FastMCP

PG_CONN     = "dbname=pg_source_index"
OLLAMA      = "http://localhost:11434"
EMB_MODEL   = "nomic-embed-text"
CHAT_MODEL  = "qwen2.5-coder:7b"
TOP_K       = 5
PG_SRC      = "/path/to/postgresql"     # where cscope.out lives

mcp = FastMCP("pg-source-explorer")

def embed(text):
    resp = requests.post(f"{OLLAMA}/api/embeddings", json={
        "model": EMB_MODEL, "prompt": text[:2000]
    })
    return resp.json()["embedding"]

def vector_search(query, subsystem=None, top_k=TOP_K):
    conn = psycopg2.connect(PG_CONN)
    cur  = conn.cursor()
    q_embed = str(embed(query))
    if subsystem:
        cur.execute("""
            SELECT file_path, function_name, chunk_text, subsystem,
                   1 - (embedding <=> %s::vector) AS similarity
            FROM code_chunks WHERE subsystem = %s
            ORDER BY embedding <=> %s::vector LIMIT %s
        """, (q_embed, subsystem, q_embed, top_k))
    else:
        cur.execute("""
            SELECT file_path, function_name, chunk_text, subsystem,
                   1 - (embedding <=> %s::vector) AS similarity
            FROM code_chunks
            ORDER BY embedding <=> %s::vector LIMIT %s
        """, (q_embed, q_embed, top_k))
    rows = cur.fetchall()
    cur.close(); conn.close()
    return rows

@mcp.tool()
def ask_pg(question: str, subsystem: str = "") -> str:
    """
    Ask a natural language question about PostgreSQL internals.
    Searches indexed PG source and returns an LLM answer grounded
    in actual source context.

    Args:
        question  : e.g. "How does PostgreSQL evict dirty buffers?"
        subsystem : Optional filter — buffer, wal, executor, mvcc,
                    heap, storage, locking. Leave empty for all.
    """
    results = vector_search(question, subsystem=subsystem.strip() or None)
    if not results:
        return "No relevant chunks found. Is the index built?"

    context = "\n\n---\n\n".join([
        f"File: {r[0]}\nFunction: {r[1]}\nSubsystem: {r[3]}\n\n{r[2]}"
        for r in results
    ])
    prompt = f"""You are an expert in PostgreSQL internals at C source level.
Use the source code context below to answer the question.
Always reference specific function names and file paths.

CONTEXT:
{context}

QUESTION: {question}
Answer:"""

    resp = requests.post(f"{OLLAMA}/api/generate", json={
        "model": CHAT_MODEL, "prompt": prompt, "stream": False
    })
    return resp.json()["response"]

@mcp.tool()
def search_pg(query: str, subsystem: str = "", top_k: int = 5) -> str:
    """
    Semantic search over indexed PostgreSQL source.
    Returns top matching code chunks with file paths and similarity scores.

    Args:
        query     : e.g. "buffer eviction clock sweep"
        subsystem : Optional filter (buffer, wal, executor, etc.)
        top_k     : Number of results (default 5, max 10)
    """
    results = vector_search(query, subsystem=subsystem.strip() or None,
                            top_k=min(top_k, 10))
    if not results:
        return "No results found."

    output = []
    for i, r in enumerate(results, 1):
        output.append(
            f"── Result {i} ──\n"
            f"File: {r[0]}  Function: {r[1]}  "
            f"Subsystem: {r[3]}  Similarity: {r[4]:.3f}\n\n"
            f"{r[2][:800]}{'...' if len(r[2]) > 800 else ''}"
        )
    return "\n\n".join(output)

@mcp.tool()
def search_symbol(symbol: str, search_type: str = "callers") -> str:
    """
    Look up a C symbol in PostgreSQL source using cscope.

    Args:
        symbol      : e.g. "ReadBuffer", "BufMgrLock"
        search_type : callers | definition | references | callees
    """
    type_map = {"callers": "3", "definition": "1",
                "references": "0", "callees": "2"}
    flag = type_map.get(search_type, "3")

    try:
        result = subprocess.run(
            ["cscope", "-d", "-f", f"{PG_SRC}/cscope.out",
             "-L", f"-{flag}", symbol],
            capture_output=True, text=True, timeout=10
        )
        if not result.stdout.strip():
            return f"No {search_type} found for '{symbol}'."

        lines = result.stdout.strip().split('\n')
        output = [f"cscope {search_type} for '{symbol}':\n"]
        for line in lines[:30]:
            parts = line.split()
            if len(parts) >= 3:
                output.append(f"  {parts[0]}:{parts[2]}  (in {parts[1]})")
            else:
                output.append(f"  {line}")
        if len(lines) > 30:
            output.append(f"\n  ... and {len(lines) - 30} more")
        return "\n".join(output)

    except FileNotFoundError:
        return "cscope not found. Run: brew install cscope"
    except subprocess.TimeoutExpired:
        return "cscope timed out."

if __name__ == "__main__":
    print("Starting pg-source-explorer MCP server...")
    print(f"  Chat model : {CHAT_MODEL}")
    print(f"  Embed model: {EMB_MODEL}")
    mcp.run(transport="stdio")

Step 6: Wire into Zed

In Zed settings.json (Cmd+Shift+P → open settings):

{
  "context_servers": {
    "pg-source-explorer": {
      "source": "custom",
      "command": {
        "path": "/Users/yourname/pg-tools-env/bin/python",
        "args": ["/path/to/pg_mcp_server.py"]
      }
    }
  }
}

Restart Zed. Check the Agent Panel for a green dot next to pg-source-explorer.

Step 6 (alt) — Wire into VSCode

Create ~/.vscode/mcp.json for global access:

{
  "servers": {
    "pg-source-explorer": {
      "type": "stdio",
      "command": "/Users/yourname/pg-tools-env/bin/python",
      "args": ["/path/to/pg_mcp_server.py"],
      "env": {}
    }
  }
}

Open the file in VSCode — click the Start CodeLens button that appears above the server entry. Then switch Copilot Chat to Agent mode and enable the tools.

Using It

Always start your PostgreSQL cluster and Ollama first:

bin/pg_ctl -D /path/to/cluster start
source ~/pg-tools-env/bin/activate
ollama serve

Then in the Agent Panel:

# Full RAG answer grounded in source
Use the ask_pg tool to explain how PostgreSQL evicts dirty buffers

# Raw source chunks
Use search_pg to find code related to clock sweep

# Call graph
Use search_symbol to find who calls ReadBuffer

Does It Actually Help?

Honest answer: yes, with caveats.

The biggest value is cscope + ctags — deterministic, instant, no LLM needed.

The RAG layer (ask_pg) is genuinely useful when you want to understand what a function does in context, not just navigate to it. The answer is grounded in your local source, not the LLM's training data - so it references the exact version of PG you're working with.

Here's a concrete example. When I asked about MemoryContext, the RAG answer surfaced the callback mechanism (MemoryContextCallback) - a detail the hosted LLM skipped entirely. That came directly from mcxt.h chunks in the index.

The LLM layer (qwen2.5-coder:7b) is a 7B model - fine for code explanation, not as strong as Claude for architecture reasoning. I use local LLM for source navigation, hosted Claude for design decisions.

Comfortable even on 16GB. Models unload after 5 minutes idle, so you're not paying the RAM cost the whole session.

The Full Stack

Zed / VSCode Agent Panel
        ↓
pg-source-explorer MCP (3 tools)
        ↓
ask_pg → pgvector similarity (HNSW) → qwen2.5-coder:7b
search_pg → pgvector similarity
search_symbol → cscope
        ↓
33,734 chunks of PostgreSQL 18 source — on your machine, for free

The code is on GitHub: https://github.com/samsiva-dev/pg_mcp_server

TL;DR — pg_ext_memcheck runs inside a PostgreSQL backend and watches the MemoryContext tree, shared-memory boundaries, and DSM lifecycle of another extension under test. It catches context leaks, wrong-context allocations, bloat, and shmem overruns — and attributes each finding to the library that caused it. It complements Valgrind; it does not replace it. CI is green on PG 15, 16, 17, and 18. MIT-licensed.

The gap nobody else fills

Valgrind and AddressSanitizer are excellent. If your extension does a use-after-free on a raw malloc'd buffer, or overruns a calloc region, they'll catch it. They've earned their reputation.

But to those tools, a PostgreSQL backend is just another C program that happens to call malloc and free a lot. They have no idea that PostgreSQL layers a MemoryContext abstraction on top of malloc, and that this abstraction has its own correctness rules:

• A palloc() in the wrong context (say, TopMemoryContext instead of a per-query context) is a permanent leak for the lifetime of the backend process — but every byte of it is a perfectly valid heap allocation. Valgrind is silent.

• A child MemoryContext created in _PG_init and never deleted accumulates across every query — but again, the heap allocations are valid. Valgrind is silent.

• An extension writes one byte past its declared ShmemAlloc() region. The page is still mapped, the write doesn't fault, and the corruption only shows up later when a neighbouring struct gives wrong answers. Valgrind, in most builds, is silent.

• A MemoryContextReset() doesn't call free() on individual allocations — it bulk-resets a block list. A pointer into a reset context is not a use-after-free in the malloc sense, but dereferencing it is still a bug. Valgrind is silent.

These are the bugs that cause "weird, hard-to-reproduce" behaviour: session bloat after a few hours, stale-pointer corruption only under concurrent load, OOMs in long-running connections. Every PostgreSQL extension author has seen at least one. None of them are caught by raw-heap tools.

pg_ext_memcheck is built specifically for that class. The intended workflow stays simple:

Valgrind / ASan        →  fix raw heap bugs first
pg_ext_memcheck        →  fix PostgreSQL-semantics bugs second ship

What v0.1.0-beta detects

I want to be precise about what's in the box, because a correctness tool that overstates is worse than useless.

Findings land in a shared-memory ring buffer with severity bands (INFO, WARNING, ERROR), a human-readable detail string, a backend PID, a timestamp — and attribution back to the library that caused them, resolved via dladdr() over the planner/executor hook chain. That attribution is what turns a generic "TopMemoryContext grew by 8 KB" message into something you can actually act on: "…and the library that grew it was my_extension.so."

How it works, briefly

Three pieces, one ring buffer:

1. Context walker — snapshots the MemoryContext tree starting at TopMemoryContext, recording (name, depth, parentHash, totalAllocated, totalFree) for every live context. Identity is name-and-depth based (pointers are unstable across runs), so diffs are stable across PostgreSQL versions.

2. Hook layer — planner_hook and ExecutorStart/ExecutorEnd hooks bracket a query: before-snapshot at the start, after-snapshot at the end, diff in between. The before-snapshot lives in a dedicated long-lived MemoryContext so its lifetime is independent of whichever transient context the planner happens to be running in.

3. Violation log — a 2048-entry LWLock-guarded ring buffer in shared memory. Queryable from SQL (ext_memcheck.end() returns the current session's findings; ext_memcheck.flush_violations() drains it into a regular table for persistence).

A shmem sentinel probe plants byte 0xDE just past the declared end of registered segments and verifies it after the workload runs — that's the shmem-overrun detector. DSM segments can be tracked manually via track_dsm_handle() and reported as leaks at session end.

Read More about the project at: Docs

A concrete example

Suppose your extension accidentally does this in an executor hook:

MemoryContextAlloc(TopMemoryContext, 8192);   /* whoops */

That's a perfect 8 KB-per-query permanent leak. With pg_ext_memcheck:

CREATE EXTENSION pg_ext_memcheck;             -- requires shared_preload_libraries

SET pg_ext_memcheck.memcheck_mode = 'all';    -- snapshot both planner and executor
SELECT ext_memcheck.begin('');                -- open the test window

SELECT my_extension.do_work('input');
SELECT my_extension.do_work('more_input');

SELECT * FROM ext_memcheck.end();

 check_type      | severity | detail                                                         | source_lib
-----------------+----------+----------------------------------------------------------------+-----------------
 wrong_ctx_alloc | WARNING  | context 'TopMemoryContext' (depth 0): allocated grew by 8192…  | my_extension.so
 wrong_ctx_alloc | WARNING  | context 'TopMemoryContext' (depth 0): allocated grew by 8192…  | my_extension.so

Two findings, one per query, naming the offending context and the library that grew it. That's the entire intended user experience.

Tested against real bugs (positive detection)

A regression suite that only asserts "the call returned without erroring" tells you nothing about whether the tool actually catches the bug it claims to catch. v0.1.0 ships with a deliberately-buggy companion extension — buggy_pg_ext — that leaks 8 KB into TopMemoryContext on every query via its ExecutorStart hook.

The regression test does three things end-to-end:

1. Loads buggy_pg_ext per session (no global preload — other tests stay clean).

2. Runs two SELECT queries.

3. Asserts that ext_memcheck.end() returns at least one wrong_ctx_alloc row whose detail mentions TopMemoryContext and whose source_lib contains buggy_pg_ext.

A second test sets allowed_contexts = ['TopMemoryContext'] and asserts the violations vanish — proving the pattern filter actually filters, not that the result was accidental.

That's positive detection: the bug exists, the tool catches it, the tool attributes it, and the filter behaves as documented. CI runs the full suite green on PostgreSQL 15, 16, 17, and 18.

Honest scope — what's not in this beta

• Use-after-reset detection is Phase 2. The design calls for a BackgroundWorker to run crash-inducing tests in isolation (so a SIGSEGV confirms the bug rather than killing your session). The worker harness is a stub today; the scenario context_reset_storm will land alongside it.

• DSM auto-tracking is bounded by PostgreSQL itself. There is no dsm_create_hook or dsm_attach_hook, and the per-backend dsm_segment list isn't enumerable from public API. So the realistic path for a v0.2 improvement is emit_log_hook — capturing PostgreSQL's own "resource was not closed: dynamic shared memory segment" warnings and folding them into the violation log. That catches the common un-pinned leak case. Pinned-segment leaks remain fundamentally indistinguishable from intentional persistence.

• Additional scenarios (concurrent_backends, cursor_leak, oom_simulation, cold_warm_cold) are designed but not implemented.

• Not safe for production monitoring. Snapshot/diff has measurable per-query overhead. This is a testing tool: explicit begin(), run your workload, end(), done.

Try it

Requirements: PostgreSQL 15+ with server headers, a C compiler, and pg_config on PATH.

git clone https://github.com/samsiva-dev/pg_ext_memcheck.git
cd pg_ext_memcheck
make
sudo make install

# postgresql.conf
shared_preload_libraries = 'pg_ext_memcheck'

CREATE EXTENSION pg_ext_memcheck;
SELECT ext_memcheck.begin('');
-- exercise your extension
SELECT * FROM ext_memcheck.end();

The four built-in stress scenarios — growth_benchmark, tx_abort_loop, wrong_context_probe, shmem_sentinel_probe — are good first probes if you don't have a target query in mind.

Contributing

If you maintain a PostgreSQL extension and point this at it, I'd genuinely like to know what it finds — true positives and false positives both. The issue tracker is the right place, and there's an open invitation in the README. PRs are welcome too: the Phase 2 BGWorker harness, the emit_log_hook DSM bridge, and the missing stress scenarios are all good first targets.

⭐ Repository: https://github.com/samsiva-dev/pg_ext_memcheck

📜 License: MIT

🏷️ Tag: v0.1.0-beta

Thanks for reading — and if you ship an extension, please run this against it.

In this blog, we are going into Module 8: Concurrency & Locking - the mechanism PostgreSQL uses to coordinate simultaneous access to shared data without corruption.

The Lock Hierarchy - Two Levels

PostgreSQL has two distinct locking systems that work together:

• Table-Level locks

• Row-Level Locks

Part 1: Table-level locks (relation locks)

Stored in shared memory in the lock table. Eight lock modes, ordered by restrictiveness:

1. AccessShareLock - SELECT

2. RowShareLock - SELECT FOR UPDATE / FOR SHARE

3. RowExclusiveLock - INSERT , DELETE , UPDATE

4. ShareUpdateExclusiveLock - VACUUM , ANALYZE , CREATE INDEX CONCURRENTLY

5. ShareLock - CREATE INDEX (non-concurrent)

6. ShareRowExclusiveLock - CREATE TRIGGER , some ALTER TABLE

7. ExclusiveLock - REFRESH MATERIALIZED VIEW CONCURRENTLY

8. AccessExclusiveLock - DROP , TRUNCATE , VACUUM FULL , ALTER TABLE , LOCK TABLE , most DDLs.

The conflict matrix - what blocks what

                           AS  RS  RE  SUE  S  SRE  E  AE
AccessShareLock      (AS)  .   .   .   .   .   .   .   X
RowShareLock         (RS)  .   .   .   .   .   .   X   X
RowExclusiveLock     (RE)  .   .   .   .   X   X   X   X
ShareUpdateExclusiveLock(SUE) .  .  .  X   X   X   X   X
ShareLock            (S)   .   .   X   X   .   X   X   X
ShareRowExclusiveLock(SRE) .   .   X   X   X   X   X   X
ExclusiveLock        (E)   .   X   X   X   X   X   X   X
AccessExclusiveLock  (AE)  X   X   X   X   X   X   X   X

X = conflict (one blocks the other)
. = compatible (both can proceed)

Key observations from the matrix:

• SELECT never blocks SELECT

  • AS vs AS = Compatible → Reads never block reads

• SELECT blocks DDL :

  • AS vs AE = Conflict → Alter Table waits for all SELECTs to finish

• Writes never block reads MVCC :

  • RE vs AS = compatible → INSERT/UPDATE/DELETE never blocks SELECT

• VACUUM never blocks normal DML

  • SUE vs AS/RS/RE = compatible → autovacuum runs alongside production traffic

• The most dangerous: ALTER TABLE acquires AE

  • It must wait for ALL existing locks to clear AND new queries queue behind it.

Part 2: How Table Locks are Acquired and Stored

The lock table in shared memory

PostgreSQL maintains a lock table in shared memory - a hash table keyed by (database OID, relation OID) . Each entry contains:

typedef struct LOCK {
    LOCKTAG     tag;           /* unique identifier for the lockable object */
    LOCKMASK    grantMask;     /* bitmask of lock modes currently granted */
    LOCKMASK    waitMask;      /* bitmask of lock modes being waited for */
    SHM_QUEUE   procLocks;     /* list of PROCLOCK objects for this lock */
    PROC_QUEUE  waitProcs;     /* list of waiting backends */
    int         requested[MAX_LOCKMODES];  /* count of each mode requested */
    int         granted[MAX_LOCKMODES];    /* count of each mode granted */
    int         nRequested;    /* total requested locks */
    int         nGranted;      /* total granted locks */
} LOCK;

Each backend also has a PROCLOCK entry linking it to a lock:

typedef struct PROCLOCK {
    PROCLOCKTAG tag;          /* (LOCK *, PGPROC *) pair */
    PGPROC      *groupLeader; /* lock group leader */
    LOCKMASK    holdMask;     /* bitmask of lock modes held */
    LOCKMASK    releaseMask;  /* bitmask of lock modes to release */
    SHM_QUEUE   lockLink;     /* list of PROCLOCKs for same LOCK */
    SHM_QUEUE   procLink;     /* list of PROCLOCKs for same PGPROC */
} PROCLOCK;

Lock escalation does not exist

Unlike some other databases, PostgreSQL does not escalate row locks to table locks. A transaction that updates 10 million rows holds 10 million rows holds 10 million row-level locks (via xmax , not the lock table) and still only holds one RowExclusiveLock on the table. There is no automatic promotion to a table-level write lock.

Fast-path locking

For the common case of AccessShareLock and RowExclusiveLock on regular tables, PostgreSQL uses a fast-path optimization - it stores up to 16 weak locks per backend in the PGPROC struct directly, bypassing the shared lock table entirely. Only when a conflicting lock appears does it fall back to the main lock table.

-- See all current locks:
SELECT pid,
       locktype,
       relation::regclass,
       mode,
       granted
FROM pg_locks
WHERE relation IS NOT NULL
ORDER BY relation, pid;

Part 3: Row-Level Locks - No Lock Table Entry

Row-level locks are fundamentally different from table-level locks. They are not stored in the lock table. Instead they are encoded directly in the tuple header - specifically in xmax and t_infomask.

How a row lock is stored

SELECT * FROM orders WHERE id = 42 FOR UPDATE;

What happens on the heap page:

Before FOR UPDATE:
  tuple: xmin=1000, xmax=0, t_infomask=0x0900
                                        ↑
                              XMIN_COMMITTED | XMAX_INVALID

After FOR UPDATE (transaction 5001):
  tuple: xmin=1000, xmax=5001, t_infomask=0x0440
                                            ↑
                              XMAX_EXCL_LOCK | XMAX_LOCK_ONLY

The key flags in t_infomask :

HEAP_XMAX_LOCK_ONLY  0x0080  — xmax is a lock, not a delete
HEAP_XMAX_EXCL_LOCK  0x0040  — exclusive lock (FOR UPDATE)
HEAP_XMAX_KEYSHR_LOCK 0x0010 — key-share lock (FOR KEY SHARE)

When the locking transaction commits or rolls back, the xmax is left in place. The next transaction to visit the tuple checks whether xmax is still active (via CLOG) - if the locking transaction is done, the lock is considered released. This is why row locks have zero cleanup cost - they disappear when the transaction ends.

Lock modes for row-level operation

• FOR KEY SHARE - weakest. Prevents key updates and deletes. Used by foreign key checks on referenced rows.

• FOR SHARE - prevents updates and deletes.

• FOR NO KEY UPDATE - like FOR UPDATE but allows key-share lockers. Used by UPDATE on non-key columns.

• FOR UPDATE - strongest. Prevents all concurrent modification. Used by UPDATE and DELETE.

Conflict matrix for row locks:

                   KEY SHARE   SHARE   NO KEY UPDATE   UPDATE
FOR KEY SHARE        .          .          .             X
FOR SHARE            .          .          X             X
FOR NO KEY UPDATE    .          X          X             X
FOR UPDATE           X          X          X             X

Example

-- Demonstrate row lock:
-- Terminal 1:
BEGIN;
SELECT * FROM orders WHERE id = 42 FOR UPDATE;
-- Row is now locked

-- Terminal 2:
SELECT * FROM orders WHERE id = 42 FOR UPDATE;
-- Blocks! Waiting for Terminal 1 to commit/rollback

-- See the wait:
SELECT pid, locktype, relation::regclass, page, tuple, mode, granted
FROM pg_locks
WHERE NOT granted;

Part 4: MultiXactId - When Multiple Transactions Lock One Row

What happens when two transactions both hold a FOR SHARE lock on the same row at the same time? They are compatible, so both should be able to lock it. But the tuple's xmax field is only 32 bits - it can only store one XID.

PostgreSQL solves this with MultiXactId:

Normal row lock:
  xmax = 5001  (single locker XID)
  t_infomask: XMAX_KEYSHR_LOCK | XMAX_LOCK_ONLY

Multiple shared lockers:
  xmax = 123   ← this is a MultiXactId, not a real XID!
  t_infomask: XMAX_IS_MULTI | XMAX_KEYSHR_LOCK | XMAX_LOCK_ONLY

The MultiXactId is a pointer into the multixact subsystem - files in $PGDATA/pg_multixact/ that store arrays of (XID, lock_mode) pairs:

pg_multixact/members/  → arrays of (XID, mode) per MultiXact
pg_multixact/offsets/  → MultiXactId → offset into members file

-- MultiXact occupies just as much space as XID — 32 bits
-- It also has a wraparound problem: vacuum_multixact_freeze_max_age
-- Monitor it like XID age:

SELECT datname,
       age(datfrozenxid)     AS xid_age,
       mxid_age(datminmxid)  AS mxid_age
FROM pg_database
ORDER BY mxid_age DESC;

Part 5: Deadlock Detection

A deadlock occurs when two or more transactions are each waiting for a lock held by the other:

T1 holds lock on row A, waits for lock on row B
T2 holds lock on row B, waits for lock on row A
→ neither can proceed → deadlock

How PostgreSQL detects deadlocks

PostgreSQL does not use a timeout to detect deadlocks. It uses a wait-for graph algorithm:

1. When T1 waits for a lock, it sleeps for deadlock_timeout (default 1s)
   — this is the "optimistic" wait: most locks clear within 1s

2. After deadlock_timeout elapses, T1 calls DeadLockCheck():
   a. Build a directed graph: T1 → T2 means "T1 is waiting for T2"
   b. Walk the graph using DFS looking for cycles
   c. If cycle found: pick one transaction to abort (the "victim")
      — PostgreSQL picks the transaction that would be cheapest to restart
      — usually the one that has done the least work

3. The victim receives:
   ERROR: deadlock detected
   DETAIL: Process 1234 waits for ShareLock on transaction 5001
           Process 5678 waits for ShareLock on transaction 1234
   HINT:  See server log for query details.

Example

-- Demonstrate deadlock:
-- Terminal 1:
BEGIN;
UPDATE orders SET status='x' WHERE id=1;
-- (now pause)

-- Terminal 2:
BEGIN;
UPDATE orders SET status='y' WHERE id=2;
UPDATE orders SET status='y' WHERE id=1;  -- waits for T1

-- Terminal 1:
UPDATE orders SET status='x' WHERE id=2;  -- waits for T2 → deadlock!

-- After deadlock_timeout (1s), one transaction gets:
-- ERROR:  deadlock detected

-- Monitor deadlocks:
SELECT deadlocks FROM pg_stat_database WHERE datname = current_database();

Part 6: Lock Queuing - The Hidden Traffic Jam

Understanding lock queuing is critical for production systems. Locks are not just granted or denied - they queue.

Timeline:

t=0  T1 acquires AccessShareLock (SELECT) — granted immediately
t=1  T2 acquires AccessShareLock (SELECT) — granted immediately
t=2  T3 requests AccessExclusiveLock (ALTER TABLE) — BLOCKED by T1, T2
     T3 enters the wait queue for AE lock

t=3  T4 requests AccessShareLock (SELECT) — BLOCKED by T3!
     Even though AS is compatible with AS, T4 must wait because T3 is
     already in the queue. This prevents T3 from starving.

t=4  T1 commits — T3 still waiting (T2 still holds AS)
t=5  T2 commits — T3 granted AE lock
     T3 is now running ALTER TABLE

t=6  T4 finally gets AS lock (after T3 completes)

This is the ALTER TABLE traffic jam. A single ALTER TABLE on a busy table:

1. Waits for all existing connections to release locks

2. Blocks ALL new queries behind it (even simple SELECTs)

3. Can cascade into hundreds of waiting connections

Safe ALTER TABLE pattern

-- Instead of running ALTER TABLE alone (dangerous on busy tables):
ALTER TABLE orders ADD COLUMN notes text;

-- Use lock_timeout + retry loop:
SET lock_timeout = '2s';
BEGIN;
ALTER TABLE orders ADD COLUMN notes text;
COMMIT;
-- If it times out, retry during a quieter period

-- Even safer: check for blocking sessions first:
SELECT count(*) FROM pg_stat_activity
WHERE query NOT LIKE '%pg_stat_activity%'
  AND state != 'idle'
  AND pid != pg_backend_pid();
-- Only run ALTER TABLE when this is near zero

Part 7: Advisory Locks

Advisory locks are application-level locks with no automatic association to database objects. PostgreSQL provides the locking mechanism; your application decides what it means.

-- Session-level advisory lock (held until released or session ends):
SELECT pg_advisory_lock(12345);
-- ... do work ...
SELECT pg_advisory_unlock(12345);

-- Transaction-level advisory lock (released at COMMIT/ROLLBACK):
BEGIN;
SELECT pg_advisory_xact_lock(12345);
-- ... do work ...
COMMIT;  -- lock released automatically

-- Try-lock (non-blocking):
SELECT pg_try_advisory_lock(12345);
-- Returns TRUE if lock acquired, FALSE if already held

-- Lock with two 32-bit integers (more namespace):
SELECT pg_advisory_lock(hashtext('job_processor'), job_id);

SKIP LOCKED - the queue pattern

SKIP LOCKED is not an advisory lock - it is a row-level lock modifier. It tells PostgreSQL: "if you encounter a row that is already locked, skip it instead of waiting." This is the foundation of efficient work queues:

-- Multiple workers can safely dequeue without contention:
-- Worker 1:
SELECT * FROM jobs WHERE status='pending' ORDER BY id LIMIT 1 FOR UPDATE SKIP LOCKED;
-- Locks job_id=1

-- Worker 2 (simultaneously):
SELECT * FROM jobs WHERE status='pending' ORDER BY id LIMIT 1 FOR UPDATE SKIP LOCKED;
-- Sees job_id=1 is locked → skips to job_id=2
-- No blocking, no waiting

Part 8: Lock Monitoring in Production

-- ═══ 1. See everything currently locked ═══

SELECT
    pid,
    locktype,
    CASE locktype
        WHEN 'relation' THEN relation::regclass::text
        WHEN 'tuple'    THEN relation::regclass::text || ':' || page::text || ',' || tuple::text
        WHEN 'transactionid' THEN transactionid::text
        ELSE locktype
    END AS object,
    mode,
    granted,
    waitstart
FROM pg_locks
ORDER BY granted, waitstart NULLS LAST;

-- ═══ 2. Find blocked queries and their blockers ═══

SELECT
    blocked.pid                          AS blocked_pid,
    blocked.usename                      AS blocked_user,
    now() - blocked.query_start          AS wait_time,
    blocked.query                        AS blocked_query,
    blocking.pid                         AS blocking_pid,
    now() - blocking.query_start         AS blocking_duration,
    blocking.query                       AS blocking_query
FROM pg_stat_activity blocked
JOIN pg_stat_activity blocking
    ON blocking.pid = ANY(pg_blocking_pids(blocked.pid))
WHERE cardinality(pg_blocking_pids(blocked.pid)) > 0
ORDER BY wait_time DESC;

-- ═══ 3. Identify long-running transactions (lock holders) ═══

SELECT pid,
       usename,
       now() - xact_start           AS tx_duration,
       now() - query_start          AS query_duration,
       state,
       left(query, 100)             AS query
FROM pg_stat_activity
WHERE xact_start IS NOT NULL
  AND state != 'idle'
ORDER BY xact_start ASC
LIMIT 10;

-- ═══ 4. Count lock waits per table (operational health) ═══

SELECT
    relation::regclass AS table,
    mode,
    count(*) FILTER (WHERE granted)     AS granted,
    count(*) FILTER (WHERE NOT granted) AS waiting
FROM pg_locks
WHERE relation IS NOT NULL
GROUP BY relation, mode
HAVING count(*) FILTER (WHERE NOT granted) > 0
ORDER BY waiting DESC;

-- ═══ 5. Kill a blocking session (use carefully!) ═══

-- Soft kill (waits for current query to finish):
SELECT pg_cancel_backend(pid);

-- Hard kill (terminates session immediately):
SELECT pg_terminate_backend(pid);

-- Kill all idle-in-transaction sessions > 10 minutes:
SELECT pg_terminate_backend(pid)
FROM pg_stat_activity
WHERE state = 'idle in transaction'
  AND now() - state_change > interval '10 minutes';

Part 9: Lock Timeout and Statement Timeout

• lock_timeout - Prevent queries from waiting forever for locks.

  • If a lock cannot be acquired within specified time (say 5s), it throws "ERROR: canceling statement due to lock timeout"

• statement_timeout - Prevent long-running queries from holding locks.

  • If a query runs longer than specified time (say 30s), it throws "ERROR: canceling statement due to statement timeout"

• idle_in_transaction_session_timeout - Prevent idle transaction from holding locks.

  • If a transaction is open but idle for the given time (say 5min), it throws "ERROR: termination connection due to idle-in-transaction timeout"

-- Best practice: set all three in postgresql.conf
SET lock_timeout                        = '30s'
SET statement_timeout                   = '60s'
SET idle_in_transaction_session_timeout = '5min'

-- Per-session override for maintenance work:
SET LOCAL lock_timeout = '0';        -- no timeout for this transaction
SET LOCAL statement_timeout = '0';   -- no timeout for this transaction

Part 10: Hands-On Lab

-- ═══ 1. Observe lock acquisition ═══

-- See your own locks:
BEGIN;
SELECT * FROM orders LIMIT 1;
SELECT pid, locktype, relation::regclass, mode, granted
FROM pg_locks
WHERE pid = pg_backend_pid();
-- Should see AccessShareLock on orders
-- Also see ExclusiveLock on your transaction ID
COMMIT;

-- ═══ 2. Demonstrate lock conflict ═══

-- Terminal 1:
BEGIN;
LOCK TABLE orders IN SHARE MODE;
SELECT pg_sleep(30);  -- hold the lock

-- Terminal 2:
SET lock_timeout = '3s';
BEGIN;
INSERT INTO orders VALUES (...);  -- blocked by SHARE lock
-- After 3s: ERROR: canceling statement due to lock timeout

-- ═══ 3. Observe row-level locking in tuple ═══

CREATE TABLE lock_demo (id int, val text);
INSERT INTO lock_demo VALUES (1, 'hello');

BEGIN;
SELECT * FROM lock_demo WHERE id = 1 FOR UPDATE;

-- Inspect the tuple while locked:
SELECT lp, t_xmin, t_xmax, t_infomask
FROM heap_page_items(get_raw_page('lock_demo', 0));
-- t_xmax = your transaction XID (lock recorded in tuple!)
-- t_infomask has XMAX_EXCL_LOCK | XMAX_LOCK_ONLY bits set

COMMIT;

-- After commit, check again:
SELECT lp, t_xmin, t_xmax, t_infomask
FROM heap_page_items(get_raw_page('lock_demo', 0));
-- t_xmax still shows the XID — but CLOG says committed
-- Next accessor checks CLOG → sees lock released

-- ═══ 4. Reproduce and observe a deadlock ═══

-- Terminal 1:
BEGIN;
UPDATE lock_demo SET val='T1' WHERE id=1;

-- Terminal 2:
BEGIN;
UPDATE lock_demo SET val='T2' WHERE id=2;
UPDATE lock_demo SET val='T2' WHERE id=1;  -- waits

-- Terminal 1:
UPDATE lock_demo SET val='T1' WHERE id=2;  -- deadlock!
-- One terminal will get: ERROR: deadlock detected

-- Check deadlock counter:
SELECT deadlocks FROM pg_stat_database
WHERE datname = current_database();

-- ═══ 5. SKIP LOCKED queue pattern ═══

CREATE TABLE work_queue (
    id bigserial primary key,
    payload text,
    status text DEFAULT 'pending'
);
INSERT INTO work_queue(payload)
SELECT 'job_' || g FROM generate_series(1,100) g;

-- Simulate two workers claiming jobs simultaneously:
-- Worker 1:
BEGIN;
SELECT id, payload FROM work_queue
WHERE status = 'pending'
ORDER BY id
LIMIT 5
FOR UPDATE SKIP LOCKED;
-- Claims jobs 1-5

-- Worker 2 (simultaneously):
BEGIN;
SELECT id, payload FROM work_queue
WHERE status = 'pending'
ORDER BY id
LIMIT 5
FOR UPDATE SKIP LOCKED;
-- Claims jobs 6-10 (skipped 1-5 which are locked)
-- No blocking!

-- ═══ 6. Advisory lock for distributed job ═══

-- Only one session can run this job:
SELECT CASE
    WHEN pg_try_advisory_lock(12345) THEN 'Got the lock — running job'
    ELSE 'Another worker has the lock — skipping'
END;

-- See advisory locks in pg_locks:
SELECT pid, locktype, classid, objid, mode, granted
FROM pg_locks
WHERE locktype = 'advisory';

SELECT pg_advisory_unlock(12345);

Conclusion

In this module, we explored how PostgreSQL manages concurrent access at every level — from the 8-mode table lock hierarchy and its conflict matrix, to row-level locks encoded directly in the tuple's xmax field with zero lock table overhead, to MultiXactId for shared row locks, deadlock detection via wait-for graph cycle analysis, the hidden lock queuing problem that turns a single ALTER TABLE into a traffic jam, and advisory locks with SKIP LOCKED for contention-free work queues.

What's Next → Module 9: Replication

You now understand how PostgreSQL coordinates concurrent writes safely. Module 9 goes into how those writes are streamed to replicas - physical streaming replication at the WAL level, logical replication and the decoding pipeline, replication slots and their wraparound risk, and synchronous vs asynchronous commit.

Then I remembered my 10th class days - those were the days we were all glued to our textbooks grinding everything over and over again, didn't we? I used to underline paragraph after paragraph, sometimes I was genuinely confused about why the hell I underlined that line, when I read the textbook again during revision.

One day, my teacher flipped through my book, saw all those underlined paragraphs, and explained the importance of underlining. He said: don't underline everything - underline the word or two that actually carries the meaning. It helped me study better, and I followed that through BTech 1st year - until my laptop and smartphone replaced the need for a textbook, simply through PDFs.

Now that I think about it, it hits differently - how a simple tweak in approach can make all the difference in studying better. It made me think about life too - we all try to do things that are meant to change us, but we burn out or exhaust ourselves halfway through. For instance, I started going to the gym 5 days a week. I kept it up for 2 months - then my body got burned out and all that work went to waste over the next 2 months. So I switched to 3 days a week, and my body feels better than ever.

If something isn't working, it doesn't mean you can't do it - it just means you haven't found your version of it yet. Sometimes all it takes is underlining less.

Traits are how Rust achieves polymorphism - shared behaviour across different types without inheritance. Generics are how you write code that works over many types without duplicating the logic.

Let's start with What problem we are trying to solve with Traits & Generics, then about Traits, Generics and bringing all together with an example.

The Problem

Consider we want to find the largest elements in a slice of different data types say i32 , f64 etc. Without traits and generics, we need to write a separate function for each data type:

fn largest_i32(list: &[i32]) -> i32 {
    let mut largest = list[0];

    for &item in list.iter() {
        if item > largest {
            largest = item;
        }
    }

    largest
}

fn largest_f64(list: &[f64]) -> f64 {
    let mut largest = list[0];

    for &item in list.iter() {
        if item > largest {
            largest = item;
        }
    }

    largest
}

Here, the logic is a pure duplication of code as we wrote for two different data types and which is redundant and unnecessary. Traits and Generics helps in eliminating these problems. Before looking at the solution, here's the mental model:

Generics eliminate the duplication. Traits are constraints that implementing types must satisfy.

Together, the solution would be:

fn largest<T: PartialOrd>(list: &[T]) -> &T { ... }
// works for any T that can be compared

• T - a generic type placeholder; can be i32 , f32 or even a String

• PartialOrd - a trait constraint meaning the type must support comparison operators, or in other words, only types that implement PartitalOrd can be passed as a slice &[T] to this function.

Traits: defining shared behaviour

A trait defines a set of method signatures that a type (data type, structs, enums etc..) must implement. Think of it as an interface. Like Java interfaces, traits define a contract - but unlike Java, Rust traits can have default implementations and can be added to existing types.

trait Summary {
  fn summarise(&self) -> String;
}

This says: any type that implements Summary must provide a summarise method that takes &self and returns a String . The trait does not say how, implementing type decides that.

Example

Implementing Summary trait on a type:

struct Article {
  title: String,
  author: String,
  content: String,
}

struct Tweet {
  username: String,
  content: String,
}

impl Summary for Article {
  fn summarise(&self) -> String {
    format!("{} by {}", self.title, self.author)
  }
}

impl Summary for Tweet {
  fn summarise(&self) -> String {
    format!("{}: {}", self.username, self.content)
  }
}

Now both Article and Tweet satisfy the Summary contract. The method call is the same regardless of which type you have:

let article = Article{ 
  title: "Rust Module-5",
  author: "Siva",
  content: "Generics & Traits", 
};

let tweet = Tweet{ 
  username: "sambasiva",
  content: "Releasing a series on Rust",
};

println!("{}", article.summarise());  // Prints "Rust Module-5 by Siva"
println!("{}", tweet.summarise());    // Prints "sambasiva: Releasing a series on Rust"

Default implementation

A trait can provide a default body that types can override if they wanted to or else inherit the default behaviour.

trait Summary {
	fn summarise(&self) -> String {
		String::from("(Read more...)") // Default behaviour
	}
}

impl Summary for Article {} // Uses default summarise

// Or Override it
impl Summary for Tweet {
	fn summarise(&self) -> String {
		format!("{}: {}", self.username, self.content)
	}
}

fn main() {
  let article = Article{ 
    title: "Rust Module-5",
    author: "Siva",
    content: "Generics & Traits", 
  };

  let tweet = Tweet{ 
    username: "sambasiva",
    content: "Releasing a series on Rust",
  };

  println!("{}", article.summarise());  // Prints "(Read more...)"
  println!("{}", tweet.summarise());    // Prints "sambasiva: Releasing a series on Rust"
}

Generics

Generics let you write a function or struct that is parameterised over a type, resolved at compile time. First we will start with functions.

Generic Functions

fn first<T>(list: &[T]) -> &T {
	&list[0]
}

T is a type parameter - a placeholder. When you call first(&[1, 2, 3]) , the compiler substitutes T = i32 . When you call first(&["a", "b"]) , it substitues T = &str . Two separate compiled functions - zero runtime cost. This is called monomorphisation.

Generic Structs

struct Pair<T> {
	first: T,
	second: T,
}

impl<T> Pair<T> {
	fn new(first: T, second: T) -> Self {
		Pair { first, second }
	}
}

fn main() {
  let pair1 = Pair { first: 3, second: 4 } // Pass
  let pair2 = Pair { first: 3, second: 4.0 } // Throws error
}

Why error for pair2? Because we defined only one generic parameter to the struct Pair i.e T . In case of pair2 , first is i32 and second is f64 , two different data types, so the error. The fix is simple, we can pass the multiple type parameters each with different identifier. For example:

struct Pair<T, K> {
  first: T,
  second: K,
}

impl<T, K> Pair<T, K> {
	fn new(first: T, second: K) -> Self {
		Pair { first, second }
	}
}

fn main() {
  let pair1 = Pair { first: 3, second: 4 } // Pass 
  let pair2 = Pair { first: 3, second: 4.0 } // Now Pass
}

Trait Bounds - constraining Generics

A bare T can be anything - you can't call any methods on it because the compiler doesn't know what T supports. Traits bounds express the requirements for those types:

fn largest<T: PartialOrd>(list: &[T]) -> &T {
	let mut largest = &list[0];
	for item in list {
		if item > largest { // requires PartialOrd
			largest = item;
		}
	}
	largest
}

T: PartialOrd means "T must implement the PartialOrd trait" - i.e., T must support > , < , >= , <= . Without this bound, item > largest is a compile error because the compiler can't guarantee T supports comparison. So this function works for any type that implements PartialOrd - integers, floats, even String . A custom struct with no ordering would fail this bound.

Multiple Bounds with "+"

We can define as many trait bounds on a Generic type as we want with the help of + .

fn print_summary<T: Summary + std::fmt::Display>(item: &T) {
	println!("{}", item.summarise());
}

In the above example, we can call this function on the types which implements both Summary and std::fmt::Display traits.

where clause: a clear syntax for complex bounds:

fn compare<T, U>(t: &T, u:&U) -> String
where
	T: Summary + Clone,
	U: Summary + std::fmt::Debug,
{
	//...
}

Both forms are equivalent - where is just more readable when bounds get long.

Traits as Function Parameters - impl Trait

Instead of a generic type parameter, we can also use impl Trait syntax directly in the parameter.

fn notify(item: &impl Summary) {
	println!("{}", item.summarise());
}

This says "accept any reference to any type that implements Summary ". It is syntactic sugar for a generic with a bound:

fn notify<T: Summary>(item: &T) { ... } // equivalent to above impl Summary

Use impl Trait for simple cases. Use explicit generics when you need to refer to T multiple times or return it.

Returning traits - dyn Trait

Sometimes you want to return "some type that implements a trait" without specifying which. This requires a different mechanism - traits objects with dyn :

fn make_summary(is_article: bool) -> Box<dyn Summary> {
    if is_article {
        Box::new(Article { ... })
    } else {
        Box::new(Tweet { ... })
    }
}

Box<dyn Summary>is a fat pointer - a pointer to the data plus a pointer to a vtable of method implementations. The concrete type is decided at runtime, not compile time - this is slower than generics but allows more flexibility.

Key Standard Library Traits

These are the traits you will encounter constantly. Knowing what they mean is essential:

Display — defines how a type is formatted with {}. Implement this to make your type printable.

Debug — defines formatting with {:?}. Usually derived automatically.

Clone — provides the .clone() method for explicit deep copy.

Copy — marker trait, makes assignment copy instead of move. Requires Clone.

PartialOrd / Ord — comparison operators <, > etc.

PartialEq / Eq — equality operators ==, !=.

Iterator — the trait behind every for loop and iterator chain. One required method: next().

Most of these can be derived automatically by the compiler for your types:

#[derive(Debug, Clone, PartialEq)]
struct Point {
    x: f64,
    y: f64,
}

let p1 = Point { x: 1.0, y: 2.0 };
let p2 = p1.clone();
println!("{:?}", p1);       // requires Debug
println!("{}", p1 == p2);   // requires PartialEq

#[derive(...)] is a macro that auto-generates the trait implementation for you based on the struct's fields.

Complete Example

use std::fmt;

trait Area {
    fn area(&self) -> f64;
    fn describe(&self) -> String {
        format!("This shape has area {:.2}", self.area())
    }
}

#[derive(Debug, Clone)]
struct Circle {
    radius: f64,
}

#[derive(Debug, Clone)]
struct Rectangle {
    width: f64,
    height: f64,
}

impl Area for Circle {
    fn area(&self) -> f64 {
        std::f64::consts::PI * self.radius * self.radius
    }
}

impl Area for Rectangle {
    fn area(&self) -> f64 {
        self.width * self.height
    }
}

impl fmt::Display for Circle {
    fn fmt(&self, f: &mut fmt::Formatter) -> fmt::Result {
        write!(f, "Circle(r={})", self.radius)
    }
}

fn print_area(shape: &impl Area) {
    println!("{}", shape.describe());
}

fn largest_area(shapes: &[Box<dyn Area>]) -> f64 {
    shapes.iter()
          .map(|s| s.area())
          .fold(0.0_f64, f64::max)
}

fn main() {
    let c = Circle { radius: 5.0 };
    let r = Rectangle { width: 4.0, height: 6.0 };

    print_area(&c);
    print_area(&r);

    let shapes: Vec<Box<dyn Area>> = vec![
        Box::new(Circle { radius: 3.0 }),
        Box::new(Rectangle { width: 10.0, height: 2.0 }),
        Box::new(Circle { radius: 7.0 }),
    ];

    println!("Largest area: {:.2}", largest_area(&shapes));
}

Conclusion

Traits and Generics together solve the duplication problem we started with - traits define what a type must do, generics let you write code that works for any type that qualifies. The compiler resolves generics at compile time (monomorphisation, zero cost), while dyn Trait defers the decision to runtime when flexibility matters more than speed. Master these two, and you hold the key to nearly every abstraction in Rust's standard library.

The Books:

1. Your Dreams Are Mine Now - Ravinder Singh

2. A Psalm For The Wild Built - Becky Chambers (Partial)

Your Dreams Are Mine Now

This is the love story between two students studying at Delhi University and what happened to them when tried to bring the change in University Politics.

The Plot

The story is between the two students - Rupali, a Bihari girl who joined DU with bigger ambitions and Arjun, a Delhite, second year student who is active in the DU student politics and fighting against changes to the reservation quota in the university. The story revolves around these two polar opposite souls, how various circumstances brought them together, made them fall in love, and pushed them to fight for change.

My Thoughts

After completion of this book, the title doesn't reflect what actually unfolds in the book even though the author tried to craft an ending that resonates with the title. The author drew from a real incident that happened in Delhi and built a story around it. Some conversations feel stretched where a few lines would've done. That said, it never bores you - overall a good, breezy read.

But then I remembered my summers before 2019. What happened after 2019? Well, that's a story for another blog post. Not that summers before are hot, but there was pure joy in them.

I used to wake up at 7 o'clock but not to get ready for work, but to play cricket. We built the wickets with whatever we found like bricks, wooden sticks etc. and played until the sun is over our heads. But not once did we get dehydrated, Guess why? Because we had clay pots that kept the water cool. Some days we would even cycle kilometres to play against a neighbouring village - no complaints, no excuses, just cricket. Not to mention getting cursed out by the farmers every time the ball landed in their fields - a guarantee, not a possibility.

Every summer, my village would suddenly feel fuller. Cousins arriving at my grandparent's house - chaos, noise, and instant comfort all at once. Carrom boards would come out, and so would the arguments over who's cheating. We'd tease each other over the silliest things, fight over even sillier ones, and five minutes later it was forgotten. Writing this now, I'm smiling without even realising it.

How can we continue talking about Summers without paying tribute to Mangoes, Ice Apple and Ice Cream? These were the OGs of summer, then and now. Dozens of mangoes, no worrying about pimples. And those ice apple shells? We'd turn them into little carts and race each other down the street.

And every single day ended with us all sitting on the benches, chairs, chit-chatting about everything - men discussing politics, women discussing serials, we boys teasing each other, cousins sitting under the moonlight and staring at the stars and gossiping. I miss those simpler days.

Now summers are just summers - at least for me. We have smartphones to capture every moment, cameras ready at all times. But somehow, these moments are captured perfectly in memory...

In this blog, we'll explore how VACUUM cleans dead tuples and removes bloat, how it prevents XID wraparound, and how autovacuum - PostgreSQL's background maintenance engine decides when and how aggressively to act.

Part 1: Why VACUUM Exists?

Every write operation in PostgreSQL creates a debt that must eventually be paid. For example:

INSERT → writes 1 new tuple
       → debt: none (yet)

UPDATE → writes 1 new tuple version
       → marks old tuple dead (xmax set)
       → writes 1 new index entry per index (assume N indexes)
       → marks old index entries dead
       → debt: 1 dead heap tuple + N dead index entries

DELETE → marks tuple dead (xmax set)
       → marks index entries dead
       → debt: 1 dead heap tuple + N dead index entries

This debt accumulates on every page. And Dead tuples cause:

• Waste space: pages fill with unreachable data

• Slow scans: every scan reads and discards dead tuples

• Block index-only scans - all_visible bit cannot be set while dead tuples exists

• Risk wraparound - old xmin values must be frozen before XID space/range exhausts

And VACUUM is the debt collector, whose responsibility to clear all the debt being created, which will discuss in the next part in clear.

Part 2: What VACUUM Actually Does?

VACUUM on a table is not a single operation. It is a sequence of precise steps

Step 1: Acquire ShareUpdateExclusiveLock

VACUUM orders;

VACUUM acquires ShareUpdateExclusiveLock - the weakest table lock. This:

• Allows concurrent SELECT , INSERT , UPDATE and DELETE

• Block concurrent VACUUM - only one VACUUM/table at a time

• Blocks DDL statements on the table like ALTER TABLE and DROP TABLE

This is why standard VACUUM does not block normal operations. VACUUM FULL is different altogether, it acquires AccessExclusiveLock and blocks everything.

Step 2: Compute OldestXmin

Before touching any page, VACUUM computes OldestXmin - the oldest transaction ID that any active transaction could need to see:

OldestXmin = min(
    all active transaction XIDs,
    all open cursor XIDs,
    all prepared transaction XIDs,
    all replication slot restart_lsn XIDs
)

Any tuple with xmax < OldestXmin is dead to everyone i.e., no active transaction can ever see it again. These are safe to remove.

Step 3: Scan the heap - page by page

VACUUM reads every heap page sequentially. For each page, it performs the following checks:

1. Read page into shared buffers

2. Check visibility map:
   if all_visible bit SET → SKIP this page entirely
      i.e., no dead tuples possible, no work to do here
   if all_frozen bit SET → SKIP for freeze pass too

3. For each tuple on page:
   a. Check xmin/xmax against OldestXmin
   b. If dead (xmax < OldestXmin AND xmax is COMMITTED)
         add to dead_tuples[] array (stored in maintenance_work_mem)
   c. If live but xmin old enough for freezing
         mark for freeze (set HEAP_XMIN_FROZEN bit)
         WAL - log the change

4. If any tuples frozen: WAL - log a FREEZE record

The dead_tuples[] array in maintenance_work_mem accumulates the TIDs of dead tuples. When it fills up, VACUUM must flush it by cleaning indexes before it can continue scanning the heap; this is why maintenance_work_mem matters for VACUUM performance.

Step 4: Clean Indexes

For each index on the table, VACUUM calls ambulkdelete() :

For B-Tree:
    Scan index leaf page
    For each index entry whose TID is in dead_tuples[]:
        mark the index entry as dead (LP_DEAD flag)
    Return count 

This is O(indexSize), not O(deadTuples) complexity
Why? VACUUM must scan the entire index to find dead entries

This is why a table with many indexes is expensive to VACUUM. Each index gets a full scan.

Step 5: Heap Cleanup

After index cleanup, VACUUM makes a second pass (first is to mark dead tuples) over the heap pages that had dead tuples:

For each page with dead tuples:
  1. Remove dead tuple data
  2. Update ItemId flags: LP_DEAD → LP_UNUSED
  3. Compact the page (shift live tuples toward the end)
  4. Update pd_lower (free space pointer moves back)
  5. Update FSM: report new free space to free space map
  6. If ALL tuples on page are visible to everyone:
       set all_visible bit in visibility map
  7. If ALL tuples on page are frozen:
       set all_frozen bit in visibility map
  8. WAL-log all changes

Step 6: Update Statistics

Once all the above steps done, it's time for the VACUUM to update the stats in pg_class , pg_stat_user_tables and Truncate trailing empty pages if possible.

1. Update pg_class:
   relpages    ← new page count estimate
   reltuples   ← new live tuple count estimate
   relallvisible ← pages with all_visible bit set

2. Update pg_stat_user_tables:
   n_dead_tup  ← reset to 0
   last_vacuum ← now()

Part 3: Freezing - Preventing XID Wraparound

XID is 32bit. After ~4 billion transactions, it wraps around i.e., transaction IDs restart from 3 (XIDs 0–2 are reserved for system use). Without intervention, old tuples with small xmin values would appear to be "in the future" - invisible to everyone and causes database corruption.

The freeze threshold

Following parameters control when tuples are frozen:

• vacuum_freeze_min_age

  • A tuple is eligible for freezing when its xmin is this many transactions old. VACUUM won't freeze newer tuples.

  • Default: 50M XIDs

• vacuum_freeze_table_age

  • When the table's relfrozenxid is this old, VACUUM performs an aggressive freeze scan - visits every page regardless of the visibility map.

  • Default: 150M XIDs

• autovacuum_freeze_max_age

  • When a table's relfrozenxid reaches this age, autovacuum is forced to run on it - even if it's otherwise inactive. This is the safety net. If it triggers, you have a problem.

  • Default: 200M XIDs

What freezing does?

-- Before freeze;
-- t_xmin = 9582, t_infomask = 0x0100 (HEAP_XMIN_COMITTED)

VACUUM FREEZE orders;

-- After freeze
-- t_xmin = 9582 (UNCHANGED - PG 14+ preserves original XID)
-- t_infomask = 0x0300 (HEAP_XMIN_COMMITTED | HEAP_XMIN_FROZEN) 
   -- added frozen bit (0x0200)

Once frozen bit is set, XID value becomes irrelevant and never be checked again for freezing or vacuuming.

Monitor wraparound proximity

-- Most critical query for PostgreSQL health:
SELECT datname,
       age(datfrozenxid)                          AS xid_age,
       2000000000 - age(datfrozenxid)             AS xids_remaining,
       round(100.0 * age(datfrozenxid) / 2000000000, 2) AS pct_toward_wraparound
FROM pg_database
ORDER BY age(datfrozenxid) DESC;

-- Per-table view:
SELECT schemaname,
       relname,
       age(relfrozenxid)                          AS table_xid_age,
       pg_size_pretty(pg_total_relation_size(relid)) AS size
FROM pg_stat_user_tables
ORDER BY age(relfrozenxid) DESC
LIMIT 20;

-- ⚠️  WARNING thresholds:
-- age > 1,500,000,000 → URGENT: manual VACUUM FREEZE immediately
-- age > 1,800,000,000 → CRITICAL: PostgreSQL will shut down soon
-- age > 2,100,000,000 → PostgreSQL refuses new transactions

Part 4: Autovacuum - The Background Maintenance Engine

Manual VACUUM is not practical at scale. Autovacuum runs in the background automatically. Understanding its decision algorithm is essential for tuning it.

Autovacuum Architecture

postmaster
  └── autovacuum launcher  (1 process, always running)
        └── autovacuum worker  (up to autovacuum_max_workers, default 3)
              └── one worker per database, one table at a time

The launcher wakes up every autovacuum_naptime seconds (default: 1 minute), checks pg_stat_user_tables for tables needing work, and forks workers.

The Vacuum trigger formula

A table is eligible for autovacuum when:

n_dead_tup > autovacuum_vacuum_threshold + autovacuum_vacuum_scale_factor × reltuples

Default:
  n_dead_tup > 50 + 0.02 × reltuples
  = dead tuples exceed 50 + 2% of live tuples

Example:
  Table with 10,000,000 rows:
  threshold = 50 + 0.02 × 10,000,000 = 200,050 dead tuples
  → autovacuum triggers after 200K dead tuples accumulate

  Table with 1,000 rows:
  threshold = 50 + 0.02 × 1,000 = 70 dead tuples
  → triggers after just 70 dead tuples

The Analyze trigger formula

n_mod_since_analyze > autovacuum_analyze_threshold + autovacuum_analyze_scale_factor × reltuples

Default:
  n_mod_since_analyze > 50 + 0.1 × reltuples
  = modifications exceed 50 + 10% of live tuples

Cost-based Throttling - why autovacuum seems slow

Autovacuum is intentionally throttled to avoid I/O saturation:

autovacuum_vacuum_cost_delay    = 2ms   (pause between cost limit hits)
autovacuum_vacuum_cost_limit    = 200   (cost units before pausing)

Cost per operation:
  vacuum_cost_page_hit   = 1    (page found in shared_buffers)
  vacuum_cost_page_miss  = 10   (page read from disk)
  vacuum_cost_page_dirty = 20   (page dirtied by VACUUM)

Example: 100% cache miss workload
  200 cost limit / 10 cost per miss = 20 pages per 2ms burst
  = 20 pages × 8KB = 160KB per 2ms
  = ~80 MB/s maximum VACUUM throughput
  For a 100GB table: 100GB / 80MB/s ≈ 21 minutes minimum

This is by design — autovacuum should not compete with your production workload. But if it can't keep up with your write rate, you need to tune cost limits and scale factors per table:

-- Per-table autovacuum tuning (overrides global settings):
ALTER TABLE orders SET (
    autovacuum_vacuum_scale_factor = 0.01,   -- trigger at 1% instead of 2%
    autovacuum_vacuum_cost_delay = 0,         -- no throttling for this table
    autovacuum_vacuum_cost_limit = 1000       -- higher cost limit
);

-- For large, frequently-updated tables:
ALTER TABLE events SET (
    autovacuum_vacuum_scale_factor = 0.005,  -- 0.5%
    autovacuum_vacuum_threshold = 1000,
    autovacuum_analyze_scale_factor = 0.02
);

Part 5: Table Bloat - Diagnosing the Problem

Bloat is the gap between the logical size of your data and the physical size of the files on disk. It comes in two forms.

Heap Bloat

-- Quick bloat estimate using pgstattuple:
CREATE EXTENSION pgstattuple;

SELECT * FROM pgstattuple('orders');
-- table_len        = 1073741824  (1 GB physical size)
-- tuple_count      = 5000000     (live rows)
-- tuple_len        = 600000000   (bytes used by live tuples)
-- tuple_percent    = 55.9        (% of pages with live data)
-- dead_tuple_count = 800000      (dead rows)
-- dead_tuple_len   = 96000000    (bytes used by dead tuples)
-- dead_tuple_percent = 8.9       (% of pages with dead data)
-- free_space       = 377741824   (free bytes in pages)
-- free_percent     = 35.2        ← 35% of the table is wasted!

-- Full bloat scan (slow but accurate):
SELECT pg_size_pretty(table_len)          AS total,
       pg_size_pretty(tuple_len)          AS live_data,
       pg_size_pretty(dead_tuple_len)     AS dead_data,
       pg_size_pretty(free_space)         AS free,
       round(dead_tuple_percent::numeric, 1) AS dead_pct,
       round(free_percent::numeric, 1)    AS free_pct
FROM pgstattuple('orders');

Index Bloat

-- Index bloat via pgstattuple:
SELECT * FROM pgstatindex('idx_orders_status');
-- index_size        = 209715200   (200 MB)
-- leaf_pages        = 24000
-- empty_pages       = 1200        ← pages with no live entries
-- deleted_pages     = 3400        ← pages fully reclaimed
-- avg_leaf_density  = 68.4        ← B-tree pages 68% full (100% = no bloat)
-- leaf_fragmentation = 12.3       ← % of leaf pages out of logical order

-- Bloat estimate without pgstattuple (from catalog stats):
SELECT
    indexrelname,
    pg_size_pretty(pg_relation_size(indexrelid)) AS index_size,
    round(100.0 * pg_relation_size(indexrelid) /
          nullif(pg_total_relation_size(relid), 0), 1) AS pct_of_table,
    idx_scan,
    idx_tup_read,
    idx_tup_fetch
FROM pg_stat_user_indexes
WHERE relname = 'orders'
ORDER BY pg_relation_size(indexrelid) DESC;

Once you've confirmed severe bloat with the queries above, standard VACUUM won't be enough, it can only reclaim space within existing pages, not shrink the file itself.

Part 6: VACUUM FULL vs pg_repack

When bloat is severe, standard VACUUM cannot help - it reclaims space within pages but cannot return pages to the OS or compact the file. For that you need a table rewrite.

VACUUM FULL

VACUUM FULL orders;

What it does:

• Acquires AccessExclusiveLock - blocks all reads and writes

• Creates a brand new heap file

• Copies all live tuples into the new file (compact)

• Rebuilds all indexes from scratch

• Drops the old file

• Releases lock

• Vacuum full also reset relfrozenxid to the current XID - so after a VACUUM FULL, the table's wraparound age resets to 0

Pros: Table is fully compacted; all bloat is eliminated.

Cons:

• Complete table lock for the entire duration

• duration = proportional to table size

• 100GB table = potentially hours of downtime

pg_repack - zero-downtime alternative

-- Install
CREATE EXTENSION pg_repack;

-- Repack a table online
pg_repack -d mydb -t orders

-- Repack only indexes (even faster)
pg_repack -d mydb -t orders --only-indexes

How pg_repack works without locking:

1. Create a new empty table (shadow table)

2. Copy all live tuples to shadow table (no lock, reads allowed)

3. Create a trigger on original table: log all changes to a delta table

4. Apply delta changes to shadow table (catch up with live writes)

5. Repeat step 4 until delta is small (milliseconds of lag)

6. Acquire brief AccessExclusiveLock (milliseconds only)

7. Apply final delta, swap table OIDs, drop original

8. Release lock

Downtime = milliseconds (just the final OID swap), not hours.

VACUUM FULL:  simple, built-in, requires maintenance window
pg_repack:    complex, extension required, truly online

Part 7: Reading VACUUM VERBOSE Output

VACUUM (VERBOSE, ANALYZE) orders;

INFO:  vacuuming "public.orders"
INFO:  scanned index "orders_pkey" to remove 84000 row versions  -- index cleanup pass
      DETAIL: CPU: user: 0.42s, system: 0.08s, elapsed: 1.23s
INFO:  scanned index "idx_orders_status" to remove 84000 row versions
      DETAIL: CPU: user: 0.38s, system: 0.05s, elapsed: 1.01s
INFO:  "orders": removed 84000 row versions in 7200 pages          -- heap cleanup
      DETAIL: CPU: user: 0.12s, system: 0.04s, elapsed: 0.18s
INFO:  index "orders_pkey" now contains 5000000 row versions in 14000 pages
      DETAIL: 84000 index row versions were removed.
              0 index pages have been deleted, 0 are currently reusable.
INFO:  "orders": found 84000 removable, 5000000 nonremovable row versions
                 in 62800 out of 62800 pages
      DETAIL: 0 dead row versions cannot be removed yet, oldest xmin: 1234567
              There were 12000 unused item identifiers.              -- reusable slots
              Skipped 0 pages due to buffer pins, 0 frozen pages.
              0 pages are entirely empty.
              CPU: user: 1.24s, system: 0.23s, elapsed: 4.87s
INFO:  analyzing "public.orders"
INFO:  "orders": scanned 30000 of 62800 pages, containing 2400000 live rows
                 and 0 dead rows; 30000 rows in sample, 5000000 estimated total rows

After running VACUUM VERBOSE, these are the numbers that tell you whether VACUUM did its job:

84000 removable row versions   → dead tuples successfully collected
0 cannot be removed yet        → blocked by long-running transaction
Skipped N frozen pages         → visibility map working (those pages skipped)
0 pages entirely empty         → no file truncation possible (no trailing empty pages)
14000 pages in pkey index      → index is growing

Conclusion

In this module, we explored how VACUUM and autovacuum work under the hood, starting from:

1. Why VACUUM exists? every UPDATE and DELETE leaves dead tuples and dead index entries behind due to MVCC's append-only write model, and without VACUUM the table grows forever, index-only scans stop working, and XID wraparound eventually corrupts the entire database.

2. The exact VACUUM sequence: computing OldestXmin as the reclaim watermark, scanning heap pages while skipping all_visible ones, collecting dead TIDs into maintenance_work_mem, cleaning indexes via ambulkdelete(), compacting pages, updating the FSM, and setting visibility map bits.

3. How autovacuum decides when to act: the trigger formula, cost-based throttling parameters, and how to tune aggressiveness per table using ALTER TABLE ... SET (autovacuum_vacuum_scale_factor = ...) for large high-churn tables.

4. How XID freezing prevents wraparound: setting the HEAP_XMIN_FROZEN infomask bit in PostgreSQL 14+, the three age thresholds that control when freezing happens, and how to monitor proximity to the 2.1 billion XID danger zone using age(datfrozenxid).

5. When to use VACUUM FULL versus pg_repack : full table lock for hours versus online shadow-table rewrite with milliseconds of downtime.

What's Next → Module 8: Concurrency & Locking

We've now seen that VACUUM itself needs locks to run, that long-running transactions block OldestXmin from advancing, and that VACUUM FULL holds AccessExclusiveLock for its entire duration. Module 8 goes into the locking system itself; the full lock hierarchy from AccessShareLock to AccessExclusiveLock, how row-level locks work through xmax and MultiXactId rather than a lock table, deadlock detection, advisory locks, and the pg_locks queries that diagnose blocking in production.

Let's start with structs, then move to enums and bring it all together with pattern matching.

Part 1: Structs

A struct or structure, is a custom data type that lets us group and name multiple related values that make up a meaningful group under a named type.

Definition

Using struct keyword we can define our own structure in Rust. For example:

struct User {
    username: String,   // Calls as Field
    email: String,
    age: u32,
    active: bool,
}

Creating Instance and Access

To use a struct after we defined it, we have to create an instance by giving a concrete value to the each field in the struct. We can do that by stating the name of the struct and then add the curly brackets containing the key:value pairs, where the keys are the names of the fields and values are the data we wanted to store.

fn main() {
    let user = User {
        username: String::from("siva"),
        email: String::from("siva@example.com"),
        age: 25,
        active: true,
    };
  
    println!("{}", user.username);
}

Note: Since struct acts as a template for a group, we don't need to create/assign the fields in the same order as we defined in the struct.

Now, if we want to access a value from the instance we just created, we can use the . notation to access the particular filed and get the value.

let username = user.username;

Structs are immutable by default - the same rule as any variable. To mutate the fields, the entire binding must be mut , as Rust does not allow marking each individual fields as mut . It is all or nothing.

let mut user = User {
    username: String::from("siva"),
    email: String::from("siva@example.com"),
    age: 25,
    active: true,
};

user.age = 24; // Allowed now

And also, we can create a new instance reusing fields from an existing one, or what we call Struct update syntax.

let user2 = User {
    email: String::from("other@example.com"),
    ..user   // fills remaining fields from user defined above
} 

Note: ..user moves fields that are not Copy . If username is a String , it moves out of user and no long fully usable, so use when it is absolute necessary.

Part 2: Types of Struct

In Rust, we can define or use a struct in three ways, say:

1. Named field struct

2. Tuple struct

3. Unit struct

Named Field Struct

Standard way of defining the structs as we discussed above.

struct User {
    username: String,
    email: String,
    age: u32,
    active: bool,
}

Tuple Struct

Tuple structs is named tuples, useful when the field's position carries meaning:

struct Point(f64, f64);
struct Color(u8, u8, u8);

let p = Point(3.0, 4.0);
let c = Color(255, 128, 0);

println!("{}", p.0); // Access fields by position number

Unit Structs

Unit-like structs can be useful when you need to implement a trait (we'll discuss more in upcoming modules) on some type but don't have any data that you want to store in the type itself.

struct AlwaysEqual;

fn main() {
    let subject = AlwaysEqual;
}

Part 3: Behaviour with impl - Methods & Associated Functions

Methods are similar to functions. We declare them with the fn keyword followed by a name, parameters and a return value. Unlike functions, methods are defined within the context of a struct (or enum/trait), and their first parameter is always self, which represents the instance of the struct the method is being called on. The only exception for self is, if the function is an associated function to struct like the function create/initialize a struct.

Rust separates data definition from behaviour. We can define the set of methods in an impl block, not in the struct itself.

Example

// Struct (data definition)
struct Rectangle {
    width: f64,
    height: f64,
} 

// Methods (behaviour)
impl Rectangle {
    // associated
    fn new(width: f64, height: f64) -> Rectangle {
        Rectangle { width, height } // field init shortand when name matches
    }

    // method - takes &self, borrows the instance
    fn area(&self) -> f64 {
        self.width * self.height
    }

    // mutable method - takes &mut self
    fn scale(&mut self, factor: f64) {
        self.width *= factor;
        self.height *= factor;
    }

    // consuming method - takes self, moves the instance
    fn into_square(self) -> Rectangle {
        let side = self.width.min(self.height);
        Rectangle { width: side, height: side }
    }
}

fn main() {
    let mut r = Rectangle::new(10.0, 5.0);
    println!("area: {}", r.area());
    r.scale(2.0);
    println!("after scale: {}x{}", r.width, r.height);
}

The three method receives types - &self , &mut self , self - map directly to the borrowing rules. &self borrows immutably. &mut self borrows mutably. self takes ownership - the caller loses the instance after calling this method.

Rectangle::new is an associated function (no self ). It is the Rust convention for constructors. There is no new keyword - it is just a naming convention.

Part 4: Enums

Also called Enumerations. Enums allow you to define a type by enumerating its possible variants. And this is where Rust diverges sharply from C. Rust enums are algebraic data types - each variant can carry its own data of different types.

Defining the Enums

Using enum keyword, we can define an enum in the Rust. For example:

enum Shape {
    Circle(f64),
    Rectangle(f64, f64),
    Triangle(f64, f64, f64),
}

This is a single type Shape that can be any one of three variants, each carrying different data. Compare this to C where we would need a union plus a tag field plus discipline to not access the wrong union member. Rust eliminates that entire pattern: the compiler knows which variant is active, and pattern matching forces you to handle each one explicitly.

Another example:

enum Message {
    Quit,
    Move { x: i32, y: i32 },
    Write(String),
    ChangeColor(i32, i32, i32),
}

This enum has four variants with different types:

• Quit : Has no data associated with it at all

• Move : Has named fields, like a struct does

• Write : Includes a single String

• ChangeColor : Includes three i32 values.

Enum Values

We can create instances of each of the three variants of Shape like this:

let c = Shape::Circle(10.0);
let r = Shape::Rectangle(10.0, 15.0);
let t = Shape::Triangle(5.0, 6.0, 10.0);

Standard Rust's Enums

The most important enums in all of Rust are built into the standard library:

1. Option<T>

2. Result<T, E>

Option<T>

Represents a value that may or may not exists. Rust has no null . Instead:

enum Option<T> {
    Some(T), // there is a value
    None,    // there is no value
}

let maybe: Option<i32> = Some(42);
let nothing: Option<i32> = None;

You cannot use an Option<T> as if it were a T directly - the compiler forces you to handle the None case. This eliminates an entire class of null pointer bugs.

Result<T, E>

Represents either success or failure.

enum Result<T, E> {
    Ok(T),   // Success, carries the value
    Err(E),  // Failure, carries the error
}

fn divide(a: f64, b: f64) -> Result<f64, String> {
    if b == 0.0 {
        Err(String::from("division by zero"))
    } else {
        Ok(a/b)
    }
}

Part 5: Pattern Matching - match

match is the primary way to work with enums. It is exhaustive - the compiler forces you to handle every variant. No case can be silently ignored. An example using Shape enum defined above:

fn area(shape: &Shape) -> f64 {
	match shape {
		Shape::Circle(r) => std::f64::consts::PI * r * r,
		Shape::Rectangle(w, h) => w * h,
		Shape::Triangle(a, b, c) => {
			let s = (a + b + c) / 2.0;
			(s * (s-a) * (s-b) * (s-c)).sqrt() 
		}
	}
}

Each arm is pattern -> expression . The pattern de-structure the variant and bind its inner values to names. If you miss a variant, the compiler tells you - no runtime surprises.

For Option :

let value: Option<i32> = Some(42);

match value {
    Some(n) => println!("got: {}", n),
    None => println!("nothing"),
};

Catch-all patterns

match number {
    1 => println!("one"),
    2 => println!("two"),
    _ => println!("something else"), // _ matches anything, binds nothing
}

if let - shorthand when you only care about one variant:

if let Some(n) = value {
    println!("got: {}", n);
} // equivalent to matching Some and ignoring None

while let - loop while a pattern matches:

while let Some(top) = stack.pop() {
    println!("{}", top);
}

Part 6: Exercises

1. Define a struct Transaction with fields: id: u64 , amount: f64 , status: String . Add an impl block with a constructor new and a method is_large(&self) -> bool that returns true if amount > 1000.0 .

struct Transaction {
    id: u64,
    amount: f64,
    status: String,
}

impl Transaction {
    fn new(id: u64, amount: f64, status: String) -> Transaction {
        Transaction { id, amount, status }
    }

    fn is_large(&self) -> bool {
        self.amount > 1000.0
    }
}

fn main() {
    let txn1 = Transaction::new(1, 900.0, String::from("success"));
    let txn2 = Transaction::new(2, 1001.0, String::from("success"));

    println!("Txn1 is large = {}", txn1.is_large());
    println!("Txn2 is large = {}", txn2.is_large());
}

1. Define an enum Command with variants: Quit , Move { x: i32, y: i32 } , Print(String) . Write a match that handles all three and prints something meaningful for each.

enum Command {
    Quit,
    Move { x: i32, y: i32 },
    Print(String)
}

fn execute_command(cmd: &Command) {
    match cmd {
        Command::Quit        => println!("Quitting"),
        Command::Move{x, y}  => println!("Moving x:{} and y:{}", x, y),
        Command::Print(s)    => println!("{}", s)
    }
}

fn main() {
    let cmd1 = Command::Quit;
    let cmd2 = Command::Move {
        x: 10,
        y: 10,
    };
    let cmd3 = Command::Print("Hello".to_string());

    execute_command(&cmd1);
    execute_command(&cmd2);
    execute_command(&cmd3);
}

Conclusion

Structs let you group related data into meaningful types. Enums let a single type represent multiple distinct variants, each carrying its own payload. match ties it all together - exhaustive, compiler-enforced, no silent ignores. Together, they replace the scattered nulls, union hacks, and runtime surprises you'd find in C. This is Rust making correctness a compile-time guarantee, not a runtime hope.

What's Next: Traits & Generics
So far, every type we've written is fixed to one kind of data. Traits and Generics change that letting you write code that works across many types while keeping the compiler's full safety guarantees. That's the next module.

If ownership is the rule, borrowing is the exception that makes the rule practical.

Without borrowing, every function call would consume its arguments, and that's genuinely painful to work with.

Part 1: The Core Idea - References

A Reference is a pointer to a value that you do not own. We are borrowing it, like lending a book. The lender still owns it. When the borrow ends, the book goes back.

The syntax is &T for an immutable reference, &mut T for a mutable one.

let s = String::from("hello");
let r = &s                      // r borrows s - s still owns the heap data

println!("{}", r);              // Valid, prints "hello"
println!("{}", s);              // Valid, prints "hello"

The & in &s creates a reference. The value r on the stack is just a pointer to the address of s . It does not own the heap data. When r goes out of scope, nothing is freed. When s goes out of scope, the heap is freed - because s is still the owner.

Stack
----------------------
r(&String) ptr --> s
----------------------
s(owner)
ptr -> heap
len: 5
cap: 5                  -------------> Heap | Heap data 'h' 'e' 'l' 'l' 'o' |
----------------------                 

Part 2: Immutable vs Mutable References

Rust has exactly two references types, and the rules around them are asymmetric by design.

1. Immutable Reference &T

2. Mutable Reference &mut T

An immutable reference &T lets you read the value. You can have as many of these as you want simultaneously. No one can modify the value while any immutable reference exists.

A mutable reference &mut T lets you both read and write the value. You can have exactly one at a time. No immutable references can exist simultaneously with a mutable one.

let mut s = String::from("hello");

let r1 = &s;           // fine, read-only
let r2 = &s;           // fine, read-only // multiple immutable refs allowed at a same time
println!("{} {}", r1, r2);  

let r3 = &mut s;       // fine, r1 & r2 are no longer used after above println
r3.push_str(" world");  // r3 is a mutable one, so it can make changes to s's heap
println!("{}", r3);

// Not allowed, error: cannot borrow `s` as mutable because it is also borrowed as immutable
let r4 = &s;
let r5 = &mut s;
println!("{} {}", r4, r5); 

The rule stated precisely: at any given point in the code, you may have either one mutable reference OR any number of immutable references - never both at the same time.

Part 3: The Borrow Checker in action

Case 1: Simultaneous Mutable and Immutable References

let mut s = String::from("hello");
let r1 = &s;            // immutable borrow begins
let r2 = &mut s;        // cannot borrw s as mutable because r1 is still alive

println!("{}", r1);

If this were allowed, r2 could modify s 's heap buffer, while r1 still holds the old pointer - classic use-after-free case.

Case 2: Two mutable references

let mut s = String::from("hello");
let r1 = &mut s;
let r2 = &mut s;        // cannot borrow s as mutable "more than once"
r1.push_str(" world");

If both r1 and r2 could mutate s simultaneously, we have a data race - even on a single thread, the mutation order is ambiguous and the internal state (ptr, len, cap) in the stack could become inconsistent.

Case 3: Dangling Reference

fn dangle() -> &String {            // returning a reference to local data
  let s = String::from("hello");
  &s                                // 's' will be dropped when function returns
}

The compiler rejects this: s will be freed/deallocated when dangle returns, so the reference would point to freed memory when we tried to access it. In C this compiles fine and produces a dangling pointer. Rust refuses to compile it.

The solution is to return the String itself by giving up the ownership to the caller

fn no_dangle() -> String {
   let s = String::from("hello");
   s
}

This works fine. Ownership is moved, and nothing is deallocated.

Part 4: &str VS String - a crucial distinction

Now that we understand references, &str should make complete sense.

String is an owned, heap-allocated, growable string. &str is a borrowed reference to a string slice, it is just a pointer and a length. It can point into a String 's heap buffer, or into a string literal in the binary's read-only segment.

let s: String = String::from("hello world");
let slice: &str = &s[0..5];    // borrows 5 bytes of s's heap buffer
let literal: &str = "hello";   // points into read-only binary segment

The idiomatic guideline: if your function only needs to read a string, take &str - not &String . This is more flexible because both String and &str can be passed as &str :

fn print_it(s: &str) {
   println!("{}", s);
}

let owned = String::from("hello");
print_it(&owned);                   // &String auto-coerces to &str
print_it("world");                  // &str literal works directly

This auto-coercion is called de-ref coercion - &String automatically becomes &str when the context demands it. We will discuss more about this in the traits module.

Before we wrap up, there's one more borrowed type worth understanding - slices.

Part 5: Slices - references to a contiguous sequence

The same idea generalises beyond strings. A slice &[T] is a reference to a contiguous portion of an array or Vec.

let arr = [1, 2, 3, 4, 5];
let slice: &[i32] = &arr[1..4];      // borrows elements 2,3,4
println!("{:?}", slice);             // [2,3,4]

A slice is always a fat pointer - two words on the stack: a pointer to the first element, and the length. No ownership, no allocation.

Conclusion

Borrowing is Rust's answer to a hard problem: how do you share data without copying it, and without the chaos of unchecked aliasing?

The rules are simple to state but deep in consequence:

1. References let you read or modify data without owning it

2. Immutable references can coexist freely; mutable references demand exclusivity

3. The borrow checker enforces these rules at compile time — no runtime cost, no garbage collector needed

Once these rules click, &str, slices, and the broader Rust type system start to feel less like restrictions and more like a contract that makes your code provably safe. Ownership tells you who is responsible. Borrowing tells you who is allowed to look or touch and for how long.

In the next post, we'll move into Structs, Enums and Pattern Matching.

Today, we are going to discuss little deeper and most important topic in all of Rust i.e., Ownership. Everything else like borrowing, lifetimes, concurrency safety is built on top of what Ownership is.

Part 1: The Problem Rust is Solving

In C, memory bugs fall into a few categories:

• Use-after-free: You free a buffer and then dereference it.

• Double-free: Two code paths both call free on the same pointer.

• Memory Leak: Nobody calls free at all.

• Dangling Pointer: a pointer outlives the data it points to or in simpler word accessing a pointer beyond its scope.

Languages like C++ and Java solve this with a Garbage Collector - a runtime process that tracks all live references and frees memory when nothing points to it anymore. It brings GC pauses, heap pressure, and no control over layout or freeing timing.

Rust's answer is different: Encode the rules of memory ownership into the type variables, and have the compiler enforce them at compile time. Zero runtime cost, zero garbage collection, zero undefined behaviour.

And the rules are called the "Ownership System".

Part 2: The Ownership Rules

There are three axioms/rules. Everything else is a consequence of them.

1. Every value in Rust has exactly one owner i.e a Variable.

2. When the owner goes out of scope, the value is dropped (memory freed).

3. There can only be one owner at a time.

If any of the rules are violated, the program won't compile. And these features of ownership won't slow down our program as well since these will be checked at compile time itself, so if compilation passes, we can safely assume our program is memory bug free.

Part 3: Stack v/s Heap

Before going deep dive into Ownership, let's discuss where the values and data live. Rust explicitly holds these some data structures based on type system.

Many programming languages don't require you to think about the stack and the heap very often. But in a systems programming language like Rust, whether a value is on the stack or the heap affects how the language behaves and why you have to make certain decisions.

Stack

1. Stack stores the values in the order it gets them, and remove in opposite, or we can say it follows LIFO (Last In First Out) principle.

2. All the data stored on stack must have a known, fixed size at compile time. Data with an unknown size or a size that might change must be stored on the heap instead.

3. On function return, its entire stack frame is gone i.e., all local variables on it are freed automatically.

4. Fast Access and No Runtime allocation.

Heap

1. The heap is less organized: When you put data on the heap, you request a certain amount of space. The memory allocator finds an empty spot in the heap (which is big enough), marks it as being in use, and returns a pointer, which is the address of that location.

2. Request memory at Runtime via an Allocator,

3. Persists until explicitly freed.

4. Stack stores a pointer to it.

In Rust, types that are entirely stack-resident implement the Copy trait (more on this below) - integers, booleans, floats, tuples, fixed arrays.

So what is the Copy trait? In Rust, when we assigns a value of one variable to another variable, if the value is copied to another variable instead of giving a reference/pointer, then that type has a Copy trait. Types that has own heap memory are like String , Vec<T> , Box<T> - do not implement Copy. This distinction drives the move semantics which we are going to learn now.

Part 4: Move Semantics

fn main() {
   let num1 = 5;
   let num2 = num1;                   // Now "5" is copied to num2 as well
   println!("{} {}", num1, num2);     // Prints 5, 5
   
   let s1 = String::from("hello");
   let s2 = s1;                     // Ownership moved from s1 to s2
   println!("{}", s1);              // Compile Error: borrow of moved value: `s1`
}

Why does this fail?

Let's look closer at what String actually is in memory:

As discussed above, String memory will be allocated in the Heap, but a pointer to that Heap location is stored in the stack (4th point in Part 3 Heap section). Now let's look closer at what String actually is in memory:

A String on the stack is a three-field struct:

1. a pointer to heap data

2. a length

3. a capacity

So, when we write let s2 = s1 , Rust does not deep-copy the heap data. Instead it copies the three stack fields (pointer, len, cap) to s2, and then immediately invalidates s1 . This is a Move. Ownership of the heap data transferred from s1 to s2 . And there is now exactly one owner to the memory location in Heap i.e s2(Axiom 1 in ownership rules).

Why does Rust do this instead of Copying?

Because copying heap data is an O(n) operation. Rust never silently does expensive things. If we want a deep copy, we must ask for it explicitly with .clone() .

fn main() {
   let s1 = String::from("hello");
   let s2 = s1.clone();         // Explicit deep copy - heap data duplicated
   println!("{}", s1);          // s1 is valid and prints "hello"
   println!("{}", s2);          // s2 is ALSO valid and prints "hello", has it's own copy
}

.clone() is a signal in code review: "this is an allocation, this costs memory and time." It is intentional, never hidden.

Part 5: Copy Types - the exception

For stack-only types, there is no heap to worry about i.e., copying is just copying bits. Rust mark these types with the Copy trait, and for them, assignment copies instead of moving.

let x: i32 = 5;
let y = x;  // x is Copy - this is a bitwise copy, not move

println!("{}", x); // x is still valid
println!("{}", y); // y has it's own copy

The Copy types include: all integer types, f32/f64, bool, char, tuples and arrays composed entirely of Copy types.

String is NOT Copy because it owns heap memory. &str (a string reference - not owner) IS Copy, because it is just a pointer, it does not own the heap data.

Part 6: Ownership and Functions

What happens when we pass the values to functions as Parameters/Arguement, a Move happens, not just an assignment.

fn print_string(s: String) {          //s become the owner now
	println!("{}", s);
}                                    // s dropped here and heap freed

fn main() {
	let s = String::from("hello");
	print_string(s);               // ownership moves into the function
	println!("{}", s);            // compile error: borrow of moved value: `s`
}

The function print_string took ownership of s . When it returned, s was dropped. The caller no longer has it.

We have two ways out of this:

1. Brute-force

2. Borrowing (will discuss in next module)

Option 1: Return Ownership

The brute-force option is to return the ownership back to the original owner who passed it.

fn print_string(
   s: String        // Takes the ownership from the Caller
) -> String /* Returning String returns ownership to the caller back */ { 
	println!("{}", s);
	s 
}

fn main() {
	let s = String::from("hello");
	let s = print_string(s);     // get ownership back
	println!("{}", s);           // valid now
}

This is intentionally verbose. Rust is showing us the cost. The real solution is lending without transferring ownership i.e Borrowing.

Option 2: Borrowing

If ownership is the rule, borrowing is the exception that makes the rule practical. Without borrowing every function call would consume its arguments and it’s painful.

Borrowing lets you hand data to a function/variable without giving up ownership of it.

Example

let s = String::from("hello");
let r = &s // r borrows s - s still owns the heap data

println!("{}", r); // Valid, prints "hello"
println!("{}", s); // Valid, prints "hello"

& let us borrow the heap from s to r , then r can work on the borrowed data. We will discuss in detailed in next module

Part 7: Drop - Automatic Cleanup

When a value's owner goes out of scope, Rust calls it's drop function automatically. This is analogous to a C++ destructor, except in Rust it run deterministically, at a known point in the code, not whenever a Garbage Collector (GC) decides to collect.

{
   let s = String::from("hello");     // heap allocated
   // Use 's' as per the use-case
   // <-- 's' goes out of scope here. Drop called, heap freed.
}

We never call drop manually (well, std::mem::drop(s) exists for forced early drops, but it's uncommon in practice). The compiler inserts the call automatically.

This is how Rust achieves C-level performance without a Garbage collector, memory is freed as soon as it's no longer needed, deterministically, with zero runtime bookkeeping.

Conclusion

Ownership is Rust's core bet: instead of managing memory at runtime (GC) or leaving it to the programmer (C/C++), encode the rules into the type system and let the compiler enforce them. The three axioms: one owner, drop on scope exit, no simultaneous owners - are simple. But everything that follows (borrowing, lifetimes, Arc, Mutex) is just the compiler asking "does this respect ownership?" at increasingly complex levels.

In the next post, we'll look at Borrowing and References - the mechanism that lets you use data without taking ownership of it, which is how real Rust code avoids the verbose "return ownership back" pattern we saw in Part 6.