Mautic DevOps & Maintenance Toolkit

A collection of high-performance Bash and SQL utilities designed for advanced Mautic administration. This toolkit is specifically built to run securely outside the Mautic web root, offering a "surgical" approach to database integrity, cleanup, and synchronization.

---

🛠 Global Setup & Configuration

To ensure security and ease of use across the entire suite, the scripts use a shared environment file to locate your Mautic instance.

1. Project Structure

It is recommended to keep these scripts in a dedicated maintenance folder (e.g., /home/user/mautic-tools/) rather than the public web directory.

2. Create Environment File (.env)

Create a file named .env in the root of this repository:

# Path to your Mautic root directory (without trailing slash)
# Example for a Cloudron environment: /app/data/public
MAUTIC_ROOT="/app/data/public"

3. Set Permissions

Ensure the scripts are executable:

chmod +x *.sh

---

📋 Script Catalog

1. mautic_clean_submissions.sh

Purpose: Deep-cleans form submission history for a specific lead.

In Mautic, deleting a contact via the UI often fails to purge data from the the many dynamic form_results_... tables. This script maps a Lead's email to their submission history and removes all traces from both the master log and the dynamic result tables.

Usage:

By default, the script runs in Dry Run Mode (preview only).

• Preview changes:

  ./mautic_clean_submissions.sh user@example.com

• Execute deletion:

  ./mautic_clean_submissions.sh user@example.com --confirm

Features:

• Multi-Form Awareness: Cleans all unique form tables associated with a single lead.
• Integrity Logic: Deletes child records (results) before parent records (log) to prevent SQL orphans.
• Dry Run Safety: Prevents accidental data loss by requiring an explicit confirmation flag.
• Credential Discovery: Automatically extracts DB access from Mautic’s local.php.

---

🔍 Technical Background: The "Orphan" Problem

Mautic's database can often fall out of sync, leading to discrepancies between the UI and SQL counts. This usually happens in three stages:

1. The Ghost Content: Rows exist in form_results_X but the master ID in form_submissions is gone.
2. The Orphan Log: Rows exist in form_submissions but the lead_id no longer exists in the leads table.
3. The UI Filter: Mautic's frontend only shows submissions linked to active leads, hiding the "orphans" still bloating your database.

This toolkit aims to resolve these discrepancies.

---

⚠️ Safety & Disclaimer

Caution

Database manipulation bypasses Mautic's application layer. These scripts perform hard deletes on your production data.

• Always perform a full database backup before running maintenance scripts.
• Test scripts on a staging environment or with specific test emails first.
• These tools are intended for GDPR "Right to be Forgotten" compliance and clearing test data.

---

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.