pgmoneta

https://pgmoneta.github.io/
Admin
pgmoneta is a backup and restore solution for PostgreSQL that supports full and incremental backups,...
Tokens:15,136
Snippets:119
Trust Score:9.7
Update:6 months ago
Show doc for...
Tokens:
Raw
### Install Documentation Dependencies

Source: https://pgmoneta.github.io/doc/DEVELOPERS.html

Installs pandoc and a basic TeX Live scheme, which are required for generating user and developer guides.

```shell
dnf install pandoc texlive-scheme-basic
```

--------------------------------

### Start PostgreSQL server

Source: https://pgmoneta.github.io/doc/DEVELOPERS.html

Start the PostgreSQL server using pg_ctl. Check the log file in /tmp/pgsql/log for any errors if the startup fails.

```shell
pg_ctl  -D /tmp/pgsql/ start
```

--------------------------------

### Install API Documentation Dependencies

Source: https://pgmoneta.github.io/doc/DEVELOPERS.html

Installs graphviz and doxygen, which are required for generating the API documentation.

```shell
dnf install graphviz doxygen
```

--------------------------------

### Build and Install pgmoneta

Source: https://pgmoneta.github.io/doc/DEVELOPERS.html

Clones the pgmoneta repository, creates a build directory, configures the build with Clang and Debug type, and then builds and installs the project.

```shell
cd /usr/local
git clone https://github.com/pgmoneta/pgmoneta.git
cd pgmoneta
mkdir build
cd build
cmake -DCMAKE_C_COMPILER=clang -DCMAKE_BUILD_TYPE=Debug ..
make
make install
```

--------------------------------

### Display pgmoneta Help Information

Source: https://pgmoneta.github.io/doc/GETTING_STARTED.html

Run this command to see available options and usage instructions for pgmoneta. Ensure pgmoneta is installed and in your system's PATH.

```bash
pgmoneta -?
```

--------------------------------

### Install Basic Dependencies

Source: https://pgmoneta.github.io/doc/DEVELOPERS.html

Installs essential development tools and libraries required for building pgmoneta, including git, compilers, build tools, and various development headers.

```shell
dnf install git gcc clang clang-analyzer clang-tools-extra cmake make libev libev-devel openssl openssl-devel systemd systemd-devel zlib zlib-devel libzstd libzstd-devel lz4 lz4-devel libssh libssh-devel python3-docutils libatomic bzip2 bzip2-devel libarchive libarchive-devel libasan libasan-static
```

--------------------------------

### Run pgmoneta with Configuration

Source: https://pgmoneta.github.io/doc/GETTING_STARTED.html

This command starts pgmoneta using the specified configuration and user files. If no errors appear, the service is running and ready for backups.

```bash
pgmoneta -c pgmoneta.conf -u pgmoneta_users.conf
```

--------------------------------

### Install PostgreSQL 17

Source: https://pgmoneta.github.io/doc/DEVELOPERS.html

Installs PostgreSQL 17, including server, contrib, and libs packages, after disabling the default module.

```shell
dnf -qy module disable postgresql
dnf install -y postgresql17 postgresql17-server postgresql17-contrib postgresql17-libs
```

--------------------------------

### Install PostgreSQL Repository (Fedora)

Source: https://pgmoneta.github.io/doc/DEVELOPERS.html

Installs the PostgreSQL YUM repository for RPM-based distributions like Fedora.

```shell
rpm -Uvh https://download.postgresql.org/pub/repos/yum/reporpms/F-42-x86_64/pgdg-redhat-repo-latest.noarch.rpm
```

--------------------------------

### Install Code Coverage Tools

Source: https://pgmoneta.github.io/doc/DEVELOPERS.html

Installs gcovr and gcc, which are required for generating code coverage reports when using GCC builds.

```shell
dnf install gcovr gcc
```

--------------------------------

### Install PostgreSQL Repository (RHEL 9.x x86_64)

Source: https://pgmoneta.github.io/doc/DEVELOPERS.html

Installs EPEL, the PostgreSQL YUM repository, and enables the CRB repository for RHEL 9.x on x86_64 architectures.

```shell
dnf install https://dl.fedoraproject.org/pub/epel/epel-release-latest-9.noarch.rpm
rpm -Uvh https://download.postgresql.org/pub/repos/yum/reporpms/EL-9-x86_64/pgdg-redhat-repo-latest.noarch.rpm
dnf config-manager --set-enabled crb
```

--------------------------------

### Install gcovr using pip

Source: https://pgmoneta.github.io/doc/DEVELOPERS.html

Installs gcovr using pip, as it may not be available as a DNF package on some distributions.

```shell
pip3 install gcovr
```

--------------------------------

### Configure Extra Files/Directories for Backup

Source: https://pgmoneta.github.io/doc/CONFIGURATION.html

Use the 'extra' parameter to specify files or directories to be copied from the server during a backup. This requires the pgmoneta_ext extension to be installed on the server.

```ini
extra = /tmp/myfile1, /tmp/myfile2, /tmp/mydir1, /tmp/mydir2
```

--------------------------------

### Install PostgreSQL Repository (RHEL 9.x aarch64)

Source: https://pgmoneta.github.io/doc/DEVELOPERS.html

Installs EPEL, the PostgreSQL YUM repository, and enables the CRB repository for RHEL 9.x on aarch64 architectures.

