From be538d1fefb5a6e9e73120fed17cb8ab30344a15 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?As=C4=B1m=20Atasert?= <asimatasert@outlook.com>
Date: Thu, 16 Jul 2026 14:19:45 +0300
Subject: [PATCH 1/3] feat: source-side compression and stale staging purge for
 SSH dumps (v3.10.0)

- --compress-where source|target (default: target, old behavior): with
  zstd/xz/bzip2, compress the dump on the SSH source host before the
  transfer, so slow uplinks move the compressed artifact instead of the
  raw dump. Falls back to target-side compression with a warning when
  the tool is missing on the source or compression fails. gzip is
  unaffected (pg_dump -Z already compresses in-format at the source).
- --from-stale <time> (default: 72h, 0 disables): with --from-keep 0,
  purge this job's leftover dumps older than <time> from the source
  staging dir before dumping. Failed or interrupted runs never reach
  the post-transfer cleanup, so their dumps piled up in /tmp forever.
- Widen the --from-keep retention and fetch latest-dump globs from
  _*.dump to _*.dump* so compressed staging artifacts are matched.
- Both options are validated (enum / strict time format), supported in
  config files and jobs.yaml (save_job), and documented in --help and
  all READMEs.

Verified end-to-end against a postgres:16+sshd container: source-side
compression (pg_restore -l integrity check on the transferred artifact),
missing-tool fallback, stale purge scoping (only this job's old files),
from-keep retention with compressed names, and unchanged default-path
behavior.
---
 README.md         |  11 ++++-
 README_DE.md      |   2 +
 README_ES.md      |   2 +
 README_RU.md      |   2 +
 src/00-header.sh  |   2 +-
 src/01-globals.sh |  14 ++++++
 src/30-help.sh    |  11 +++++
 src/50-config.sh  |   2 +
 src/55-dump.sh    |  71 +++++++++++++++++++++++++++-
 src/62-fetch.sh   |   2 +-
 src/76-jobs.sh    |   2 +
 src/90-args.sh    |   2 +
 src/99-main.sh    |  12 +++++
 t-pgsql           | 118 ++++++++++++++++++++++++++++++++++++++++++++--
 14 files changed, 244 insertions(+), 9 deletions(-)

diff --git a/README.md b/README.md
index 26088bf..2f62f4d 100644
--- a/README.md
+++ b/README.md
@@ -283,6 +283,13 @@ Creates a database backup.
   --from-password-file .secrets/prod.pass \
   --from-keep 3  # Keep last 3 dumps
 
+# Slow uplink? Compress on the source host, then transfer the small file
+./t-pgsql dump \
+  --from "ssh://user@server/postgres@localhost/prod" \
+  --from-password-file .secrets/prod.pass \
+  --compress zstd \
+  --compress-where source  # 20 GB raw dump can shrink to ~1 GB before the copy
+
 # Custom dump name
 ./t-pgsql dump \
   --from "postgres@localhost/mydb" \
@@ -469,7 +476,7 @@ operation:
   exit_code: 0
 
 environment:
-  script_version: "3.9.0"
+  script_version: "3.10.0"
   executed_by: dbadmin
   executed_on: macbookair
   working_dir: /opt/t-pgsql/t-pgsql
@@ -1026,6 +1033,7 @@ Supported keys mirror the flags: `from`, `to`, `password`/`from_password`/`to_pa
 | `--compress <type>` | Compression algorithm | `gzip` | No | `zstd`, `xz`, `bzip2`, `none` |
 | `--compress-level <1-9>` | Compression level | `6` | No | `9` |
 | `--pg-compress-level <0-9>` | pg_dump internal compression | `6` | No | `0` (no compression) |
+| `--compress-where <where>` | For SSH dumps: run zstd/xz/bzip2 on the `source` host before the copy, or on the `target` after it. `source` moves a much smaller file over slow uplinks; falls back to `target` if the tool is missing on the source | `target` | No | `source` |
 
 ### Storage Parameters
 
@@ -1034,6 +1042,7 @@ Supported keys mirror the flags: `from`, `to`, `password`/`from_password`/`to_pa
 | `--output <dir>` | Output directory for dumps | `<script dir>/../data/dumps` | No | `/backups/daily` |
 | `--keep <N>` | Number of local dumps to keep | `-1` (all) | No | `7`, `0` (delete), `-1` (all) |
 | `--from-keep <N>` | Number of dumps to keep on source | `1` | No | `3`, `0` (delete), `-1` (all) |
+| `--from-stale <time>` | With `--from-keep 0`: purge this job's leftover dumps older than `<time>` from the source staging dir before dumping (failed runs never reach the normal cleanup) | `72h` | No | `48h`, `2d`, `0` (off) |
 | `--dump-name <name>` | Custom dump filename (without timestamp) | Database name | No | `myapp-backup` |
 | `--skip-if-recent <time>` | Skip if dump exists within timeframe | - | No | `24h`, `12h`, `1d`, `today` |
 | `--file <path>` | Specific dump file for restore | - | No | `./dumps/backup.tar.gz` |
diff --git a/README_DE.md b/README_DE.md
index 2068cc4..85b35a5 100644
--- a/README_DE.md
+++ b/README_DE.md
@@ -1026,6 +1026,7 @@ Die unterstützten Schlüssel spiegeln die Flags wider: `from`, `to`, `password`
 | `--compress <type>` | Komprimierungsalgorithmus | `gzip` | Nein | `zstd`, `xz`, `bzip2`, `none` |
 | `--compress-level <1-9>` | Komprimierungsstufe | `6` | Nein | `9` |
 | `--pg-compress-level <0-9>` | Interne Komprimierung von pg_dump | `6` | Nein | `0` (keine Komprimierung) |
+| `--compress-where <where>` | Bei SSH-Dumps: zstd/xz/bzip2 auf dem `source`-Host vor dem Kopieren ausführen oder auf dem `target` danach. `source` überträgt eine viel kleinere Datei über langsame Uplinks; fällt auf `target` zurück, wenn das Tool auf der Quelle fehlt | `target` | Nein | `source` |
 
 ### Speicherparameter
 
@@ -1034,6 +1035,7 @@ Die unterstützten Schlüssel spiegeln die Flags wider: `from`, `to`, `password`
 | `--output <dir>` | Ausgabeverzeichnis für Dumps | `<script dir>/../data/dumps` | Nein | `/backups/daily` |
 | `--keep <N>` | Anzahl der lokal zu behaltenden Dumps | `-1` (alle) | Nein | `7`, `0` (löschen), `-1` (alle) |
 | `--from-keep <N>` | Anzahl der auf der Quelle zu behaltenden Dumps | `1` | Nein | `3`, `0` (löschen), `-1` (alle) |
+| `--from-stale <time>` | Mit `--from-keep 0`: vor dem Dump liegengebliebene Dumps dieses Jobs, die älter als `<time>` sind, aus dem Staging-Verzeichnis der Quelle löschen (fehlgeschlagene Läufe erreichen die normale Bereinigung nie) | `72h` | Nein | `48h`, `2d`, `0` (aus) |
 | `--dump-name <name>` | Benutzerdefinierter Dump-Dateiname (ohne Zeitstempel) | Datenbankname | Nein | `myapp-backup` |
 | `--skip-if-recent <time>` | Überspringen, wenn innerhalb des Zeitrahmens ein Dump existiert | - | Nein | `24h`, `12h`, `1d`, `today` |
 | `--file <path>` | Bestimmte Dump-Datei für die Wiederherstellung | - | Nein | `./dumps/backup.tar.gz` |
diff --git a/README_ES.md b/README_ES.md
index 276c05c..c41c447 100644
--- a/README_ES.md
+++ b/README_ES.md
@@ -1026,6 +1026,7 @@ Las claves admitidas reflejan las opciones: `from`, `to`, `password`/`from_passw
 | `--compress <type>` | Algoritmo de compresión | `gzip` | No | `zstd`, `xz`, `bzip2`, `none` |
 | `--compress-level <1-9>` | Nivel de compresión | `6` | No | `9` |
 | `--pg-compress-level <0-9>` | Compresión interna de pg_dump | `6` | No | `0` (sin compresión) |
+| `--compress-where <where>` | Para dumps SSH: ejecutar zstd/xz/bzip2 en el host `source` antes de la copia, o en el `target` después. `source` transfiere un archivo mucho más pequeño por enlaces lentos; recurre a `target` si la herramienta falta en el origen | `target` | No | `source` |
 
 ### Parámetros de almacenamiento
 
@@ -1034,6 +1035,7 @@ Las claves admitidas reflejan las opciones: `from`, `to`, `password`/`from_passw
 | `--output <dir>` | Directorio de salida para los dumps | `<script dir>/../data/dumps` | No | `/backups/daily` |
 | `--keep <N>` | Número de dumps locales a conservar | `-1` (todos) | No | `7`, `0` (eliminar), `-1` (todos) |
 | `--from-keep <N>` | Número de dumps a conservar en el origen | `1` | No | `3`, `0` (eliminar), `-1` (todos) |
+| `--from-stale <time>` | Con `--from-keep 0`: antes del dump, purgar del directorio de staging del origen los dumps de este job más antiguos que `<time>` (las ejecuciones fallidas nunca llegan a la limpieza normal) | `72h` | No | `48h`, `2d`, `0` (desactivado) |
 | `--dump-name <name>` | Nombre de archivo de dump personalizado (sin marca de tiempo) | Nombre de la base de datos | No | `myapp-backup` |
 | `--skip-if-recent <time>` | Omite si existe un dump dentro del periodo | - | No | `24h`, `12h`, `1d`, `today` |
 | `--file <path>` | Archivo de dump específico para restaurar | - | No | `./dumps/backup.tar.gz` |
diff --git a/README_RU.md b/README_RU.md
index 9a9647d..4666bf6 100644
--- a/README_RU.md
+++ b/README_RU.md
@@ -1026,6 +1026,7 @@ verbose: true
 | `--compress <type>` | Алгоритм сжатия | `gzip` | Нет | `zstd`, `xz`, `bzip2`, `none` |
 | `--compress-level <1-9>` | Уровень сжатия | `6` | Нет | `9` |
 | `--pg-compress-level <0-9>` | Внутреннее сжатие pg_dump | `6` | Нет | `0` (без сжатия) |
+| `--compress-where <where>` | Для SSH-дампов: запускать zstd/xz/bzip2 на хосте `source` до копирования или на `target` после. `source` передаёт значительно меньший файл по медленным каналам; при отсутствии инструмента на источнике откат к `target` | `target` | Нет | `source` |
 
 ### Параметры хранилища
 
@@ -1034,6 +1035,7 @@ verbose: true
 | `--output <dir>` | Каталог вывода для дампов | `<script dir>/../data/dumps` | Нет | `/backups/daily` |
 | `--keep <N>` | Количество локальных дампов для хранения | `-1` (все) | Нет | `7`, `0` (удалить), `-1` (все) |
 | `--from-keep <N>` | Количество дампов для хранения на источнике | `1` | Нет | `3`, `0` (удалить), `-1` (все) |
+| `--from-stale <time>` | С `--from-keep 0`: перед дампом удалять из staging-каталога источника оставшиеся дампы этого задания старше `<time>` (неудачные запуски никогда не доходят до обычной очистки) | `72h` | Нет | `48h`, `2d`, `0` (выкл) |
 | `--dump-name <name>` | Пользовательское имя файла дампа (без временной метки) | Имя базы данных | Нет | `myapp-backup` |
 | `--skip-if-recent <time>` | Пропустить, если дамп существует в пределах временного окна | - | Нет | `24h`, `12h`, `1d`, `today` |
 | `--file <path>` | Конкретный файл дампа для восстановления | - | Нет | `./dumps/backup.tar.gz` |
diff --git a/src/00-header.sh b/src/00-header.sh
index 7d34631..f2185c6 100644
--- a/src/00-header.sh
+++ b/src/00-header.sh
@@ -21,7 +21,7 @@
 # ==============================================================================
 # VERSION & PATHS
 # ==============================================================================
-VERSION="3.9.0"
+VERSION="3.10.0"
 SCRIPT_NAME="t-pgsql"
 SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
 
diff --git a/src/01-globals.sh b/src/01-globals.sh
index 83c8fb0..d5114f3 100644
--- a/src/01-globals.sh
+++ b/src/01-globals.sh
@@ -81,6 +81,20 @@ BWLIMIT_KBIT=""               # derived: scp -l wants Kbit/s
 PV_RATE=""                    # derived: pv -L rate for streaming clone
 RETRIES=0                     # extra retries for scp transfers on failure
 
+# Where external compression (zstd/xz/bzip2) runs for SSH dumps:
+#   target (default) = copy the raw dump, compress locally (old behavior)
+#   source           = compress on the source host first, then copy the small
+#                      file — a 20x+ transfer saving on slow uplinks
+COMPRESS_WHERE="target"
+COMPRESS_WHERE_SET=false      # true if --compress-where passed on CLI
+
+# Before an SSH dump with --from-keep 0, purge leftover dumps of the same job
+# older than this from the source temp dir. Failed or interrupted runs never
+# reach the post-transfer cleanup, so their dumps would otherwise pile up in
+# /tmp forever. 0 disables.
+FROM_STALE="72h"
+FROM_STALE_SET=false          # true if --from-stale passed on CLI
+
 # Migration / upgrade
 GLOBALS=false                 # also migrate cluster globals (roles, tablespaces)
 PG_BINDIR=""                  # dir prepended to PATH so a specific PostgreSQL
diff --git a/src/30-help.sh b/src/30-help.sh
index 767c268..b7b75bf 100644
--- a/src/30-help.sh
+++ b/src/30-help.sh
@@ -72,6 +72,12 @@ COMPRESSION:
                                   compression is disabled so data is compressed once.
     --pg-compress-level <0-9>     Advanced: override pg_dump's built-in -Z level
                                   (only affects the gzip type; default: 6)
+    --compress-where <where>      For SSH dumps with zstd/xz/bzip2 (default: target):
+                                  target = copy the raw dump, compress locally
+                                  source = compress on the source host first, then
+                                  copy the much smaller file (best on slow uplinks).
+                                  Falls back to target if the tool is missing there.
+                                  gzip is unaffected (pg_dump -Z compresses in-place).
 
 STORAGE:
     --output <dir>                Output directory (default: env T_PGSQL_OUTPUT_DIR,
@@ -80,6 +86,11 @@ STORAGE:
     --keep <N>                    Keep last N local dumps (-1=all, 0=none)
     --from-keep <N>               For SSH sources: how many dumps to keep in the remote
                                   /tmp staging dir (default: 1, -1=all, 0=delete)
+    --from-stale <time>           With --from-keep 0: before dumping, purge this job's
+                                  leftover dumps older than <time> from the remote
+                                  staging dir — failed runs never reach the normal
+                                  cleanup and would pile up there (default: 72h,
+                                  0 disables). Examples: 48h, 2d
     --skip-if-recent <time>       Skip if dump exists within timeframe
                                   Examples: 24h, 12h, 1d, today
     --from-file [pattern]         Fetch existing dump (for fetch command)
diff --git a/src/50-config.sh b/src/50-config.sh
index 383e597..8b78654 100644
--- a/src/50-config.sh
+++ b/src/50-config.sh
@@ -49,7 +49,9 @@ load_config() {
             output) [ "$OUTPUT_DIR_SET" != true ] && OUTPUT_DIR="$value" ;;
             keep) [ "$KEEP_SET" != true ] && KEEP="$value" ;;
             from_keep|from-keep) [ "$FROM_KEEP_SET" != true ] && FROM_KEEP="$value" ;;
