Torquebox database connections with JNDI

Normally, a regular Rails application running on MRI Ruby needs to have just a couple of lines in the config/database.yml file to set up the database. That’s still available for a Rails application running JRuby and a web server like Puma or even a fully-fledged application server (I’ll use AS from now on) like Torquebox.

However, if you’re using Torquebox, you might want to define the database connection at the AS level. This will allow you to manage the database connections in a central place which is especially useful if you have multiple applications in the same AS. Also, you can use the JBoss tools (see below) to inspect your application which is always a nice thing.

For some reason, most guides out there aren’t very specific when it comes to the software version. This short how-to has been tested on the following:

  • Torquebox 3.1.1
  • JBoss 7.2 (comes bundled with Torquebox 3.1.1)
  • MySQL J connector 5.1.34
  • Rails 4.1

I’m using the following conventions, which are typical for Torquebox installations:

Setting up

First, you need to download the MySQL J connector. I’ve used the platform independent version because I am using Ubuntu 14.04. The latest stable version as of now is 5.1.34. Inside the archive there’s a mysql-connector-java-5.1.34-bin.jar that is the actual connector.

You need to create the following folder structure: $JBOSS_HOME/modules/com/mysql/main and you need to place the mysql-connector-java-5.1.34-bin.jar file that you extracted and create a new file called modules.xml with the following contents:

The name="com.mysql" needs to match the folder structure that you have created in the $JBOSS_HOME/modules directory. So if you want to use name="com.mysql.jdbc" then you need to create $JBOSS_HOME/modules/com/mysql/jdbc/main and place the modules.xml and the connector file there.

Note down the name attribute. It will be used in the standalone.xml or standalone-ha.xml file that we’ll edit below.

Most JBoss 7 guides will say that you can also just drop the mysql-connector-java-5.1.34-bin.jar in the $JBOSS_HOME/standalone/deployments folder and JBoss will pick it up. That’s actually the simplified version of the module deployment that we did above, but in my case it did not properly configure the MySQL driver probably because JBoss detects that this is not a JDBC-compliant driver.

Creating the AS database configuration

In order to tell the JBoss AS that it has to connect to a data source, you need to edit the profile XML. For standalone servers, the configuration files are in the $JBOSS_HOME/standalone/configurations folder. Normally they are either standalone.xml or standalone-ha.xml, but you can set up custom profiles also. Open it up and in the profile section you need to add the following subsystem:

Note the jndi-name attribute for the datasource element. That’s what you’re going to use in your app’s database.yml file. The rest of the connection configuration should be rather straightforward. However, do pay attention to these items:

  • In the drivers section you specify a driver with the attribute module="com.mysql" which has to match the name attribute created in the module.xml file above.
  • As of version 5.1.30 and higher, the MySQL driver contains two classes and JBoss tries to add it twice so you need to add the <driver-class> element (see WFLY-3128)

You also have to remember that you’re setting up the datasource settings for the entire container. So all the apps that will reference the defined JNDI will use the same username and password to connect to the same database and they will use a part of the shared connection pool which allows just 50 connections at one point.

Once you’re done, be sure to restart the container (I use the service configuration file shipped with Torquebox) and look at the server logs. You should not see any errors and if you do, make sure you have the right paths and that you edited correctly the configuration files.

The Rails configuration

Once you have the JBoss container running without any errors, using its datasource is rather trivial. Just edit the config/database.yml file and add the following:

Note that you don’t need anything else than the adapter and the JNDI name, which is identical to the jndi-name attribute we added in the datasources subsystem earlier, except for the java: prefix.

Some things to note:

  • The default connection pool size for AR-JDBC is 5. You might want to change that, based on your application’s needs.
  • Don’t specify a number of connections higher than the one configured in the JBoss configuration
  • Be careful that other applications might share the AS and use the same connection pool

Once you’re done with these settings and the application works just fine, you can use some of the tools that are shipped with JBoss to gather more insights. For example, here’s a quick way to get some stats regarding the active connections for the configured data source:

Just be careful to match the YOURDB string with the one defined in the standalone.xml file.