```shell
dnf install https://dl.fedoraproject.org/pub/epel/epel-release-latest-9.noarch.rpm
rpm -Uvh https://download.postgresql.org/pub/repos/yum/reporpms/EL-9-aarch64/pgdg-redhat-repo-latest.noarch.rpm
dnf config-manager --set-enabled crb
```

--------------------------------

### Add LaTeX Packages for PDF Generation

Source: https://pgmoneta.github.io/doc/DEVELOPERS.html

Installs necessary LaTeX packages required for generating PDF documentation, including footnote, pagecolor, and source code related packages.

```shell
dnf install 'tex(footnote.sty)' 'tex(footnotebackref.sty)' 'tex(pagecolor.sty)' 'tex(hardwrap.sty)' 'tex(mdframed.sty)' 'tex(sourcesanspro.sty)' 'tex(ly1enc.def)' 'tex(sourcecodepro.sty)' 'tex(titling.sty)' 'tex(csquotes.sty)' 'tex(zref-abspage.sty)' 'tex(needspace.sty)' 'tex(selnolig.sty)'
```

--------------------------------

### Download and Install Eisvogel LaTeX Template

Source: https://pgmoneta.github.io/doc/DEVELOPERS.html

Downloads the Eisvogel LaTeX template, extracts it, and places it in the pandoc user data directory for PDF generation.

```shell
wget https://github.com/Wandmalfarbe/pandoc-latex-template/releases/download/v3.3.0/Eisvogel-3.3.0.tar.gz
tar -xzf Eisvogel-3.3.0.tar.gz
mkdir -p $HOME/.local/share/pandoc/templates
mv Eisvogel-3.3.0/eisvogel.latex $HOME/.local/share/pandoc/templates/
```

--------------------------------

### Backup Throughput and Compression

Source: https://pgmoneta.github.io/doc/PROMETHEUS.html

Endpoints to get backup compression ratios and throughputs for various operations.

```APIDOC
## GET /pgmoneta_backup_compression_ratio

### Description
Retrieves the compression ratio for a backup.

### Method
GET

### Endpoint
/pgmoneta_backup_compression_ratio

### Query Parameters
- **name** (string) - Required - The server identifier
- **label** (string) - Required - The backup label

### Response
#### Success Response (200)
- **compression_ratio** (float) - The ratio of backup size to restore size.

### Response Example
{
  "compression_ratio": 0.5
}

## GET /pgmoneta_backup_throughput

### Description
Retrieves the backup throughput for a server (MB/s).

### Method
GET

### Endpoint
/pgmoneta_backup_throughput

### Query Parameters
- **name** (string) - Required - The server identifier
- **label** (string) - Required - The backup label

### Response
#### Success Response (200)
- **throughput_mbs** (float) - The backup throughput in MB/s.

### Response Example
{
  "throughput_mbs": 120.5
}

## GET /pgmoneta_backup_basebackup_mbs

### Description
Retrieves the basebackup throughput for a server (MB/s).

### Method
GET

### Endpoint
/pgmoneta_backup_basebackup_mbs

### Query Parameters
- **name** (string) - Required - The server identifier
- **label** (string) - Required - The backup label

### Response
#### Success Response (200)
- **basebackup_mbs** (float) - The basebackup throughput in MB/s.

### Response Example
{
  "basebackup_mbs": 150.2
}

## GET /pgmoneta_backup_manifest_mbs

### Description
Retrieves the manifest throughput for a server (MB/s).

### Method
GET

### Endpoint
/pgmoneta_backup_manifest_mbs

### Query Parameters
- **name** (string) - Required - The server identifier
- **label** (string) - Required - The backup label

### Response
#### Success Response (200)
- **manifest_mbs** (float) - The manifest throughput in MB/s.

### Response Example
{
  "manifest_mbs": 50.0
}

## GET /pgmoneta_backup_compression_zstd_mbs

### Description
Retrieves the Zstandard compression throughput for a server (MB/s).

### Method
GET

### Endpoint
/pgmoneta_backup_compression_zstd_mbs

### Query Parameters
- **name** (string) - Required - The server identifier
- **label** (string) - Required - The backup label

### Response
#### Success Response (200)
- **compression_zstd_mbs** (float) - The Zstandard compression throughput in MB/s.

### Response Example
{
  "compression_zstd_mbs": 80.7
}

## GET /pgmoneta_backup_compression_gzip_mbs

### Description
Retrieves the Gzip compression throughput for a server (MB/s).

### Method
GET

### Endpoint
/pgmoneta_backup_compression_gzip_mbs

### Query Parameters
- **name** (string) - Required - The server identifier
- **label** (string) - Required - The backup label

### Response
#### Success Response (200)
- **compression_gzip_mbs** (float) - The Gzip compression throughput in MB/s.

### Response Example
{
  "compression_gzip_mbs": 75.3
}

## GET /pgmoneta_backup_compression_bzip2_mbs

### Description
Retrieves the Bzip2 compression throughput for a server (MB/s).

### Method
GET

### Endpoint
/pgmoneta_backup_compression_bzip2_mbs

### Query Parameters
- **name** (string) - Required - The server identifier
- **label** (string) - Required - The backup label

### Response
#### Success Response (200)
- **compression_bzip2_mbs** (float) - The Bzip2 compression throughput in MB/s.

### Response Example
{
  "compression_bzip2_mbs": 60.1
}

## GET /pgmoneta_backup_compression_lz4_mbs

### Description
Retrieves the LZ4 compression throughput for a server (MB/s).

### Method
GET

### Endpoint
/pgmoneta_backup_compression_lz4_mbs

### Query Parameters
- **name** (string) - Required - The server identifier
- **label** (string) - Required - The backup label

### Response
#### Success Response (200)
- **compression_lz4_mbs** (float) - The LZ4 compression throughput in MB/s.

### Response Example
{
  "compression_lz4_mbs": 95.8
}

## GET /pgmoneta_backup_encryption_mbs

### Description
Retrieves the encryption throughput for a server (MB/s).

### Method
GET

### Endpoint
/pgmoneta_backup_encryption_mbs

### Query Parameters
- **name** (string) - Required - The server identifier
- **label** (string) - Required - The backup label

### Response
#### Success Response (200)
- **encryption_mbs** (float) - The encryption throughput in MB/s.

### Response Example
{
  "encryption_mbs": 110.4
}

## GET /pgmoneta_backup_linking_mbs

### Description
Retrieves the linking throughput for a server (MB/s).

### Method
GET

### Endpoint
/pgmoneta_backup_linking_mbs

### Query Parameters
- **name** (string) - Required - The server identifier
- **label** (string) - Required - The backup label

### Response
#### Success Response (200)
- **linking_mbs** (float) - The linking throughput in MB/s.

### Response Example
{
  "linking_mbs": 130.0
}

## GET /pgmoneta_backup_remote_ssh_mbs

### Description
Retrieves the remote SSH throughput for a server (MB/s).

### Method
GET

### Endpoint
/pgmoneta_backup_remote_ssh_mbs

### Query Parameters
- **name** (string) - Required - The server identifier
- **label** (string) - Required - The backup label

### Response
#### Success Response (200)
- **remote_ssh_mbs** (float) - The remote SSH throughput in MB/s.

### Response Example
{
  "remote_ssh_mbs": 140.5
}

## GET /pgmoneta_backup_remote_s3_mbs

### Description
Retrieves the remote S3 throughput for a server (MB/s).

### Method
GET

### Endpoint
/pgmoneta_backup_remote_s3_mbs

### Query Parameters
- **name** (string) - Required - The server identifier
- **label** (string) - Required - The backup label

### Response
#### Success Response (200)
- **remote_s3_mbs** (float) - The remote S3 throughput in MB/s.

### Response Example
{
  "remote_s3_mbs": 160.7
}

## GET /pgmoneta_backup_remote_azure_mbs

### Description
Retrieves the remote Azure throughput for a server (MB/s).

### Method
GET

### Endpoint
/pgmoneta_backup_remote_azure_mbs

### Query Parameters
- **name** (string) - Required - The server identifier
- **label** (string) - Required - The backup label

### Response
#### Success Response (200)
- **remote_azure_mbs** (float) - The remote Azure throughput in MB/s.

### Response Example
{
  "remote_azure_mbs": 155.2
}
```

