### Snappy Compression Example

Source: https://github.com/enterprisedb/barman/blob/master/docs/user_guide/commands/barman_cloud/backup.inc.rst

Compresses the backup using snappy during upload to the cloud. Requires the optional 'python-snappy' library to be installed.

```text
barman-cloud-backup --snappy s3://my-bucket/my-path/ my-server
```

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

### Barman Configuration File Example

Source: https://github.com/enterprisedb/barman/blob/master/docs/contributor_guide/writing_docs.md

Shows an example of a Barman configuration file. Use this for demonstrating configuration settings.

```ini
[barman]
; System user
barman_user = barman

; Directory of configuration files. Place your sections in separate files with
; .conf extension
; For example place the 'main' server section in /etc/barman.d/main.conf
configuration_files_directory = /etc/barman.d
```

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

### Install Barman Command

Source: https://github.com/enterprisedb/barman/blob/master/docs/contributor_guide/writing_docs.md

Demonstrates the command to install Barman. This is typically run as a root user.

```bash
dnf install barman
```

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

### SQL Command Example

Source: https://github.com/enterprisedb/barman/blob/master/docs/contributor_guide/writing_docs.md

Example of creating a user using SQL. This is used in reference and general task-based documentation.

```sql
CREATE USER my_user;
```

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

### SQL Query Example

Source: https://github.com/enterprisedb/barman/blob/master/docs/contributor_guide/writing_docs.md

Provides an example of an SQL query to be executed. Use this for demonstrating database interactions.

```sql
SELECT *
FROM pg_stat_activity;
```

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

### Barman Server Configuration Example

Source: https://github.com/enterprisedb/barman/blob/master/docs/user_guide/pre_requisites.md

Example of how to configure the connection information for a PostgreSQL server in Barman's configuration file.

```ini
[my-server]
; ...
conninfo = host=pghost user=barman dbname=postgres application_name=myapp
```

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

### Full Local-to-Cloud Example with AWS S3

Source: https://github.com/enterprisedb/barman/blob/master/docs/user_guide/backup.md

A comprehensive configuration for local-to-cloud backups to AWS S3, including bandwidth limiting, WAL compression, and AWS-specific settings. This setup ensures efficient and secure cloud backups.

```text
[myserver]
backup_method = local-to-cloud
barman_user = postgres
basebackups_directory = s3://my-backup-bucket
wals_directory = s3://my-backup-bucket
conninfo = host=localhost dbname=postgres user=postgres
bandwidth_limit = 5120  ; 5 MB/s
compression = gzip
aws_region = us-west-2
aws_profile = barman
archiver = on
```

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

### Install Tox Dependencies

Source: https://github.com/enterprisedb/barman/blob/master/docs/README.md

Installs the required Python modules for using tox to build documentation. Run this from the project's root directory.

```bash
pip install -r requirements-tox.txt
```

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

### Initialize LocalBackupInfo

Source: https://github.com/enterprisedb/barman/blob/master/docs/contributor_guide/modules/barman.infofile.md

Example of initializing a LocalBackupInfo object, which stores meta-information about a single backup.

```python
LocalBackupInfo(server='my_server', info_file='/path/to/backup.info', backup_id='12345')
```

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

### List Example

Source: https://github.com/enterprisedb/barman/blob/master/docs/contributor_guide/writing_docs.md

Example of introducing a list without using 'the following'. The color palette includes:

```rst
The color palette includes:
```

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

### GPG Encryption Example

Source: https://github.com/enterprisedb/barman/blob/master/docs/contributor_guide/modules/barman.command_wrappers.md

Example demonstrating how to encrypt a file using the GPG wrapper. Requires specifying the recipient's key identifier.

```python
>>> gpg = GPG(
...     action="encrypt",
...     input_filepath="file.txt",
...     output_filepath="file.txt.gpg",
...     recipient="user@example.com"
... )
>>> gpg()
```

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

