pg_coredump: Easier coredump collection for PostgreSQL

The PostgreSQL extension makes it easier to generate coredump files for PostgreSQL in the advent of a crash.

Table of contents

1. Overview
2. Rationale
3. Build from sources
4. Setting up
5. Helper functions

Overview

A core dump is a file containing a snapshot of a process's memory when the process terminates unexpectedly. On most Unix based systems a core dump file is automatically generated by the kernel in response to an illegal operation performed by the software during runtime, like invalid/unaligned memory access, division by zero, etc, the default action is to terminate the process. Core dumps may also be produced on demand, with the help of a debugger or some other tool.

Rationale

Every Linux distribution usually handle core dumps in different ways, sometimes an admistrator may not be allowed to adjust global system settings which affect core dump generation, this scenario becomes even worse on containerized applications like kubernetes, where the core files are usually exported in the supervisor's volume, pg_coredump comes to the rescue by allowing the process itself to generate a coredump whenever it crashes, thus not depending on external settings. By default pg_coredump exports a core dump file onPGDATA directory, with a core.<unix_ts>.<PID> file name pattern.

Building from sources

1. If postgres is installed in a non standard directory, set the PG_CONFIG environment variable to point to the pg_config executable.

2. Clone the repository, build and install it with the following commands:

   git clone --recurse-submodules https://github.com/Percona-Lab/pg_coredump.git

3. Compile and install the extension

   cd pg_coredump
   make USE_PGXS=1
   sudo make USE_PGXS=1 install

Setting up

The extension must be configured using one of the shared library preloading settings in PostgreSQL. Note that the example here uses shared_preload_libraries which requires a server restart. If you want to make the extension active for new client connections without restarting the server you may want to consider session_preload_libraries instead.

1. Add extension to the shared_preload_libraries:

   1. Via configuration file postgresql.conf

      shared_preload_libraries=pg_coredump 
      

   2. Via SQL using ALTER SYSTEM command

      ALTER SYSTEM SET shared_preload_libraries = 'pg_coredump';

2. Start or restart the postgresql cluster to apply the changes.

   • On Debian and Ubuntu:

     sudo systemctl restart postgresql-17

   • On RHEL 8 compatible OS (replace XX with your version):

     sudo systemctl restart postgresql-XX.service

3. CREATE EXTENSION with SQL (requires superuser or a database owner privileges): NOTE: This step is only required if you want to use any of the helper functions provided by pg_coredump extension, by default the extension is already active if configured in the PostgreSQL library preloading settings.

   CREATE EXTENSION pg_coredump;

Helper functions

The extension provides the following helper functions:

pg_coredump(dir text)

Generates a coredump on the directory provided, returns t if the operation was successfully executed, f otherwise.