--------------------------------

### Create database user and database

Source: https://pgmoneta.github.io/doc/DEVELOPERS.html

Create a new user 'myuser' with a password and a database 'mydb' owned by 'myuser'. Ensure the PostgreSQL bin path is set.

```shell
export PATH=/usr/pgsql-17/bin:$PATH
createuser -P myuser
createdb -E UTF8 -O myuser mydb
```

--------------------------------

### Create pgmoneta Configuration File

Source: https://pgmoneta.github.io/doc/DEVELOPERS.html

Sets up the main pgmoneta configuration file. This includes network settings, backup directory, compression, retention, logging, and primary PostgreSQL instance details.

```bash
cat > pgmoneta.conf
[pgmoneta]
host = *
metrics = 5001

base_dir = /home/pgmoneta/backup

compression = zstd

retention = 7

log_type = file
log_level = info
log_path = /tmp/pgmoneta.log

unix_socket_dir = /tmp/

[primary]
host = localhost
port = 5432
user = repl
wal_slot = repl

```

--------------------------------

### Display pgmoneta-admin help

Source: https://pgmoneta.github.io/doc/GETTING_STARTED.html

View the available commands and options for the administration utility.

```bash
pgmoneta-admin -?
```

--------------------------------

### Perform a Backup with Pgmoneta CLI

Source: https://pgmoneta.github.io/doc/GETTING_STARTED.html

Initiates a backup operation for the 'primary' server using the specified configuration file. Ensure the configuration file path is correct.

```bash
pgmoneta-cli -c pgmoneta.conf backup primary
```

--------------------------------

### Create pgmoneta backup directory

Source: https://pgmoneta.github.io/doc/DEVELOPERS.html

Create a 'backup' directory for pgmoneta to store backups.

```shell
mkdir backup
```

--------------------------------

### Pgmoneta CLI Help Output

Source: https://pgmoneta.github.io/doc/GETTING_STARTED.html

Displays all available commands and options for the pgmoneta-cli utility. Use this to understand the full range of administrative tasks supported.

```text
pgmoneta-cli 0.20.0
  Command line utility for pgmoneta

Usage:
  pgmoneta-cli [ -c CONFIG_FILE ] [ COMMAND ]

Options:
  -c, --config CONFIG_FILE                        Set the path to the pgmoneta.conf file
  -h, --host HOST                                 Set the host name
  -p, --port PORT                                 Set the port number
  -U, --user USERNAME                             Set the user name
  -P, --password PASSWORD                         Set the password
  -L, --logfile FILE                              Set the log file
  -v, --verbose                                   Output text string of result
  -V, --version                                   Display version information
  -F, --format text|json|raw                      Set the output format
  -C, --compress none|gz|zstd|lz4|bz2             Compress the wire protocol
  -E, --encrypt none|aes|aes256|aes192|aes128     Encrypt the wire protocol
  -s, --sort asc|desc                             Sort result (for list-backup)
      --cascade                                   Cascade a retain/expunge backup
  -?, --help                                      Display help

Commands:
  annotate                 Annotate a backup with comments
  archive                  Archive a backup from a server
  backup                   Backup a server
  clear <what>             Clear data, with:
                           - 'prometheus' to reset the Prometheus statistics
  compress                 Compress a file using configured method
  conf <action>            Manage the configuration, with one of subcommands:
                           - 'get' to obtain information about a runtime configuration value
                             conf get <parameter_name>
                           - 'ls' to print the configurations used
                           - 'reload' to reload the configuration
                           - 'set' to modify a configuration value;
                             conf set <parameter_name> <parameter_value>;
  decompress               Decompress a file using configured method
  decrypt                  Decrypt a file using master-key
  delete                   Delete a backup from a server
  encrypt                  Encrypt a file using master-key
  expunge                  Expunge a backup from a server
  info                     Information about a backup
  list-backup              List the backups for a server
  mode                     Switch the mode for a server
  ping                     Check if pgmoneta is alive
  restore                  Restore a backup from a server
  retain                   Retain a backup from a server
  shutdown                 Shutdown pgmoneta
  status [details]         Status of pgmoneta, with optional details
  verify                   Verify a backup from a server

```

--------------------------------

### Specify Configuration Directory with Flag and Environment Variable

Source: https://pgmoneta.github.io/doc/CONFIGURATION.html

Demonstrates setting a custom configuration directory using both the -D flag and the PGMONETA_CONFIG_DIR environment variable. The -D flag takes precedence.

```bash
pgmoneta -D /custom/config/dir -d
```

```bash
export PGMONETA_CONFIG_DIR=/custom/config/dir
pgmoneta -d
```

--------------------------------

### Create replication role

Source: https://pgmoneta.github.io/doc/DEVELOPERS.html

Connect to the PostgreSQL instance and create a 'repl' role with replication privileges and a password.

```sql
psql postgres
CREATE ROLE repl WITH LOGIN REPLICATION PASSWORD 'secretpassword';
\q
```

--------------------------------

### Create pgmoneta OS user

Source: https://pgmoneta.github.io/doc/DEVELOPERS.html

Create a new operating system user named 'pgmoneta' and set its password.

```shell
sudo su -
useradd -ms /bin/bash pgmoneta
passwd pgmoneta
exit
```

--------------------------------

### Initialize PostgreSQL cluster

Source: https://pgmoneta.github.io/doc/DEVELOPERS.html

Initialize a new PostgreSQL cluster in the /tmp/pgsql directory. Ensure the PostgreSQL binary path is set correctly.

```shell
export PATH=/usr/bin:$PATH
initdb -k /tmp/pgsql
```

--------------------------------

### Basic pgmoneta Configuration

Source: https://pgmoneta.github.io/doc/GETTING_STARTED.html

This configuration file sets up pgmoneta to listen on all network interfaces, enable Prometheus metrics, specify backup storage, compression, retention, and logging. It also defines connection details for a primary PostgreSQL instance.

```ini
[pgmoneta]
host = *
metrics = 5001

base_dir = /home/pgmoneta

compression = zstd

storage_engine = local

retention = 7

log_type = file
log_level = info
log_path = /tmp/pgmoneta.log

unix_socket_dir = /tmp/

[primary]
host = localhost
port = 5432
user = repl
wal_slot = repl
```

--------------------------------

### Configure Dynamic Linker Paths

Source: https://pgmoneta.github.io/doc/DEVELOPERS.html

Adds /usr/local/lib and /usr/local/lib64 to the dynamic linker configuration to resolve shared library loading errors, followed by running ldconfig.

```shell
/usr/local/lib
/usr/local/lib64
ldconfig
```

--------------------------------

### Pgmoneta CLI TLS Connection

Source: https://pgmoneta.github.io/doc/GETTING_STARTED.html

Illustrates how to connect to pgmoneta using TLS when both TLS and management are enabled. Requires specific key and certificate files with appropriate permissions.

```text
pgmoneta-cli -c ~/.pgmoneta/pgmoneta.conf --host <host> --port <port> --user <user> --password <password> --encrypt aes --cert ~/.pgmoneta/pgmoneta.crt --key ~/.pgmoneta/pgmoneta.key --rootcert ~/.pgmoneta/root.crt <command>
```

--------------------------------

### Configure PostgreSQL pg_hba.conf for Replication

Source: https://pgmoneta.github.io/doc/GETTING_STARTED.html

These lines in pg_hba.conf allow the 'repl' user to connect to the 'postgres' and 'replication' databases from localhost and ::1 using SCRAM-SHA-256 authentication.

```conf
local   postgres        repl                                   scram-sha-256
host    postgres        repl           127.0.0.1/32            scram-sha-256
host    postgres        repl           ::1/128                 scram-sha-256
host    replication     repl           127.0.0.1/32            scram-sha-256
host    replication     repl           ::1/128                 scram-sha-256
```

--------------------------------

### Restore a Backup with Pgmoneta CLI

