From 8d349ab6d30d9c2c9c9c7064f56627084b345a1e Mon Sep 17 00:00:00 2001
From: Renz <renz@uuxo.net>
Date: Fri, 28 Nov 2025 12:28:00 +0000
Subject: [PATCH] docs: Add --workdir flag documentation to restore sections

Enhanced documentation for --workdir flag:
- Added to Cluster Restore command reference section
- Added example to restore examples with clear "special case" comment
- Explained use case: VMs with small system disk but large NFS mounts
- Clarified it's NOT needed for standard deployments
- Prevents confusion about when to use this flag
---
 README.md | 20 ++++++++++++++++++++
 1 file changed, 20 insertions(+)

diff --git a/README.md b/README.md
index 3f57fe6..d96e52d 100755
--- a/README.md
+++ b/README.md
@@ -536,6 +536,19 @@ Restore entire PostgreSQL cluster from archive:
 ./dbbackup restore cluster ARCHIVE_FILE [OPTIONS]
 ```
 
+**Special case - Limited system disk space:**
+
+If your system disk (where PostgreSQL data resides) is small but you have large NFS mounts or additional partitions, use `--workdir` to extract on the larger storage:
+
+```bash
+# Extract to alternative location with more space
+./dbbackup restore cluster cluster_backup.tar.gz \
+  --workdir /u01/dba/restore_tmp \
+  --confirm
+```
+
+This prevents "insufficient disk space" errors on VMs with limited root partitions but large mounted storage.
+
 ### Verification & Maintenance
 
 #### Verify Backup Integrity
@@ -664,8 +677,15 @@ sudo -u postgres ./dbbackup restore cluster cluster_backup.tar.gz \
   --confirm \
   --jobs 16 \
   --verbose
+
+# Special case: Limited system disk space (use alternative extraction directory)
+sudo -u postgres ./dbbackup restore cluster cluster_backup.tar.gz \
+  --workdir /u01/dba/restore_tmp \
+  --confirm
 ```
 
+**Note:** The `--workdir` flag is only needed when your system disk is small but you have larger mounted storage (NFS, SAN, etc.). For standard deployments, it's not required.
+
 **Safety Features:**
 
 - Archive integrity validation