### Install barman-cli-cloud on Debian/Ubuntu

Source: https://github.com/enterprisedb/barman/blob/master/docs/user_guide/installation.md

Install the barman-cli-cloud package for cloud-specific utilities on Debian-based systems. Requires root privileges.

```bash
apt install barman-cli-cloud
```

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

### ServerBackupLock LOCK_PATTERN Example

Source: https://github.com/enterprisedb/barman/blob/master/docs/contributor_guide/modules/barman.lockfile.md

Provides an example of a LOCK_PATTERN for ServerBackupLock, showing how the regular expression is used to match and extract server names from lock filenames.

```python
LOCK_PATTERN = re.compile('\\.(?P<server_name>.+)-backup\\.lock')
```

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

### LZ4 Compression Example

Source: https://github.com/enterprisedb/barman/blob/master/docs/user_guide/commands/barman_cloud/backup.inc.rst

Compresses the backup using lz4 during upload to the cloud.

```text
barman-cloud-backup --lz4 s3://my-bucket/my-path/ my-server
```

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

### Install barman-cli on Debian/Ubuntu

Source: https://github.com/enterprisedb/barman/blob/master/docs/user_guide/installation.md

Install the barman command-line interface package on Debian-based systems. Requires root privileges.

```bash
apt install barman-cli
```

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

### Install Boto3 for AWS

Source: https://github.com/enterprisedb/barman/blob/master/docs/user_guide/cloud_snapshot_backup.md

Install the boto3 Python library, which is required for Barman to interact with AWS services for snapshot backups. This library is optional and not included by default.

```bash
pip3 install boto3
```

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

### Example JSON String for Server Configuration

Source: https://github.com/enterprisedb/barman/blob/master/docs/user_guide/commands/barman/config_update.inc.rst

Demonstrates the format of the JSON string required for the barman config-update command to update a server's configuration. This example enables archiving and disables streaming archiving for 'my_server'.

```json
JSON_STRING='[{“scope”: “server”, “server_name”: “my_server”, “archiver”:
“on”, “streaming_archiver”: “off”}]'
```

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

### Gzip Compression Example

Source: https://github.com/enterprisedb/barman/blob/master/docs/user_guide/commands/barman_cloud/backup.inc.rst

Compresses the backup using gzip during upload to the cloud. This option requires Python 3.2 or later.

```text
barman-cloud-backup -z s3://my-bucket/my-path/ my-server
```

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

### Install GCP Python Libraries

Source: https://github.com/enterprisedb/barman/blob/master/docs/user_guide/cloud_snapshot_backup.md

Install the necessary Python libraries for Barman to interact with Google Cloud Compute Engine for snapshot backups. Requires Python 3.7+.

```bash
pip3 install grpcio google-cloud-compute
```

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

### Bzip2 Compression Example

Source: https://github.com/enterprisedb/barman/blob/master/docs/user_guide/commands/barman_cloud/backup.inc.rst

Compresses the backup using bzip2 during upload to the cloud. This option requires Python 3.3 or later.

```text
barman-cloud-backup -j s3://my-bucket/my-path/ my-server
```

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

### Install Azure Python Libraries

Source: https://github.com/enterprisedb/barman/blob/master/docs/user_guide/cloud_snapshot_backup.md

Install the required Python libraries for Barman to interact with Microsoft Azure for snapshot backups. Requires Python 3.7+.

```bash
pip3 install azure-mgmt-compute azure-identity
```

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

### GPG Decryption Example

Source: https://github.com/enterprisedb/barman/blob/master/docs/contributor_guide/modules/barman.command_wrappers.md

Example demonstrating how to decrypt a file using the GPG wrapper. Sensitive data like passphrases should be handled as bytearray and zeroed out after use.

```python
>>> gpg = GPG(
...     action="decrypt",
...     input_filepath="file.gpg",
...     output_filepath="file.decrypted"
... )
>>> passphrase = bytearray(b"secret")
>>> gpg(stdin=passphrase)
>>> passphrase[:] = b"" * len(passphrase)
```

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

