Postgresql

Scarab has been tested on at least postgresql 7.3.4 on Linux and postgresql 8.0.1 on Windows.

1. Install postgresql if not already done so. Most Linux, BSD distributions ship with a canned version of postgresql. A version 7.3 or later should work fine. For Windows there is currently a native binary coming in an installer with a lot of goodies included and which installs the server as a service, or install postgresql as part of cygwin. Of course you can get the latest and greatest from the postgresql mirrors.

   After installation the database directories must be initialised. This is done automatically by starting the server for the first time with most binary packages (.deb, .rpm).

2. By default postgresql does not accept TCP/IP connections and the JDBC can only talk TCP/IP to the server. So after installation the configuration must be tweaked to allow access from Java. The configuration files are found in the same directory, but this directory changes from platform to platform, (eg, on Windows it is at C:\Program Files\PostgreSQL\8.0\data, on RPM based linux distros like Suse, Redhat, Mandrake look in /var/lib/pgsql/data, on Debian look in /etc/postgresql/, ...), (note : the Windows pginstall version comes preconfigured witht TCP/IP enable, so in this case you can skip to the next step)

   Change the file postgresql.conf by uncommenting the default settings and changing the values.

   ...
   #
   #       Connection Parameters 
   #
   tcpip_socket = true
   #ssl = false
   ...
   	

   Now allow access to the server by TCP/IP. Open the file pg_hba.conf in the same directory as above and add at the end the following line.

   ...
   host    all         all         127.0.0.1         255.255.255.255    md5 
   	

   If you do not want to be bothered by passwords not matching and do not care about security, you can simplify life by changing md5 to trust, but this is discouraged.

3. Scarab needs an account to connect to the server. On Limux machines log in (or su -) as postgres user. Start the psql commandline client on database template1 and run the query CREATE USER [INSERT_USERNAME_HERE] WITH PASSWORD '[INSERT_PASSWORD_HERE]'.

   Example :

   linux:~ # su - postgres
   postgres@linux:~> psql template1
   Welcome to psql 7.3.4, the PostgreSQL interactive terminal.
   
   Type:  \copyright for distribution terms
   	   \h for help with SQL commands
   	   \? for help on internal slash commands
   	   \g or terminate with semicolon to execute query
   	   \q to quit
   
   template1=# CREATE USER cc_scarab WITH PASSWORD 'secret' CREATEDB;
   CREATE USER
   template1=# \q
   postgres@linux:~> 	
   	

4. Now restart the server as usual on your platform and test if the user can log in with the command psql -h localhost -u [INSERT_USERNAME_HERE] -w template1 and test if it is possible to create and drop a new database. See the example below for inspiration.

   Example :

   postgres@linux:~> psql -h localhost -U cc_scarab template1
   Password: secret
   Welcome to psql 7.3.4, the PostgreSQL interactive terminal.
   
   Type:  \copyright for distribution terms
   	   \h for help with SQL commands
   	   \? for help on internal slash commands
   	   \g or terminate with semicolon to execute query
   	   \q to quit
   
   template1=> create database dummy;
   CREATE DATABASE
   template1=> drop database dummy;
   DROP DATABASE
   template1=> \q
   	

   When using the Windows version of postgresql, you can use the bundled pgAdmin interface to create the user and verify the access.

If you cannot login using the username and password, and create/drop a database, then this is a good place to stop and fix this first. Scarab will not work, unless the database is correctly configured. Many resources to find more information can be found on the PostgreSQL Website.

Scarab Configuration

When the database has been setup, the user account as which the application will talk to the database has been created and when the setup has been tested, the time has come to configure scarab itself.

1. Create a scarab/build.properties file. There are instructions in the SCARAB/README.txt file which detail why you want to do this.
2. In the build.properties file, fill out the following properties with the right information pertaining to Postgresql (see below for examples).

   scarab.database.name=scarab
   
   
   scarab.database.type=postgresql
   
   
   scarab.database.username=[INSERT_USERNAME_HERE]
   
   
   scarab.database.password=[INSERT_PASSWORD_HERE]