Troubleshooting External Database Connections
A common administration issue when configuring Confluence is identifying database connectivity problems. This page tells you about a helper utility, in the form of a JSP page, that can help you to isolate database connectivity issues. It checks whether you can connect to a database with your application server. If your application server cannot connect to the database, Confluence will not be able to connect to the database either.
Introduction to the Atlassian Database Check Utility
You can use this utility to:
- Check that your application server can successfully query your database, either via immediate JDBC connectivity or a datasource in the context of your application server.
- Pinpoint problems in your configuration which may occur if the above is failing.
This is what the utility does:
- Check that a JDBC driver can be loaded into memory and view what is already loaded.
- Connect to a JDBC URL and do a 'select 1' from the database.
- Find a DataSource in the JNDI environment and do the above.
- View the System classpath (to ensure that the JDBC JAR file is there).
Using the Utility
If you have already set up Confluence completely
- Download the attached testdatabase.jsp to your
<confluence-install>\confluencedirectory. - Restart Confluence
- Go to http://MY-CONF-SERVER:MY-CONF-PORT/testdatabase.jsp.
- Check that your database driver is loaded into memory. If not, check the system classpath for the JDBC driver file, and that the driver is in the
<confluence-install>\libdirectory (for Confluence version 2.10 onwards) or<confluence-install>\common\lib(for earlier versions). Here are some instructions. - Enter the DB settings Confluence is using and test the database. If an error appears, check that the db service is running, the location matches, and that any users specified actually exist with the right login and permissions. You may be able to find a workaround by Googling the error.
If you cannot set up Confluence because of an error in 'Configuring Database'
- Record the DB settings you are using for your direct JDBC or datasource connection in the 'Configure Database' step of your setup.
- Download the attached testdatabase.jsp to your
<confluence-install>\confluencedirectory. - Rename your
<confluence-install>\confluence\WEB-INF\web.xmlfile tobackup web.xml. This disables redirection. - Restart Confluence.
- Go to http://MY-CONF-SERVER:MY-CONF-PORT/testdatabase.jsp.
- Check that your database driver is loaded into memory. If not, check the system classpath for the JDBC driver file, and that the driver is in the
<confluence-install>\common\libdirectory as described in these instructions. - Enter the DB settings you recorded and test the database. If an error appears, check that the db service is running, the location matches, and that any users specified actually exist with the right login and permissions. You may be able to find a workaround by Googling the error.
- After correcting the error, rename
<confluence-install>\confluence\WEB-INF\backup web.xmlback toweb.xml.
Notes
If you use this utility, please let us know ways in which we could improve it or leave helpful hints for others here.
For a comprehensive set of database instructions that might be helpful for troubleshooting, please refer to the following links:
Requesting Technical Support
If you are still stuck after attempting the suggestions above, lodge a free technical support request with information on your database setup.