+            from_stale|from-stale) [ "$FROM_STALE_SET" != true ] && FROM_STALE="$value" ;;
             compress) [ "$COMPRESS_SET" != true ] && COMPRESS="$value" ;;
+            compress_where|compress-where) [ "$COMPRESS_WHERE_SET" != true ] && COMPRESS_WHERE="$value" ;;
             exclude_table|exclude-table) [ -z "$EXCLUDE_TABLES" ] && EXCLUDE_TABLES="$value" ;;
             exclude_schema|exclude-schema) [ -z "$EXCLUDE_SCHEMAS" ] && EXCLUDE_SCHEMAS="$value" ;;
             exclude_data|exclude-data) [ -z "$EXCLUDE_DATA" ] && EXCLUDE_DATA="$value" ;;
diff --git a/src/55-dump.sh b/src/55-dump.sh
index 7f09a1c..8cbb47f 100644
--- a/src/55-dump.sh
+++ b/src/55-dump.sh
@@ -127,6 +127,7 @@ cmd_dump() {
     esac
 
     local result=0
+    local remote_compressed=false comp_ext=""
 
     if [ "$FROM_TYPE" = "ssh" ]; then
         log_info "Dumping via SSH..."
@@ -135,6 +136,20 @@ cmd_dump() {
         local dump_base_name="${DUMP_NAME:-$FROM_DATABASE}"
         local remote_file="${remote_dump_dir}/${dump_base_name}_${ts}.dump"
 
+        # Purge leftovers from failed/interrupted runs (--from-stale). Post-transfer
+        # cleanup never runs when a run dies mid-way, so its dump would sit in the
+        # source temp dir forever. Only with --from-keep 0: a positive keep policy
+        # manages its own retention, and -1 means keep everything on the source.
+        local stale_min=$(( $(parse_time_to_seconds "$FROM_STALE") / 60 ))
+        if [ "$FROM_KEEP" -eq 0 ] && [ "$stale_min" -gt 0 ]; then
+            local stale_out
+            stale_out=$(ssh -p "$FROM_SSH_PORT" "${SSH_OPTS[@]}" "${FROM_SSH_USER}@${FROM_SSH_HOST}" \
+                "find $(pq "$remote_dump_dir") -maxdepth 1 -name $(pq "${dump_base_name}_*.dump*") -mmin +${stale_min} -print -delete 2>/dev/null")
+            if [ -n "$stale_out" ]; then
+                log_info "Purged $(echo "$stale_out" | wc -l | tr -d ' ') stale source dump(s) older than ${FROM_STALE}"
+            fi
+        fi
+
         local cmd=""
         if [ "$SUDO" = true ]; then
             # Use sudo -u postgres (peer auth)
@@ -153,6 +168,37 @@ cmd_dump() {
         ssh_exec "$FROM_SSH_PORT" "${FROM_SSH_USER}@${FROM_SSH_HOST}" "$cmd"
         result=$?
 
+        # Source-side compression (--compress-where source): shrink the dump on
+        # the source host BEFORE the copy, so a slow uplink moves the compressed
+        # artifact instead of the raw dump. Falls back to the old transfer-then-
+        # compress path if the tool is missing or compression fails — never
+        # blocks the backup. gzip needs nothing here: pg_dump -Z already
+        # compressed it in-format on the source.
+        if [ $result -eq 0 ] && [ "$COMPRESS_WHERE" = "source" ]; then
+            case "$COMPRESS" in
+                zstd|xz|bzip2)
+                    local clvl="$COMPRESS_LEVEL" ccmd=""
+                    [ "$clvl" -lt 1 ] && clvl=1
+                    case "$COMPRESS" in
+                        zstd)  [ "$clvl" -gt 19 ] && clvl=19; comp_ext="zst"; ccmd="zstd -q -${clvl} --rm -f $(pq "$remote_file")" ;;
+                        xz)    [ "$clvl" -gt 9 ]  && clvl=9;  comp_ext="xz";  ccmd="xz -${clvl} -f $(pq "$remote_file")" ;;
+                        bzip2) [ "$clvl" -gt 9 ]  && clvl=9;  comp_ext="bz2"; ccmd="bzip2 -${clvl} -f $(pq "$remote_file")" ;;
+                    esac
+                    if ssh -p "$FROM_SSH_PORT" "${SSH_OPTS[@]}" "${FROM_SSH_USER}@${FROM_SSH_HOST}" "command -v $(pq "$COMPRESS") >/dev/null 2>&1"; then
+                        log_info "Compressing on source ($COMPRESS)..."
+                        if ssh -p "$FROM_SSH_PORT" "${SSH_OPTS[@]}" "${FROM_SSH_USER}@${FROM_SSH_HOST}" "$ccmd"; then
+                            remote_file="${remote_file}.${comp_ext}"
+                            remote_compressed=true
+                        else
+                            log_warn "Source-side compression failed; transferring raw and compressing on target"
+                        fi
+                    else
+                        log_warn "'$COMPRESS' not found on source host; transferring raw and compressing on target"
+                    fi
+                    ;;
+            esac
+        fi
+
         if [ $result -eq 0 ]; then
             log_info "Transferring..."
             if ! scp_transfer "$FROM_SSH_PORT" "${FROM_SSH_USER}@${FROM_SSH_HOST}:${remote_file}" "$dump_file"; then
