The only one configurable option is `ptrack.map_size` (in MB). Default is `-1`, which means `ptrack` is turned off. In order to reduce number of false positives it is recommended to set `ptrack.map_size` to `1 / 1000` of expected `LTDATA` size (i.e. `1000` for a 1 TB database).
To disable `ptrack` and clean up all remaining service files set `ptrack.map_size` to `0`.
ptrack_version() — returns ptrack version string.
ptrack_init_lsn() — returns LSN of the last ptrack map initialization.
ptrack_get_pagemapset(start_lsn pg_lsn) — returns a set of changed data files with a number of changed blocks and their bitmaps since specified `start_lsn`.
ptrack_get_change_stat(start_lsn pg_lsn) — returns statistic of changes (number of files, pages and size in MB) since specified `start_lsn`.
Usage example:
postgres=# SELECT ptrack_version();
ptrack_version
----------------
2.2
(1 row)
postgres=# SELECT ptrack_init_lsn();
ptrack_init_lsn
-----------------
0/1814408
(1 row)
postgres=# SELECT * FROM ptrack_get_pagemapset('0/185C8C0');
path | pagecount | pagemap
---------------------+-----------+----------------------------------------
base/16384/1255 | 3 | \x001000000005000000000000
base/16384/2674 | 3 | \x0000000900010000000000000000
base/16384/2691 | 1 | \x00004000000000000000000000
base/16384/2608 | 1 | \x000000000000000400000000000000000000
base/16384/2690 | 1 | \x000400000000000000000000
(5 rows)
postgres=# SELECT * FROM ptrack_get_change_stat('0/285C8C8');
files | pages | size, MB
-------+-------+------------------------
20 | 25 | 0.19531250000000000000
(1 row)
You can only use `ptrack` safely with `wal_level >= 'replica'`. Otherwise, you can lose tracking of some changes if crash-recovery occurs, since certain commands are designed not to write WAL at all if wal_level is minimal, but we only durably flush `ptrack` map at checkpoint time.
Currently, you cannot resize `ptrack` map in runtime, only on postmaster start. Also, you will loose all tracked changes, so it is recommended to do so in the maintainance window and accompany this operation with full backup.
You will need up to `ptrack.map_size * 3` of additional disk space, since `ptrack` uses two additional temporary files for durability purpose.
We use a single shared hash table in `ptrack`, which is mapped in memory from the file on disk using `mmap`. Due to the fixed size of the map there may be false positives (when some block is marked as changed without being actually modified), but not false negative results. However, these false postives may be completely eliminated by setting a high enough `ptrack.map_size`.
All reads/writes are made using atomic operations on `uint64` entries, so the map is completely lockless during the normal PostgreSQL operation. Because we do not use locks for read/write access and cannot control `mmap` eviction back to disk, `ptrack` keeps a map (`ptrack.map`) since the last checkpoint intact and uses up to 2 additional temporary files:
working copy `ptrack.map.mmap` for doing `mmap` on it;
temporary file `ptrack.map.tmp` to durably replace `ptrack.map` during checkpoint.
Map is written on disk at the end of checkpoint atomically block by block involving the CRC32 checksum calculation that is checked on the next whole map re-read after crash-recovery or restart.
To gather the whole changeset of modified blocks in `ptrack_get_pagemapset()` we walk the entire `LTDATA` (`base/**/*`, `global/*`, `lt_tblspc/**/*`) and verify using map whether each block of each relation was modified since the specified LSN or not.