
Postgres Database contains one or more schemas and schema contains objects including relations. Schema is a kind of namespace, so relations and other objects exist in a schema. Relations look and behave like tables and views. Even indexes are defined as a relation also.
What is RelCache?Structural RelationData has all contents to handle a relation to read, write, create, drop and etc. So, every operation with relation must be access to the RelationData and some operation will try to modify or delete the RelationData. It should also be processed fast and safe concurrently. RelCache provides various kinds of functions.
How it works?RelationCache is based on hash table.
Default Process Unit
- Relation Cache Insert
- add new relation to cache
- if already exists,
- if replace is not allowed, then ASSERT
- if allowed, delete old cache with reference count == 0
- if old cache has 1 or more ref count, then return error
- Relation Cache Lookup
- search with rel id
- if find, return rel
- if not, return null
- Relation cache Delete
- search with rel id
- if find, delete rel
- if not, return error
Who makes the cache Insert?
The first one is Initialize Postgres. During initialization, system catalogs (pg_database, pg_authid, pg_auth_members, pg_class and etc.) are created and rel caches for them are necessary. If there is pg_inernal.init file and it is read successfully, create relation cache with it. If not, gather hard coded data from source code and create cache. After creation, write down rel cache data into the file, also.
The second one is producing new relation, like CREATE TABLE. Allocate memory for new rel cache and insert cache into the hash map.
The third is failed cache lookup. If there is a relation in database but its cache is not, then postgres will build new cache from its system catalog tables. Every member of relation is stored in separated catalogs already. After building, postgres insert it to the hash map too.
Who lookup the cache?
Every function that accesses to relation must get rel cache. CREATE, DROP, ALTER, INSERT, SELECT and more. That’s why postgres construct cache for relation.
Who calls Relation Cache Delete?
When the result is invalid from get rel cache, delete invalid cache and rebuild it. Also, when a transaction is committing, it cleans and rebuilds caches, which it opened. A cache made in that transaction is rebuilt, the others are cleaned. If it was abort, not commit, then every cache will be cleaned. Cache clean does not mean delete always. If its reference count is greater than 0, the cache will survive.
How ALTER works?
ALTER query must check relation’s reference count. ALTER can be processed when the ref cnt is 1. That count means any other transaction is not access to this relation. So ALTER transaction could update easily relations’ properties. After it, ALTER transaction must update system catalogs too and set ‘valid = false’ to current rel cache. When ALTER transaction commits, the reference count will be 0. After a while, new transaction tries to access this relation and get rel cache. It will find out cache is invalid and ref cnt is 0, so it can rebuild the cache with system catalog and get valid rel cache.
Conclusion
In this post, we briefly describe what relation cache is and how it works in PostgreSQL.
Common questions
Can I query relcache contents directly with SQL?
Not directly. PostgreSQL has no dedicated view listing every relcache entry, but the pg_backend_memory_contexts view, available in PostgreSQL 14 and later, shows memory usage for cache related contexts in the current session, which gives an indirect but practical picture of cache size.
Does restarting a connection clear relcache problems?
Yes. Closing a backend connection discards its relcache along with the rest of its memory. A new connection always starts with a cold cache that it rebuilds lazily as it touches relations.
Do VACUUM and ANALYZE invalidate relcache entries?
Plain VACUUM and ANALYZE update statistics without changing a relation's structure or storage file, so they don't force other backends to discard that relation's cached descriptor. VACUUM FULL rewrites the relation and does trigger invalidation.
Is relcache the same as the prepared statement plan cache?
No. Relcache stores descriptors for relations built from catalog data, while the plan cache used by prepared statements stores compiled execution plans. A relcache invalidation can indirectly force a cached plan to be replanned.
Sources
About this page
Last reviewed October 30, 2026 by the Nine Bits editors. Read our editorial policy or report an error.