SWI-Prolog ODBC Interface
Jan Wielemaker
SWI,
University of Amsterdam
The Netherlands
E-mail: jan@swi-prolog.org
This document describes the SWI-Prolog interface to ODBC, the Microsoft
standard for Open DataBase Connectivity. These days there are
ODBC managers from multiple vendors for many platforms as well as
drivers for most databases, making it an attractive target for a Prolog
Database connection.
The database interface is envisioned to consist of two layers. The first layer is an encapsulation of the core functionality of ODBC. This layer makes it possible to run SQL queries. The second layer exploits the relation between Prolog predicates and database tables, providing ---a somewhat limited--- natural Prolog view on the data. The current interface only covers the first layer. |
The value of RDMS for Prolog is often over-estimated, as Prolog itself can manage substantial amounts of data. Nevertheless a Prolog/RDMS interface provides advantages if data is already provided in an RDMS, data must be shared with other applications, there are strong persistency requirements or there is too much data to fit in memory.
The popularity of ODBC makes it possible to design a single foreign-language module that provides RDMS access for a wide variety of databases on a wide variety of platforms. The SWI-Prolog RDMS interface is closely modelled after the ODBC API. This API is rather low-level, but defaults and dynamic typing provided by Prolog give the user quite simple access to RDMS, while the interface provides the best possible performance given the RDMS independency constraint.
The Prolog community knows about various high-level connections between RDMS and Prolog. We envision these layered on top of the ODBC connection described here.
The ODBC interface deals with a single ODBC environment but with multiple simultaneous connections. The predicates in this section deal with connection management.
alias
option is used. The options below are defined. In addition, options of
odbc_set_connection/2
may be provided.
user(User)
.
once
(default if an alias
is provided), a second call to open the same DSN simply
returns the existing connection. If multiple
(default if
there is no alias name), a second connection to the same data-source is
opened.
The following example connects to the WordNet database, using the
connection alias wordnet
and opening the connection only
once:
open_wordnet :- odbc_connect('WordNet', _, [ user(jan), password(xxx), alias(wordnet), open(once) ]). |
true
(default), each update statement is committed
immediately. If false
, an update statement starts a
transaction that can be committed or rolled-back. See section
2.3 for details on transaction management.
ODBC distinguishes between direct execution of literal SQL strings and parameterized execution of SQL strings. The first is a simple practical solution for infrequent calls (such as creating a table), while parameterized execution allows the driver and database to precompile the query and store the optimized code, making it suitable for time-critical operations. In addition, it allows for passing parameters without going through SQL-syntax and thus avoiding the need for quoting.
for Options.
INSERT
) use odbc_query/2.
Here is a small example using the connection created from odbc_connect/3.
lemma(Lemma) :- odbc_query(wordnet, 'SELECT (lemma) FROM word', row(Lemma). |
Please note that the SQL-statement does not end in the ;
character. Options defines the following options:
default
to use
default conversion for that column. The length of the type-list must
match the number of columns in the result-set.
For example, in the table word
the first column is
defined with the SQL type DECIMAL(6)
. Using this SQL-type,
``001'' is distinct from ``1'', but using Prolog integers is a valid
representation for Wordnet wordno
identifiers. The
following query extracts rows using Prolog integers:
?- odbc_query(wordnet, 'select * from word', X, [ types([integer,default]) ]). X = row(1, entity) |
See also section 2.6 for notes on type-conversion.
SELECT
). The predicate prints a
diagnostic message if teh query returns a result.
ODBC provides for `parameterized queries'. These are SQL queries with
a ?
-sign at places where parameters appear. The ODBC
interface and database driver may use this to precompile the
SQL-statement, giving better performance on repeated queries. This is
exactly what we want if we associate Prolog predicates to database
tables. This interface is defined by the following predicates:
for Options.
?
)
and unify Statement with a handle to the created statement. Parameters
is a list of descriptions, one for each parameter. Each parameter
description is one of the following:
char
, varchar
,
etc. to specify the field-width. In odbc_execute/2,
the must supply the value in default Prolog type for this SQL type. See section
2.6 for details.
atom > date |
The use must supply an atom of format YYYY-MM-DD
rather
than a term date(Year,Month,Day)
. This construct enhances
flexibility and allows for passing values that have no proper
representation in Prolog.
Options defines a list of options for executing the statement. See odbc_query/4 for details.
ODBC doesn't appear to allow for multiple cursors on the same
result-set. (1) This
would imply there can only be one active odbc_execute/3
(i.e. have a choice-point) on a prepared statement. Suppose we have a
table age (name char(25), age integer)
bound to the
predicate age/2 we cannot write the code below without special
precautions. The ODBC interface therefore creates a clone of a statement
if it discovers the statement is being executed, which is discarded
after the statement is finished. (2)
same_age(X, Y) :- age(X, AgeX), age(Y, AgeY), AgeX = AgeY. |
ODBC can run in two modi. By default, all update actions are immediately committed on the server. Using odbc_set_connection/2 this behaviour can be switched off, after which each SQL statement that can be inside a transaction implicitely starts a new transaction. This transaction can be ended using odbc_end_transaction/2.
commit
pending updates are made permanent, using
rollback
they are discarded.
The ODBC documentation has many comments on transation management and its interaction with database cursors.
With this interface we do not envision the use of Prolog as a database manager. Nevertheless, elementary access to the structure of a database is required, for example to validate a database satisfies the assumptions made by the application.
all_types
to enumerate all known types. This predicate
calls SQLGetTypeInfo() and its facet names are derived from the
specification of this ODBC function:
NULL
. May be unknown
false
,
true
, like_only
or all_except_like
.
Databases have a poorly standardized but rich set of datatypes. Some
have natural Prolog counterparts, some not. A complete mapping requires
us to define Prolog data-types for SQL types that have no standardized
Prolog counterpart (such as timestamp), the definition of a default
mapping and the possibility to define an alternative mapping for a
specific column. For example, many variations of the SQL DECIMAL
type cannot be mapped to a Prolog integer. Nevertheless, mapping to an
integer may be the proper choice for a specific application.
The Prolog/ODBC interface defines the following Prolog result types
with the indicated default transformation. Different result-types can be
requested using the types(TypeList)
option for the
odbc_query/4
and odbc_prepare/5
interfaces.
char
, varchar
,
longvarchar
, decimal
and numeric
.
Can be used for all types.
bit
, tinyint
,
smallint
and integer
. Please note that
SWI-Prolog integers are signed 32-bit values, where SQL allows for
unsigned values as well. Can be used for the integral, and decimal
types as well as the types date
and time_stamp
,
which are represented as POSIX time-stamps (seconds after Jan 1, 1970).
real
, float
and
double
. Can be used for the integral, float and decimal
types as well as the types date
and time_stamp
,
which are represented as POSIX time-stamps (seconds after Jan 1, 1970).
Representing time this way is compatible to SWI-Prologs time-stamp
handling.
date(Year,Month,Day)
used as
default for the SQL type date
.
time(Hour,Minute,Second)
used as
default for the SQL type time
.
time_tamp(Year,Month,Day,Hour,Minute,Second,Fraction)
used
as default for the SQL type time_stamp
.
Disregarding some details, ODBC operations return success, error or `success with information'. This section explains how results from the ODBC layer are reported to Prolog.
If an ODBC operation returns `with info', the info is extracted from
the interface and handled to the Prolog message dispatcher print_message/2.
The level of the message is informational
and the term is
of the form:
If an ODBC operation signals an error, it throws the exception
error(
. The
arguments of the odbc(3) term are explained in section
2.7.1.
odbc(State, Native, Message)
, _)
In addition, the Prolog layer performs the normal tests for proper arguments and state, signalling the conventional instantiation, type, domain and resource exceptions.
There is a wealth on ODBC implementations that are completely or almost compatible to this interface. In addition, a number of databases are delivered with an ODBC compatible interface. This implies you get the portability benefits of ODBC without paying the configuration and performance price. Currently this interface is, according to the PHP documentation on this subject, provided by Adabas D, IBM DB2, Solid, and Sybase SQL Anywhere.
The SWI-Prolog ODBC interface was developed using unixODBC and MySQL on SuSE Linux.
On MS-Windows, the ODBC interface is a standard package, linked
against
odbc32.lib
.
The following issues are indentified and waiting for concrete problems and suggestions.
$Null$
and the compound term 'NULL'(_).
Installation on Unix system uses the commonly found configure,
make and make install sequence. SWI-Prolog should be
installed before building this package. If SWI-Prolog is not installed
as pl, the environment variable PL
must be set to
the name of the SWI-Prolog executable. Installation is now accomplished
using:
% ./configure % make % make install |
This installs the foreign libraries in $PLBASE/lib/$PLARCH
and the Prolog library files in $PLBASE/library
, where
$PLBASE
refers to the SWI-Prolog `home-directory'.