by Michael Neumann (neumann@s-direknet.de)
$Id: DBD_SPEC.html,v 1.14 2001/09/07 13:32:39 michael Exp $
The directory layout is the following:
DBD/ DBD/Driver1 DBD/Driver1/Driver1.rb DBD/Driver1/helper.rb . . DBD/Driver2 . . .
Where "Driver1" and "Driver2" are the names of DBD driver. For example if you have two drivers installed, "Oracle" and "Sybase" it would look like:
DBD/ DBD/Oracle DBD/Oracle/Oracle.rb # <== this is the main driver DBD/Oracle/oracle.so # <== is used by Oracle.rb DBD/Sybase/Sybase.so # <== this is the main driver # has no helper files
When DBI loads a DBD driver it search all "DBD" directories in Ruby's LOAD_PATH ($:).
The DBD driver is simply named after the Database, e.g. Oracle, DB2 etc. The suffix will normally be ".rb" but can be any other valid suffix, which Ruby is possible to load, e.g. ".so", ".sl" or ".dll", and depends for non-Ruby DBD driver on the underlying operating system. When I refer to the driver name, then I speak of the filename without the suffix, e.g. Oracle or DB2.
The name specified in the DSN *1 must be the same as the driver name.
A DBD driver has to provide three classes in the namespace
DBI::DBD::
DriverName where DriverName is the name of the
driver, e.g. Oracle or DB2.
The three classes must be named Driver
, Database
and Statement
.
This class must inherit from DBI::BaseDriver
.
Driver
connect( dbname, user, auth, attr )
Connect to a database and return a newly created Database
object.
Driver
default_user
Return an array of the form ['username', 'password']
which represent
the default user when no user and password was specified.
Defaults to ['', '']
if not implemented.
default_attributes
Return a Hash
containing the default attributes which are used
in connect
additional to the ones the user specify.
Defaults to {}
(empty hash) if not implemented.
data_sources
Return an array of all valid DSN this driver can access.
Defaults to []
(empty array) if not implemented.
disconnect_all
Disconnect all connections made with this driver.
Defaults to raise a NotImplementedError.
This class must inherit from DBI::BaseDatabase
.
Database
disconnect
Disconnect from database. But before you have to rollback all outstanding transactions, so all changes not yet commited get lost.
prepare( statement )
Prepare the SQL statement and return an object of class Statement
.
ping
Ping the database, and check if the connection is alive. This can be implemented by executing a SQL statement like "SELECT 1 FROM DUAL" for Oracle database, or for other databases this should be query on a table which normally always exists.
Return true
if the connection is alive, otherwise false
.
Database
commit
rollback
Commit or roll back the current transaction.
Defauls to raise a NotSupportedError, so if the database do not implement transactions (mSQL, mySQL, CSV) do not overwrite this method.
tables
Return an Array of all tables and views.
Defaults to return the empty Array [].
columns( table )
Return more information about the columns of table table. Return an Array of Hashes, like Statement#column_info do.
Defaults to return an empty Array [].
execute( statement, *bindvars )
Immediate execution (without preparation) of SQL statement with binding of placeholders to values given in bindvars before.
Return a Statement
object.
Defaults to the call sequence of Database#prepare(), Statement#bind_params() and Statement#execute().
do( statement, *bindvars )
Execution of SQL statement with binding of placeholders to values given
in bindvars before, but without returning a Statement
object.
So this is used for 'INSERT', 'UPDATE', 'DELETE' as well as for DCL, which
do not return a result-set.
Return the RPC (Row Processed Count) or nil
if no RPC is available.
Defaults to Database#execute() and Statement#rows() followed by Statement#finish().
quote( value )
Quote the given value value database specific and return the result.
NOTE: This method is not really useful, because of Statement#bind_param.
[ attr ]
Return value of attribute attr.
Defauls to return the value of @attr[attr]
.
[attr] = value
Set value of attribute attr to value. An attribute is e.g. "AutoCommit". Raise an NotSupportedError, if the database do not support an attribute.
The default implementation is to raise a NotSupportedError.
This class must inherit from DBI::BaseStatement
.
Statement
bind_param( param, value, attribs )
Bind param which is either a String
which is then the name of the
placeholder used in the SQL statement (e.g. Oracle: "SELECT * FROM EMP WHERE ENAME = :ename")
or it is a Fixnum
which is then the number of the placeholder where counting starts at 1.
value is the value which is bound to the placeholder.
If value is a String
, then the default SQL type is VARCHAR
or CHAR
.
If value is a Fixnum
or Bignum
, the default SQL type is INT
.
If value is a Float
, the default SQL type is FLOAT
.
attribs is not yet used in this version but could be a hash containing more information like parameter type etc.
execute
Execute the statement.
finish
Free all the resources for the statement.
After calling finish
no other operation on this
statement is valid.
fetch
Fetch the current row.
Return a Array
containing all column-data or nil
if
the last column has been read.
Note: This method should return not a newly created object on each call, instead you should return one and the same Array object but with changed data.
column_info
Return an Array
of Hash
's, one for each column.
Each Hash
object must have at least one key 'name' which
value is the name of that column.
Further possible values are 'sql_type' (integer, e.g. DBI::SQL_INT),
'type_name' (string), 'precision' (= column size), 'scale' (= decimal digits),
'default', 'nullable', 'indexed', 'primary' and 'unique'.
rows
Return the RPC (Row Processed Count) of the last executed statement, or
nil
if no such exist.
Statement
bind_params( *bindvars )
Binds the placeholders in the statement to the values of bindvars.
Defaults to calling bind_param for each value, with param starting from 1 increasingly.
cancel
Free any result set resources which were made after a call to execute
.
After calling this method, a call to one of the fetch methods is no more valid.
Defaults to do nothing.
fetch_scroll( direction, offset )
direction is one of the following constants:
offset is a positive or negativ number (only when SQL_FETCH_RELATIVE is used).
By default only SQL_FETCH_NEXT, SQL_FETCH_LAST, SQL_FETCH_RELATIVE (if positive) are implemented, otherwise it raises NotSupportedError.
Note: This method should return not a newly created object on each call, instead you should return one and the same Array object but with changed data.
fetch_many( cnt )
Return an Array
of the next cnt rows, where a row is itself an Array
.
Note: Unlike fetch
, this method should return a new Array object.
If there are no more cnt rows available return the rest.
Return nil
if no rows are available.
Defaults to multiple calls to fetch
.
fetch_all
Return an Array
of all rows which have not yet been fetched, where a row is
itself an Array
(see Statement#fetch_many).
Note: Unlike fetch
, this method should return a new Array object.
Return nil
if no rows are available.
Defaults to multiple calls to fetch
.
*1Data Source Name, e.g. "dbi:Oracle:oracle.neumann"