GoKawiilReading The Internals of PostgreSQL: Database Cluster, Databases, and Tables June 28, 2026
I'm delving into Postgres Internals and while doing that I thought it would be better to write my notes to keep me accountable and try to internalize my readings. Thanks Hironobu Suzuki for this great reference and his work on Postgres. Here is the source link https://www.interdb.jp/pg/index.html.
Logical Structure of Database Cluster#
A database cluster is not a collection of database servers in the context of PostgreSQL (SQL standard uses the term catalog cluster). It means a group of databases managed by a single PostgreSQL instance. That is most probably a correct definition in dictionary terms, but usually when you hear database cluster you would assume multiple nodes/instances of databases that act as a single system.
A database is a collection of database objects such as tables, indexes, views, etc. In PostgreSQL, databases are also database objects and they are represented by Oid , which is an unsigned int object identifier.
sql SELECT oid , datname FROM pg_database ORDER BY oid ; oid datname 1 template1 4 template0 5 postgres
Built-in objects (databases in this query) have hardcoded low values. Other user-created tables/objects start having OIDs from 16384 (OIDs 1-16383 are reserved or used by init objects).
database cluster · one PostgreSQL instance template1 oid 1 template0 oid 4 postgres oid 5 shop oid 16384 pg_database lists every database (one shared catalog per cluster) objects inside 'shop' orders table oid 16386 orders_pkey index oid 16395 views, sequences, … more objects oid … every object is identified by its own Oid
These objects and their relations are stored in system catalogs which are just regular tables in PostgreSQL. Some examples are:
Table Description pg_class Tables and other objects that are similar to tables (views, indexes, TOAST tables etc.) pg_database Stores information about available databases. pg_index Index information ... ...
... continue reading