255 lines
8.7 KiB
Plaintext
255 lines
8.7 KiB
Plaintext
This is a simple readme describing how to compile and use the jdbc driver.
|
|
|
|
This file was amended on May 2 2000 to document the changes made in the 7.0
|
|
release.
|
|
|
|
---------------------------------------------------------------------------
|
|
|
|
This isn't a guide on how to use JDBC - for that refer to Javasoft's web site:
|
|
|
|
http://www.javasoft.com
|
|
|
|
For problems with this driver, then refer to the postgres-interfaces email
|
|
list:
|
|
|
|
http://www.postgresql.org
|
|
|
|
---------------------------------------------------------------------------
|
|
|
|
COMPILING
|
|
|
|
There are actually two versions of the driver. One for the JDBC1.2 specification, and one for the JDBC2 specification. To compile the driver, you need to select the correct one.
|
|
|
|
If you have JDK1.1.x you need to type: make jdbc1
|
|
|
|
If you have JDK1.2 or JDK1.3, you need to type: make jdbc2
|
|
|
|
This will compile the driver, and build a .jar file (Java ARchive) called
|
|
postgresql.jar
|
|
|
|
That jar file will contain the driver for _your_ version of the JDK.
|
|
|
|
REMEMBER: Once you have compiled the driver, it will work on ALL platforms
|
|
that support that version of the API. You don't need to build it for each
|
|
platform.
|
|
|
|
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.
|
|
|
|
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.
|
|
|
|
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.
|
|
|
|
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/
|
|
|
|
---------------------------------------------------------------------------
|
|
|
|
INSTALLING THE DRIVER
|
|
|
|
To install the driver, the .class files have to be in the classpath. To do
|
|
this, 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
|
|
|
|
---------------------------------------------------------------------------
|
|
|
|
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("org.postgresql.Driver");
|
|
} catch(Exception e) {
|
|
// your error handling code goes here
|
|
}
|
|
|
|
Remember, this method restricts your code to just the postgresql database.
|
|
However, this is how most people load the driver.
|
|
|
|
2: Parameters
|
|
|
|
This method specifies the driver from the command line. When running the
|
|
application, you specify the driver using the option:
|
|
|
|
-Djdbc.drivers=org.postgresql.Driver
|
|
|
|
eg: This is an example of running one of my other projects with the driver:
|
|
|
|
java -Djdbc.drivers=org.postgresql.Driver uk.org.retep.finder.Main
|
|
|
|
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
|
|
|
|
---------------------------------------------------------------------------
|
|
|
|
That's the basics related to this driver. You'll need to read the JDBC Docs
|
|
on how to use it. However, there are some examples included in the example
|
|
directory. To build, type: make examples
|
|
|
|
To run them, they follow the same syntax. For example, the basic example shows
|
|
how to insert data, and perform queries:
|
|
|
|
java example.basic jdbc:postgresql:test user password
|
|
|
|
---------------------------------------------------------------------------
|
|
|
|
POSTGRESQL SPECIFICS
|
|
--------------------
|
|
|
|
Large Objects:
|
|
|
|
A "feature" of PostgreSQL is that access to LargeObjects is only permitted
|
|
within a Transaction. Because of this, any use of LargeObjects (also known
|
|
as Blobs) requires that the Connection.setAutoCommit() method be called
|
|
disabling the autocommit feature.
|
|
|
|
For example:
|
|
|
|
Connection db; // open the connection here
|
|
db.setAutoCommit(false); // Turn off AutoCommit
|
|
|
|
------------------
|
|
|
|
Large Object API
|
|
|
|
Most of the time, you can use the getBytes()/setBytes() methods to read and
|
|
write small Large Objects. However, PostgreSQL's own internal api's are
|
|
available. These allow you to access the object as if it was a file.
|
|
|
|
The first thing you need to do is to open the LargeObjectManager. This class
|
|
handles the opening of existing objects, and creating new ones. To do this,
|
|
you use the following line of code:
|
|
|
|
LargeObjectManager lobj;
|
|
lobj = ((org.postgresql.Connection)db).getLargeObjectAPI();
|
|
|
|
where db is a reference to an open Connection object.
|
|
|
|
Once that is done, you can use the API for the lifetime of that Connection.
|
|
|
|
To create an object, you call the create() method. This takes an argument
|
|
with the file modes you intend to use. The following line is normally
|
|
sufficient:
|
|
|
|
int oid = lobj.create(LargeObjectManager.READ|LargeObjectManager.WRITE);
|
|
|
|
Here, lobj is the LargeObjectManager we have opened earlier, and oid is the
|
|
Large Object's oid in the database.
|
|
|
|
To open an existing object, you use the open() method. This takes an oid, and
|
|
the file permissions. It then returns a LargeObject object.
|
|
|
|
LargeObject obj = lobj.open(oid,LargeObjectManager.WRITE);
|
|
|
|
Once the LargeObject is open, you can call methods to read, write, seek etc.
|
|
Here's the supported methods:
|
|
|
|
int oid = obj.getOID(); Return the objects oid
|
|
obj.close(); Close the object
|
|
byte data[] = obj.read(int len); Read len bytes
|
|
onj.read(byte data[],int off,int len); Read into data[off] len bytes
|
|
obj.write(byte data[]); Write the array data
|
|
obj.write(byte data[],int off,int len); Write len bytes from data[off]
|
|
obj.seek(int pos,int ref); As fseek in C.
|
|
obj.seek(int pos); Move to pos (from the begining)
|
|
int pos = obj.tell(); Returns the current position
|
|
int size = obj.size(); Returns the objects size
|
|
|
|
Caveat: If you commit(), rollback() a transaction, or turn on autocommit whilst
|
|
an object is open PostgreSQL will close it. You will need to reopen the object
|
|
before using it again. Using the existing LargeObject will cause an
|
|
SQLException to be thrown.
|
|
|
|
------------------
|
|
|
|
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();
|
|
|
|
Please note: This may change later, so that the driver uses the same format
|
|
internally (similar to how the ODBC driver works).
|
|
|
|
------------------
|
|
|
|
JDBC supports database specific data types using the getObject() call. The
|
|
following types have their own Java equivalents supplied by the driver:
|
|
|
|
box, circle, line, lseg, path, point, polygon
|
|
|
|
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.
|
|
|
|
---------------------------------------------------------------------------
|
|
|
|
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
|
|
|
|
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.
|