Benchw Installation Instructions
================================


1 Build
=======

The build process has been constructed using Autoconf, so is the 'usual' :

$ ./configure 
$ make
$ make install

The configure process tries to be clever about large file access (i.e 64 bit)
for the platforms that need it.

The project should be buildable on Windows with minor changes to the header
files (let me know if you actually do this).
 

2 Dataset Creation
==================

The steps here involve generating the dataset dumpfile, the schema creation
file, the data load file(s) and finally the query test files.

As an example lets write the dump files in '/var/benchw/dump' and the scripts
in '/var/benchw/scripts'.

I will use Postgresql as an example (it only changes the -t option of
loadgen and possibly a -m option on datagen):

$ cd /usr/local/benchw/bin
$ ./datagen -s 1 -d /var/benchw/dump
$ ./schemagen -d /var/benchw/scripts
$ ./loadgen -d /var/benchw/scripts -l /var/benchw/dump -t pg
$ ./querygen -d /var/benchw/scripts 

The various options for the binaries are :

-d <path>	Where file(s) are written. The default is '.' (all binaries)
-s <size>	Size of the dataset. The default is 1. Makes a 1G dataset.
			Decimals are accepted (datagen only).
-m <fmt>	Specify a format for dataset files, delimited (-m del) [default] 
			and fixed width (-m fixed) (datagen only).
-l <path>	Where dump files *were* written by datagen the default is '.'
			(loadgen only).
-t <db>		Specify database manager load file(s) syntax - as this is
			anything but standard (loadgen only).


3 Database Preparation
======================

You need to create a database and designate a user / schema for the tables.
Using Postgresql as an example again :

$ psql -d template1 -c "CREATE DATABASE dbbenchw"
$ psql -d dbbenchw -c "CREATE USER ware"

Now the tables can be created :

$ psql -d dbbenchw -Uware -f schema.sql


4 Running The Tests
===================

The elapsed time for these steps should be noted. However you will probably
want to perform these steps several times with different os and database
configuration settings.
In addition you may want to experiment with indexes other than the suggested
ones to improve performance (indexes are free -i.e you can index anything you
like). It is allowable to create the indexes *before* loading the data, if your
database manager prefers this.


Load the data :

$ psql -d dbbenchw -f load.sql


Create (suggested) indexes (or your own custom ones) :

$ psql -d dbbenchw -f indexes.sql


Run the queries :

$ psql -d dbbenchw -f qtype0.sql
$ psql -d dbbenchw -f qtype1.sql
$ psql -d dbbenchw -f qtype2.sql
$ psql -d dbbenchw -f qtype3.sql
$ psql -d dbbenchw -f qtype4.sql 


5 Comparison Of Results
=======================

At this stage (beta), the  results 'metric' consists of the various elapsed
times for the load, index and 5 queries.

It is always nice to be able to spit out one number (e.g. some sort of
weighted average of the above), but as yet there has been insufficient testing
to produce any meaningful weightings for such. In any case its not clear (to 
me) that a single number output is very meaningful.


6 Database Managers
===================

The current supported set are Postgresql, Mysql, Oracle, DB2, Sapdb and 
Firebird. (Firebird users be sure to consult DBMNOTES).

Any remotely ANSI92 compliant database should be suitable (you may need to
edit the file generated by loadgen).


7 Porting And Optimizations For Database Managers
=================================================

These are discussed in the file DBMNOTES.
