« Back to Custom Deployments

Derby Java DB RDBMS

Overview #

This is a small "how to" guide on configuring Tomcat/Liferay to run and boot Apache Derby (JavaDB) as it's backend RDBMS in 'embedded server mode'. This mode means the database will be accessed by liferay inside the same JVM in embedded mode, but network multiuser access to the same database will also be possible, (perhaps by other programs, or RDBMS tools such as Squirrel http://squirrel-sql.sourceforge.net/ or DBVisualizer http://www.minq.se/products/dbvis/), via normal JDBC.

Motivation #

  1. Apache Derby (aka Java DB by Sun Microsystems) is a great enterprise RDBMS and a Java standard. A good overview of why you might want to investigate using Derby as your production RDBMS can be found in this presentation: http://www.papercut.com/anonftp/pub/open-source/apache-derby/ApacheDerbyAJUGPresentation.pdf
  2. 'Embedded Server mode' is a useful feature that is usually somewhat overlooked (IMO).

References: #

  1. Derby admin guide http://db.apache.org/derby/docs/10.5/adminguide/ see the section named 'embedded server example', and the various sections on configuring user/password authentication - the simplest possible setup is described below where user/passwords are embedded into the properties file, you can hook it up to LDAP or insert/manage users/passwords in the database itself if required
  2. Java DB background http://developers.sun.com/javadb/
  3. Apache Derby site: http://db.apache.org/derby/

Precis: #

  • Ensure app server has the derby jars in it's classpath
  • Setup Liferay portal-ext.properties to boot/access Derby in embedded mode as it's RDBMS
  • Tell Derby it's data/config dir by setting the java property derby.system.home in the app server JVM
  • set derby startup properties to run requiring authentication, and also to boot the network server

Complete Steps for Tomcat 6/Liferay 5.2.3: #

  • Download the latest Apache derby http://db.apache.org/derby/derby_downloads.html and unzip (I'm using 10.8. on a mac in this guide) I'll refer to this unzipped directory as ${DERBY_HOME} from here on
  • Get the tomcat 6/liferay 6.x from http://downloads.sourceforge.net/lportal/ as a bundle and unzip - I'll refer to this directory as ${LIFERAY_HOME} from here on
  • Copy the files derby.jar and derbynet.jar from the ${DERBY_HOME}/lib directory to ${LIFERAY_HOME}/tomcat-6.0.18/lib/ext
  • create a text file portal-ext.properties and save it to:


  • put the following into this new portal-ext.properties:

jdbc.default.url=jdbc:derby:lportal jdbc.default.username=liferay jdbc.default.password=liferay }}}

  • Decide what directory will contain (all) your derby database data, in this example I'll put it next to the hsql data that resides in ${LIFERAY_HOME}/data - to do the same do then mkdir ${LIFERAY_HOME}/data/derby - I'll refer to this directory as DATA_DIR (change it to your data directory)
  • the JVM that Tomcat and Liferay is running in needs a property set to tell Derby where it's derby.system.home (data dir and config dir) is. This can be done by putting the value into either the env vars JAVA_OPTS or CATALINA_OPTS so tomcat uses it when it starts up. It's best to do this in the startup file for tomcat, but can be done from the command line like I have below. Note I also set the DERBY_OPTS system wide env variable, this is so that any other tool that boots the Derby database (like the ij command tool) will also use the correct startup properties and data directory:
export DERBY_OPTS="-Dderby.system.home=**DATA_DIR**"
export JAVA_OPTS="-Dderby.system.home=**DATA_DIR**"  
  • put a file derby.properties into the directory DATA_DIR (which we pointed ${DERBY_SYSTEM_HOME} at) with content:
* when running embedded mode, also start the network server
* Listen on all interfaces (allow connections from other IPs, not just localhost)
* Turn on authentication - a good move when running network server
* hard code a user/password for username liferay, change to use LDAP or RDBMS users etc...
  • Create the database - easiest way is either by appending ";create=true" to jdbc URL - but this can cause issues if left on the URL forever because if for some reason the DERBY_SYSTEM_HOME env var is not picked up and used by Tomcat, then Derby will not complain but just create a new empty RDBMS into the working directory; so I usually manually create the RDBMS the first time by connecting to it once with create=true via the derby util ij, (You could also use Squirrel etc). To do this using ij add ${DERBY_HOME}/bin to your PATH env variable and export the ${DERBY_HOME} env variable itself, then use the ij tool:
 connect 'jdbc:derby:lportal;create=true;user=liferay;password=liferay';quit;

look inside the DATA_DIR to verify database (actually just a directory) now exists called lportal

  1. startup tomcat/liferay/derby database - run ${LIFERAY_HOME}/tomcat-6.0.18/bin/startup.sh (or bat)
  2. Liferay is running using embedded RDBMS derby mode, now you can check you can also connect from a remote JVM/machine in an app via JDBC - (e.g. squirrel) at JDBC url:

jdbc:derby://localhost:1527/lportal (replace localhost with the actual ip/machine if on another computer) user liferay password liferay

with the JDBC driver class being org.apache.derby.jdbc.ClientDriver which can be found in the jar called ${DERBY_HOME}/lib/derbyclient.jar

0 Attachments
Average (0 Votes)
The average rating is 0.0 stars out of 5.