[FREE] Why Linux Kills PostgreSQL: What the Manual Says (And How to Fix It)
The official documentation explains exactly how to prevent Linux from killing your database. Here's what it says.
Table of Contents
The Warning in the Manual Most DBAs Skip
What the Manual Says: Linux Memory Overcommit
Why This Is Catastrophic
The Manual’s Four Solutions
Solution 1: Isolate PostgreSQL
Solution 2: Add Swap Space
Solution 3: Reduce PostgreSQL Memory Usage
Solution 4: Change Linux Kernel Behavior
The Manual’s Kernel Settings: Strict Overcommit
What Mode 2 Does
The Manual’s Kernel Settings: OOM Score Adjustment
Critical: Child Process Configuration
What the Manual Says: Linux Huge Pages
Why Huge Pages Help
Kernel Requirements
Calculating Huge Page Requirements
Allocating Huge Pages
Handling Allocation Failures
Permissions
PostgreSQL Configuration
Quick Implementation Guide
For OOM Protection
For Huge Pages
The Key Takeaways
References
🚀 Get the PostgreSQL Health Report: single SQL function that runs 60+ diagnostic checks including TXID wraparound detection, autovacuum health, much more and ready-to-run fixes.
The Warning in the Manual Most DBAs Skip
Deep in Chapter 19 of the PostgreSQL documentation Server Setup and Operation there’s a section called Linux Memory Overcommit that contains this ominous message:
The default virtual memory behavior on Linux is not optimal for PostgreSQL.
That's the PostgreSQL manual telling you directly: Linux default settings can kill your database.
What the Manual Says: Linux Memory Overcommit
Because of the way that the kernel implements memory overcommit, the kernel might terminate the PostgreSQL postmaster (the supervisor server process) if the memory demands of either PostgreSQL or another process cause the system to run out of virtual memory.
When this happens, you’ll find:
Out of Memory: Killed process 12345 (postgres).Why This Is Catastrophic
This indicates that the postgres process has been terminated due to memory pressure. Although existing database connections will continue to function normally, no new connections will be accepted. To recover, PostgreSQL will need to be restarted.
The Manual’s Four Solutions
Solution 1: Isolate PostgreSQL
One way to avoid this problem is to run PostgreSQL on a machine where you can be sure that other processes will not run the machine out of memory.
Solution 2: Add Swap Space
If memory is tight, increasing the swap space of the operating system can help avoid the problem, because the out-of-memory (OOM) killer is invoked only when physical memory and swap space are exhausted.
Solution 3: Reduce PostgreSQL Memory Usage
If PostgreSQL itself is the cause of the system running out of memory, you can avoid the problem by changing your configuration. In some cases, it may help to lower memory-related configuration parameters, particularly shared_buffers, work_mem, and hash_mem_multiplier.
In other cases, the problem may be caused by allowing too many connections to the database server itself. In many cases, it may be better to reduce max_connections and instead make use of external connection-pooling software.
Solution 4: Change Linux Kernel Behavior
Strict Overcommit:
Which can be used with or without altering vm.overcommit_memory, is to set the process-specific OOM score adjustment value for the postmaster process to -1000, thereby guaranteeing it will not be targeted by the OOM killer.
The simplest way to do this is to execute in the PostgreSQL startup script just before invoking postgres. Note that this action must be done as root, or it will have no effect; so a root-owned startup script is the easiest place to do it.
sysctl -w vm.overcommit_memory=2Important: It is possible to modify the kernel's behavior so that it will not overcommit memory.
Although this setting will not prevent the OOM killer1 from being invoked altogether, it will lower the chances significantly and will therefore lead to more robust system behavior. This is done by selecting strict overcommit mode via sysctl.
OOM Score Adjustment:
If you do this, you should also set these environment variables in the startup script before invoking postgres:
These settings will cause postmaster child processes to run with the normal OOM score adjustment of zero, so that the OOM killer can still target them at need.
echo -1000 > /proc/self/oom_score_adj
export PG_OOM_ADJUST_FILE=/proc/self/oom_score_adj
export PG_OOM_ADJUST_VALUE=0What the Manual Says: Linux Huge Pages
Using huge pages reduces overhead when using large contiguous chunks of memory, as PostgreSQL does, particularly when using large values of shared_buffers.
Calculate requirements:
postgres -D $PGDATA -C shared_memory_size_in_huge_pagesAllocate:
sysctl -w vm.nr_hugepages= set accordinglyConfigure PostgreSQL:
huge_pages = onThe Key Takeaways
Linux defaults are bad for PostgreSQL not optimal
The OOM killer targets the postmaster no new connections
Strict overcommit mode (vm.overcommit_memory=2) reduces OOM invocations
OOM score adjustment (-1000) protects postmaster, but set PG_OOM_ADJUST_VALUE for children
Huge pages reduce overhead important with large shared_buffers
Allocate huge pages early fragmentation prevents late allocation
References
postgresql-16 chapter 19 Linux Memory Overcommit
📧 Want the deep-dive playbooks?
Paid subscribers get complete Sev-1 incident guides with production SQL queries for memory diagnostics, OOM risk assessment, and step-by-step recovery procedures.
Next week will share more diagnostic Queries for Paid Audience.
🚀 Get the PostgreSQL Health Report: a single SQL function that runs 60+ diagnostic checks including TXID wraparound detection, autovacuum health, and ready-to-run fixes..