G.1. pgpro_datactl — manage Postgres Pro Enterprise data files
G.1.1. Overview
The pgpro_datactl utility provides tools for managing Postgres Pro Enterprise data files, including a module for CFS (Compressed File Storage) operations. This module offers the following functionalities:
Retrieving metadata from compressed files, including their compression algorithm and location.
Unpacking CFS files for further analysis.
Repacking compressed files and changing their compression level.
Preventing potential failures caused by corrupted files.
G.1.2. Installation
pgpro_datactl is provided with Postgres Pro Enterprise as a separate pre-built package pgpro-datactl-ent-14
(for the detailed installation instructions, see Chapter 17).
G.1.3. Commands
pgpro_datactl supports the following commands:
G.1.3.1. Important Notes
Before running these commands, pay attention to the following operation specifics:
The
repack
andunpack
operations require the Postgres Pro Enterprise cluster to be stopped. This is necessary to prevent data corruption and ensure file consistency.When using the
--in-place
option with therepack
command, note that:The tablespace will be overwritten directly during the operation.
All the existing data in the target tablespace will be replaced.
G.1.3.2. unpack
pgpro_datactl unpack --source=source_path
--target=target_path
[--calg=compression_algorithm
] [--zero-on-error] [--log-level=logging_level
] [--help]
Unpacks CFS files.
-s=
source_path
--source=
source_path
Specifies the path to a compressed file or directory.
Note
The path must be in the directory named
PG_
that contains theversion
_date
pg_compression
file.-t=
target_path
--target=
target_path
Specifies the path to a directory where the unpacked files will be placed.
If the source and target directories are the same, files are unpacked with a
.dec
extension.-c=
compression_algorithm
--calg=
compression_algorithm
Specifies the compression algorithm used. If omitted, the
unpack
command will take this value from thepg_compression
file.--zero-on-error
If this option is specified, any corrupted blocks are replaced with zeros, preventing the process termination or error messages.
--log-level=
logging_level
Sets the logging level. Possible values:
debug
,info
,warning
, anderror
.
Example:
pgpro_datactl unpack -s /path/to/archive.cfs -t /path/to/destination -c zstd
In this example, unpack
extracts archive.cfs
compressed with the zstd
algorithm into the directory /path/to/destination
.
G.1.3.3. probe
pgpro_datactl probe --source=source_path
[--log-level=logging_level
] [--help]
Analyzes the specified file and identifies the following:
Compression type:
zlib
orzstd
compression algorithm.Fragmentation level: Analyzes the corresponding
*.cfm
file (if available) and reports the percentage of unused storage space in the physical file.Whether the file belongs to CFS: Checks the presence of an associated
*.cfm
file, which indicates whether the file belongs to a CFS archive.
-s=
source_path
--source=
source_path
Specifies the path to the required file.
--log-level=
logging_level
Sets the logging level. Possible values:
debug
,info
,warning
, anderror
.
Example output:
Probing path: /data/sample.dat Has cfm file: Yes pg_compression: zstd Actual compression: zstd Fragmentation: 5%
In this example, the file is compressed with the zstd
algorithm, is part of a CFS archive, and has a fragmentation level of five percent.
G.1.3.4. info
pgpro_datactl info --source=source_path
[--log-level=logging_level
] [--help]
Analyzes the file and displays the following information:
The file physical size, virtual size, and utilized file space in bytes.
Whether the garbage collector (
GC
) is active.Whether the
*.cfm
file is present and accessible.
-s=
source_path
--source=
source_path
Specifies the path to the required file.
--log-level=
logging_level
Sets the logging level. Possible values:
debug
,info
,warning
, anderror
.
Example output:
Physical size: 10485760 Virtual size: 9437184 Used size: 7864320 GC active: Yes
G.1.3.5. repack
pgpro_datactl repack --source=source_path
--t-calg=target_compression_algorithm
--target=target_path
[--calg=compression_algorithm
] [--clevel=compression_level
] [--zero-on-error] [--log-level=logging_level
] [--in-place] [--help]
Changes the compression algorithm and/or compression level of CFS files.
Returns the following information:
Compression algorithm ID
Compression level
Copy status:
1
(complete) or0
(incomplete)
If interrupted, the process can resume from the point of failure by re-executing the command with identical compression options (both --t-calg
and --calg
values), leveraging per-datafile .status
files to maintain the operation state.
-s=
source_path
--source=
source_path
Specifies the path to a compressed file or directory.
Note
The path must be in the directory named
PG_
that contains theversion
_date
pg_compression
file.--t-calg=
target_compression_algorithm
Specifies the target compression algorithm. If omitted, the files will be decompressed (unpacked).
-t=
target_path
--target=
target_path
Specifies the output location for recompressed files.
-c=
compression_algorithm
--calg=
compression_algorithm
Specifies the current compression algorithm. If omitted, the
repack
command will take this value from thepg_compression
file.--log-level=
logging_level
Sets the logging level. Possible values:
debug
,info
,warning
, anderror
.--clevel=
compression_level
Specifies the compression level for the chosen target compression algorithm. The default value is
1
.--zero-on-error
If this option is specified, any corrupted blocks are replaced with zeros, preventing the process termination or error messages.
--in-place
If this option is specified while
target_path
is omitted, the recompressed files will be placed in the source directory.Warning
Using this option will remove all the source files from the source directory, thus should be considered carefully.
G.1.3.6. ground
pgpro_datactl ground --source=source_path
--block-num=block_number
[--calg=compression_algorithm
] [--log-level=logging_level
] [--help]
Replaces the specified corrupted blocks, which may appear during decompression, with zeros.
-s=
source_path
--source=
source_path
Specifies the path to the required file.
--block-num=
block_number
Specifies the number of the block that should be replaced.
-c=
compression_algorithm
--calg=
compression_algorithm
Specifies the current compression algorithm. If the value does not match the CFS tablespace compression algorithm, the operation will complete with an error.
--log-level=
logging_level
Sets the logging level. Possible values:
debug
,info
,warning
, anderror
.
Example:
pgpro_datactl ground -s /path/to/archive.cfs --block-num 4 --calg pglz
In this example, ground
replaces the block number 4 with a zero and uses the pglz
algorithm to compress it.
G.1.3.7. stat
pgpro_datactl stat --source=source_path
--cfs [--log-level=logging_level
] [--help]
Collects tablespace statistics and outputs the results as a CSV file.
This command does not modify any files (read-only operation). No locks are acquired.
-s=
source_path
--source=
source_path
Specifies the path to a compressed file or directory.
Note
The path must be in the directory named
PG_
that contains theversion
_date
pg_compression
file.--cfs
Specifies the tablespace type.
Note
Currently only the CFS type support is implemented.
--log-level=
logging_level
Sets the logging level. Possible values:
debug
,info
,warning
, anderror
.