Request a Demo
G.1. pgpro_datactl — manage Postgres Pro Enterprise data files
Prev UpAppendix G. Postgres Pro Modules and Extensions Shipped as Individual PackagesHome Next

G.1. pgpro_datactl — manage Postgres Pro Enterprise data files

G.1.1. Overview
G.1.2. Installation
G.1.3. Commands

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 and unpack 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 the repack 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_version_date that contains the 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 the pg_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, and error.

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 or zstd 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, and error.

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, and error.

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) or 0 (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_version_date that contains the 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 the pg_compression file.

--log-level=logging_level

Sets the logging level. Possible values: debug, info, warning, and error.

--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, and error.

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_version_date that contains the 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, and error.

Prev Up Next
Appendix G. Postgres Pro Modules and Extensions Shipped as Individual Packages Home G.2. pgpro_pwr — workload reports
epub pdf