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.


2 answers

1 accepted

1 vote
Accepted answer
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.

"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)."

This information is incorrect, the bucket is not based on the issue ID at all. It's based on the issue number (issuenum) which can be obtained by looking at the DB table jiraissue. There appears to be no way to get this number through the rest services, other than parsing the original issue key. However, as noted above, moving issues may create complications in this regard and so that shouldn't be considered a reliable source for obtaining this path.

Suggest an answer

Log in or Sign up to answer
Community showcase
Posted Tuesday in Statuspage

Introducing Statuspage Getting Started guides! First up: What is Statuspage?

Over the next several weeks we'll be sharing some of our Getting Started guides here in the community. Throughout this series of posts, we'd love to hear from customers and non-customers ab...

21 views 2 1
Join discussion

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