📦 n8n-workflow-backup

🚀 Automated incremental backup tool for n8n workflows stored in PostgreSQL.
💾 Herramienta de respaldo incremental automatizado para los workflows de n8n almacenados en PostgreSQL.

📌 Overview / Descripción general

English:
n8n-workflow-backup is a secure and configurable Python-based tool that performs local, incremental backups of your n8n workflows stored in PostgreSQL. It uses the updatedAt field to detect changes and stores only modified workflows, avoiding duplication and saving space.

Español:
n8n-workflow-backup es una herramienta segura y configurable basada en Python que realiza respaldos incrementales locales de los workflows de n8n almacenados en PostgreSQL. Utiliza el campo updatedAt para detectar cambios y respalda solo los workflows modificados, evitando duplicaciones y ahorrando espacio.

✨ Features / Características

• ✅ Incremental backups based on workflow changes
• 📦 JSON export + ZIP packaging
• 📁 UTC timestamps for cross-timezone consistency
• 🔐 Safe cleanup with protective markers
• 📄 Output metadata for integration (.env.output)
• ⚙️ Cron and systemd automation examples

🔐 Security & Safety / Seguridad y protección

Defense Mechanism	Description
Marker files	Temporary folders are only deleted if a .n8n-backup-marker exists.
UTC timestamps	Avoids errors due to time zone differences between backup clients and the server.
Critical path checks	The script avoids deleting risky system directories like /tmp, /var, /etc, etc.
No modification of n8n DB	Only reads workflows. No schema changes.

⚙️ Requirements / Requisitos

• Python 3.7 or higher
• PostgreSQL database with n8n
• Only local filesystem (for now)

📥 Installation / Instalación

📦 Using pip

python3 -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt

⚡ Using uv

uv venv
source .venv/bin/activate
uv pip install -r requirements.txt

🧪 Using Poetry

poetry install
poetry run python backup_workflows_incremental.py

🔧 Configuration (.env)

Create a .env file in the root directory:

POSTGRES_HOST=localhost
POSTGRES_PORT=5432
POSTGRES_DB=n8n
POSTGRES_USER=your_user
POSTGRES_PASSWORD=your_password

REPO_ROOT=/your/path/to/backups
TEMP_FOLDER_NAME=/tmp/n8n_exports
CLEAN_TEMP=true

A .env.example file is included as a template.

🧾 Output File (.env.output)

After a successful backup, the script generates .env.output with useful variables:

LAST_N8N_BACKUP_ZIP=/path/to/n8n-backup-2025-07-16_14-02-33.zip
LAST_N8N_BACKUP_TIMESTAMP=2025-07-16_14-02-33
LAST_N8N_BACKUP_TIMESTAMP_UTC=2025-07-16T14:02:33Z
LAST_N8N_BACKUP_SIZE_BYTES=12450
LAST_N8N_BACKUP_NUM_FILES=12
LAST_N8N_BACKUP_DURATION_SEC=2.89

🕒 Automation / Automatización

📆 Using Cron

Example crontab (runs daily at 2am):

0 2 * * * /path/to/backup-cron.sh

Include environment loading in backup-cron.sh:

#!/bin/bash
cd /path/to/n8n-workflow-backup
source .venv/bin/activate
python backup_workflows_incremental.py

⏱️ Using Systemd

Include these two files in your repo:

backup.service

[Unit]
Description=n8n Workflow Backup

[Service]
Type=oneshot
WorkingDirectory=/path/to/n8n-workflow-backup
ExecStart=/path/to/n8n-workflow-backup/.venv/bin/python backup_workflows_incremental.py

backup.timer

[Unit]
Description=Daily n8n Workflow Backup

[Timer]
OnCalendar=*-*-* 02:00:00
Persistent=true

[Install]
WantedBy=timers.target

Enable with:

sudo systemctl enable --now backup.timer

📄 License / Licencia

This project is licensed under the MIT License.
You may copy, modify, and distribute this software freely, but attribution to the original author must be maintained.

👤 Author / Autor

Developed and maintained by VisX
MIT License included