Showing results for 
Search instead for 
Did you mean: 
Sign up Log in

Earn badges and make progress

You're on your way to the next level! Join the Kudos program to earn points and save your progress.

Deleted user Avatar
Deleted user

Level 1: Seed

25 / 150 points

Next: Root


1 badge earned


Participate in fun challenges

Challenges come and go, but your rewards stay with you. Do more to earn more!


Gift kudos to your peers

What goes around comes around! Share the love by gifting kudos to your peers.


Rise up in the ranks

Keep earning points to reach the top of the leaderboard. It resets every quarter so you always have a chance!


Come for the products,
stay for the community

The Atlassian Community can help you and your team get more value out of Atlassian products and practices.

Atlassian Community about banner
Community Members
Community Events
Community Groups

Using mysql instead of HSQL db with Atlassian PDK

Right now Atlassian PDK runs the Confluence/Jira/... with HSQL db as a backend. Is there any way we can change this backend to say MySQL.

Issue with HSQL is, during runtime its locked by App and hence can't be opened to update/see things on fly from SQL Browser.

Any pointers?


13 answers

1 accepted

Comments for this post are closed

Community moderators have prevented the ability to post new answers.

Post a new question

17 votes
Answer accepted

Thanks to Joseph (for atlas-create-home-zip info) and Shailesh for to get around atlas-clean issue!

Below is complete Recipe to use mysql along with Atlassian PDK.

NOTE: Do not run atlas-clean during performing following steps. Otherwise you have to start from the very first step.

***** Preparation ******
1. Create atlas-create-jira-plugin to create Jira Plugin project.
2. Execute atlas-run for first time. It will create hsql database along with "home" directory in target/jira directory.
3. Configure Jira as per need (like creation of Project, issues). This is the data you always need to pre-populate after you do atlas-clean which wipes out everything from target directory (including home directory).
4. Take Jira Data backup (System -> Import & Export -> Backup System).
5. Shutdown Jira Instance.

*** Configure mysql data source ********
6. update target/jira/dbconfig.xml by replacing hsql settings with MySQL JNDI data source.

<?xml version="1.0" encoding="UTF-8"?>
    <validation-query>select 1</validation-query>

schema-name, url, username, password these fields needs to change to reflect your database settings.

7. Do not remove database.* files (which are hsql database files) Atlassian Maven script do refer them after clean installation. Leave them alone, After your mysql installation successful, they are useless. Don't refer them!

8. execute command atlas-create-home-zip. This will create file in target/jira directory.
9. Copy this file to handy location.

**** Changes to pom.xml ******
10. Add <productDataPath> configuration property and set it to this file in order to load the JIRA data.


******** Setting up Tomcat class path for mysql drivers ********
11. To avoid mysql driver Class not found exceptions, we need to put mysql driver file (mysql-connector-java-5.1.13.jar) in tomcat/lib directory.

**** Show Time ******
12. Execute atlas-run
In the logs you will see many info messages about no tables found. Below is one example:

[INFO] [talledLocalContainer] 2011-09-20 00:56:40,801 main WARN      [core.entity.jdbc.DatabaseUtil] Entity "OSPropertyDecimal" has no table in the database

Also log will show that it's correctly picking up mysql database as we have updated in dbconfig.xml

13. Access JIRA from url as displayed in console log.
14. You will be redirected to JIRA Setup Step 2. Click on import your existing data so that we can use the earlier JIRA export. (This will help to take care of license. Developer license will get imported along with data)

15. Once setup complete message appears, log in to JIRA using your credentials as set earlier.
16. Verify if data is imported correct or not.
17. That's it. Now you are all set to use MySQL with Atlassian PDK.

***** Getting around with Atlas-clean ******
There is one drawback with above approach!

If for some reason you need to use atlas-clean, contents from tomcat directory (including mysql-connector-java-5.1.13.jar) will get deleted.

18. To avoid this, create with addition of mysql jar file. And then using "maven install" update your maven repository to use this file instead of standard tomcat zip that you downloaded from atlassian maven repository.

atlas-mvn install:install-file -DgroupId=org.apache.tomcat -DartifactId=apache-tomcat -Dversion=6.0.20 -Dpackaging=zip -DgeneratePom=false

**** Show Time - One more Time ****
19. Execute atlas-clean to get ready for fresh run.
20. Execute atlas-run to start JIRA using pre-populated data (as stored in along with mysql database.

This time we JIRA will immediately re-direct to login screen (skipping installation / data import setps!)

*** Live Happily ****
Run atlas-create-home-zip command again if you want to use latest JIRA data / application settings.

End of Recipe!

MattS Rising Star Sep 19, 2011

Nice! A couple of comments.

Step 1. I think you mean atlas-create-jira-plugin not atlas-create-jira-template?

Step 11. Put the MySQL jar file where?

Matt, I've updated step 1 and 11. Thanks.

EddieW Rising Star Sep 20, 2011

Raju, mark your answer accepted..

Joe Clark Atlassian Team Sep 20, 2011

Great work summarising your investigations! Hopefully this will help a whole bunch of other developers, too. :-)

This still works perfectly except that the version of Tomcat has changed and with one addition. Even on Mac OS JIRA loads Tomcat from a file named If you simply change the version in the maven command above the file will be copied to The solution was simply to manually add -windows-x64.

Also I feel like Atlassian should simplify the process or at least make an official guide about this, took me quite some time to find this answer and it feels very wrong to have to follow a 20-step answer on a QA-site in order to get such a simple task working.

In Step 6 update path to {basedir}/target/jira/home

5 votes
Joe Clark Atlassian Team Sep 15, 2011

