Attachment Storage Configuration

Database attachment storage was deprecated in Confluence 5.5. If you currently store attachments in the database you will be able to continue to do so, but you will be unable to switch to storing attachments in the database in Confluence 5.5 or later.

System Administrators can configure where Confluence stores attachments. Attachments can be stored in a:

  • File system - locally in the Confluence home directory, or
  • Database - in Confluence's configured database (deprecated)

To configure Confluence attachment storage:

  • Choose the cog icon , then choose General Configuration under Confluence Administration
  • Choose Attachment Storage

On this page:

Related pages:

Attachment Storage Options

Local File System

By default, Confluence stores attachments in the attachments directory within the configured Confluence home folder.

Database (deprecated)

Confluence 5.4 and earlier gives administrators the option to store attachments in the database that Confluence is configured to use.

While storing attachments in the database can offer some advantages (such as ease of backup, and avoiding issues with some characters in attachment filenames), please be aware that the amount of space used by the database will increase because of greater storage requirements.

Migrating between attachment storage systems

You can migrate your attachments from one storage system to another. All existing attachments will be moved over to the new attachment storage system.

When the migration occurs, all other users will be locked out of the Confluence instance. This is to prevent modification of attachments while the migration occurs. Access will be restored as soon as the migration is complete.

When migrating attachments from your database to a filesystem, the attachments are removed from the database after migration. However, when migrating attachments from a filesystem to your database, the attachments remain on the filesystem after migration.

To improve logging during the migration, add the package com.atlassian.confluence.pages.persistence.dao with level DEBUG. See Configuring Logging for more information.

To migrate, follow the steps below:

  1. Choose the cog icon , then choose General Configuration under Confluence Administration
  2. Click 'Attachment Storage' in the left-hand panel. The current configuration will be displayed.
    Screenshot: Attachment storage configuration
  3. Click the 'Edit' button to modify the configuration.
  4. Select the storage system you desire.
    Screenshot: Edit attachment storage
  5. Click the 'Save' button to save the changes.
  6. A screen will appear, asking you to confirm your changes. Clicking 'Migrate' will take you to a screen that displays the progress of the migration.
    Screenshot: migration warning

The following external website provides further information on migrating attachments from database to file system storage that you might find helpful -

Was this helpful?

Thanks for your feedback!

Why was this unhelpful?

