PG_CHECKSUMS(1)

💖 PG_CHECKSUMS(1) 💖

okay so bestie, welcome to pg_checksums from the PostgreSQL 13.23 documentation — this is the little tool that turns data checksums on, turns them off, or checks them in a PostgreSQL database cluster. it's giving "quiet little utility that could ruin your whole week if you use it wrong," so let's go 🫶

---

🌸 SYNOPSIS 🌸

pg_checksums [option...] [[-D | --pgdata]datadir]

---

✨ DESCRIPTION ✨

so pg_checksums does three things and honestly it slays at all of them: it checks, enables, or disables data checksums in a PostgreSQL cluster. 🎀

⚠️ the server must be shut down cleanly before you run pg_checksums. no cap, this is not optional. do not be the main character who skips this step.

When you're verifying checksums, the exit status is zero if there are no checksum errors, and nonzero if at least one checksum failure is detected. When you're enabling or disabling checksums, the exit status is nonzero if the operation failed. like, the exit status tells the story okay 😌

Also important: when verifying checksums, every file in the cluster is scanned 👀. When enabling checksums, every file in the cluster is rewritten in-place. And disabling checksums? that one only updates the file pg_control — lowkey the laziest of the three, and honestly good for it 💅

---

🦋 OPTIONS 🦋

the following command-line options are available, bestie:

• -D directory, --pgdata=directory — specifies the directory where the database cluster is stored. you know, the whole vibe of the thing 🗂️
• -c, --check — checks checksums. this is the default mode if nothing else is specified, so if you just vibe in with no flags, this is what you get ✨
• -d, --disable — disables checksums. bye checksums 💀
• -e, --enable — enables checksums. hello checksums 👑
• -f filenode, --filenode=filenode — only validate checksums in the relation with filenode filenode. targeted, selective, iconic 🎯
• -N, --no-sync — by default, pg_checksums will wait for all files to be written safely to disk. this option causes pg_checksums to return without waiting, which is faster, but means that a subsequent operating system crash can leave the updated data directory corrupt. generally, this option is useful for testing but should not be used on a production installation. this option has no effect when using --check. 🚨 bestie, danger vibes only, do not do this in prod, i'm begging 😭
• -P, --progress — enable progress reporting. turning this on will deliver a progress report while checking or enabling checksums. we love a progress bar, it's giving "are we there yet" 📊
• -v, --verbose — enable verbose output. lists all checked files. every single one. all up in your terminal 🌈
• -V, --version — print the pg_checksums version and exit. quick lil flex ⭐
• -?, --help — show help about pg_checksums command line arguments, and exit. when in doubt, ask for help, that's self care 💜

---

🧚 ENVIRONMENT 🧚

• PGDATA — specifies the directory where the database cluster is stored; can be overridden using the -D option. so -D wins, sorry PGDATA 🙈
• PG_COLOR — specifies whether to use color in diagnostic messages. possible values are always, auto and never. yes you can make your error messages cute 🌸

---

🔥 NOTES 🔥

Enabling checksums in a large cluster can potentially take a long time ⏳. During this operation, the cluster or other programs that write to the data directory must not be started or else data loss may occur. like. literally. do not touch it. hands off. 🙅

When using a replication setup with tools which perform direct copies of relation file blocks (for example pg_rewind(1)), enabling or disabling checksums can lead to page corruptions in the shape of incorrect checksums if the operation is not done consistently across all nodes. 👀 When enabling or disabling checksums in a replication setup, it is thus recommended to stop all the clusters before switching them all consistently. Destroying all standbys, performing the operation on the primary and finally recreating the standbys from scratch is also safe. so like, nuke and rebuild, it's fiiiine 🧨

If pg_checksums is aborted or killed while enabling or disabling checksums, the cluster's data checksum configuration remains unchanged, and pg_checksums can be re-run to perform the same operation. okay that's actually a relief, no half-finished chaos, we respect that 💖

---

and that's the whole page bestie — go forth, check those checksums, and please read the notes twice 🎀

later, legend 🦋 — this was the pg_checksums page from the PostgreSQL 13.23 documentation, dated 2025. mwah 💅