[IMP] database_cleanup: purge orphaned attachments

Add wizard to list ir.attachment records whose store_fname points to a
missing file on disk when storage is "file", and allow purging those
rows.

task 5258

Author: Aldeigja

database_cleanup/README.rst

@@ -1,3 +1,7 @@
+.. image:: https://odoo-community.org/readme-banner-image
+   :target: https://odoo-community.org/get-involved?utm_source=readme
+   :alt: Odoo Community Association
+
 ================
 Database cleanup
 ================
@@ -13,7 +17,7 @@ Database cleanup
 .. |badge1| image:: https://img.shields.io/badge/maturity-Beta-yellow.png
     :target: https://odoo-community.org/page/development-status
     :alt: Beta
-.. |badge2| image:: https://img.shields.io/badge/licence-AGPL--3-blue.png
+.. |badge2| image:: https://img.shields.io/badge/license-AGPL--3-blue.png
     :target: http://www.gnu.org/licenses/agpl-3.0-standalone.html
     :alt: License: AGPL-3
 .. |badge3| image:: https://img.shields.io/badge/github-OCA%2Fserver--tools-lightgray.png?logo=github
@@ -28,8 +32,8 @@ Database cleanup
 
 |badge1| |badge2| |badge3| |badge4| |badge5|
 
-Clean your Odoo database from remnants of modules, models, columns and
-tables left by uninstalled modules (prior to 7.0) or a homebrew database
+Clean your Odoo database from remnants of modules, models, columns, tables and
+attachment records left by uninstalled modules (prior to 7.0) or a homebrew database
 upgrade to a new major version of Odoo.
 
 Caution! This module is potentially harmful and can *easily* destroy the
@@ -48,7 +52,7 @@ Usage
 
 After installation of this module, go to the Settings menu -> Technical ->
 Database cleanup. This menu is only available to members of the *Access Rights*
-group. Go through the modules, models, columns and tables
+group. Go through the modules, models, columns, tables and attachment
 entries under this menu (in that order) and find out if there is orphaned data
 in your database. You can either delete entries by line, or sweep all entries
 in one big step (if you are *really* confident).

database_cleanup/__manifest__.py

@@ -20,6 +20,7 @@
         "views/purge_data.xml",
         "views/create_indexes.xml",
         "views/purge_properties.xml",
+        "views/purge_attachments.xml",
         "views/menu.xml",
         "security/ir.model.access.csv",
     ],

database_cleanup/models/__init__.py

@@ -4,6 +4,7 @@
 from . import purge_fields
 from . import purge_columns
 from . import purge_tables
+from . import purge_attachments
 from . import purge_data
 from . import purge_menus
 from . import create_indexes

database_cleanup/models/purge_attachments.py

@@ -0,0 +1,82 @@
+# Copyright 2026 Cetmix
+# License AGPL-3.0 or later (http://www.gnu.org/licenses/agpl.html).
+
+import os
+
+from odoo import _, api, fields, models
+from odoo.exceptions import UserError
+
+
+class CleanupPurgeLineAttachment(models.TransientModel):
+    _inherit = "cleanup.purge.line"
+    _name = "cleanup.purge.line.attachment"
+    _description = "Cleanup Purge Line Attachment"
+
+    attachment_id = fields.Many2one("ir.attachment")
+    wizard_id = fields.Many2one("cleanup.purge.wizard.attachment", readonly=True)
+
+    def purge(self):
+        """Unlink orphaned attachment records upon manual confirmation.
+
+        Filters unpurged lines with attachment_id, unlinks their ir.attachment
+        records, and marks lines as purged.
+        :return: result of to_unlink.write({"purged": True})
+        """
+        if self:
+            objs = self
+        else:
+            objs = self.env["cleanup.purge.line.attachment"].browse(
+                self._context.get("active_ids")
+            )
+        to_unlink = objs.filtered(lambda x: not x.purged and x.attachment_id)
+        self.logger.info("Purging attachments: %s", to_unlink.mapped("name"))
+        to_unlink.mapped("attachment_id").unlink()
+        return to_unlink.write({"purged": True})
+
+
+class CleanupPurgeWizardAttachment(models.TransientModel):
+    _inherit = "cleanup.purge.wizard"
+    _name = "cleanup.purge.wizard.attachment"
+    _description = "Purge attachments"
+
+    @api.model
+    def find(self):
+        """Collect ir.attachment records whose backing files are missing on disk.
+
+        Requires file storage. Searches binary attachments with store_fname,
+        checks each file exists via os.path.isfile(_full_path(store_fname)).
+
+        :raises UserError: if storage != "file" or no orphaned entries found
+        """
+        if self.env["ir.attachment"]._storage() != "file":
+            raise UserError(
+                _(
+                    "Attachment storage is not 'file'. "
+                    "Purge of orphaned attachments only works with file storage."
+                )
+            )
+        res = []
+        attachments = self.env["ir.attachment"].search(
+            [
+                ("store_fname", "!=", False),
+                ("type", "=", "binary"),
+            ]
+        )
+        for attach in attachments:
+            full_path = self.env["ir.attachment"]._full_path(attach.store_fname)
+            if not os.path.isfile(full_path):
+                res.append(
+                    (
+                        0,
+                        0,
+                        {
+                            "attachment_id": attach.id,
+                            "name": attach.store_fname or attach.name or str(attach.id),
+                        },
+                    )
+                )
+        if not res:
+            raise UserError(_("No orphaned attachment entries found"))
+        return res
+
+    purge_line_ids = fields.One2many("cleanup.purge.line.attachment", "wizard_id")

database_cleanup/readme/DESCRIPTION.rst

@@ -1,5 +1,5 @@
-Clean your Odoo database from remnants of modules, models, columns and
-tables left by uninstalled modules (prior to 7.0) or a homebrew database
+Clean your Odoo database from remnants of modules, models, columns, tables and
+attachment records left by uninstalled modules (prior to 7.0) or a homebrew database
 upgrade to a new major version of Odoo.
 
 Caution! This module is potentially harmful and can *easily* destroy the

database_cleanup/readme/USAGE.rst

@@ -1,6 +1,6 @@
 After installation of this module, go to the Settings menu -> Technical ->
 Database cleanup. This menu is only available to members of the *Access Rights*
-group. Go through the modules, models, columns and tables
+group. Go through the modules, models, columns, tables and attachment
 entries under this menu (in that order) and find out if there is orphaned data
 in your database. You can either delete entries by line, or sweep all entries
 in one big step (if you are *really* confident).

database_cleanup/security/ir.model.access.csv

@@ -17,3 +17,5 @@ access_cleanup_purge_line_menu,access_cleanup_purge_line_menu,model_cleanup_purg
 access_cleanup_purge_wizard_menu,access_cleanup_purge_wizard_menu,model_cleanup_purge_wizard_menu,base.group_user,1,1,1,1
 access_cleanup_purge_line_property,access_cleanup_purge_line_property,model_cleanup_purge_line_property,base.group_user,1,1,1,1
 access_cleanup_purge_wizard_property,access_cleanup_purge_wizard_property,model_cleanup_purge_wizard_property,base.group_user,1,1,1,1
+access_cleanup_purge_line_attachment,access_cleanup_purge_line_attachment,model_cleanup_purge_line_attachment,base.group_user,1,1,1,1
+access_cleanup_purge_wizard_attachment,access_cleanup_purge_wizard_attachment,model_cleanup_purge_wizard_attachment,base.group_user,1,1,1,1

database_cleanup/static/description/index.html

@@ -3,7 +3,7 @@
 <head>
 <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
 <meta name="generator" content="Docutils: https://docutils.sourceforge.io/" />
-<title>Database cleanup</title>
+<title>README.rst</title>
 <style type="text/css">
 
 /*
@@ -360,18 +360,23 @@
 </style>
 </head>
 <body>
-<div class="document" id="database-cleanup">
-<h1 class="title">Database cleanup</h1>
+<div class="document">
 
+
+<a class="reference external image-reference" href="https://odoo-community.org/get-involved?utm_source=readme">
+<img alt="Odoo Community Association" src="https://odoo-community.org/readme-banner-image" />
+</a>
+<div class="section" id="database-cleanup">
+<h1>Database cleanup</h1>
 <!-- !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
 !! This file is generated by oca-gen-addon-readme !!
 !! changes will be overwritten.                   !!
 !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
 !! source digest: sha256:8e972dd8d647163c6d93e026514d854ced08bbe13ac2c39e3a7c36202e1aa328
 !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! -->
-<p><a class="reference external image-reference" href="https://odoo-community.org/page/development-status"><img alt="Beta" src="https://img.shields.io/badge/maturity-Beta-yellow.png" /></a> <a class="reference external image-reference" href="http://www.gnu.org/licenses/agpl-3.0-standalone.html"><img alt="License: AGPL-3" src="https://img.shields.io/badge/licence-AGPL--3-blue.png" /></a> <a class="reference external image-reference" href="https://github.com/OCA/server-tools/tree/16.0/database_cleanup"><img alt="OCA/server-tools" src="https://img.shields.io/badge/github-OCA%2Fserver--tools-lightgray.png?logo=github" /></a> <a class="reference external image-reference" href="https://translation.odoo-community.org/projects/server-tools-16-0/server-tools-16-0-database_cleanup"><img alt="Translate me on Weblate" src="https://img.shields.io/badge/weblate-Translate%20me-F47D42.png" /></a> <a class="reference external image-reference" href="https://runboat.odoo-community.org/builds?repo=OCA/server-tools&amp;target_branch=16.0"><img alt="Try me on Runboat" src="https://img.shields.io/badge/runboat-Try%20me-875A7B.png" /></a></p>
-<p>Clean your Odoo database from remnants of modules, models, columns and
-tables left by uninstalled modules (prior to 7.0) or a homebrew database
+<p><a class="reference external image-reference" href="https://odoo-community.org/page/development-status"><img alt="Beta" src="https://img.shields.io/badge/maturity-Beta-yellow.png" /></a> <a class="reference external image-reference" href="http://www.gnu.org/licenses/agpl-3.0-standalone.html"><img alt="License: AGPL-3" src="https://img.shields.io/badge/license-AGPL--3-blue.png" /></a> <a class="reference external image-reference" href="https://github.com/OCA/server-tools/tree/16.0/database_cleanup"><img alt="OCA/server-tools" src="https://img.shields.io/badge/github-OCA%2Fserver--tools-lightgray.png?logo=github" /></a> <a class="reference external image-reference" href="https://translation.odoo-community.org/projects/server-tools-16-0/server-tools-16-0-database_cleanup"><img alt="Translate me on Weblate" src="https://img.shields.io/badge/weblate-Translate%20me-F47D42.png" /></a> <a class="reference external image-reference" href="https://runboat.odoo-community.org/builds?repo=OCA/server-tools&amp;target_branch=16.0"><img alt="Try me on Runboat" src="https://img.shields.io/badge/runboat-Try%20me-875A7B.png" /></a></p>
+<p>Clean your Odoo database from remnants of modules, models, columns, tables and
+attachment records left by uninstalled modules (prior to 7.0) or a homebrew database
 upgrade to a new major version of Odoo.</p>
 <p>Caution! This module is potentially harmful and can <em>easily</em> destroy the
 integrity of your data. Do not use if you are not entirely comfortable
@@ -392,10 +397,10 @@ <h1 class="title">Database cleanup</h1>
 </ul>
 </div>
 <div class="section" id="usage">
-<h1><a class="toc-backref" href="#toc-entry-1">Usage</a></h1>
+<h2><a class="toc-backref" href="#toc-entry-1">Usage</a></h2>
 <p>After installation of this module, go to the Settings menu -&gt; Technical -&gt;
 Database cleanup. This menu is only available to members of the <em>Access Rights</em>
-group. Go through the modules, models, columns and tables
+group. Go through the modules, models, columns, tables and attachment
 entries under this menu (in that order) and find out if there is orphaned data
 in your database. You can either delete entries by line, or sweep all entries
 in one big step (if you are <em>really</em> confident).</p>
@@ -404,23 +409,23 @@ <h1><a class="toc-backref" href="#toc-entry-1">Usage</a></h1>
 </a>
 </div>
 <div class="section" id="bug-tracker">
-<h1><a class="toc-backref" href="#toc-entry-2">Bug Tracker</a></h1>
+<h2><a class="toc-backref" href="#toc-entry-2">Bug Tracker</a></h2>
 <p>Bugs are tracked on <a class="reference external" href="https://github.com/OCA/server-tools/issues">GitHub Issues</a>.
 In case of trouble, please check there if your issue has already been reported.
 If you spotted it first, help us to smash it by providing a detailed and welcomed
 <a class="reference external" href="https://github.com/OCA/server-tools/issues/new?body=module:%20database_cleanup%0Aversion:%2016.0%0A%0A**Steps%20to%20reproduce**%0A-%20...%0A%0A**Current%20behavior**%0A%0A**Expected%20behavior**">feedback</a>.</p>
 <p>Do not contact contributors directly about support or help with technical issues.</p>
 </div>
 <div class="section" id="credits">
-<h1><a class="toc-backref" href="#toc-entry-3">Credits</a></h1>
+<h2><a class="toc-backref" href="#toc-entry-3">Credits</a></h2>
 <div class="section" id="authors">
-<h2><a class="toc-backref" href="#toc-entry-4">Authors</a></h2>
+<h3><a class="toc-backref" href="#toc-entry-4">Authors</a></h3>
 <ul class="simple">
 <li>Therp BV</li>
 </ul>
 </div>
 <div class="section" id="contributors">
-<h2><a class="toc-backref" href="#toc-entry-5">Contributors</a></h2>
+<h3><a class="toc-backref" href="#toc-entry-5">Contributors</a></h3>
 <ul class="simple">
 <li>Stefan Rijnhart &lt;<a class="reference external" href="mailto:stefan&#64;opener.amsterdam">stefan&#64;opener.amsterdam</a>&gt;</li>
 <li>Holger Brunn &lt;<a class="reference external" href="mailto:hbrunn&#64;therp.nl">hbrunn&#64;therp.nl</a>&gt;</li>
@@ -437,7 +442,7 @@ <h2><a class="toc-backref" href="#toc-entry-5">Contributors</a></h2>
 </ul>
 </div>
 <div class="section" id="maintainers">
-<h2><a class="toc-backref" href="#toc-entry-6">Maintainers</a></h2>
+<h3><a class="toc-backref" href="#toc-entry-6">Maintainers</a></h3>
 <p>This module is maintained by the OCA.</p>
 <a class="reference external image-reference" href="https://odoo-community.org">
 <img alt="Odoo Community Association" src="https://odoo-community.org/logo.png" />
@@ -450,5 +455,6 @@ <h2><a class="toc-backref" href="#toc-entry-6">Maintainers</a></h2>
 </div>
 </div>
 </div>
+</div>
 </body>
 </html>

database_cleanup/tests/__init__.py

@@ -4,6 +4,7 @@
 from . import common
 from . import test_create_indexes
 from . import test_identifier_adapter
+from . import test_purge_attachments
 from . import test_purge_columns
 from . import test_purge_data
 from . import test_purge_fields

database_cleanup/tests/test_purge_attachments.py

@@ -0,0 +1,74 @@
+# Copyright 2026 Cetmix
+# License AGPL-3.0 or later (http://www.gnu.org/licenses/agpl.html).
+
+import base64
+import os
+
+from odoo.tests.common import tagged
+
+from .common import Common, environment
+
+
+# Use post_install to get all models loaded more info: odoo/odoo#13458
+@tagged("post_install", "-at_install")
+class TestCleanupPurgeLineAttachment(Common):
+    def setUp(self):
+        """Create two ir.attachment records; delete backing file of one (orphan).
+
+        :var orphan: ir.attachment with backing file removed via os.unlink
+        :var valid: ir.attachment with file intact
+        :return: None
+        """
+        super().setUp()
+        with environment() as env:
+            IrAttachment = env["ir.attachment"]
+            datas = base64.b64encode(b"test_orphan").decode("ascii")
+            orphan = IrAttachment.create(
+                {
+                    "name": "test_orphan_attachment.txt",
+                    "type": "binary",
+                    "datas": datas,
+                }
+            )
+            datas_valid = base64.b64encode(b"test_valid").decode("ascii")
+            valid = IrAttachment.create(
+                {
+                    "name": "test_valid_attachment.txt",
+                    "type": "binary",
+                    "datas": datas_valid,
+                }
+            )
+            # Delete backing file to create orphan
+            full_path = IrAttachment._full_path(orphan.store_fname)
+            os.unlink(full_path)
+            self.orphan_attach_id = orphan.id
+            self.valid_attach_id = valid.id
+
+    def test_find_orphaned_attachments(self):
+        """Assert wizard find() includes orphan in purge lines, excludes valid.
+
+        :var wizard: cleanup.purge.wizard.attachment
+        :var line_attachment_ids: ids from purge_line_ids.mapped("attachment_id")
+        :return: None
+        """
+        with environment() as env:
+            wizard = env["cleanup.purge.wizard.attachment"].create({})
+            line_attachment_ids = wizard.purge_line_ids.mapped("attachment_id").ids
+            self.assertIn(self.orphan_attach_id, line_attachment_ids)
+            self.assertNotIn(self.valid_attach_id, line_attachment_ids)
+
+    def test_purge_orphaned_attachments(self):
+        """Assert purge_all() removes orphan record, leaves valid intact.
+
+        :var wizard: cleanup.purge.wizard.attachment
+        :var orphan: ir.attachment browsed by self.orphan_attach_id
+        :var valid: ir.attachment browsed by self.valid_attach_id
+        :return: None
+        """
+        with environment() as env:
+            wizard = env["cleanup.purge.wizard.attachment"].create({})
+            wizard.purge_all()
+            orphan = env["ir.attachment"].browse(self.orphan_attach_id)
+            valid = env["ir.attachment"].browse(self.valid_attach_id)
+            self.assertFalse(orphan.exists())
+            self.assertTrue(valid.exists())