@@ -160,6 +206,26 @@ cmd_dump() {
                 result=1
             fi
 
+            # The local name was reserved as a plain .dump path; when the bytes
+            # arrived already compressed, rename to the real extension so
+            # metadata, retention and restore see what the file actually is.
+            if [ $result -eq 0 ] && [ "$remote_compressed" = true ]; then
+                local final_file="${dump_file}.${comp_ext}" _m=0
+                while [ -e "$final_file" ]; do
+                    _m=$((_m + 1))
+                    [ "$_m" -gt 10000 ] && { log_error "Too many colliding dumps for ${dump_file}.${comp_ext}"; result=1; break; }
+                    final_file="${dump_file}.${_m}.${comp_ext}"
+                done
+                if [ $result -eq 0 ]; then
+                    if mv "$dump_file" "$final_file"; then
+                        dump_file="$final_file"
+                    else
+                        log_error "Could not rename transferred dump to $final_file"
+                        result=1
+                    fi
+                fi
+            fi
+
             # Cleanup based on FROM_KEEP — ONLY after a successful transfer, so a
             # failed copy never deletes the only remaining copy on the source.
             if [ $result -eq 0 ] && [ "$FROM_KEEP" -eq 0 ]; then
@@ -168,7 +234,7 @@ cmd_dump() {
             elif [ $result -eq 0 ] && [ "$FROM_KEEP" -gt 0 ]; then
                 log_info "Keeping last $FROM_KEEP dump(s) on source..."
                 local dump_base_name="${DUMP_NAME:-$FROM_DATABASE}"
-                local cleanup_cmd="cd $(pq "$remote_dump_dir") && ls -t $(pq "$dump_base_name")_*.dump 2>/dev/null | tail -n +$((FROM_KEEP + 1)) | xargs -r rm -f"
+                local cleanup_cmd="cd $(pq "$remote_dump_dir") && ls -t $(pq "$dump_base_name")_*.dump* 2>/dev/null | tail -n +$((FROM_KEEP + 1)) | xargs -r rm -f"
                 ssh -p "$FROM_SSH_PORT" "${SSH_OPTS[@]}" "${FROM_SSH_USER}@${FROM_SSH_HOST}" "$cleanup_cmd"
             elif [ $result -eq 0 ]; then
                 log_info "Keeping source dump (--from-keep -1)"
@@ -193,7 +259,8 @@ cmd_dump() {
         # External compression must happen BEFORE metadata is written, and
         # dump_file must be advanced to the compressed artifact so meta_write
         # sees an existing file (and DUMP_FILE reflects what really exists).
-        if [ "$COMPRESS" != "gzip" ] && [ "$COMPRESS" != "none" ]; then
+        # Skipped when the file already arrived compressed from the source.
+        if [ "$remote_compressed" != true ] && [ "$COMPRESS" != "gzip" ] && [ "$COMPRESS" != "none" ]; then
             if compress_file "$dump_file"; then
                 case "$COMPRESS" in
                     zstd)  dump_file="${dump_file}.zst" ;;
diff --git a/src/62-fetch.sh b/src/62-fetch.sh
index 50e0cdb..9462ada 100644
--- a/src/62-fetch.sh
+++ b/src/62-fetch.sh
@@ -41,7 +41,7 @@ cmd_fetch() {
         # Auto-find latest dump for database (--from-file or --from-file latest)
         log_info "Finding latest dump for: $FROM_DATABASE"
         remote_file=$(ssh -p "$FROM_SSH_PORT" "${SSH_OPTS[@]}" "${FROM_SSH_USER}@${FROM_SSH_HOST}" \
-            "ls -t /tmp/t-pgsql/$(pq "$FROM_DATABASE")_*.dump 2>/dev/null | head -1")
+            "ls -t /tmp/t-pgsql/$(pq "$FROM_DATABASE")_*.dump* 2>/dev/null | head -1")
     fi
 
     if [ -z "$remote_file" ]; then
diff --git a/src/76-jobs.sh b/src/76-jobs.sh
index 337a750..1efb944 100644
--- a/src/76-jobs.sh
+++ b/src/76-jobs.sh
@@ -34,6 +34,8 @@ save_job() {
     [ "$COMPRESS" != "gzip" ] && args="$args --compress $(pq "$COMPRESS")"
     [ "$COMPRESS_LEVEL" != 6 ] && args="$args --compress-level $COMPRESS_LEVEL"
     [ "$PG_COMPRESS_LEVEL_SET" = true ] && args="$args --pg-compress-level $PG_COMPRESS_LEVEL"
+    [ "$COMPRESS_WHERE" != "target" ] && args="$args --compress-where $(pq "$COMPRESS_WHERE")"
+    [ "$FROM_STALE" != "72h" ] && args="$args --from-stale $(pq "$FROM_STALE")"
 
     # Streaming
     [ "$STREAM" = true ] && args="$args --stream"
diff --git a/src/90-args.sh b/src/90-args.sh
index 6d588ce..85e1e0d 100644
--- a/src/90-args.sh
+++ b/src/90-args.sh
@@ -82,10 +82,12 @@ parse_args() {
             --compress) COMPRESS="$2"; COMPRESS_SET=true; shift 2 || _need_val "$1" ;;
             --compress-level) COMPRESS_LEVEL="$2"; shift 2 || _need_val "$1" ;;
             --pg-compress-level) PG_COMPRESS_LEVEL="$2"; PG_COMPRESS_LEVEL_SET=true; shift 2 || _need_val "$1" ;;
+            --compress-where) COMPRESS_WHERE="$2"; COMPRESS_WHERE_SET=true; shift 2 || _need_val "$1" ;;
 
             --output) OUTPUT_DIR="$2"; OUTPUT_DIR_SET=true; shift 2 || _need_val "$1" ;;
             --keep) KEEP="$2"; KEEP_SET=true; shift 2 || _need_val "$1" ;;
             --from-keep) FROM_KEEP="$2"; FROM_KEEP_SET=true; shift 2 || _need_val "$1" ;;
