Hauler
Reference Manual

For Hauler version 1.0.0. Documentation revised 8-Feb-2003.
Copyright (c) 2001-2003 by Rune Berg.
Licensed under the GNU General Public License (GPL).

Hauler homepage on the Internet || Latest version of this document on the Internet


Contents:

 
Introduction

Hauler is a command line driven software program that executes user-defined SQL queries towards a MySQL database server and prints the result sets on the standard output stream, as XML or various text ("flat file") formats.

Hauler is useful for web applications or data export purposes where the database is held in a MySQL server.

Note that the MySQL database server is a product by MySQL AB. I am not - nor is Hauler - affiliated with that company.

 
Prerequisites for running Hauler

Hauler runs on x86 Linux systems the appropriate system libraries installed. (You may succeed in building and running Hauler on other platforms, but I haven't tried that.)

Obviously, you need a running MySQL server (or network access to such) and the necessary login credentials. Talk to your database/system administrator if you're unsure.

To do anything useful with Hauler (or any other MySQL client), you need the MySQL Reference Manual, as this explains the SQL query syntax used. This should be available from http://www.mysql.com/documentation/index.html

 
Using Hauler

Usage / Command syntax

Usage: Connection options: Overall output format option: XML specific output format options: CSV/delimited specific output format options: Common output format options: Other options:

XML output

This output format (which is the default) prints the SQL query result set(s) as an XML (Extensible Markup Language) document.

The XML document produced has a root element ROOT (but see the --rootelement option) containing one row set element (as given in the command) for each query / result set. Each row set element contains one row element (as given in the command) per result set row. Each row element, in turn, contains one element per result set column. Any '<' within a column (field) value gets encoded as &lt; in the corresponding element, and any '&' as &amp;.

To describe XML output, let's start with a MySQL database haulerdoc containing a table person, for which the SQL query:

yields the following result set:

Given this table, let's see what output is produced by various Hauler invokations.

First, a 'default', single query Hauler invokation:

The output is:

Notice here that:

Next, let's use two queries, to get an XML document with two row set elements:

The output is:

Notice here that:

Next, let's use the --rootelement option to change the root element:

The output is:

Next, let's use the --rownumattr option to add a NUM="..." attribute in each row element:

The output is:

Next, let's use the --nulls option to make any NULL values (in the SQL sense) produce an output element:

The output is:

Notice how the comment field from the third row now produces an output element NULL (which you can change using the --null option)

Next, let's use the --null option combined with the --nulls option to make any NULL values (in the SQL sense) produce an output element with an element value of our choice:

The output is:

Next, let's use the --nullattr option to make any NULL values (in the SQL sense) produce an output element with a NULL="true" attribute

the output is

Notice how the presence of the --nullattr option implies the effect of the --nulls option.

Next, let's use the --indent option to change per-element-level indentation from a tab to a space:

The output is:

Next, let's use the --nonewlines option to strip the output of newlines:

The output is:

Notice how the presence of the --nonewlines option implies the effect of the --indent option, i.e. making the output devoid of any insignificant whitespace.

Next, let's use the --uppercase option to force all element and attribute names to upper case:

The output is:

Finally, let's use the --lowercase option to force all element and attribute names to lower case:

The output is:

CSV output

The CSV (Comma Separated Values) output format (which is enabled by the --outputformat=csv option) is a 'flat file' type of format. The SQL query result set is printed as an initial line of column names (but see the --nofieldnamesrow option) followed by one line per result set row.

The CSV format works according to the following rules:

To describe CSV output, let's start with a MySQL database haulerdoc containing a table quote, for which the query:

yields the following result set:

Given this table, let's see what output is produced by various Hauler invokations.

First, a 'default' Hauler CSV invokation (i.e. one with no command line options to affect the CSV output):

The output is:

Notice here that:

Next, let's use the --nofieldnamesrow option to skip the column names (i.e. the first output line)

The output is:

Next, let's use the --fielddelimiter option to separate output fields by a semicolon:

The output is:

Next, let's use the --null option to change the output for NULL values:

The output is:

Next, let's use the --uppercase option to print the column names in upper case:

The output is:

The --lowercase option works the opposite: the column names row get printed in lower case.

Delimited output

This format is rather similar to the CSV format, only 'dumber': no double quotes are printed around values that contain the field delimiter or a double quote, which can make the output unsuitable for futher processing. On the plus side, the field delimiter can any length.

To describe delimited output, let's start with a MySQL database haulerdoc containing the same table quote used in the CSV examples above. That is, one for which the query:

yields the following result set:

Given this table, let's see what output is produced by various Hauler invokations.

First, a 'default' Hauler delimited invokation (i.e. one with no command line options to affect the delimited output):

The output is:

Notice here that:

Next, lets use the --fielddelimiter option to change the field delimiter to two semicolons:

The output is:

The --nofieldnamesrow, --null, --uppercase and --lowercase options work the same way as for CSV output.

 
Version history

The public releases of Hauler are:

 
Known bugs & limitations

These are the known bugs in Hauler 1.0.0:

These are the known limitations in Hauler 1.0.0:

For up to date Hauler information, visit the Hauler homepage on the Internet.

 
TODO

(This chapter will contain a list of features for future Hauler versions.)

 
Contact information

Hauler homepage on the Internet: http://home.online.no/~runeberg/hauler

Hauler author's email address: runeberg@online.no

 
Appendix A : Technical information

Libraries needed

The provided Hauler executable is statically linked to the MySQL client library (libmysqlclient). (However, the makefile has out-commented defs for dynamic linking.)

The provided Hauler executable requires the following shared libraries to run:

If you choose to (or must) build Hauler yourself, you may get away with different library versions.

Building

Use the supplied makefile (but read that file's initial comments - you may need to tweak it slightly). I've tried and succeeded building Hauler on SuSE Linux 8.1. Your mileage may vary.

You'll need to have installed the appropriate packages for GCC (I use version 3.2) and MySQL client development. These should be included with your Linux distribution.

 
End of document