Switch to the Database Attachment Store

Last modified by Eleni Cojocariu on 2026/09/25 02:48

Steps

Switch the wiki to the database attachment store, which keeps attachment content in the database instead of on disk, one of the two stores The Attachment Store compares.

Warning

On MySQL, raise max_allowed_packet before you start. The content of an attachment and its whole version history are written as single values, in one query, so plan on about three times the size of your largest attachment, and more where attachments have long histories. Packet for query is too large is what a value set too low looks like.

  1. Stop XWiki.
  2. Open xwiki/WEB-INF/xwiki.cfg and set the four storage hints to hibernate:
    xwiki.store.attachment.hint=hibernate
    xwiki.store.attachment.versioning.hint=hibernate
    xwiki.store.attachment.recyclebin.content.hint=hibernate
    xwiki.store.recyclebin.content.hint=hibernate

    All four ship commented out, so uncommenting them is part of the change: a line left commented keeps its default whatever value you wrote on it. The last of the four is the store for deleted Pages rather than for deleted attachments, and it belongs here because a Page carries its attachments with it into the recycle bin.

  3. Start XWiki again.
  4. Attach a file to any Page, then look for its content in the database:
    SELECT COUNT(*) FROM xwikiattachment_content;

    The table gains a row, the file you have just attached. It does not gain a row for every attachment already in the wiki, and nothing new appears under store/file in the permanent directory: the older attachments are still on disk, exactly as they were.

From here on the wiki is under the size ceiling of the database store: an attachment much larger than 30 MB cannot be saved, for the reason The Attachment Store gives.

FAQ

Does this move the attachments already on disk?

No. This is a configuration change, not a migration: it sets the store used for the next attachment saved, and every attachment already written to the filesystem stays there and is still served from there.

What does each of the four storage hints decide?

Optional Store Features describes them one by one. The fourth is the store for deleted Pages rather than for deleted attachments, and it belongs in the same change because a Page carries its attachments with it into the recycle bin.

Related

Get Connected