### Diagnose Barman Installation

Source: https://github.com/enterprisedb/barman/blob/master/docs/user_guide/diagnose_and_troubleshooting.md

Run 'barman diagnose' to gather comprehensive information about the status of all configured servers and the Barman installation itself. This command is crucial for troubleshooting and provides a global view of your Barman setup.

```bash
barman diagnose
```

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

### Example: Testing Cloud Connectivity

Source: https://github.com/enterprisedb/barman/blob/master/docs/user_guide/commands/barman_cloud/wal_restore.inc.rst

Shows how to use the --test option to verify connectivity to the configured cloud storage backend without performing any actual WAL restoration.

```bash
barman-cloud-wal-restore --test --cloud-provider aws-s3 --endpoint-url http://localhost:9000 s3://my-bucket/my-path/ my-server wal_to_restore.wal /path/to/postgres/pg_wal/
```

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

### Example Usage with Parallel Fetching

Source: https://github.com/enterprisedb/barman/blob/master/docs/user_guide/commands/barman_cloud/wal_restore.inc.rst

Demonstrates how to use the --parallel option to fetch WAL files concurrently. This can significantly speed up WAL restoration by pre-fetching subsequent files.

```bash
barman-cloud-wal-restore --parallel 5 s3://my-bucket/my-path/ my-server wal_to_restore.wal /path/to/postgres/pg_wal/
```

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

### Future Tense Example

Source: https://github.com/enterprisedb/barman/blob/master/docs/contributor_guide/writing_docs.md

Example of using future tense to indicate a feature removal in a future release.

```rst
This feature will be removed in a future release.
```

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

### Acquiring a Lock with Options

Source: https://github.com/enterprisedb/barman/blob/master/docs/contributor_guide/modules/barman.lockfile.md

Demonstrates acquiring a lock file, with options to raise an exception on failure or to wait until the lock is available. It also shows how to update the process ID in the lock file.

```python
acquire(raise_if_fail=None, wait=None, update_pid=True)
```

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

### Ambiguous 'This' Example

Source: https://github.com/enterprisedb/barman/blob/master/docs/contributor_guide/writing_docs.md

Example of using 'this' with a following noun to avoid ambiguity. This error happens when…

```rst
This error happens when…
```

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

### Configure Backup Compression Algorithm

Source: https://github.com/enterprisedb/barman/blob/master/docs/user_guide/backup.md

Select the compression algorithm for backups using `pg_basebackup`. Supported algorithms include `gzip`, `lz4`, `zstd`, and `none`. Ensure corresponding CLI utilities are installed.

```text
backup_compression = gzip | lz4 | zstd | none
```

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

### Build HTML Documentation

Source: https://github.com/enterprisedb/barman/blob/master/docs/README.md

Generates HTML documentation using the tox environment 'docs'.

```bash
tox -e docs -- html
```

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

### Install barman on SLES

Source: https://github.com/enterprisedb/barman/blob/master/docs/user_guide/installation.md

Use this command to install the core barman package on SLES-based systems. Requires root privileges.

```bash
zypper install barman
```

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

### Install barman on Debian/Ubuntu

Source: https://github.com/enterprisedb/barman/blob/master/docs/user_guide/installation.md

Use this command to install the core barman package on Debian-based systems. Requires root privileges.

```bash
apt install barman
```

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

### Build PDF Documentation

Source: https://github.com/enterprisedb/barman/blob/master/docs/README.md

Generates PDF documentation using the tox environment 'docs'.

```bash
tox -e docs -- latexpdf
```

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

### Conditional Tense Example

Source: https://github.com/enterprisedb/barman/blob/master/docs/contributor_guide/writing_docs.md

Example of using conditional tense to explain conditions and actions. A message should appear. If it doesn't, restart the server.