The Atlassian Plugin SDK by default, downloads a zipped up "Home" directory for your product that is pre-configured to connect to an in-process HSQL db.

The cool thing is that you can override this behaviour and provide a customised "Home" directory instead. The basic process for doing this is as follows:

1) Run up an instance of the target product using atlas-run

2) Configure the product the way you like

3) Shut down the product

4) run the command atlas-create-home-zip

5) Store the resultant zip file somewhere handy

6) Add a <productDataPath> configuration property to your pom.xml, that points to the zip file.

Check out the documentation for more info:

Thanks Joseph.

I will follow the steps and get back with updates.

2 votes
brainicorn Atlassian Team Nov 26, 2012

Just letting everyone know, as of SDK 4.1, you can now just specify a custom datasource in you pom.xml


Thanks Jonathan!

This ticket contains better details on how to use the new datasource system:

Is there any guide, that specifies what I should put into pom when I want to use MySQL?


2 votes
Joe Clark Atlassian Team Sep 15, 2011

Also, if you are running a product other than Confluence (which has a bug that prevents this), you can run HSQL as a separate process and then configure the product to connect to it remotely by changing the connection string, for example:


To start HSQLDB as a process, try this:

java -cp hsqldb.jar org.hsqldb.Server -database.0 file:/path/to/database -dbname.0 databasename
MattS Rising Star Sep 15, 2011

Useful tip, thanks.


Why is this so complex? A recipe containing 18 steps just to connect to a different database does not sound right to me! :)

Here is an old issue that has not been resolved yet: I think this is just what we need, i.e. a way to define the connection parameters. Please vote for the issue and put some pressure on Atlassian to make this a simple task.

Best regards,


Hi Bjarni,

Agreed, there are too many steps to follow. I will vote on the issue you mentioned. Also add this workaround till issue gets resolved.



1 vote
Joe Clark Atlassian Team Sep 19, 2011

According to the documentation (, the MySQL JDBC driver is only included with the JIRA standalone distribution. The Atlassian SDK only downloads the WAR of JIRA to run up the app, so as the documentation suggests, you'll probably need to add this library to the tomcat classpath.


To configure mysql instead of hsql datbase, I've performed steps as you mentioned.
1. After running atlas-run first time, updated dbconfig.xml (from jira/home directory) to use mysql as a Datasource.
2. Later updated productDataPath to point to zip file created by atlas-create-home-zip command.
3. Also added,
OSGI instructions to import necessary packages as follows:

<!-- OSGi intructions go there -->



and Added JNDI, mysql dependencies as below: <dependency>










All these changes are done in pom.xml

When I run atlas-run again,

it does pick the dbconfig.xml correctly from generated zip location as pointed in But later it throws following exception:

[INFO] [talledLocalContainer] 2011-09-19 16:08:25,009 main ERROR [atlassian.jira.startup.LauncherContextListener] Unable to start JIRA.
[INFO] [talledLocalContainer] java.lang.IllegalArgumentException: JDBC Driver class 'com.mysql.jdbc.Driver could not be loaded.'
[INFO] [talledLocalContainer] at com.atlassian.jira.config.database.JdbcDatasource.registerDriver(
Not sure why it's still couldn't able to find out mysql jar file. I've tried this for Jira 4.4.1 / 5.0-m2 / 5.0-m4. But same issue persists.

Do we need to add this jar in jira.war (jira webapp lib directory) or tomcat lib directory? Since these both options are created dynamically by atlas-run, how one can configure them to add these jars.

Any idea what's still missing?

Thanks, mysql is not part of atlassian pdk 3.4. Also I couldn't able to find hsql in current repository for pdk. Do we have to add these files manually?

I have problems after migrating from HSQL to existing mySQL database. All issues are in place and searchable, but JIRA cannot find issues assigned to current user, e.g. the Assigned to me gadget shows no issues. The same is true for any piece of code that uses filters like assignee = currentuser()


Any ideas?

Seems that in case of existing database one needs to reindex it after connecting to JIRA.

0 votes

Hi Everyone,

Just FYI.  If you are switching to using an actual non-HSQL database I think its MUCH easier just to develop against a 'downloaded'/'standalone' version of Confluence.  I could set up 5 of those in the time it would take to read through the steps above and likely debug them.

As you all probably know there is a decent wizard for connecting the db and really just two simple standard steps (home directory creation + pointing to it) to get it all up and running.

Just my $0.02.   The above is only worth it if its faster and easier than setting up a standalone version, which appears to be far from the case when you throw a real database into the mix at present.


I have simple way I did:

- Edit dbconfig.xml:



- Copy mysql-connector-java-x.x.x.jar


-> so when we start

I have simple way, I did:

- Edit dbconfig.xml in:



    &lt;validation-query&gt;select 1&lt;/validation-query&gt;

- Copy mysql-connector-java-x.x.x.jar


-> ok, we run command atlas-run

Hope this will help somebody.

That's what I've mentioned in my detailed comment. What more it talks about is how you can have these settings even though you clean up the target.

Anyways as Jonathan mentioned above, with Atlassian SDK 4.1, this is a inbuilt feature.

Hello All,

I try and try to get this work, but it s always going back to hsql.
Maybe I m wrong in the pom.xml...




Please help me.


Only problem that may be is location of

In above pom.xml you have mentioned productDataPath as ${basedir}/src/main/resources/ Can you make sure it's there?

Also general practice is you copy them under test resources. so path can be ${basedir}/src/test/resources/

Hope this helps,


Comments for this post are closed

Community moderators have prevented the ability to post new answers.

Post a new question


Atlassian Community Events