1997-09-26 10:22:21 +02:00
|
|
|
This is a simple readme describing how to compile and use the jdbc driver.
|
|
|
|
|
|
|
|
This isn't a guide on how to use JDBC - for that refer to Javasoft's web site:
|
|
|
|
|
|
|
|
http://www.javasoft.com
|
|
|
|
|
|
|
|
or the JDBC mailing list:
|
|
|
|
|
|
|
|
jdbc@java.blackdown.org
|
|
|
|
|
|
|
|
http://www.blackdown.org
|
|
|
|
|
1998-01-11 22:14:56 +01:00
|
|
|
For problems with this driver, then refer to the postgres-interfaces email
|
|
|
|
list:
|
|
|
|
|
|
|
|
http://www.postgresql.org
|
|
|
|
|
1999-01-17 05:51:59 +01:00
|
|
|
When PostgreSQL V6.4 was released, full documentation for the driver was
|
|
|
|
included in the main documentation tree (under the doc directory).
|
|
|
|
|
|
|
|
This file was finally amended on December 29 1998 to account for the major
|
|
|
|
changes made to the driver since V6.4 was released.
|
1998-01-11 22:14:56 +01:00
|
|
|
|
1997-09-26 10:22:21 +02:00
|
|
|
---------------------------------------------------------------------------
|
|
|
|
|
|
|
|
COMPILING
|
|
|
|
|
|
|
|
To compile the driver, simply use make in the src/interfaces/jdbc directory.
|
|
|
|
This will compile the driver, and build a .jar file (Java ARchive).
|
|
|
|
|
|
|
|
REMEMBER: once you have compiled the driver, it will work on ALL platforms
|
|
|
|
that support the JDK 1.1 api or later.
|
|
|
|
|
1999-01-17 05:51:59 +01:00
|
|
|
The V6.5 driver introduced support for the JDBC2 specification (which is used
|
|
|
|
with JDK 1.2 api and later). This caused us some problems because classes
|
|
|
|
written for JDBC1 and JDBC2 are not compatible, so a large chunk of the
|
|
|
|
driver had to be re-written to accomodate this.
|
|
|
|
|
|
|
|
Running make will build a .jar file (postgresql.jar) which contains the driver.
|
|
|
|
That jar file will contain the driver for _your_ version of the JDK. That is,
|
|
|
|
if you run make using JDK 1.1.7, then you will get the JDBC1 driver. If you
|
|
|
|
run using 1.2 then you will get the JDBC2 driver.
|
|
|
|
|
|
|
|
Tip: If you want the driver to run on both JDBC1 or JDBC2, first compile under
|
|
|
|
JDK 1.1.x, then recompile under JDK 1.2.
|
|
|
|
|
|
|
|
In testing, I've done this using 1.1.6 (running under linux), and running make
|
|
|
|
on my Win95 based Laptop (CygWin B20.1 was used to get a GNUMake - and a
|
|
|
|
decent shell {bash}).
|
|
|
|
|
|
|
|
When the .jar file is built, it includes all the classes under postgresql, and
|
|
|
|
the driver automatically selects the correct classes.
|
|
|
|
|
1997-09-26 10:22:21 +02:00
|
|
|
That means you don't have to compile it on every platform. Believe me, I
|
|
|
|
still hear from people who ask me "I've compiled it ok under Solaris, but it
|
|
|
|
won't compile under Linux" - there's no difference.
|
|
|
|
|
1999-01-17 05:51:59 +01:00
|
|
|
PS: When you run make, don't worry if you see more than one or two calls to
|
|
|
|
javac. This is normal, because the driver dynamically loads classes, and
|
|
|
|
the Makefile ensures everything gets compiled.
|
|
|
|
|
|
|
|
I advise you don't try running javac outside of make. You may miss something.
|
1997-09-26 10:22:21 +02:00
|
|
|
|
1997-09-29 22:11:51 +02:00
|
|
|
Possible problems
|
|
|
|
|
|
|
|
You may see a message similar to:
|
|
|
|
|
|
|
|
postgresql/Driver.java:87: interface java.sql.Connection is an interface. It can't be instantiated.
|
|
|
|
return new Connection (host(), port(), props, database(), url, this);
|
|
|
|
|
|
|
|
This is caused by not having the current directory in your CLASSPATH. Under
|
|
|
|
Linux/Solaris, unset the CLASSPATH environment variable, and rerun make.
|
|
|
|
|
1999-01-17 05:51:59 +01:00
|
|
|
If you are still having problems, I keep a copy of the driver (for different
|
|
|
|
versions of the backend) on my web site http://www.retep.org.uk/postgres/
|
|
|
|
|
1997-09-26 10:22:21 +02:00
|
|
|
---------------------------------------------------------------------------
|
|
|
|
|
|
|
|
INSTALLING THE DRIVER
|
|
|
|
|
|
|
|
To install the driver, the .class files have to be in the classpath. This can be
|
|
|
|
done in two ways:
|
|
|
|
|
|
|
|
1: create a directory "postgresql" (and it must be called this) in the current
|
|
|
|
directory (or a directory in the class path), and copy all .class files
|
|
|
|
into it.
|
|
|
|
|
|
|
|
2: copy the postgres.jar file into a directory, and add it to the classpath.
|
|
|
|
|
|
|
|
ie: under LINUX/SOLARIS (the example here is my linux box):
|
|
|
|
|
|
|
|
export CLASSPATH=.:/usr/local/lib/postgresql.jar:/usr/local/jdk1.1.1/lib/classes.zip
|
|
|
|
|
|
|
|
note: in java, .zip and .jar files hold collections of classes.
|
|
|
|
|
|
|
|
---------------------------------------------------------------------------
|
|
|
|
|
|
|
|
USING THE DRIVER
|
|
|
|
|
|
|
|
To use the driver, you must introduce it to JDBC. Again, there's two ways
|
|
|
|
of doing this:
|
|
|
|
|
|
|
|
1: Hardcoded.
|
|
|
|
|
|
|
|
This method hardcodes your driver into your application/applet. You
|
|
|
|
introduce the driver using the following snippet of code:
|
|
|
|
|
|
|
|
try {
|
|
|
|
Class.forName("postgresql.Driver");
|
|
|
|
} catch(Exception e) {
|
|
|
|
// your error handling code goes here
|
|
|
|
}
|
|
|
|
|
|
|
|
Remember, this method restricts your code to just the postgresql database.
|
|
|
|
|
|
|
|
2: Parameters
|
|
|
|
|
|
|
|
This method specifies the driver from the command line. When running the
|
|
|
|
application, you specify the driver using the option:
|
|
|
|
|
|
|
|
-Djdbc.drivers=postgresql.Driver
|
|
|
|
|
|
|
|
eg: This is an example of running one of my other projects with the driver:
|
|
|
|
|
|
|
|
java -Djdbc.drivers=postgresql.Driver finder.finder
|
|
|
|
|
|
|
|
note: This method only works with Applications (not for Applets).
|
|
|
|
However, the application is not tied to one driver, so if you needed
|
|
|
|
to switch databases (why I don't know ;-) ), you don't need to
|
|
|
|
recompile the application (as long as you havent hardcoded the url's).
|
|
|
|
|
|
|
|
---------------------------------------------------------------------------
|
|
|
|
|
|
|
|
JDBC URL syntax
|
|
|
|
|
|
|
|
The driver recognises JDBC URL's of the form:
|
|
|
|
|
|
|
|
jdbc:postgresql:database
|
|
|
|
|
|
|
|
jdbc:postgresql://host/database
|
|
|
|
|
|
|
|
jdbc:postgresql://host:port/database
|
|
|
|
|
|
|
|
Also, you can supply both username and passwords as arguments, by appending
|
|
|
|
them to the URL. eg:
|
|
|
|
|
|
|
|
jdbc:postgresql:database?user=me
|
|
|
|
jdbc:postgresql:database?user=me&password=mypass
|
|
|
|
|
1999-01-17 05:51:59 +01:00
|
|
|
Previous versions you had to use an auth argument to tell the driver what
|
|
|
|
authentication scheme to use when connecting to the database.
|
1997-10-30 19:24:44 +01:00
|
|
|
|
1999-01-17 05:51:59 +01:00
|
|
|
However, this is no longer supported because the database tells the driver
|
|
|
|
what scheme it's expecting.
|
1998-01-11 22:14:56 +01:00
|
|
|
|
1997-09-26 10:22:21 +02:00
|
|
|
---------------------------------------------------------------------------
|
|
|
|
|
|
|
|
That's the basics related to this driver. You'll need to read the JDBC Docs
|
|
|
|
on how to use it.
|
|
|
|
|
|
|
|
POSTGRESQL SPECIFICS
|
|
|
|
--------------------
|
|
|
|
|
1997-10-30 19:24:44 +01:00
|
|
|
Date datatype:
|
|
|
|
|
|
|
|
The driver now issues the "show datestyle;" query when it first connects, so
|
|
|
|
any call to ResultSet.getDate() how returns the correct date.
|
|
|
|
|
|
|
|
One caveat though: if you change the datestyle from within JDBC, you must also
|
|
|
|
issue the "show datestyle" query. Without this, the driver will not know of
|
|
|
|
the change.
|
|
|
|
|
|
|
|
ie:
|
|
|
|
Statement s = db.createStatement();
|
|
|
|
...
|
|
|
|
s.executeUpdate("set datestyle='european'");
|
|
|
|
s.executeUpdate("show datestyle");
|
|
|
|
..
|
|
|
|
s.close();
|
1999-01-17 05:51:59 +01:00
|
|
|
|
|
|
|
Please note: This may change later, so that the driver uses the same format
|
|
|
|
internally (similar to how the ODBC driver works).
|
|
|
|
|
1997-10-30 19:24:44 +01:00
|
|
|
------------------
|
|
|
|
|
1997-09-26 10:22:21 +02:00
|
|
|
JDBC supports database specific data types using the getObject() call. The
|
|
|
|
following types have their own Java equivalents supplied by the driver:
|
|
|
|
|
1999-01-17 05:51:59 +01:00
|
|
|
box, circle, line, lseg, path, point, polygon
|
1997-09-26 10:22:21 +02:00
|
|
|
|
|
|
|
When using the getObject() method on a resultset, it returns a PG_Object,
|
|
|
|
which holds the postgres type, and its value. This object also supports
|
|
|
|
methods to retrive these types.
|
|
|
|
|
|
|
|
Eg: column 3 contains a point, and rs is the ResultSet:
|
|
|
|
|
|
|
|
PG_Object o = (PG_Object)rs.getObject(3);
|
|
|
|
PGpoint p = o.getPoint();
|
|
|
|
System.out.println("point returned x="+p.x+", y="+p.y);
|
|
|
|
|
|
|
|
Also, when using these classes, their toString() methods return the correct
|
|
|
|
syntax for writing these to the database.
|
|
|
|
|
|
|
|
---------------------------------------------------------------------------
|
|
|
|
|
1999-01-17 05:51:59 +01:00
|
|
|
Peter T Mount, December 29 1998
|
|
|
|
home email: pmount@retep.org.uk http://www.retep.org.uk
|
|
|
|
work email: petermount@it.maidstone.gov.uk or peter@taer.maidstone.gov.uk
|
1997-10-30 19:24:44 +01:00
|
|
|
|
1999-01-17 05:51:59 +01:00
|
|
|
PS: Please use the home email whenever possible. If you must contact me at work
|
|
|
|
then please cc my home one at the same time.
|