PackageDescription: JdmMysqlDriver


Jdm Mysql Driver

Last published: July 17, 2003 by 'cdegroot'

Defines 21 Classes
Extends 23 Classes

VERSION INFORMATION

This document is for JdmMysqlDriver 1.0.0

INSTALLATION:

To install the Mysql driver, load the parcel named "JdmMysqlDriver-X.X.X"
from the distribution directory. If you want to load the test suite as
well, load the parcel JdmMysqlDriverTests-X.X.X.

MYSQL VERSIONS SUPPORTED:

The Mysql driver has only been tested using versions 3.21.33b,
3.22.14-gamma, 3.22.20, and 3.23.27-beta however all versions in between
should work. The driver has been tested on both Linux and NT.

--UPDATE version 0.2.0 has only been tested with mysql version 3.22.14-gamma
and 3.22.20. Tested platforms are Linux (Red Hat dist 5.1)
kernel 2.0.36.

The driver does not support the YEAR type which is new to 3.22.

USAGE:

Using the driver is fairly simple. To execute a query you need to
create a connection to the database, create a statement on the connection,
and execute your query.

Example:

Let's say I want to connect to the "test" database on the localhost.
My user name is "doe" and my password is "mypass".

| connection statement result |

connection := JdmConnection on:
(JdmConnectionSpec new initialize user: 'miller'; password: 'mypass';
database: 'test').

The JdmConnectionSpec is initialized with defaults for all the values
which are:

user := ''.
password := ''.
host := 'localhost'.
port := 3306.
database := 'test'

Now I want to insert a row into a table I have named "aTable". First
I need to create a statement.

statement := connection createStatement.

Now execute the query.

result := statement executeQuery: 'insert into aTable (aField) values (aValue)'.

The result that is returned is a JdmResult. It holds two values: The result
type and the actual result value. For update queries (such as INSERT,
UPDATE, DELETE, CREATE TABLE, etc) the type is set to #update and the
value is an Integer designating the number of rows effected. For read
queries (such as SELECT...others such as SHOW, DESCRIBE, etc are not
yet implemented) the type is set to #read and the value is a JdmResultSet.

A JdmResultSet reads rows off the result stream. It also contains a
collection of column information (JdmColumns) which describe the type, size,
and other characteristics of the returned column. Generally you
grab the columns by sending the "next" message to the result set.
The next message returns a Boolean which indicates whether or not
there are any more rows to be read. Do NOT read past the last row...
currently the driver will block when this happens.

A common usage of a JdmResultSet would be:

| resultSet value |

[resultSet next] whileFalse: [value := resultSet valueNamed: 'columnName'].

The result set has several accessing methods. They are:

valueAt: anInteger -- returns the Smalltalk value at column
number anInteger
rawValueAt: anInteger -- returns the raw (String) value at column
number anInteger
valueNamed: aString -- returns the Smalltalk value for the column
named aString.
rawValueNamed: aString -- returns the raw (String) value for the column
named aString

The value* methods use the JdmFieldConverter to convert the Mysql
data into Smalltalk objects. The only unsupported Mysql type is
the YEAR type. Mysql sends the types of columns with it's query
results which are used to determine what Smalltalk object a field should be
converted to. Unfortunately, it reports TEXT as BLOBs so TEXT values
result in ByteArrays. This conversion can be avoided by sending
the rawValue* messages instead. Mysql SETS are also misreported.
Mysql says they are Strings so SETS are not automatically parsed.

--UPDATE Holders have been removed. The JdmFieldConverter class
handles all conversions now.

NOTES

The error handling in the driver needs some work. General errors and
database errors are reported well, but if the protocol fails the results can
be non-deterministic. The protocol SHOULDNT fail unless the connection
is broken.

UPDATE -- I added a flush method to clear the result set. It still has to
be done manually since I don't see a clean way of having the
JdmStatement clear a result set opened on the current connection.

If a JdmResultSet is opened and not read to the end, no further queries
can be made on the connection. Eventually the driver will handle this,
but it does not at this time.

Mysql supports times between -838:59:59 and 838:59:59 however the VisualWorks
Time class only supports times between 00:00:00 and 23:59:59 so any value
in the database outside this range cannot be converted to Time. You can
get the raw value and handle it yourself.

If you declare a Mysql numeric type with the qualifier ZEROFILL, automatic
conversion to the corresponding Smalltalk type will drop the zeroes. Get
the raw value to avoid this.

Only full Timestamps are currently converted (ie a TIMESTAMP(14)).

TESTING

See INSTALLATION for installing the test suites. To run the test suites
your mysql server needs to be on the local machine, the database "test"
needs to exist (it is created initially by the mysql_install_db script),
and all users on the localhost need full access to the database "test".

The aforementioned conditions are true when Mysql is first installed.

The tests run fairly slow since each row consists of all possible
Mysql types and many of the inserted values are generated.

To run the tests execute the following:

JdmMysqlTestSuite new run inspect