Hacking J-Bird (Version 0.5.2): Accessing J-Bird from Perl using DBD::JDBC

The J-Bird database can be accessed by Perl scripts that make use of Perl's DBD::JDBC module. You should know from the start that this is something of a hack. DBD::JDBC has not been maintained since 2001, and to install it you will have to edit the module source code to make a small change. Without a maintainer, the module could fail permanently as Perl's method of handling databases (DBI interface) evolves. DBD::JDBC has not been thoroughly tested. For best results, use only SQL, and avoid explicitly invoking JDBC methods. DBD::JDBC should be safe to use for reading the database. It is unknown whether modifying the database is risky. Always backup your data and be prepared to lose everything but the backup.

There is another risk. DBD::JDBC uses a proxy server that listens for network connections. Although it's extremely unlikely that exploits have been written to take advantage of the proxy server, it is possible that someone might discover the open port and probe it. At least, the proxy server is written in Java. You really are on your own.

To use DBD::JDBC, you will install and modify the module, write your Perl scripts that query J-Bird, start the DBD::JDBC proxy server, run your Perl scripts and then stop the proxy server. This page discusses how to modify the module, how to start and stop the proxy server, and it provides a sample Perl script that queries J-Bird.

Modifying DBD::JDBC

In the file JDBC.pm, comment-out lines 1028 and 1060. They contain the string BIGINT. Type BIGINT is no longer supported by the Perl database interface (DBI). If you are uncomfortable about editing the file, don't. When you try to run your Perl script, it will bomb with error messages that identify the lines in JDBC.pm that need to be commented out.

Install DBD::JDBC according to its directions. The module is available from the Comprehensive Perl Archive Network. It is not listed in the index of modules. Go to an ftp site, and it will be in the directory with other Perl DBD modules. The most recent version is 0.64.

Running DBD::JDBC proxy server

The DBD::JDBC proxy must be running for your Perl scripts to access the J-Bird database. The proxy is a Java program. A script is provided that runs the proxy. You will need to edit the script. At the very least, you need to specify the location of the jar file that contains the proxy. You may wish to change other parameters as well. The script can be downloaded as dbd-jdbc-proxy.sh, and it is provided below for inspection.


#! /bin/sh

# This script runs the proxy server that is used by DBD::JDBC to access
# databases.  It provides access to the Mckoi database that is used
# by J-Bird.  

# 1) Edit the fields below to reflect the location of the dbd_jdbc.jar file
#    and the home of J-Bird.
# 2) Edit other aspects of the script to your liking.
# 3) Run the script.
# 4) There seems to be no way of stopping the proxy other than using ctrl-C
#    to halt it.

##### Edit the following to suit your needs

			# the DBD-JDBC module jar file
DBD_JDBC_JAR="$HOME/usr/src/DBD-JDBC-0.64/dbd_jdbc.jar"
			# the directory in which J-Bird is installed
JBIRD_HOME="$HOME/J-Bird"
			# the port on which the DBD-JDBC server listens
PORT=37776
			# DBD-JDBC server verbosity: silent, brief, verbose,
			# tedious, abusive
TRACE=brief

##################### Shouldn't need to edit below ##########################

MCKOI_HOME="$JBIRD_HOME/downloads/drivers/Mckoi"
MCKOI_CP="$MCKOI_HOME/mckoidb.jar:$MCKOI_HOME/gnu-regexp.jar"

export CLASSPATH="$DBD_JDBC_JAR:$MCKOI_CP"

DRIVER=com.mckoi.JDBCDriver 

cd "$JBIRD_HOME"

java -Djdbc.drivers=$DRIVER 					\
     -Ddbd.port=$PORT						\
     -Ddbd.trace=$TRACE						\
     com.vizdom.dbd.jdbc.Server

The only way to stop the proxy is to kill it by using the ctrl-C break sequence or by using the kill command.

A sample Perl script that accesses J-Bird

The Perl script below uses the DBD::JDBC Perl module to print a tab-delimited list of region name, locality, species common name, date, and observer of every tick in the database. Read the script and modify it as needed. The script can be downloaded as dbd-jdbc-example.pl.


#! /usr/bin/perl

# Example script showing use of DBD::JDBC to access J-Bird.
# This script prints in tab-delimited format region name, locality,
# date, common name and observer for all ticks stored in J-Bird.

# The script is written under the assumption that the DBD::JDBC proxy
# is run from the J-Bird directory.  The script dbd-jdbc-proxy.sh
# runs the proxy from the J-Bird directory as this script expects.

use strict;
no strict "vars";
no strict "subs";
no strict "refs";

use DBI;

			# Name of Mckoi database config file used
			# by J-Bird. Relative path should be OK for everyone 
			# because the DBD::JDBC proxy is run from the J-Bird
			# directory.

my $mckoi_config = "./mckoidb.conf";

my $user = "jbird";
my $pw = "chirp";

			# Host and port on which DBD::JDBC proxy is running
			# No need to change these if no change as been
			# made to dbd-jdbc-proxy.sh.

my $host = "127.0.0.1";
my $port = "37776";
			# Characterset being used on your computer
my $charset = "ASCII";

	# Query region name, locality, date, common name, observer name
	# for all ticks
 
my $query = <<EOQ;
SELECT regions.RegName, trips.Locality, trips.ObsDate, commonnames.Common, 
		observers.ObsName
	FROM commonnames, ticks, trips, regions, observers
	WHERE commonnames.SpecNo = ticks.SpecNo 
		AND ticks.TripNo = trips.TripNo 
		AND trips.Region = regions.RegNo
		AND ticks.Observer = observers.ObsNo
EOQ

	# alternative simple query

# my $query = "SELECT * FROM ticks";

################## You shouldn't need to edit anything below here ############

			# URL for J-Bird database

my $url = "jdbc:mckoi:local://$mckoi_config";

			# DBD::JDBC DSN

my $dsn="dbi:JDBC:hostname=$host;port=$port;url=$url;jdbc_character_set=$charset";

			# ACTION

my $dbh = DBI->connect($dsn, $user, $pw);
my $sth = $dbh -> prepare($query);
$sth -> execute;
while (my @row = $sth -> fetchrow_array) {
	print join("\t", @row), "\n";
}
$sth -> finish;
$dbh -> disconnect;


Previous (Hacking - arbitrary GUI) Contents Next (Database schema)

SourceForge Logo

Page last updated 17 July 2004