Source: https://pgmoneta.github.io/doc/GETTING_STARTED.html

Restores a backup for the 'primary' server from a specific timestamp to a target directory. Requires the configuration file, server name, timestamp, and restore path.

```bash
pgmoneta-cli -c pgmoneta.conf restore primary <timestamp> /path/to/restore
```

--------------------------------

### Create replication slot

Source: https://pgmoneta.github.io/doc/DEVELOPERS.html

Create a physical replication slot named 'repl'. Alternatively, configure automatic slot creation in pgmoneta.

```sql
psql postgres
SELECT pg_create_physical_replication_slot('repl', true, false);
\q
```

--------------------------------

### pgmoneta-cli Command Reference

Source: https://pgmoneta.github.io/doc/GETTING_STARTED.html

Overview of the pgmoneta-cli command-line interface, including global options and available administrative commands.

```APIDOC
## pgmoneta-cli Commands

### Description
The pgmoneta-cli tool is used to perform administrative tasks on a pgmoneta server. It supports various commands for backup management, configuration updates, and system monitoring.

### Usage
`pgmoneta-cli [ -c CONFIG_FILE ] [ COMMAND ]`

### Options
- **-c, --config** (string) - Path to the pgmoneta.conf file
- **-h, --host** (string) - Host name
- **-p, --port** (integer) - Port number
- **-U, --user** (string) - User name
- **-P, --password** (string) - Password
- **-F, --format** (text|json|raw) - Set the output format
- **-v, --verbose** (flag) - Output text string of result

### Available Commands
- **backup** - Backup a server
- **restore** - Restore a backup from a server
- **shutdown** - Shutdown pgmoneta
- **status** - Status of pgmoneta
- **conf get/ls/reload/set** - Manage runtime configuration
- **list-backup** - List the backups for a server
- **ping** - Check if pgmoneta is alive
```

--------------------------------

### Create Physical Replication Slot

Source: https://pgmoneta.github.io/doc/GETTING_STARTED.html

This SQL command creates a physical replication slot named 'repl'. The 'true' argument enables streaming, and 'false' indicates that the slot should not be dropped if it becomes unused.

```sql
SELECT pg_create_physical_replication_slot('repl', true, false);
```

--------------------------------

### Switch to pgmoneta user

Source: https://pgmoneta.github.io/doc/DEVELOPERS.html

Switch to the 'pgmoneta' user to perform operations related to pgmoneta.

```shell
sudo su -
su - pgmoneta
```

--------------------------------

### Verify standard user access

Source: https://pgmoneta.github.io/doc/DEVELOPERS.html

Test the connection for the 'myuser' to the 'mydb' database using the password 'mypass'.

```shell
psql -h localhost -p 5432 -U myuser mydb
\q
```

--------------------------------

### Add pgmoneta Master Key

Source: https://pgmoneta.github.io/doc/GETTING_STARTED.html

This command initializes the master key for pgmoneta's user vault. It is a prerequisite for adding user credentials.

```bash
pgmoneta-admin master-key
```

--------------------------------

### Create postgres OS user

Source: https://pgmoneta.github.io/doc/DEVELOPERS.html

If the 'postgres' user does not exist, use these commands to create it and set its password.

```shell
useradd -ms /bin/bash postgres
passwd postgres
```

--------------------------------

### Create PostgreSQL Replication Role

Source: https://pgmoneta.github.io/doc/GETTING_STARTED.html

This SQL command creates a PostgreSQL role named 'repl' with replication privileges and a password. Ensure the password matches the one configured in pgmoneta.

```sql
CREATE ROLE repl WITH LOGIN REPLICATION PASSWORD 'secretpassword';
```

--------------------------------

### Set the master key

Source: https://pgmoneta.github.io/doc/GETTING_STARTED.html

Generate and set the master key for all users.

```bash
pgmoneta-admin -g master-key
```

--------------------------------

### Switch to postgres user

Source: https://pgmoneta.github.io/doc/DEVELOPERS.html

Open a new terminal and switch to the 'postgres' user to perform subsequent operations within its environment.

```shell
sudo su -
su - postgres
```

--------------------------------

### Add custom pg_hba.conf entries

Source: https://pgmoneta.github.io/doc/DEVELOPERS.html

Add these new entries to pg_hba.conf to configure access for specific users and databases using SCRAM-SHA-256 authentication.

```ini
host    mydb             myuser          127.0.0.1/32            scram-sha-256
host    mydb             myuser          ::1/128                 scram-sha-256
host    postgres         repl            127.0.0.1/32            scram-sha-256
host    postgres         repl            ::1/128                 scram-sha-256
host    replication      repl            127.0.0.1/32            scram-sha-256
host    replication      repl            ::1/128                 scram-sha-256
```

--------------------------------

### Add pgmoneta Replication User

Source: https://pgmoneta.github.io/doc/DEVELOPERS.html

Adds a user for replication with a specified password. This grants pgmoneta access to the database.

```bash
pgmoneta-admin -f pgmoneta_users.conf -U repl -P secretpassword user add
```

--------------------------------

### Verify replication user access

Source: https://pgmoneta.github.io/doc/DEVELOPERS.html

Test the connection for the 'repl' user to the 'postgres' database using the password 'secretpassword'.

```shell
psql -h localhost -p 5432 -U repl postgres
\q
```

--------------------------------

### Check PostgreSQL server status

Source: https://pgmoneta.github.io/doc/DEVELOPERS.html

Use pg_isready to check if the PostgreSQL server is running and accepting connections.

```shell
pg_isready
```

--------------------------------

### Set summarize_wal in postgresql.conf

Source: https://pgmoneta.github.io/doc/DEVELOPERS.html

For PostgreSQL version 17 and above, set summarize_wal to 'on' to enable 'Online: true' in pgmoneta server status.

```shell
summarize_wal = on
```

--------------------------------

### Clone pgmoneta Repository

Source: https://pgmoneta.github.io/doc/DEVELOPERS.html

Clones the pgmoneta repository from GitHub to your local machine.

```git
git clone git@github.com:<username>/pgmoneta.git
```

--------------------------------

### Shutdown Pgmoneta with CLI

Source: https://pgmoneta.github.io/doc/GETTING_STARTED.html

Gracefully shuts down the pgmoneta service using the specified configuration file. This command should be used with caution.

```bash
pgmoneta-cli -c pgmoneta.conf shutdown
```

--------------------------------

### View pgmoneta Backup Status

Source: https://pgmoneta.github.io/doc/DEVELOPERS.html

Displays the status and details of pgmoneta backups.

```bash
pgmoneta-cli -c pgmoneta.conf status details
```

--------------------------------

### Default pg_hba.conf entries

Source: https://pgmoneta.github.io/doc/DEVELOPERS.html

These are the default entries in the pg_hba.conf file that should be removed.

```ini
host    all             all             127.0.0.1/32            trust
host    all             all             ::1/128                 trust
host    replication     all             127.0.0.1/32            trust
host    replication     all             ::1/128                 trust
```

--------------------------------

### Backup and Restore Size Information

Source: https://pgmoneta.github.io/doc/PROMETHEUS.html

Endpoints to retrieve the size of backups and restores for a given server.

```APIDOC
## GET /pgmoneta_restore_size

### Description
Retrieves the size of a restore for a specified server.

### Method
GET

### Endpoint
/pgmoneta_restore_size

### Query Parameters
- **name** (string) - Required - The server identifier
- **label** (string) - Required - The backup label

### Response
#### Success Response (200)
- **size** (integer) - The size of the restore in bytes.

### Response Example
{
  "size": 1073741824
}

## GET /pgmoneta_restore_size_increment

### Description
Retrieves the size increment of a restore for a specified server.

### Method
GET

### Endpoint
/pgmoneta_restore_size_increment

### Query Parameters
- **name** (string) - Required - The server identifier
- **label** (string) - Required - The backup label

### Response
#### Success Response (200)
- **size_increment** (integer) - The size increment of the restore in bytes.

### Response Example
{
  "size_increment": 536870912
}

## GET /pgmoneta_backup_size

### Description
Retrieves the size of a backup for a specified server.

### Method
GET

### Endpoint
/pgmoneta_backup_size

### Query Parameters
- **name** (string) - Required - The server identifier
- **label** (string) - Required - The backup label

### Response
#### Success Response (200)
- **size** (integer) - The size of the backup in bytes.

### Response Example
{
  "size": 2147483648
}

## GET /pgmoneta_backup_total_size

### Description
Retrieves the total size of all backups for a specified server.

### Method
GET

### Endpoint
/pgmoneta_backup_total_size

### Query Parameters
- **name** (string) - Required - The server identifier

### Response
#### Success Response (200)
- **total_size** (integer) - The total size of backups in bytes.

### Response Example
{
  "total_size": 10737418240
}
```

--------------------------------

### Set wal_level in postgresql.conf

Source: https://pgmoneta.github.io/doc/DEVELOPERS.html

Set the wal_level parameter in postgresql.conf to 'replica'. This is necessary for replication functionalities.

```shell
wal_level = replica
```

--------------------------------

### Prometheus Metrics Overview

Source: https://pgmoneta.github.io/doc/PROMETHEUS.html

This section lists the available Prometheus metrics for pgmoneta.

```APIDOC
## Prometheus Metrics 

This page documents the various Prometheus metrics exposed by pgmoneta.

### pgmoneta_state 

The state of pgmoneta

### pgmoneta_version 

The version of pgmoneta

#### Attributes
- **version** (string) - The version of pgmoneta

### pgmoneta_logging_info 

The number of INFO logging statements

### pgmoneta_logging_warn 

The number of WARN logging statements

### pgmoneta_logging_error 

The number of ERROR logging statements

### pgmoneta_logging_fatal 

The number of FATAL logging statements

### pgmoneta_retention_days 

The retention days of pgmoneta

### pgmoneta_retention_weeks 

The retention weeks of pgmoneta

### pgmoneta_retention_months 

The retention months of pgmoneta

### pgmoneta_retention_years 

The retention years of pgmoneta

### pgmoneta_retention_server 

The retention of a server

#### Attributes
- **name** (string) - The server identifier
- **parameter** (string) - The day, week, month or year

### pgmoneta_compression 

The compression used

### pgmoneta_used_space 

The disk space used for pgmoneta

### pgmoneta_free_space 

The free disk space for pgmoneta

### pgmoneta_total_space 

The total disk space for pgmoneta

### pgmoneta_wal_shipping 

The disk space used for WAL shipping for a server

#### Attributes
- **name** (string) - The server identifier

### pgmoneta_wal_shipping_used_space 

The disk space used for WAL shipping of a server

#### Attributes
- **name** (string) - The server identifier

### pgmoneta_wal_shipping_free_space 

The free disk space for WAL shipping of a server

#### Attributes
- **name** (string) - The server identifier

### pgmoneta_wal_shipping_total_space 

The total disk space for WAL shipping of a server

#### Attributes
- **name** (string) - The server identifier

### pgmoneta_workspace 

The disk space used for workspace for a server

#### Attributes
- **name** (string) - The server identifier

### pgmoneta_workspace_free_space 

The free disk space for workspace of a server

#### Attributes
- **name** (string) - The server identifier

### pgmoneta_workspace_total_space 

The total disk space for workspace of a server

#### Attributes
- **name** (string) - The server identifier

### pgmoneta_hot_standby 

The disk space used for hot standby for a server

#### Attributes
- **name** (string) - The server identifier

### pgmoneta_hot_standby_free_space 

The free disk space for hot standby of a server

#### Attributes
- **name** (string) - The server identifier

### pgmoneta_hot_standby_total_space 

The total disk space for hot standby of a server

#### Attributes
- **name** (string) - The server identifier

### pgmoneta_server_timeline 

The current timeline a server is on

#### Attributes
- **name** (string) - The server identifier

### pgmoneta_server_parent_tli 

The parent timeline of a timeline on a server

#### Attributes
- **name** (string) - The server identifier
- **tli** (string) - 

### pgmoneta_server_timeline_switchpos 

The WAL switch position of a timeline on a server (showed in hex as a parameter)

#### Attributes
- **name** (string) - The server identifier
- **tli** (string) - 
- **walpos** (string) - 

### pgmoneta_server_workers 

The numbeer of workers for a server

#### Attributes
- **name** (string) - The server identifier

### pgmoneta_server_online 

Is the server in an online state

#### Attributes
- **name** (string) - The server identifier

### pgmoneta_server_primary 

Is the server a primary ?

#### Attributes
- **name** (string) - The server identifier

### pgmoneta_server_valid 

Is the server in a valid state

#### Attributes
- **name** (string) - The server identifier

### pgmoneta_wal_streaming 

The WAL streaming status of a server

#### Attributes
- **name** (string) - The server identifier

### pgmoneta_server_operation_count 

The count of client operations of a server

#### Attributes
- **name** (string) - The server identifier

### pgmoneta_server_failed_operation_count 

The count of failed client operations of a server

#### Attributes
- **name** (string) - The server identifier

### pgmoneta_server_last_operation_time 

The time of the latest client operation of a server

#### Attributes
- **name** (string) - The server identifier

### pgmoneta_server_last_failed_operation_time 

The time of the latest failed client operation of a server

#### Attributes
- **name** (string) - The server identifier

### pgmoneta_server_checksums 

Are checksums enabled

#### Attributes
- **name** (string) - The server identifier

### pgmoneta_server_summarize_wal 

Is summarize_wal enabled

#### Attributes
- **name** (string) - The server identifier

### pgmoneta_server_extensions_detected 

The number of extensions detected on server

#### Attributes
- **name** (string) - The server identifier

```

--------------------------------

### Check for postgres OS user

Source: https://pgmoneta.github.io/doc/DEVELOPERS.html

Use this command to verify if an operating system user named 'postgres' already exists.

```shell
getent passwd | grep postgres
```

--------------------------------

### Add pgmoneta User

Source: https://pgmoneta.github.io/doc/GETTING_STARTED.html

This command adds a user to the pgmoneta user vault, using the specified configuration file. Ensure pgmoneta_users.conf exists and is accessible.

```bash
pgmoneta-admin -f pgmoneta_users.conf user add
```

--------------------------------

### Backup Management and Retention

Source: https://pgmoneta.github.io/doc/PROMETHEUS.html

Endpoints for managing backup retention and checking active backup processes.

```APIDOC
## POST /pgmoneta_backup_retain

### Description
Retains a backup for a specified server.

### Method
POST

### Endpoint
/pgmoneta_backup_retain

### Query Parameters
- **name** (string) - Required - The server identifier
- **label** (string) - Required - The backup label

### Response
#### Success Response (200)
- **message** (string) - Confirmation message indicating the backup has been retained.

### Response Example
{
  "message": "Backup retained successfully."
}

## GET /pgmoneta_active_backup

### Description
Checks if there is an active backup process for a server.

### Method
GET

### Endpoint
/pgmoneta_active_backup

### Query Parameters
- **name** (string) - Required - The server identifier

### Response
#### Success Response (200)
- **active** (boolean) - True if an active backup is running, false otherwise.

### Response Example
{
  "active": true
}

## GET /pgmoneta_active_restore

### Description
Checks if there is an active restore process for a server.

### Method
GET

### Endpoint
/pgmoneta_active_restore

### Query Parameters
- **name** (string) - Required - The server identifier

### Response
#### Success Response (200)
- **active** (boolean) - True if an active restore is running, false otherwise.

### Response Example
{
  "active": false
}

## GET /pgmoneta_active_archive

### Description
Checks if there is an active archiving process for a server.

### Method
GET

### Endpoint
/pgmoneta_active_archive

### Query Parameters
- **name** (string) - Required - The server identifier

### Response
#### Success Response (200)
- **active** (boolean) - True if an active archive is running, false otherwise.

### Response Example
{
  "active": true
}

## GET /pgmoneta_active_delete

### Description
Checks if there is an active delete process for a server.

### Method
GET

### Endpoint
/pgmoneta_active_delete

### Query Parameters
- **name** (string) - Required - The server identifier

### Response
#### Success Response (200)
- **active** (boolean) - True if an active delete is running, false otherwise.

### Response Example
{
  "active": false
}

## GET /pgmoneta_active_retention

### Description
Checks if there is an active retention process for a server.

### Method
GET

### Endpoint
/pgmoneta_active_retention

### Query Parameters
- **name** (string) - Required - The server identifier

### Response
#### Success Response (200)
- **active** (boolean) - True if an active retention is running, false otherwise.

### Response Example
{
  "active": true
}
```