```rst
A message should appear. If it doesn't, restart the server.
```

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

### Software Behavior Example

Source: https://github.com/enterprisedb/barman/blob/master/docs/contributor_guide/writing_docs.md

Example of describing software behavior without using first person plural. Next, Barman processes the instruction.

```rst
Next, Barman processes the instruction.
```

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

### Instantiate ServerWalReceiveLock

Source: https://github.com/enterprisedb/barman/blob/master/docs/contributor_guide/modules/barman.lockfile.md

Demonstrates how to instantiate ServerWalReceiveLock and access its filename property. It also shows how to use a matched group dictionary to initialize the lock.

```python
>>> ServerWalReceiveLock('/tmp', 'server-name').filename
'/tmp/.server-name-receive-wal.lock'
>>> m = ServerWalReceiveLock.LOCK_PATTERN.match(
        '.server-name-receive-wal.lock')
>>> ServerWalReceiveLock('/tmp', **(m.groupdict())).filename
'/tmp/.server-name-receive-wal.lock'
```

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

### First Person Plural Example

Source: https://github.com/enterprisedb/barman/blob/master/docs/contributor_guide/writing_docs.md

Example of using first person plural ('we') to recommend an action to the user. We recommend that you restart your server.

```rst
We recommend that you restart your server.
```

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

### Install PostgreSQL Client Tools on RHEL/Rocky/Alma Linux

Source: https://github.com/enterprisedb/barman/blob/master/docs/user_guide/pre_requisites.md

Command to install the PostgreSQL client package on RHEL, Rocky Linux, or Alma Linux systems.

```bash
sudo dnf install postgresql
```

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

### Show Barman Server Configuration

Source: https://github.com/enterprisedb/barman/blob/master/docs/user_guide/diagnose_and_troubleshooting.md

Use 'barman show-servers' to list all configuration options and their values for a specific PostgreSQL server managed by Barman.

```bash
$ barman show-servers pg16
Server local16:
    active: True
    archive_command: barman-wal-archive barman-server pg16 %p
    archive_mode: on
    archive_timeout: 0
    archived_count: 1
    ...
```

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

### Install barman-cli on SLES

Source: https://github.com/enterprisedb/barman/blob/master/docs/user_guide/installation.md

Install the barman command-line interface package on SLES-based systems. This package includes barman-cli-cloud utilities. Requires root privileges.

```bash
zypper install barman-cli
```

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

### ConfigChange.__init__

Source: https://github.com/enterprisedb/barman/blob/master/docs/contributor_guide/modules/barman.config.md

Initializes a ConfigChange object representing a configuration change.

```APIDOC
## __init__(key, value, config_file=None)

### Description
Initialize a [`ConfigChange`](#barman.config.ConfigChange) object.

### Parameters
#### Path Parameters
- **key** (string) - the configuration setting to be changed.
- **value** (string) - the new configuration value.
- **config_file** (string, optional) - configuration file associated with the change, if any, or `None`.
```

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

### Custom JSON Encoder Default Method Example

Source: https://github.com/enterprisedb/barman/blob/master/docs/contributor_guide/modules/barman.utils.md

Example of implementing the default method in a subclass of JSONEncoder to support arbitrary iterators by converting them to lists.

```python
def default(self, o):
    try:
        iterable = iter(o)
    except TypeError:
        pass
    else:
        return list(iterable)
    # Let the base class default method raise the TypeError
    return super().default(o)
```

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

### Configure Snapshot Backup Method

Source: https://github.com/enterprisedb/barman/blob/master/docs/user_guide/cloud_snapshot_backup.md

Set the backup method to snapshot and specify the cloud provider, instance, and disks for snapshot backups.

```text
backup_method = snapshot
snapshot_provider = CLOUD_PROVIDER
snapshot_instance = INSTANCE_NAME
snapshot_disks = DISK_NAME1,DISK_NAME2
```

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

