How is the attachment storage path constructed in JIRA?


I am wondering about the attachment storage path for JIRA. On a server that I am running, the structure of the attachments directory (/var/atlassian/application-data/jira/data/attachments/) looks like this:

`-- JSDT
    `-- 10000
        `-- JSDT-2
            |-- 10100
            `-- thumbs
                `-- _thumb_10100.png

I am currently writing a groovy script in which I need to determine the path to an attachment. In answers to questions such as, PathUtils.joinPaths() is used to construct the path. However, it does not seem to add the "10000"-directory seen above. My questions related to this are:

  • Why do I have that directory? I.e. has there been a change to the directory structure since the answer to the above linked question was written? I am running JIRA Software 7.1.2 (with JSD) and can't really remember how it looked before.
  • Where does the number 10000 come from? When is a "20000"-directory added? What is the logic behind it and its relation to the attachment IDs.
  • Are there any methods that can be used to access this?

I bet I am missing something trivial, but what I see is a bit inconsistent with what I've found when looking around answers and documentation.


1 answer

1 accepted

1 vote
Chris Fuller Atlassian Team Apr 07, 2016

We have gone through several different directory structures for attachments over the years.  Although it may seem pointless on a small system, consider for a moment that there are JIRA instances out that that have tens of thousands of issues in a single project.

Operating systems and their filesystems impose certain limits on the number of files that can be contained in a single directory.  On ext3, for example, you may not have more than 65,535 entries in a single directory.  If we used just the issue key, then as your product grew:

`-- JSDT
    |-- JSDT-1
    |  ...
    `-- JSDT-65535
    !!! JSDT-65536 !!!


At some point you wouldn't be able to attach files to any new issues because the directory entry slots would be exhausted.  This has happened before:

We changed the layout in 7.0.0 (and JRA-19873 probably should have been marked as fixed as a result).

The "10000" is a grouping number based on the issue ID (meaning the database row's ID, not the issue number that goes after the project key).  Issues that get IDs from 10000 - 19999 go into the "10000" bucket.  Those from 20000 to 29999 go into the "20000" bucket.  This way there is a worst case of 10,000 issue directories in a single bucket, which is still within the limitations set by all of our supported operating systems.  Other points:

  • The JSDT there is the original project key.  If you rename / rekey the project, the original one will still be used for this.
  • The 10000 comes from quantization of the issue ID, not the attachment ID.  The attachment ID is not related to it.
  • We consider the filesystem layout of attachments an implementation detail, not API.  It could change at any time, even in a minor release.
  • If you absolutely need to do this, there are a few APIs you can use to get to it.  Most of these are deprecated because there is no longer any guarantee that attachments live in the filesystem at all (in Cloud, for instance, they don't), but AttachmentUtils.getAttachmentDirectory is probably closest to what you want.

Thanks for the detailed explanation!

I believe that the upgrade to JIRA 7 does not change the existing directory structure, just affects new attachments

Yes, the upgrade doesn't affect previous file structure, new attachments will be created in new grouping folders.

Suggest an answer

Log in or Sign up to answer
How to earn badges on the Atlassian Community

How to earn badges on the Atlassian Community

Badges are a great way to show off community activity, whether you’re a newbie or a Champion.

Learn more
Community showcase
Published Sunday in Agility

You asked for it, so we delivered: images on issues have arrived

A picture tells a thousand words. And agility boards have just released their latest feature: cover images on issues – so now your board can tell a story at first glance. Upload attachmen...

301 views 3 11
Read article

Atlassian User Groups

Connect with like-minded Atlassian users at free events near you!

Find a group

Connect with like-minded Atlassian users at free events near you!

Find my local user group

Unfortunately there are no AUG chapters near you at the moment.

Start an AUG

You're one step closer to meeting fellow Atlassian users at your local meet up. Learn more about AUGs

Groups near you