This is a tutorial on how to use Confluence as a query / reporting engine, querying SQL data sources like the Jira database. For our example we query JIRA's database to build a Monthly Worklogs Report, showing hours worked per day for every user in a given month. We use the free Play SQL Base plugin.


Of course, Tempo Timesheets is the de-facto plugin for this sort of thing, and already has a report like what we're building:

Tempo's report is prettier and more powerful, allowing hours to grouped by any field (e.g. project, or tempo Account), even hierarchically. Tempo's one deficiency here, which motivated this reimplementation, is that it cannot show users which have not logged any work.

But for the purposes of this tutorial, worklog information is just a nice example of something  in the Jira database which you'd like to query in an interactive manner.

Implementation

Choosing a Confluence SQL plugin

For this tutorial we are using the free Play SQL Base plugin. You could alternatively use PocketQuery or SQL for Confluence, which are in fact better plugins overall - in particular, they let you restrict who can run SQL queries, whereas Play SQL can't.

This tutorial uses Play SQL Base because it's what I had available. We will restrict SQL queries at the Postgres layer, which is a good thing to do anyway.

Configure Play SQL Base

In Confluence, type 'gg', 'Find new apps' and install the free Play SQL Base plugin.

In Confluence spaces you will now see a new 'Tables' menu item. Here is the page from a live Confluence instance, with various queries already defined (there's one from the Automatically deactivating inactive Jira users report):

Click 'Manage Connections and Permissions' and set up the space's database connection. Here we just use the global datasource:


Clicking 'General Admin' shows the global config:

Creating a Postgres read-only account

At this point we're about to tell Play SQL how to connect to our database. For the sake of security, we want to connect as a user with read-only  permissions, and with visibility restricted to just data necessary for our report.

The read-only requirement can be achieved with Postgres permissions. The restricted visibility requirement can be achieved by only allowing queries of predefined views, in a custom queries schema. The main Jira tables in the public  schema will be inaccessible.

First, create a 'queries' schema, with a sample view containing a small amount of data:

root@jturner-desktop:~# su - postgres
postgres@jturner-desktop:~$ psql redradish_jira
Null display is "␀".
Line style is unicode.
Border style is 2.
psql (12.2 (Ubuntu 12.2-4))
Type "help" for help.

redradish_jira=# CREATE SCHEMA IF NOT EXISTS queries;
CREATE SCHEMA
redradish_jira=# CREATE OR REPLACE VIEW queries.sample AS select project.pkey || '-' || jiraissue.issuenum AS key, summary from public.project JOIN public.jiraissue ON project.id=jiraissue.project LIMIT 5;
CREATE VIEW
redradish_jira=# select * from queries.sample;
┌──────────┬─────────────────────────────────────────┐
│   key    │                 summary                 │
├──────────┼─────────────────────────────────────────┤
│ SOC-3    │ A second Response for good measure      │
│ ML-53    │ Ongoing Atlassian Product Support, 2014 │
│ IC-34    │ Invoice 93236 - 1/Jul/15 to 30/Sep/15   │
│ JTODO-19 │ Tax Payment Q2 Due                      │
│ CLIC-2   │ Move projects to OnDemand               │
└──────────┴─────────────────────────────────────────┘
(5 rows)

Next, create a jira_queries_readonly  role that can only view the queries  schema tables, and a confluence_reports  user granted that role. These commands are cribbed shamelessly from https://blog.redash.io/postgres-readonly/, so read that to understand them properly. Run them when connected to the Jira database, not  the default 'postgres' database.

CREATE ROLE jira_queries_readonly;
GRANT CONNECT ON DATABASE redradish_jira TO jira_queries_readonly;
GRANT USAGE ON SCHEMA queries TO jira_queries_readonly;
GRANT SELECT ON ALL TABLES IN SCHEMA queries TO jira_queries_readonly;
CREATE USER confluence_reports WITH PASSWORD 'confluence_reports';
GRANT jira_queries_readonly TO confluence_reports;

Verify that, when connecting as confluence_reports we can see our sample query but not generic Jira tables:

# PGUSER=confluence_reports PGPASSWORD=confluence_reports PGHOST=localhost PGDATABASE=redradish_jira psql -tAc "select count(*) from queries.sample;"
5
# PGUSER=confluence_reports PGPASSWORD=confluence_reports PGHOST=localhost PGDATABASE=redradish_jira psql -tAc "select count(*) from public.jiraissue;"
ERROR:  permission denied for table jiraissue

Define a Datasource in Confluence

There are two ways to tell Play SQL (and other SQL plugins) how to connect to a database:

Either way will work. I used a datasource, defined as the jdbc/QueriesDS  section in my /opt/atlassian/confluence/conf/server.xml file:

        <Engine name="Standalone" defaultHost="localhost" debug="0">
            <Host name="localhost" debug="0" appBase="webapps" unpackWARs="true" autoDeploy="false" startStopThreads="4">
                    <Context path="" docBase="../confluence" debug="0" reloadable="false" useHttpOnly="true">
                    <Resource name="jdbc/ConfluenceDS" auth="Container" type="javax.sql.DataSource"
                           username="confluence"
                           password="<REDACTED>"
                           driverClassName="org.postgresql.Driver"
                           url="jdbc:postgresql://localhost:5432/confluence"
                           maxTotal="20"
                           validationQuery="select 1"/>
                    <Resource name="jdbc/QueriesDS" auth="Container" type="javax.sql.DataSource"
                           username="confluence_reports"
                           password="confluence_reports"
                           driverClassName="org.postgresql.Driver"
                           url="jdbc:postgresql://localhost:5432/jira?currentSchema=queries"
                           maxTotal="20"
                           validationQuery="select 1"/>

                    <!-- Logging configuration for Confluence is specified in confluence/WEB-INF/classes/log4j.properties -->
                      <!-- Uncomment this to DISABLE session serialization.
                    <Manager pathname=""/>
                    -->
                    <Valve className="org.apache.catalina.valves.StuckThreadDetectionValve" threshold="60"/>
                </Context>

                <Context path="${confluence.context.path}/synchrony-proxy" docBase="../synchrony-proxy" debug="0"
                         reloadable="false" useHttpOnly="true">
                    <Valve className="org.apache.catalina.valves.StuckThreadDetectionValve" threshold="60"/>
                </Context>
            </Host>
         </Engine>

You will need to restart Confluence to pick up this change.

  • It's more secure - database credentials aren't stored as plaintext in the database or in innumerable backups.
  • it lets you configure the 'QueriesDS' differently in production vs. sandbox. The database hostname for Jira might be different on the sandbox server. Rather than reconfigure PlaySQL every time you sync sandbox data, you configure 'QueriesDS' once correctly in the sandbox conf/server.xml .
  • the app server can provide stats about database connection use via JMX or JavaMelody.
  • It's just conceptually nicer (the inversion of control principle).

Configure PlaySQL with the Datasource

To recap, we've just been on a detour to create a read-only Postgres account, and edited Confluence's conf/server.xml  file to define our QueriesDS  datasource.

Now configure Play SQL to use the Datasource. Here I've configured QueriesDS as our default 'global connection':

Create a test Play SQL Table

Now return to the 'Tables' tab in a space:

Under 'Queries' click 'Create new...'.

Now query your sample  view and click 'Preview' to verify it works:


Did we mention Play SQL Base is free? It is free, but also buggy, and at this point the bugs are very evident:

  • The list of queryable tables on the right may or may not be correct. In the screenshot above it reflects an unrelated 'playsql' schema, not 'queries'.
  • SQL queries can't end with a semi-colon, or you'll get an error
  • Clicking 'Save' on a newly defined query, as you will now want to do, results in an error:


    But don't worry, your query did save.


If you persevere, it does work in the end. Don't complain - the Play SQL author makes his money from Play SQL Spreadsheets, not Play SQL Base - we're fortunate to have a free, roughly functional plugin at all.


Create the timesheets database view

So far we've successfully queried queries.sample . We now create a queries.worklog_monthly  view containing our real timesheet data.

We're not going to dwell too much on the specifics of our query. Here it is:

I suggest creating a directory in your Confluence app dir for SQL queries like this:

/opt/atlassian/jira # mkdir SQL_QUERIES
/opt/atlassian/jira # cd SQL_QUERIES/
/opt/atlassian/jira/SQL_QUERIES #

Then you can fetch the SQL directly using curl and run it to create the view in your database:

/opt/atlassian/jira/SQL_QUERIES # curl -sLOJ 'https://github.com/redradishtech/jira-interesting-sql-queries/raw/master/worklog_monthly.sql'
/opt/atlassian/jira/SQL_QUERIES # sudo -u postgres psql redradish_jira -tAXq  < worklog_monthly.sql

Verify that our confluence_reports  user can read our new queries.worklog_monthly  table:

# PGUSER=confluence_reports PGPASSWORD=confluence_reports PGHOST=localhost PGDATABASE=redradish_jira psql -tAc "select count(*) from queries.worklog_monthly;"
121

Create a worklog_monthly Play SQL Table

As we did earlier for queries.sample , now configure a Table in Play SQL for our queries.worklog_monthly  view.

You should first enter  the query:

select * from worklog_monthly

Preview it to make sure that works. If so, parametrize it:

select * from queries.worklog_monthly where year='$year'::integer and month='$month'::integer and email_address ~ '$email'

Click 'Options >>' and configure the parameters:

You may want to tick the 'Cache' checkbox if you have a lot of data to query.

Create a page containing the table

Our final step is to create a page in the Confluence space, containing a Play SQL Query macro:

Configure the macro to use  the worklog_monthly  query:


and there you have it: our final worklog report: