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:
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:
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-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-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:
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
driverssection you specify a driver with the attribute
module="com.mysql"which has to match the
nameattribute created in the
- 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
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