### Install PostgreSQL Client Tools on Debian/Ubuntu

Source: https://github.com/enterprisedb/barman/blob/master/docs/user_guide/pre_requisites.md

Command to install the PostgreSQL client package, which includes tools like pg_basebackup and pg_receivewal, on Debian or Ubuntu systems.

```bash
sudo apt-get install postgresql-client
```

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

### List Configured Barman Servers

Source: https://github.com/enterprisedb/barman/blob/master/docs/user_guide/quickstart.md

Lists all servers configured in Barman to verify the new server has been registered. Run this command on the Barman server.

```bash
barman list-servers
```

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

### ConfigChangeSet.__init__

Source: https://github.com/enterprisedb/barman/blob/master/docs/contributor_guide/modules/barman.config.md

Initializes a ConfigChangeSet object representing a set of configuration changes for a specific section.

```APIDOC
## __init__(section, changes_set=None)

### Description
Initialize a new [`ConfigChangeSet`](#barman.config.ConfigChangeSet) object.

### Parameters
#### Path Parameters
- **section** (string) - name of the configuration section related with the changes.
- **changes_set** (List[ConfigChange], optional) - list of configuration changes to be applied to the *section*.
```

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

### Barman Restore Unrecognized Arguments Error Example

Source: https://github.com/enterprisedb/barman/blob/master/docs/releases/index.md

This example demonstrates the error encountered when using `barman-cloud-restore` with an optional `backup_id` in version 3.13.0, highlighting an argument parsing issue.

```text
barman-cloud-restore source_url server_name backup_id --cloud-provider aws-s3 recovery_dir
```

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

### Switch Server Configuration Model

Source: https://github.com/enterprisedb/barman/blob/master/docs/user_guide/commands.md

Applies configuration overrides from a model to a server. The server's existing settings are combined or overridden by the model's settings. Use '--reset' to revert to default configurations.

```bash
barman config-switch SERVER_NAME MODEL_NAME
```

```bash
barman config-switch SERVER_NAME --reset
```

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

### barman-cloud-backup-show Command Synopsis

Source: https://github.com/enterprisedb/barman/blob/master/docs/user_guide/commands/barman_cloud/backup_show.inc.rst

This snippet shows the general syntax and available options for the barman-cloud-backup-show command. It outlines the parameters for specifying the backup source, server, and backup ID, along with various flags for version, help, verbosity, testing, cloud provider specifics, and output format.

```text
barman-cloud-backup-show
                [ { -V | --version } ]
                [ --help ]
                [ { { -v | --verbose } | { -q | --quiet } } ]
                [ { -t | --test } ]
                [ --cloud-provider { aws-s3 | azure-blob-storage | google-cloud-storage } ]
                [ --endpoint-url ENDPOINT_URL ]
                [ { -P | --aws-profile } AWS_PROFILE ]
                [ --profile AWS_PROFILE ]
                [ --read-timeout READ_TIMEOUT ]
                [ --addressing-style { auto | virtual | path } ]
                [ { --azure-credential | --credential } { azure-cli | managed-identity | default } ]
                [ --format FORMAT ]
                SOURCE_URL SERVER_NAME BACKUP_ID
```

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

### Example Retry Handler Function

Source: https://github.com/enterprisedb/barman/blob/master/docs/contributor_guide/modules/barman.command_wrappers.md

This is an example of a retry handler function that can be used with the Command wrapper. It accepts the Command object, arguments, keyword arguments, attempt number, and the exception.

```python
def retry_handler(command, args, kwargs, attempt, exc):
    print("Failed command!")
```

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

### Install barman-cli package on RHEL-based systems

Source: https://github.com/enterprisedb/barman/blob/master/docs/user_guide/installation.md

Install the barman-cli package on RHEL-based systems to use utilities like barman-wal-restore and barman-wal-archive. This command must be run as root on the PostgreSQL server.

```bash
dnf install barman-cli
```