/ 
Xmldoom-0.0.16
River stage zero No dependents
/ Xmldoom::doc::UsingTorque

NAME

Xmldoom::doc::UsingTorque -- How to use the Torque generator to work with your database.xml.

DESCRIPTION

Because the format used in the database definition (commonly named database.xml) is the same as Apache Torque, we can use their tools to automatically generate database.xml from the database, or automatically create the database from a database.xml.

Basically, the Torque Generator is a set of Ant scripts that call into the Torque engine. So, you need to install Ant as well.

SETTING UP THE TORQUE GENERATOR

First, you must download the Torque Generator from their project page:

http://db.apache.org/torque/download.html

Make sure you are downloading the Generator (the page is a little confusing). You'll see that there is a table there with versions going down the Y-axis and product names going across the X-axis. If the page hasn't since this writing, you want the top-cell over to the right one.

Once you've got it:

  1. Extract the archive somewhere. You'll end up with directory named like torque-gen-3.2. Go there.

  2. Edit a file named build.properties. Most of the setting don't matter for us, so you can skip down to the section labeled "DATABASE SETTINGS" (with a space between each letter). Configuring this section should be pretty self explanitory if you have ever used JDBC in Java before. In case you haven't you can check out the explanation at the end of this document named "BUILD PROPERTIES".

  3. You need to find and copy the JDBC drivers for your database into the lib/ directory. More on this in the "BUILD PROPERTIES" section.

Now you are ready to give it a go.

ANT TARGETS

To generate an XML schema from your database, run:

ant -f build-torque.xml jdbc

Most likely you won't want to use the generated file directly, because it lacks foreign-keys and any of the groovy Xmldoom special features. But it does provide a quick spring-board to allow to copy-paste and modify to get started quickly.

To create your database based on the XML description, run:

# to initially create the databas
ant -f build-torque.xml create-db

# will drop and re-create all tables in the database
ant -f build-torque.xml insert-sql

BUILD PROPERTIES

Three of the properties are JDBC dsn strings. Basically, these just pack the driver name, server host, and database name into a URI like descriptor.

# The database DSN *without* the database name.
torque.database.createUrl = jdbc:mysql://localhost:3306/

# Now, with the database name.
torque.database.buildUrl = jdbc:mysql://localhost:3306/dbname
torque.database.url      = jdbc:mysql://localhost:3306/dbname

You have to tell it where to find the JDBC driver. You will have to download the actual JAR file for this and put into the lib/ directory under your torque-gen-* directory. You can find the MySQL driver here:

http://www.mysql.com/products/connector/j/

# Describe the path inside of the JAR where the driver class is
torque.database.driver = com.mysql.jdbc.Driver

And, of course, you need to provide the appropriate credentials.

torque.database.user = myuser
torque.database.password = mypassword