+            --from-stale) FROM_STALE="$2"; FROM_STALE_SET=true; shift 2 || _need_val "$1" ;;
             --dump-name) DUMP_NAME="$2"; shift 2 || _need_val "$1" ;;
             --skip-if-recent) SKIP_IF_RECENT="$2"; shift 2 || _need_val "$1" ;;
             --from-file)
diff --git a/src/99-main.sh b/src/99-main.sh
index 2f49f48..9726170 100644
--- a/src/99-main.sh
+++ b/src/99-main.sh
@@ -57,6 +57,18 @@ main() {
         *) log_error "Invalid --compress '$COMPRESS' (use gzip|zstd|xz|bzip2|none)"; exit 1 ;;
     esac
 
+    case "$COMPRESS_WHERE" in
+        source|target) ;;
+        *) log_error "Invalid --compress-where '$COMPRESS_WHERE' (use source|target)"; exit 1 ;;
+    esac
+
+    # --from-stale is a time string that feeds $(( )) arithmetic and a remote
+    # find(1) argument; validate the format so nothing else can reach either.
+    if ! [[ "$FROM_STALE" =~ ^[0-9]+[hmd]?$ ]]; then
+        log_error "Invalid --from-stale '$FROM_STALE' (use e.g. 72h, 2d, or 0 to disable)"
+        exit 1
+    fi
+
     # Resolve --bwlimit (human units) to scp's Kbit/s. Strict pattern so the value
     # can never reach the arithmetic below as an injection payload. 10m=MByte/s,
     # 500k=KByte/s, bare number = KByte/s.
diff --git a/t-pgsql b/t-pgsql
index e2af44d..7735940 100755
--- a/t-pgsql
+++ b/t-pgsql
@@ -21,7 +21,7 @@
 # ==============================================================================
 # VERSION & PATHS
 # ==============================================================================
-VERSION="3.9.0"
+VERSION="3.10.0"
 SCRIPT_NAME="t-pgsql"
 SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
 
@@ -120,6 +120,20 @@ BWLIMIT_KBIT=""               # derived: scp -l wants Kbit/s
 PV_RATE=""                    # derived: pv -L rate for streaming clone
 RETRIES=0                     # extra retries for scp transfers on failure
 
+# Where external compression (zstd/xz/bzip2) runs for SSH dumps:
+#   target (default) = copy the raw dump, compress locally (old behavior)
+#   source           = compress on the source host first, then copy the small
+#                      file — a 20x+ transfer saving on slow uplinks
+COMPRESS_WHERE="target"
+COMPRESS_WHERE_SET=false      # true if --compress-where passed on CLI
+
+# Before an SSH dump with --from-keep 0, purge leftover dumps of the same job
+# older than this from the source temp dir. Failed or interrupted runs never
+# reach the post-transfer cleanup, so their dumps would otherwise pile up in
+# /tmp forever. 0 disables.
+FROM_STALE="72h"
+FROM_STALE_SET=false          # true if --from-stale passed on CLI
+
 # Migration / upgrade
 GLOBALS=false                 # also migrate cluster globals (roles, tablespaces)
 PG_BINDIR=""                  # dir prepended to PATH so a specific PostgreSQL
@@ -1067,6 +1081,12 @@ COMPRESSION:
                                   compression is disabled so data is compressed once.
     --pg-compress-level <0-9>     Advanced: override pg_dump's built-in -Z level
                                   (only affects the gzip type; default: 6)
+    --compress-where <where>      For SSH dumps with zstd/xz/bzip2 (default: target):
+                                  target = copy the raw dump, compress locally
+                                  source = compress on the source host first, then
+                                  copy the much smaller file (best on slow uplinks).
+                                  Falls back to target if the tool is missing there.
+                                  gzip is unaffected (pg_dump -Z compresses in-place).
 
 STORAGE:
     --output <dir>                Output directory (default: env T_PGSQL_OUTPUT_DIR,
@@ -1075,6 +1095,11 @@ STORAGE:
     --keep <N>                    Keep last N local dumps (-1=all, 0=none)
     --from-keep <N>               For SSH sources: how many dumps to keep in the remote
                                   /tmp staging dir (default: 1, -1=all, 0=delete)
+    --from-stale <time>           With --from-keep 0: before dumping, purge this job's
+                                  leftover dumps older than <time> from the remote
+                                  staging dir — failed runs never reach the normal
+                                  cleanup and would pile up there (default: 72h,
+                                  0 disables). Examples: 48h, 2d
     --skip-if-recent <time>       Skip if dump exists within timeframe
                                   Examples: 24h, 12h, 1d, today
     --from-file [pattern]         Fetch existing dump (for fetch command)
@@ -1675,7 +1700,9 @@ load_config() {
             output) [ "$OUTPUT_DIR_SET" != true ] && OUTPUT_DIR="$value" ;;
             keep) [ "$KEEP_SET" != true ] && KEEP="$value" ;;
             from_keep|from-keep) [ "$FROM_KEEP_SET" != true ] && FROM_KEEP="$value" ;;
+            from_stale|from-stale) [ "$FROM_STALE_SET" != true ] && FROM_STALE="$value" ;;
             compress) [ "$COMPRESS_SET" != true ] && COMPRESS="$value" ;;
+            compress_where|compress-where) [ "$COMPRESS_WHERE_SET" != true ] && COMPRESS_WHERE="$value" ;;
             exclude_table|exclude-table) [ -z "$EXCLUDE_TABLES" ] && EXCLUDE_TABLES="$value" ;;
             exclude_schema|exclude-schema) [ -z "$EXCLUDE_SCHEMAS" ] && EXCLUDE_SCHEMAS="$value" ;;
             exclude_data|exclude-data) [ -z "$EXCLUDE_DATA" ] && EXCLUDE_DATA="$value" ;;
@@ -1820,6 +1847,7 @@ cmd_dump() {
     esac
 
     local result=0
+    local remote_compressed=false comp_ext=""
 
     if [ "$FROM_TYPE" = "ssh" ]; then
         log_info "Dumping via SSH..."
@@ -1828,6 +1856,20 @@ cmd_dump() {
         local dump_base_name="${DUMP_NAME:-$FROM_DATABASE}"
         local remote_file="${remote_dump_dir}/${dump_base_name}_${ts}.dump"
 
+        # Purge leftovers from failed/interrupted runs (--from-stale). Post-transfer
+        # cleanup never runs when a run dies mid-way, so its dump would sit in the
+        # source temp dir forever. Only with --from-keep 0: a positive keep policy
+        # manages its own retention, and -1 means keep everything on the source.
+        local stale_min=$(( $(parse_time_to_seconds "$FROM_STALE") / 60 ))
+        if [ "$FROM_KEEP" -eq 0 ] && [ "$stale_min" -gt 0 ]; then
+            local stale_out
+            stale_out=$(ssh -p "$FROM_SSH_PORT" "${SSH_OPTS[@]}" "${FROM_SSH_USER}@${FROM_SSH_HOST}" \
+                "find $(pq "$remote_dump_dir") -maxdepth 1 -name $(pq "${dump_base_name}_*.dump*") -mmin +${stale_min} -print -delete 2>/dev/null")
+            if [ -n "$stale_out" ]; then
+                log_info "Purged $(echo "$stale_out" | wc -l | tr -d ' ') stale source dump(s) older than ${FROM_STALE}"
+            fi
+        fi
+
         local cmd=""
         if [ "$SUDO" = true ]; then
             # Use sudo -u postgres (peer auth)
@@ -1846,6 +1888,37 @@ cmd_dump() {
         ssh_exec "$FROM_SSH_PORT" "${FROM_SSH_USER}@${FROM_SSH_HOST}" "$cmd"
         result=$?
 
+        # Source-side compression (--compress-where source): shrink the dump on
+        # the source host BEFORE the copy, so a slow uplink moves the compressed
+        # artifact instead of the raw dump. Falls back to the old transfer-then-
+        # compress path if the tool is missing or compression fails — never
+        # blocks the backup. gzip needs nothing here: pg_dump -Z already
+        # compressed it in-format on the source.
+        if [ $result -eq 0 ] && [ "$COMPRESS_WHERE" = "source" ]; then
+            case "$COMPRESS" in
+                zstd|xz|bzip2)
+                    local clvl="$COMPRESS_LEVEL" ccmd=""
+                    [ "$clvl" -lt 1 ] && clvl=1
+                    case "$COMPRESS" in
+                        zstd)  [ "$clvl" -gt 19 ] && clvl=19; comp_ext="zst"; ccmd="zstd -q -${clvl} --rm -f $(pq "$remote_file")" ;;
+                        xz)    [ "$clvl" -gt 9 ]  && clvl=9;  comp_ext="xz";  ccmd="xz -${clvl} -f $(pq "$remote_file")" ;;
+                        bzip2) [ "$clvl" -gt 9 ]  && clvl=9;  comp_ext="bz2"; ccmd="bzip2 -${clvl} -f $(pq "$remote_file")" ;;
+                    esac
+                    if ssh -p "$FROM_SSH_PORT" "${SSH_OPTS[@]}" "${FROM_SSH_USER}@${FROM_SSH_HOST}" "command -v $(pq "$COMPRESS") >/dev/null 2>&1"; then
+                        log_info "Compressing on source ($COMPRESS)..."
+                        if ssh -p "$FROM_SSH_PORT" "${SSH_OPTS[@]}" "${FROM_SSH_USER}@${FROM_SSH_HOST}" "$ccmd"; then
+                            remote_file="${remote_file}.${comp_ext}"
+                            remote_compressed=true
+                        else
+                            log_warn "Source-side compression failed; transferring raw and compressing on target"
+                        fi
+                    else
+                        log_warn "'$COMPRESS' not found on source host; transferring raw and compressing on target"
+                    fi
+                    ;;
+            esac
+        fi
+
         if [ $result -eq 0 ]; then
             log_info "Transferring..."
             if ! scp_transfer "$FROM_SSH_PORT" "${FROM_SSH_USER}@${FROM_SSH_HOST}:${remote_file}" "$dump_file"; then
@@ -1853,6 +1926,26 @@ cmd_dump() {
                 result=1
             fi
 
+            # The local name was reserved as a plain .dump path; when the bytes
+            # arrived already compressed, rename to the real extension so
+            # metadata, retention and restore see what the file actually is.
+            if [ $result -eq 0 ] && [ "$remote_compressed" = true ]; then
+                local final_file="${dump_file}.${comp_ext}" _m=0
+                while [ -e "$final_file" ]; do
+                    _m=$((_m + 1))
+                    [ "$_m" -gt 10000 ] && { log_error "Too many colliding dumps for ${dump_file}.${comp_ext}"; result=1; break; }
+                    final_file="${dump_file}.${_m}.${comp_ext}"
+                done
+                if [ $result -eq 0 ]; then
+                    if mv "$dump_file" "$final_file"; then
+                        dump_file="$final_file"
+                    else
+                        log_error "Could not rename transferred dump to $final_file"
+                        result=1
+                    fi
+                fi
+            fi
+
             # Cleanup based on FROM_KEEP — ONLY after a successful transfer, so a
             # failed copy never deletes the only remaining copy on the source.
             if [ $result -eq 0 ] && [ "$FROM_KEEP" -eq 0 ]; then
@@ -1861,7 +1954,7 @@ cmd_dump() {
             elif [ $result -eq 0 ] && [ "$FROM_KEEP" -gt 0 ]; then
                 log_info "Keeping last $FROM_KEEP dump(s) on source..."
                 local dump_base_name="${DUMP_NAME:-$FROM_DATABASE}"
-                local cleanup_cmd="cd $(pq "$remote_dump_dir") && ls -t $(pq "$dump_base_name")_*.dump 2>/dev/null | tail -n +$((FROM_KEEP + 1)) | xargs -r rm -f"
+                local cleanup_cmd="cd $(pq "$remote_dump_dir") && ls -t $(pq "$dump_base_name")_*.dump* 2>/dev/null | tail -n +$((FROM_KEEP + 1)) | xargs -r rm -f"
                 ssh -p "$FROM_SSH_PORT" "${SSH_OPTS[@]}" "${FROM_SSH_USER}@${FROM_SSH_HOST}" "$cleanup_cmd"
             elif [ $result -eq 0 ]; then
                 log_info "Keeping source dump (--from-keep -1)"
@@ -1886,7 +1979,8 @@ cmd_dump() {
         # External compression must happen BEFORE metadata is written, and
         # dump_file must be advanced to the compressed artifact so meta_write
         # sees an existing file (and DUMP_FILE reflects what really exists).
-        if [ "$COMPRESS" != "gzip" ] && [ "$COMPRESS" != "none" ]; then
+        # Skipped when the file already arrived compressed from the source.
+        if [ "$remote_compressed" != true ] && [ "$COMPRESS" != "gzip" ] && [ "$COMPRESS" != "none" ]; then
             if compress_file "$dump_file"; then
                 case "$COMPRESS" in
                     zstd)  dump_file="${dump_file}.zst" ;;
@@ -2363,7 +2457,7 @@ cmd_fetch() {
         # Auto-find latest dump for database (--from-file or --from-file latest)
         log_info "Finding latest dump for: $FROM_DATABASE"
         remote_file=$(ssh -p "$FROM_SSH_PORT" "${SSH_OPTS[@]}" "${FROM_SSH_USER}@${FROM_SSH_HOST}" \
-            "ls -t /tmp/t-pgsql/$(pq "$FROM_DATABASE")_*.dump 2>/dev/null | head -1")
+            "ls -t /tmp/t-pgsql/$(pq "$FROM_DATABASE")_*.dump* 2>/dev/null | head -1")
     fi
 
     if [ -z "$remote_file" ]; then
@@ -3572,6 +3666,8 @@ save_job() {
     [ "$COMPRESS" != "gzip" ] && args="$args --compress $(pq "$COMPRESS")"
     [ "$COMPRESS_LEVEL" != 6 ] && args="$args --compress-level $COMPRESS_LEVEL"
     [ "$PG_COMPRESS_LEVEL_SET" = true ] && args="$args --pg-compress-level $PG_COMPRESS_LEVEL"
+    [ "$COMPRESS_WHERE" != "target" ] && args="$args --compress-where $(pq "$COMPRESS_WHERE")"
+    [ "$FROM_STALE" != "72h" ] && args="$args --from-stale $(pq "$FROM_STALE")"
 
     # Streaming
     [ "$STREAM" = true ] && args="$args --stream"
@@ -4834,10 +4930,12 @@ parse_args() {
             --compress) COMPRESS="$2"; COMPRESS_SET=true; shift 2 || _need_val "$1" ;;
             --compress-level) COMPRESS_LEVEL="$2"; shift 2 || _need_val "$1" ;;
             --pg-compress-level) PG_COMPRESS_LEVEL="$2"; PG_COMPRESS_LEVEL_SET=true; shift 2 || _need_val "$1" ;;
+            --compress-where) COMPRESS_WHERE="$2"; COMPRESS_WHERE_SET=true; shift 2 || _need_val "$1" ;;
 
             --output) OUTPUT_DIR="$2"; OUTPUT_DIR_SET=true; shift 2 || _need_val "$1" ;;
             --keep) KEEP="$2"; KEEP_SET=true; shift 2 || _need_val "$1" ;;
             --from-keep) FROM_KEEP="$2"; FROM_KEEP_SET=true; shift 2 || _need_val "$1" ;;
+            --from-stale) FROM_STALE="$2"; FROM_STALE_SET=true; shift 2 || _need_val "$1" ;;
             --dump-name) DUMP_NAME="$2"; shift 2 || _need_val "$1" ;;
             --skip-if-recent) SKIP_IF_RECENT="$2"; shift 2 || _need_val "$1" ;;
             --from-file)
@@ -4981,6 +5079,18 @@ main() {
         *) log_error "Invalid --compress '$COMPRESS' (use gzip|zstd|xz|bzip2|none)"; exit 1 ;;
     esac
 
+    case "$COMPRESS_WHERE" in
+        source|target) ;;
+        *) log_error "Invalid --compress-where '$COMPRESS_WHERE' (use source|target)"; exit 1 ;;
+    esac
+
+    # --from-stale is a time string that feeds $(( )) arithmetic and a remote
+    # find(1) argument; validate the format so nothing else can reach either.
+    if ! [[ "$FROM_STALE" =~ ^[0-9]+[hmd]?$ ]]; then
+        log_error "Invalid --from-stale '$FROM_STALE' (use e.g. 72h, 2d, or 0 to disable)"
+        exit 1
+    fi
+
     # Resolve --bwlimit (human units) to scp's Kbit/s. Strict pattern so the value
     # can never reach the arithmetic below as an injection payload. 10m=MByte/s,
     # 500k=KByte/s, bare number = KByte/s.

From 7c278a6345819bda3bb7f7bac96593381063f30f Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?As=C4=B1m=20Atasert?= <asimatasert@outlook.com>
Date: Thu, 16 Jul 2026 14:28:15 +0300
Subject: [PATCH 2/3] fix: map compress_where and from_stale YAML keys to batch
 job args
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

The batch runner translates YAML defaults/job keys to child CLI args via
an explicit key list in yaml.sh, which the new options were missing from
— a compress_where/from_stale set in a jobs YAML was silently ignored.
---
 src/75-yaml.sh | 2 ++
 t-pgsql        | 2 ++
 2 files changed, 4 insertions(+)

diff --git a/src/75-yaml.sh b/src/75-yaml.sh
index 0827e90..54d0a6c 100644
--- a/src/75-yaml.sh
+++ b/src/75-yaml.sh
@@ -419,6 +419,7 @@ parse_job_to_args() {
     [ -n "$(get_job_value "$job" "dump_name")" ] && args+=" --dump-name $(pq "$(get_job_value "$job" "dump_name")")"
     [ -n "$(get_job_value "$job" "keep")" ] && args+=" --keep $(pq "$(get_job_value "$job" "keep")")"
     [ -n "$(get_job_value "$job" "from_keep")" ] && args+=" --from-keep $(pq "$(get_job_value "$job" "from_keep")")"
+    [ -n "$(get_job_value "$job" "from_stale")" ] && args+=" --from-stale $(pq "$(get_job_value "$job" "from_stale")")"
     [ -n "$(get_job_value "$job" "skip_if_recent")" ] && args+=" --skip-if-recent $(pq "$(get_job_value "$job" "skip_if_recent")")"
 
     # Filtering options
@@ -432,6 +433,7 @@ parse_job_to_args() {
     [ -n "$(get_job_value "$job" "compress")" ] && args+=" --compress $(pq "$(get_job_value "$job" "compress")")"
     [ -n "$(get_job_value "$job" "compress_level")" ] && args+=" --compress-level $(pq "$(get_job_value "$job" "compress_level")")"
     [ -n "$(get_job_value "$job" "pg_compress_level")" ] && args+=" --pg-compress-level $(pq "$(get_job_value "$job" "pg_compress_level")")"
+    [ -n "$(get_job_value "$job" "compress_where")" ] && args+=" --compress-where $(pq "$(get_job_value "$job" "compress_where")")"
 
     # Streaming options
     [ -n "$(get_job_value "$job" "stream_buffer")" ] && args+=" --stream-buffer $(pq "$(get_job_value "$job" "stream_buffer")")"
diff --git a/t-pgsql b/t-pgsql
index 7735940..8ca9aad 100755
--- a/t-pgsql
+++ b/t-pgsql
@@ -3584,6 +3584,7 @@ parse_job_to_args() {
     [ -n "$(get_job_value "$job" "dump_name")" ] && args+=" --dump-name $(pq "$(get_job_value "$job" "dump_name")")"
     [ -n "$(get_job_value "$job" "keep")" ] && args+=" --keep $(pq "$(get_job_value "$job" "keep")")"
     [ -n "$(get_job_value "$job" "from_keep")" ] && args+=" --from-keep $(pq "$(get_job_value "$job" "from_keep")")"
+    [ -n "$(get_job_value "$job" "from_stale")" ] && args+=" --from-stale $(pq "$(get_job_value "$job" "from_stale")")"
     [ -n "$(get_job_value "$job" "skip_if_recent")" ] && args+=" --skip-if-recent $(pq "$(get_job_value "$job" "skip_if_recent")")"
 
     # Filtering options
@@ -3597,6 +3598,7 @@ parse_job_to_args() {
     [ -n "$(get_job_value "$job" "compress")" ] && args+=" --compress $(pq "$(get_job_value "$job" "compress")")"
     [ -n "$(get_job_value "$job" "compress_level")" ] && args+=" --compress-level $(pq "$(get_job_value "$job" "compress_level")")"
     [ -n "$(get_job_value "$job" "pg_compress_level")" ] && args+=" --pg-compress-level $(pq "$(get_job_value "$job" "pg_compress_level")")"
+    [ -n "$(get_job_value "$job" "compress_where")" ] && args+=" --compress-where $(pq "$(get_job_value "$job" "compress_where")")"
 
     # Streaming options
     [ -n "$(get_job_value "$job" "stream_buffer")" ] && args+=" --stream-buffer $(pq "$(get_job_value "$job" "stream_buffer")")"

From 0b553b3d3bfd200abf229d4364d32df1308e161a Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?As=C4=B1m=20Atasert?= <asimatasert@outlook.com>
Date: Thu, 16 Jul 2026 14:35:57 +0300
Subject: [PATCH 3/3] chore: add 3.10.0 debian changelog entry

---
 debian/changelog | 11 +++++++++++
 1 file changed, 11 insertions(+)

diff --git a/debian/changelog b/debian/changelog
index 11c62c8..2124229 100644
--- a/debian/changelog
+++ b/debian/changelog
@@ -1,3 +1,14 @@
+t-pgsql (3.10.0-1) unstable; urgency=medium
+
+  * New features for SSH dumps:
+    - --compress-where source|target: compress on the source host before
+      the transfer (falls back to target-side if the tool is missing)
+    - --from-stale <time>: purge leftover staging dumps from failed runs
+      on the source before dumping (default 72h, with --from-keep 0)
+    - Widened retention/fetch globs to match compressed staging artifacts
+
+ -- Asim Atasert <asimatasert@outlook.com>  Wed, 16 Jul 2026 15:00:00 +0300
+
 t-pgsql (3.9.0-1) unstable; urgency=medium
 
   * Packaging and audit remediation: