PG_CHECKSUMS(1)

💾 pg_checksums(1) — the data checksums glow-up 💅

okay bestie, sit down, because we're talking about pg_checksums — the PostgreSQL 17.11 utility that enables, disables, or checks data checksums in a PostgreSQL database cluster. she's giving maintenance-mode main character energy and honestly? iconic. 🎀

---

✨ SYNOPSIS ✨

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

that's it. that's the whole vibe. options, then optionally the data directory. slay. 🦋

---

🌸 DESCRIPTION 🌸

so what does pg_checksums actually do? she checks, enables, or disables data checksums in a PostgreSQL cluster. periodt. 💅

but — and this is the important part, no cap — the server must be shut down cleanly before running pg_checksums. like, cleanly. don't just yank the plug and come running to her, okay? 😭

the exit status tea ☕:

• when verifying checksums: exit status is zero if there are no checksum errors, and nonzero if at least one checksum failure is detected.
• when enabling or disabling checksums: exit status is nonzero if the operation failed.

and the behind-the-scenes lore, because it's lowkey fascinating:

• verifying checksums scans every file in the cluster. all of them. she's thorough. 👑
• enabling checksums rewrites each relation file block with a changed checksum in-place.
• disabling checksums only updates the file pg_control. that's the whole thing. tiny little update, huge vibe shift. ✨

---

💖 OPTIONS 💖

the following command-line options are available, bestie — collect them all:

• -D directory, --pgdata=directory — tells her where the database cluster lives. that's the directory, okay? don't make her guess. 🙈
• -c, --check — checks checksums. this is the default mode if nothing else is specified, so if you just run her with no flags she's already doing this. default queen behavior. 👑
• -d, --disable — disables checksums. bye bye checksums. 💀
• -e, --enable — enables checksums. hello checksums, welcome to the group chat. 🫶
• -f filenode, --filenode=filenode — only validate checksums in the relation with filenode filenode. very "I'm only checking this one" of you. 🔍
• -N, --no-sync — by default, pg_checksums waits for all files to be written safely to disk. this option makes her return without waiting, which is faster, but — and this is the scary part — it means 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. also, this option has no effect when using --check. so basically: fast and risky, only for the test girlys. 😭
• -P, --progress — enable progress reporting. turning this on will deliver a progress report while checking or enabling checksums. she'll keep you posted, bestie. 🍓
• --sync-method=method — when set to fsync, which is the default, pg_checksums will recursively open and synchronize all files in the data directory. the search for files will follow symbolic links for the WAL directory and each configured tablespace. on Linux, syncfs may be used instead to ask the operating system to synchronize the whole file systems that contain the data directory, the WAL files, and each tablespace. see recovery_init_sync_method for info about the caveats to be aware of when using syncfs. this option has no effect when --no-sync is used. 🧚
• -v, --verbose — enable verbose output. lists all checked files. every single one. she's a yapper and we love her for it. 💬
• -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 literally what it's for. 🌈

---

🦋 ENVIRONMENT 🦋

• PGDATA — specifies the directory where the database cluster is stored; can be overridden using the -D option. so -D always wins the argument, sorry PGDATA. 💅
• PG_COLOR — specifies whether to use color in diagnostic messages. possible values are always, auto and never. yes she has a color setting, because aesthetics matter. 🎨

---

🎀 NOTES 🎀

okay, listen up, because these are the real ones:

• 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. not being dramatic — that's literally what it says. 😭🙈
• 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 — consistent across every node, or nuke-and-rebuild. no in-between. 💀
• 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. she's got your back, fr fr — no half-finished mess. 🫶✨

---

ngl bestie, the takeaway is: shut the server down cleanly, don't touch the data directory while she's working, and be consistent across your replicas. do that and she'll slay every single time. 👑

---

and that's the whole page, mwah 💋 — this was PG_CHECKSUMS(1), straight outta the PostgreSQL 17.11 Documentation, dated 2026. go forth and checksum responsibly, ily 🫶💖