--------------------------------

### Set Configuration Directory Environment Variable

Source: https://pgmoneta.github.io/doc/CONFIGURATION.html

Export the PGMONETA_CONFIG_DIR environment variable to specify a custom directory for all pgmoneta configuration files. This is an alternative to using the -D flag.

```bash
export PGMONETA_CONFIG_DIR=/path/to/config_dir
pgmoneta -d
```

--------------------------------

### Set password_encryption in postgresql.conf

Source: https://pgmoneta.github.io/doc/DEVELOPERS.html

Configure the password_encryption setting in postgresql.conf to 'scram-sha-256'. This is crucial for matching the authentication method in pg_hba.conf.

```shell
password_encryption = scram-sha-256
```

--------------------------------

### WAL and Server Status

Source: https://pgmoneta.github.io/doc/PROMETHEUS.html

Endpoints for retrieving WAL file information and overall server status.

```APIDOC
## GET /pgmoneta_wal_total_size

### Description
Retrieves the total size of WAL files for a server.

### Method
GET

### Endpoint
/pgmoneta_wal_total_size

### Query Parameters
- **name** (string) - Required - The server identifier

### Response
#### Success Response (200)
- **total_wal_size** (integer) - The total size of WAL files in bytes.

### Response Example
{
  "total_wal_size": 5368709120
}

## GET /pgmoneta_total_size

### Description
Retrieves the total size occupied by Pgmoneta for a server.

### Method
GET

### Endpoint
/pgmoneta_total_size

### Query Parameters
- **name** (string) - Required - The server identifier

### Response
#### Success Response (200)
- **total_size** (integer) - The total size in bytes.

### Response Example
{
  "total_size": 107374182400
}

## GET /pgmoneta_current_wal_file

### Description
Retrieves the current streaming WAL filename for a server.

### Method
GET

### Endpoint
/pgmoneta_current_wal_file

### Query Parameters
- **name** (string) - Required - The server identifier

### Response
#### Success Response (200)
- **current_wal_file** (string) - The name of the current WAL file.

### Response Example
{
  "current_wal_file": "000000010000000000000001"
}

## GET /pgmoneta_current_wal_lsn

### Description
Retrieves the current WAL log sequence number (LSN) for a server.

### Method
GET

### Endpoint
/pgmoneta_current_wal_lsn

### Query Parameters
- **name** (string) - Required - The server identifier

### Response
#### Success Response (200)
- **current_wal_lsn** (string) - The current WAL LSN.

### Response Example
{
  "current_wal_lsn": "0/16777218"
}
```

--------------------------------

### Enable Verbose Output

Source: https://pgmoneta.github.io/doc/GETTING_STARTED.html

Re-runs a command with the '-v' flag to enable verbose output, providing more detailed information about the operation's outcome.

```bash
pgmoneta-cli -v <command>
```

--------------------------------

### Create a New Work Branch

Source: https://pgmoneta.github.io/doc/DEVELOPERS.html

Creates a new branch for development work, based on the main branch.

```git
git checkout -b mywork main
```

--------------------------------

### Add Upstream Remote for pgmoneta

Source: https://pgmoneta.github.io/doc/DEVELOPERS.html

Adds the official pgmoneta repository as an upstream remote for fetching updates.

```git
cd pgmoneta
git remote add upstream https://github.com/pgmoneta/pgmoneta.git
```

--------------------------------

### Squash Multiple Commits

Source: https://pgmoneta.github.io/doc/DEVELOPERS.html

Reorganizes multiple commits into a single commit for a cleaner history. Use 'p' for the first commit and 's' for subsequent commits to squash.

```git
git rebase -i HEAD~2
```

--------------------------------

### Rebase Branch onto Upstream Main

Source: https://pgmoneta.github.io/doc/DEVELOPERS.html

Fetches the latest changes from the upstream repository and rebases your current branch onto the main branch.

```git
git fetch upstream
git rebase -i upstream/main
```

--------------------------------

### Force Push Git Branch

Source: https://pgmoneta.github.io/doc/DEVELOPERS.html

Use this command to overwrite the remote branch with your local changes. Be cautious as this can discard history on the remote.

```sh
git push -f origin mywork
```

--------------------------------

### Undo Git Reset Hard

Source: https://pgmoneta.github.io/doc/DEVELOPERS.html

If you accidentally reset to an incorrect commit, use 'git reflog' to find the previous HEAD position and then 'git reset --hard' to revert.

```sh
git reset <commit hash> --hard
```

```sh
git reflog
```

```sh
git reset --hard
```

--------------------------------

### Check Operation Exit Code

Source: https://pgmoneta.github.io/doc/GETTING_STARTED.html

Verifies the success or failure of the last executed command by checking the shell's exit code. An exit code of 0 typically indicates success.

```bash
echo $?
```
Tokens:
Raw