33 Archived comments

  1. User avatar

    Guy Fraser (Adaptavist)

    Is there any way for hosting companies to stop administrators from storing the files in the database? We're moving our database on to a seperate server and having attachments stored in there would be a major nightmare.

    22 Mar 2006
    1. User avatar

      Tom Davies [Atlassian]

      You can change the .vm file to remove that option.


      22 Mar 2006
  2. User avatar

    David Nessl

    Has this setup been tried with the mod_dav_svn module in Apache 2.2?  This module provides WebDAV service, where files are stored in a Subversion (version control) repository.  I can configure Confluence (2.3.3) to use this type of WebDAV server for attachment storage, then the migration takes several minutes to run (as expected), but no files show up in the Subversion repository (almost as if the files were transfered but no "commits" never happened). 

    28 Feb 2007
    1. User avatar

      Matt Ryall [Atlassian]

      Although I haven't tested it, I don't think the WebDAV attachment storage works as you would expect with Subversion as a back-end. I'm basing this on the fact that there's a third-party plugin to provide exactly this functionality, although it's still in the alpha development phase.

      Try adding the extra logging as described in Troubleshooting above. If you think there's a bug in our WebDAV support, please raise a support case, and attach your logs. We'll investigate further from there.

      02 Apr 2007
      1. User avatar

        David Peterson [CustomWare]

        I believe you are correct about SVN+WebDAV - I tried using it that way myself a couple of days ago (in a different context) and it wasn't cooperative.

        02 Apr 2007
  3. User avatar

    Scott Conroy

    Really unhappy to see the WebDAV support for attachments being deprecated. My company is currently using the file storage option but we were planning to migrate to WebDAV in the near future.

    19 Dec 2007
  4. User avatar

    Phil Beck

    My confluence installation is on a linux server.  I've created a link for the attachments directory off to an NFS mount point.  It seems to be working just fine.  Has anyone encountered any issues using NFS as an attachments location?

    25 Jun 2008
    1. User avatar

      Tony Cheah Tong Nyee

      Hi Phil,

      We have not test on such configuration in depth and NFS storage is not a configuration we support. Although, we do have customers using such configuration successfully, a networked filesystem is something we like to eliminate as a potential cause of problems in support cases.
      However, the following could be the potential risks that you might want to consider:

      • Network failure
      • Two separate threads writing to an attachment could cause file corruption. This would mean two separate users writing the same attachment which is probably unlikely, but the risk still exists.

      Hope it helps.


      26 Jun 2008
  5. User avatar

    Semir Hasanbegovic


    Any recommendations on whether one should use the database for attachment storage (in our case MySQL 5) or the File System (Linux ext3)?

    We currently use the DB and it almost seems that Atlassian recommend this but I've heard people say that storing a lot of data in the DB as BLOBs is not a very good idea.

    Any thoughts?

    Our attachment data is about a GIG in size now.

    My understanding is that MySQL does not have a size limit (other than the limit of the disk it is on) so we'd be happy to keep using it unless it is better to use the FS in the long run.

    I'm not an MySQL expert so I'd appreciate some thoughts from people here.

    Many Thanks


    01 Sep 2008
    1. User avatar

      Ivo Verlaek [Atlassian Partner] Platinum Specialist

      It usually has something to do with the backup facilities of your IT Department.

      Not storing the data within your database creates two locations for your backup strategy (Database and File System).
      The backup's of each of these smaller parts are a little bit faster on it's own.

      The attachments could be stored on a NAS Drive which could be easier to implement as extending your DB.

      Storing everything on the database makes backing it up a little easier for your IT Department, as regular backups should always be performed on all your database content. The procedures are well known and they do not have to be linked to another backup with files from your file system (could be an administrative problem).

      Another reason for storing everything in the database could be a possible future migration to a confluence clustered environment.

      I usually say:
      Do whatever your IT Department thinks is best.
      Use the tools they are most familiar with as there is no big difference.

      01 Sep 2008
      1. User avatar


        Our IT people are telling us that we should see a performance boost (which we really need) by moving the attachments out of the DB and back into the filesystem, particularly as the DB is on a separate Oracle server. Has anyone seen any such improvements in the one over the other in terms of performance?

        17 Feb 2009
        1. User avatar

          Henry Tiong [Atlassian]

          Hi there,

          Though we don't have a concrete whitepaper to support this, but based on my experience, so far I haven't seen any issue with Confluence due to storing attachments in the file system. In your case however, since your DB is residing on a different machine, do note of the network latency when your Confluence is trying to retrieve/store the attachments, thought it might not be that significant if it is in the same LAN. Other performance gain that I can think of is that it your periodically database backup/dump files will definitely be much smaller.

          hope this helps,
          Henry CL Tiong
          Atlassian Support Team

          18 Feb 2009
  6. User avatar

    David Vonka

    Is there any issue with attachment size ? Our administrator tells us we should not 'use confluence as Rapidshare', i.e. upload attachments
    larger than say 5 MB. We do use quite some videocasts in our company, so the need for big uploads appears reguralry. We store the attachments in the
    filesystem. Any advice would be welcome. Thanks.

    20 Feb 2009
    1. User avatar

      Zed Yap [Atlassian]

      Hi David,

      As far as I know, there should not be any issue regarding attaching a large file size. The only thing that you have to ensure is your local disks have sufficient space.

      Hope that helps.

      Best rgds,

      25 Feb 2009
  7. User avatar



    I am interested in the comment above RE NFS - "We have not test on such configuration in depth and NFS storage is not a configuration we support".  Is this statement still true?

    23 Sep 2009
  8. User avatar

    Malte Krueger

    I am really interested in the NFS thing as well. We are currently implementing a SAN / NAS solution and i am wondering if it is possible to store the attachments in there via NFS?

    23 Feb 2011
  9. User avatar



    Is the performance of the Wiki Server impacted if we attach documents (PDF, doc, ppt etc.) to a wiki page? If yes, in what way the performance will be impacted for example, in terms of high page call-up times, server unavailable error 503 etc.,?

    Can you please share any link where the impact of the wiki server is considerable by having attachments to the Wiki page for a multiple wiki space scenario within the server?

    Thank you in advance. 

    16 Jun 2011
  10. User avatar

    Diane Sexton

    Just wanted to share that we got an error message recently. The user was trying to use Insert Link > Attachments to add a file to a page. He got an error "Could not upload the file to Confluence. The server may be unavailable."

    This was misleading because the server (which server by the way?) where the file is stored was accessible as was, obviously, the Confluence server, and less obviously, the attachments storage directory.

    It turned out that it was because the file size of the upload was bigger than the currently configured attachment file size limit.

    We got a clearer error message when uploading via Add > Attachment: "Total upload size is too large (current_upload_limit_in_MB). Reduce total filesize to below current_upload_limit_in_MB."

    The error message in the Insert Link dialog is not helpful.

    26 Jun 2012
    1. User avatar

      Robert Ellis

      I have also noticed that a user can log in, attempt to upload an image using the browse capability, it will give the message "Could not upload the file to Confluence. The server may be unavailable."  Though if I drag and drop, it works.


      18 Jul 2012
  11. User avatar

    James Roberts

    How does a migration from filesystem to database happen behind the scenes? Is it one move with a single commit at the end for all of the attachments? Any special steps need to be taken to ensure that a migration of a large amount of data (~500GB) can be accomplished without failing?

    20 Feb 2013
  12. User avatar

    ChangJoon Lee

    1. In performance wise, would Database perform like filesystem via Tomcat?
    2. If files are stored in Database, who is managing caching of attachments? 
    3. What does it mean by all records?
      1. In Migration Notes in above image, "Prior to migration, all records in the Attachment data database table will be removed."
      2. Does it mean like version history?
    4. What happens during Migration? What will users see during migration? Is server locked down?
    5. Migrating to Database, will it affect WebDav clients or any related feature? 
    6. Can we switch back to Filesystem after migrating to Database?

    Thank you~


    29 Mar 2013
  13. User avatar




    we have a lot of attachments and to check if they are all actual takes almost two days. The files are on a linux server and if there are made changes on a document it should be also updated in Confluence. That's the theory, in real life the responsible persons make changes and save the document but do not update the file (attachment) in Confluence.

    Is there a way to automation compare the Confluence attachments directly with the files on the server? If you have an other idea, please let me know

    I couldn't found anything in the documentation this is to special.


    Many thanks




    15 May 2013
  14. User avatar

    Ilke Tutku Senol


    I've newly installed Confluence 5.5.2 to my local server. 

    I'm using SSD disks for Server. When I installed Confluence, It just selected the "Locally in Confluence home directory" directory for attachments. I want to use another Chipper disk for attachments and I need to change this directory. Is there any way to do it? 



    30 May 2014
    1. User avatar


      Hi Ilke,

      please have a look at your confluence.cfg.xml, there's a property named attachments.dir which defines where attachments will be stored. The default looks like this:

      <property name="attachments.dir">${confluenceHome}/attachments</property>



      30 May 2014
      1. User avatar

        Ilke Tutku Senol

        Hi Alex,

        Thank you for the information. I solved my problem. 

        More Information for other users:

        If you want to use external directory, 

        1. you must create a user in your server (confuser)
        2. from services.msc you must assign this user as a service user for Atlassian Confluence
        3. In that directory that you want to use for attachment, you must create a directory and set the permissions for your user. 



        30 May 2014
  15. User avatar

    Choelmin LEE

    Database (deprecated)


    Is this apply to cluster version?

    04 Jul 2014
    1. User avatar

      Rachel Robins [Atlassian Tech Writer]

      Hi Choelmin, We are working on a new clustering solution that will not require you to store attachments in the database (as was the case with the current clustering solution). 

      In Confluence 5.5 we prevented users from switching to storing attachments in the database, but if you are already storing attachments in the database it will continue to work fine (standalone or in a cluster). 

      06 Jul 2014
  16. User avatar

    Kevin Gilchrist

    We have looking into why our attachments conte is not indexed and concluded that it is because they are stored on the filesystem.

    It seems that attachment content is only indexes if in the database, but that is now deprecated.

    How can we search the attachment content?  That is a critical feature for us and a major selling point of the product.

    10 Jul 2014
  17. User avatar

    Jens Rapp

    although knowing that large objects are something which shouldn't be held in a database, we may not come around this for a while. does this mean that we can't update anymore or is there any way to keep database stored attachments after upgrading?

    Maybe this function could be kept as an add-on?

    11 Sep 2014
    1. User avatar

      Rachel Robins [Atlassian Tech Writer]

      Hi Jens, if you already store attachments in the database you will still be able to, even if you upgrade.  We are limiting new installations from being able to switch to storing attachments in the database. We will provide plenty of notice, and information on how to migrate if / when we actually stop supporting attachments in the db. 

      15 Sep 2014
  18. User avatar

    David Shapiro

    I have been asked to setup confluence.  What size does the database need to be, presuming I do not save attachments in the database?  How much space should I start with for filesystem(s)?  Do you make a separate filesystem just for attachments?  Do you think it wise to have the space local to the system or on NAS?  Does it matter? 

    29 Jan 2015
  19. User avatar

    Sam Hall

    Is there an associated JIRA issue for voicing any concerns regarding deprecated DB attachment storage? I've only just noticed this situation.

    06 Jul 2015
    1. User avatar

      Giles Brunning [Atlassian Technical Writer]

      Hi Sam,

      The closest one I could find was this one:

      CONF-33691 - Database attachment storage option marked as deprecated Resolved

      It's possibly not exactly what you're looking for, so feel free to raise a new issue if you like.

      19 Jul 2015
Powered by Confluence and Scroll Viewport