Contents

• Installation
  • Install from packages or Docker (recommended)
  • Docker
  • Prerequisites
  • Build and Install
  • Verify installation
  • Upgrading to 2.5
  • Upgrading to 2.4
  • Upgrading to 2.3
  • Upgrading to 2.2
  • Migrating from pg_checksums 1.x
  • Next

Installation

Install from packages or Docker (recommended)

Method	PostgreSQL versions	Notes
PGXN / source	12–19	Always gets the latest release
PIG / APT / DNF	14–18	Binary packages from the PIGSTY repository via PGEXT.CLOUD
Docker	12–18	Prebuilt images with the extension enabled in the default database

The fastest way on a machine that already has PostgreSQL 14–18 and the PIGSTY repository configured:

# Any distribution supported by PIG
pig install pg_integrity_checksums

# Debian / Ubuntu (PIGSTY repository configured)
sudo apt install postgresql-16-pg-integrity-checksums

# RHEL / Fedora / Rocky / AlmaLinux (PIGSTY repository configured)
sudo dnf install pg_integrity_checksums_16

psql -d your_database -c "CREATE EXTENSION pg_integrity_checksums;"

Replace 16 with your PostgreSQL major version. The package page is PGEXT.CLOUD: pg_integrity_checksums.

Version note: binary packages are rebuilt by the PIGSTY/PGEXT maintainers after a release and can lag behind PGXN. Check the installed version with SELECT extversion FROM pg_extension WHERE extname = 'pg_integrity_checksums';.

Docker

Prebuilt images are published to GHCR for PostgreSQL 12–18. The extension is created automatically in POSTGRES_DB on first initialization.

docker run --rm --name pg-integrity \
  -e POSTGRES_PASSWORD=secret \
  -e POSTGRES_DB=demo \
  -p 5432:5432 \
  ghcr.io/victornagibator/pg_integrity_checksums:pg16

Then, from another terminal:

psql -h localhost -U postgres -d demo \
  -c "SELECT extversion FROM pg_extension WHERE extname = 'pg_integrity_checksums';" \
  -c "SELECT pg_table_logical_checksum('pg_class'::regclass);"

To build an image for another PostgreSQL major version locally:

docker build --build-arg PG_MAJOR=17 -t pg-integrity-checksums:pg17 .

Images are built by the Docker workflow; pull requests and releases are smoke-tested with PostgreSQL 16.

Prerequisites

• PostgreSQL 12 or later (tested on 12, 13, 14, 15, 16, 17, 18, and 19)
• C compiler and PostgreSQL development headers
• Superuser access to install the extension and to run the database-level checksum functions

Privileges: the table, page, cell, tuple and index checksum functions read relation storage directly. They require SELECT on the relation (or on the base table for an index) and reject relations protected by row-level security, because a direct page scan cannot apply RLS policies. The database-level functions are superuser-only; this is enforced in C, not just in SQL.

Note: PostgreSQL 12 and 13 are past end-of-life upstream, but they are still fully supported by this extension. The build deliberately fails with a clear error on PostgreSQL 11 and older, which lack the table-AM API the extension relies on.

Note: this extension is named pg_integrity_checksums specifically to distinguish it from the pg_checksums utility shipped with PostgreSQL core. They are unrelated: the core utility verifies data page checksums on disk, while this extension provides SQL functions for computing checksums.

Build and Install

The extension builds with PGXS, so pg_config must be on your PATH, or you can point make at a specific installation with PG_CONFIG=/path/to/pg_config.

# Clone or extract the extension
git clone https://github.com/VictorNagibator/pg_integrity_checksums

# Go into extension directory
cd pg_integrity_checksums

# Build
make

# Install
make install

# Create extension in your database
psql -d your_database -c "CREATE EXTENSION pg_integrity_checksums;"

Or install it straight from PGXN with the pgxn client:

pgxn install pg_integrity_checksums

The extension is also listed in PGEXT.CLOUD.

Verify installation

After CREATE EXTENSION, check the installed version and compute one checksum with the default 32-bit API:

SELECT extversion
FROM pg_extension
WHERE extname = 'pg_integrity_checksums';

SELECT pg_table_logical_checksum('pg_class'::regclass);

Extension 2.2 and newer also provide the optional generic API:

SELECT encode(
    pg_table_logical_checksum('pg_class'::regclass, 'fnv64'),
    'hex'
);

If the generic call reports that the function does not exist, the installed extension is older than 2.2 or the upgrade did not run. See Upgrading to 2.2.

Upgrading to 2.5

2.5 changes one default: pg_integrity_checksums.strict is now on. A database checksum (pg_database_physical_checksum, pg_database_logical_checksum) fails when a relation cannot be checksummed, instead of skipping it with a warning. Checksum values do not change. Upgrade with:

ALTER EXTENSION pg_integrity_checksums UPDATE TO '2.5.0';

The new default is picked up when the new library is loaded (new sessions after the package upgrade). Jobs that relied on the old behavior, for example a scheduled check that ran with an invalid index left over from a failed CREATE INDEX CONCURRENTLY, with a third-party index access method, or on a standby that holds unlogged tables, will now fail. Fix the underlying problem (DROP or REINDEX the invalid index), or keep skipping explicitly:

ALTER ROLE monitor SET pg_integrity_checksums.strict = off;

See Strict mode.

Upgrading to 2.4

2.4 fixes three cases where a logical or physical checksum depended on something other than the stored data. Upgrade with:

ALTER EXTENSION pg_integrity_checksums UPDATE TO '2.4.0';

Checksum values change, and old baselines no longer match, only in these cases:

• Dropped columns. Tables with dropped columns, and composite types with dropped attributes, used to hash the physical attribute number. They now hash the position among the live columns, so the checksum equals that of an identical table without the dropped columns (for example after a dump/restore). Tables without dropped columns are unchanged.
• search_path. A user-defined type used to be named with its schema when the schema was not on the session’s search_path. It is now always identified by its unqualified name. Baselines taken from a session with the default search_path (types in public) are unchanged; baselines taken with another search_path must be recreated.
• include_header = true. Physical tuple and table checksums that include the tuple header now ignore the xmin/xmax hint bits, which are set lazily by whichever session reads a tuple first. Checksums with include_header = false (the default) are unchanged.

To check whether an existing baseline is affected, recompute it after the upgrade and compare. If it differs, recreate it from the current data; the earlier value reflected the old, less stable computation.

The 2.4 upgrade also revokes EXECUTE from PUBLIC on the generic pg_database_*_checksum(boolean, boolean, text) functions. They already required a superuser.

Upgrading to 2.3

2.3 adds pg_page_checksum_status(regclass, integer), which verifies a page against the checksum stored in its header and reports data_checksums = off as checksums_disabled. Upgrade with:

ALTER EXTENSION pg_integrity_checksums UPDATE TO '2.3.0';

The 2.3 upgrade also refreshes the pg_cell_checksum and pg_page_checksum comments for installations coming from 2.2.0.

Upgrading to 2.2

2.2 adds generic algorithm overloads for FNV-1a 32-bit and 64-bit digests. Existing SQL functions and their 32-bit values are unchanged; PostgreSQL page checksums remain 16-bit. Upgrade with:

ALTER EXTENSION pg_integrity_checksums UPDATE TO '2.2.0';

Older CLI releases cannot read v2 baselines created with --hash fnv64; the 0.4 CLI reads both v1 (fnv32) and v2 (fnv64).

Migrating from pg_checksums 1.x

The extension was renamed in 2.0.0 to avoid confusion with PostgreSQL’s core pg_checksums utility. PostgreSQL has no ALTER EXTENSION ... RENAME, so migrate by reinstalling the extension and updating the GUC prefix. See MIGRATION.md for the full checklist:

DROP EXTENSION pg_checksums;
CREATE EXTENSION pg_integrity_checksums;

-- old settings
SET pg_checksums.workers = 4;
SET pg_checksums.strict = on;

-- new settings
SET pg_integrity_checksums.workers = 4;
SET pg_integrity_checksums.strict = on;

SQL function names and checksum values are unchanged, so existing logical and physical baselines remain valid. If DROP EXTENSION fails because of dependent objects, remove or recreate those dependencies explicitly rather than using CASCADE without review.

Next

Continue with Getting started for the first checksum and Concepts for the logical/physical model.