You can not select more than 25 topics
Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
636 lines
30 KiB
636 lines
30 KiB
14 years ago
|
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN">
|
||
|
|
<!-- /home/espenr/tmp/qt-3.3.8-espenr-2499/qt-x11-free-3.3.8/doc/sql-driver.doc:35 -->
|
||
|
|
<html>
|
||
|
|
<head>
|
||
|
|
<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
|
||
|
|
<title>SQL Module - Drivers</title>
|
||
|
|
<style type="text/css"><!--
|
||
|
|
fn { margin-left: 1cm; text-indent: -1cm; }
|
||
|
|
a:link { color: #004faf; text-decoration: none }
|
||
|
|
a:visited { color: #672967; text-decoration: none }
|
||
|
|
body { background: #ffffff; color: black; }
|
||
|
|
--></style>
|
||
|
|
</head>
|
||
|
|
<body>
|
||
|
|
|
||
|
|
<table border="0" cellpadding="0" cellspacing="0" width="100%">
|
||
|
|
<tr bgcolor="#E5E5E5">
|
||
|
|
<td valign=center>
|
||
|
|
<a href="index.html">
|
||
|
|
<font color="#004faf">Home</font></a>
|
||
|
|
| <a href="classes.html">
|
||
|
|
<font color="#004faf">All Classes</font></a>
|
||
|
|
| <a href="mainclasses.html">
|
||
|
|
<font color="#004faf">Main Classes</font></a>
|
||
|
|
| <a href="annotated.html">
|
||
|
|
<font color="#004faf">Annotated</font></a>
|
||
|
|
| <a href="groups.html">
|
||
|
|
<font color="#004faf">Grouped Classes</font></a>
|
||
|
|
| <a href="functions.html">
|
||
|
|
<font color="#004faf">Functions</font></a>
|
||
|
|
</td>
|
||
|
|
<td align="right" valign="center"><img src="logo32.png" align="right" width="64" height="32" border="0"></td></tr></table><h1 align=center>SQL Module - Drivers</h1>
|
||
|
|
|
||
|
|
|
||
|
|
<p> <ul>
|
||
|
|
<li> <a href="#Introduction">Introduction</a>
|
||
|
|
<li> <a href="#building">Building the drivers using configure</a>
|
||
|
|
<li> <a href="#buildingmanually">Building the plugins manually</a>
|
||
|
|
<ul>
|
||
|
|
<li> <a href="#QDB2">QDB2</a> - IBM DB2 Driver (v7.1 and higher)
|
||
|
|
<li> <a href="#QIBASE">QIBASE</a> - Borland Interbase Driver
|
||
|
|
<li> <a href="#QMYSQL3">QMYSQL3</a> - MySQL Driver
|
||
|
|
<li> <a href="#QOCI8">QOCI8</a> - Oracle Call Interface Driver, version 8 and 9
|
||
|
|
<li> <a href="#QODBC3">QODBC3</a> - Open Database Connectivity Driver
|
||
|
|
<li> <a href="#QPSQL7">QPSQL7</a> - PostgreSQL v6.x and v7.x Driver
|
||
|
|
<li> <a href="#QSQLITE">QSQLITE</a> - SQLite Driver
|
||
|
|
<li> <a href="#QTDS7">QTDS7</a> - Sybase Adaptive Server
|
||
|
|
</ul>
|
||
|
|
<li> <a href="#troubleshooting">Troubleshooting</a>
|
||
|
|
<li> <a href="#development">How to write your own database driver</a>
|
||
|
|
</ul>
|
||
|
|
<p> <a name="Introduction"></a>
|
||
|
|
<h2> Introduction
|
||
|
|
</h2>
|
||
|
|
<a name="1"></a><p> The <a href="sql.html">SQL Module</a> uses driver <a href="plugins-howto.html">plugins</a> in order to communicate with
|
||
|
|
different database APIs. Since the SQL Module API is
|
||
|
|
database-independent, all database-specific code is contained within
|
||
|
|
these drivers. Several drivers are supplied with Qt and other drivers
|
||
|
|
can be added. The driver source code is supplied and can be used as a
|
||
|
|
model for <a href="#development">writing your own drivers</a>.
|
||
|
|
<p> <em>Note:</em> To build a driver plugin you need to have the appropriate
|
||
|
|
client library for your Database Management System (DBMS). This provides
|
||
|
|
access to the API exposed by the DBMS, and is typically shipped with it.
|
||
|
|
Most installation programs also allow you to install "development
|
||
|
|
libraries", and these are what you need. These libraries are responsible
|
||
|
|
for the low-level communication with the DBMS.
|
||
|
|
<p> The drivers shipped with Qt are:
|
||
|
|
<ul>
|
||
|
|
<li> <a href="#QDB2">QDB2</a> - IBM DB2 Driver (v7.1 and higher)
|
||
|
|
<li> <a href="#QIBASE">QIBASE</a> - Borland Interbase Driver
|
||
|
|
<li> <a href="#QMYSQL3">QMYSQL3</a> - MySQL Driver
|
||
|
|
<li> <a href="#QOCI8">QOCI8</a> - Oracle Call Interface Driver, version 8, 9 and 10
|
||
|
|
<li> <a href="#QODBC3">QODBC3</a> - Open Database Connectivity Driver
|
||
|
|
<li> <a href="#QPSQL7">QPSQL7</a> - PostgreSQL v6.x and v7.x Driver
|
||
|
|
<li> <a href="#QSQLITE">QSQLITE</a> - SQLite Driver
|
||
|
|
<li> <a href="#QTDS7">QTDS7</a> - Sybase Adaptive Server
|
||
|
|
</ul>
|
||
|
|
<p> Note that not all of the plugins are shipped with the Qt Open Source Edition
|
||
|
|
due to license incompatibilities with the GPL.
|
||
|
|
<p> <a name="building"></a>
|
||
|
|
<h2> Building the drivers using configure
|
||
|
|
</h2>
|
||
|
|
<a name="2"></a><p> The Qt configure script automatically detects the available client
|
||
|
|
libraries on your machine. Run "configure -help" to see what drivers
|
||
|
|
can be built. You should get an output similar to this:
|
||
|
|
<p> <pre>
|
||
|
|
Possible values for <driver>: [ mysql oci odbc psql tds ]
|
||
|
|
Auto-Detected on this system: [ mysql psql ]
|
||
|
|
</pre>
|
||
|
|
|
||
|
|
<p> Note that on Windows, the configure script doesn't do any
|
||
|
|
auto-detection.
|
||
|
|
<p> The configure script cannot detect the neccessary libraries and include
|
||
|
|
files if they are not in the standard paths, so it may be necessary to
|
||
|
|
specify these paths using the "-I" and "-L" switches. For example, if
|
||
|
|
your MySQL include files are installed in <tt>/usr/local/mysql</tt> (or in
|
||
|
|
<tt>C:\mysql\include</tt>
|
||
|
|
|
||
|
|
configure: <tt>-I/usr/local/mysql</tt> (or <tt>-I C:\mysql\include</tt>
|
||
|
|
|
||
|
|
Windows).
|
||
|
|
<p> On Windows the -I parameter doesn't accept spaces in
|
||
|
|
filenames, so use the 8.3 name instead, i.e. use <tt>C:\progra~1\mysql</tt>
|
||
|
|
instead of <tt>C:\program files\mysql</tt>.
|
||
|
|
<p> Use the <tt>-qt-sql-<driver></tt> parameter to build the database driver
|
||
|
|
statically into your Qt library or <tt>-plugin-sql-<driver></tt> to build
|
||
|
|
the driver as a plugin. Look at the sections that follow for
|
||
|
|
additional information about required libraries.
|
||
|
|
<p> <a name="buildingmanually"></a>
|
||
|
|
<h2> Building the plugins manually
|
||
|
|
</h2>
|
||
|
|
<a name="3"></a><p> <a name="QMYSQL3"></a>
|
||
|
|
<h3> QMYSQL3 - MySQL 3.x and MySQL 4.x
|
||
|
|
</h3>
|
||
|
|
<a name="3-1"></a><p> <!-- index QMYSQL3 --><a name="QMYSQL3"></a>
|
||
|
|
<p> <h4> General information
|
||
|
|
</h4>
|
||
|
|
<a name="3-1-1"></a><p> MySQL 3.x doesn't support SQL transactions by default. There are some
|
||
|
|
backends which offer this functionality. Recent versions of the MySQL
|
||
|
|
client libraries (>3.23.34) allow you to use transactions on those
|
||
|
|
modified servers.
|
||
|
|
<p> If you have a recent client library and connect to a
|
||
|
|
transaction-enabled MySQL server, a call to the
|
||
|
|
<a href="qsqldriver.html#hasFeature">QSqlDriver::hasFeature</a>( QSqlDriver::Transactions ) function returns
|
||
|
|
TRUE and SQL transactions can be used.
|
||
|
|
<p> If the plugin is compiled against MySQL 4.x client libraries,
|
||
|
|
transactions are enabled by default.
|
||
|
|
<p> You can find information about MySQL on <a href="http://www.mysql.com">http://www.mysql.com</a>
|
||
|
|
<p> <h4> How to build the plugin on Unix/Linux
|
||
|
|
</h4>
|
||
|
|
<a name="3-1-2"></a><p> You need the MySQL header files and as well as the shared library
|
||
|
|
<tt>libmysqlclient.so</tt>. Depending on your Linux distribution you need to
|
||
|
|
install a package which is usually called "mysql-devel".
|
||
|
|
<p> Tell <a href="qmake-manual.html">qmake</a> where to find the MySQL
|
||
|
|
header files and shared libraries (here it is assumed that MySQL is
|
||
|
|
installed in <tt>/usr/local</tt>) and run <tt>make</tt>:
|
||
|
|
<p> <pre>
|
||
|
|
cd $QTDIR/plugins/src/sqldrivers/mysql
|
||
|
|
qmake -o Makefile "INCLUDEPATH+=/usr/local/include" "LIBS+=-L/usr/local/lib -lmysqlclient" mysql.pro
|
||
|
|
make
|
||
|
|
</pre>
|
||
|
|
|
||
|
|
<p> <h4> How to build the plugin on Windows
|
||
|
|
</h4>
|
||
|
|
<a name="3-1-3"></a><p> You need to get the MySQL installation files. Run SETUP.EXE and
|
||
|
|
choose "Custom Install". Install the "Libs & Include Files" Module.
|
||
|
|
Build the plugin as follows (here it is assumed that MySQL is
|
||
|
|
installed in <tt>C:\MYSQL</tt>):
|
||
|
|
<p> <pre>
|
||
|
|
cd %QTDIR%\plugins\src\sqldrivers\mysql
|
||
|
|
qmake -o Makefile "INCLUDEPATH+=C:\MYSQL\INCLUDE" "LIBS+=C:\MYSQL\LIB\OPT\LIBMYSQL.LIB" mysql.pro
|
||
|
|
nmake
|
||
|
|
</pre>
|
||
|
|
|
||
|
|
<p> If you are not using a Microsoft compiler, replace <tt>nmake</tt> with <tt>make</tt> in the statement above.
|
||
|
|
<p> <a name="QOCI8"></a>
|
||
|
|
<h3> QOCI8 - Oracle Call Interface (OCI)
|
||
|
|
</h3>
|
||
|
|
<a name="3-2"></a><p> <!-- index QOCI8 --><a name="QOCI8"></a>
|
||
|
|
<p> <h4> General information
|
||
|
|
</h4>
|
||
|
|
<a name="3-2-1"></a><p> The Qt OCI plugin supports both Oracle 8 and Oracle 9. After
|
||
|
|
connecting to the Oracle server, the plugin will auto-detect the
|
||
|
|
database version and enable features accordingly.
|
||
|
|
<p> <h4> Unicode support
|
||
|
|
</h4>
|
||
|
|
<a name="3-2-2"></a><p> If the Oracle server supports Unicode, the OCI plugin will use UTF-8
|
||
|
|
encoding to communicate with the server.
|
||
|
|
<p> <h4> BLOB/LOB support
|
||
|
|
</h4>
|
||
|
|
<a name="3-2-3"></a><p> Binary Large Objects (BLOBs) can be read and written, but be aware
|
||
|
|
that this process may require a lot of memory.
|
||
|
|
<p> Note that Oracle 9 doesn't support scrollable result sets with LOB
|
||
|
|
columns, you have to use a forward only query to select LOB fields
|
||
|
|
(see <a href="qsqlquery.html#setForwardOnly">QSqlQuery::setForwardOnly</a>()).
|
||
|
|
<p> Inserting BLOBs should be done using either a prepared query where the
|
||
|
|
BLOBs are bound to placeholders, or <a href="qsqlcursor.html">QSqlCursor</a> which uses a prepared
|
||
|
|
query to do this internally (see $QTDIR/examples/sql/blob).
|
||
|
|
<p> <h4> Know problems
|
||
|
|
</h4>
|
||
|
|
<a name="3-2-4"></a><p> When a query is in forward only mode a call to <a href="qsqlquery.html#last">QSqlQuery::last</a>() will
|
||
|
|
position the query on the last record and return TRUE, but subsequent
|
||
|
|
calls to <a href="qsqlquery.html#value">QSqlQuery::value</a>() will only return NULLs.
|
||
|
|
<p> <h4> How to build the plugin on Unix/Linux
|
||
|
|
</h4>
|
||
|
|
<a name="3-2-5"></a><p> All files required to build driver should ship with the standard Oracle
|
||
|
|
Client install.
|
||
|
|
<p> Oracle library files required to build driver:
|
||
|
|
<p> <ul>
|
||
|
|
<li> <tt>libclntsh.so</tt> (all versions)
|
||
|
|
<li> <tt>libwtc8.so</tt> (only Oracle 8) or <tt>libwtc9.so</tt> (only Oracle 9)
|
||
|
|
</ul>
|
||
|
|
<p> Tell <tt>qmake</tt> where to find the Oracle header files and shared
|
||
|
|
libraries (it is assumed that the variable <tt>$ORACLE_HOME</tt> points to
|
||
|
|
the directory where Oracle is installed) and run make:
|
||
|
|
<p> If you are using Oracle 8:
|
||
|
|
<pre>
|
||
|
|
cd $QTDIR/plugins/src/sqldrivers/oci
|
||
|
|
qmake -o Makefile "INCLUDEPATH+=$ORACLE_HOME/rdbms/public $ORACLE_HOME/rdbms/demo" "LIBS+=-L$ORACLE_HOME/lib -lclntsh -lwtc8" oci.pro
|
||
|
|
make
|
||
|
|
</pre>
|
||
|
|
|
||
|
|
<p> For Oracle version 9:
|
||
|
|
<pre>
|
||
|
|
cd $QTDIR/plugins/src/sqldrivers/oci
|
||
|
|
qmake -o Makefile "INCLUDEPATH+=$ORACLE_HOME/rdbms/public $ORACLE_HOME/rdbms/demo" "LIBS+=-L$ORACLE_HOME/lib -lclntsh -lwtc9" oci.pro
|
||
|
|
make
|
||
|
|
</pre>
|
||
|
|
|
||
|
|
<p> For Oracle version 10:
|
||
|
|
<pre>
|
||
|
|
cd $QTDIR/plugins/src/sqldrivers/oci
|
||
|
|
qmake -o Makefile "INCLUDEPATH+=$ORACLE_HOME/rdbms/public $ORACLE_HOME/rdbms/demo" "LIBS+=-L$ORACLE_HOME/lib -lclntsh" oci.pro
|
||
|
|
make
|
||
|
|
</pre>
|
||
|
|
|
||
|
|
<p> Note that some versions of the OCI client libraries contain a bug
|
||
|
|
that makes programs linked to these libraries segfault on exit. This
|
||
|
|
only happens if the QOCI8 driver is compiled as a plugin. To work
|
||
|
|
around this problem, either compile the driver into the Qt libray
|
||
|
|
itself, or configure Qt with the option '-DQT_NO_LIBRARY_UNLOAD'.
|
||
|
|
For Oracle 9, it is possible to link to the static OCI library by
|
||
|
|
using "LIBS+=$ORACLE_HOME/lib/libclntst9.a".
|
||
|
|
<p> <h4> How to build the plugin on Windows
|
||
|
|
</h4>
|
||
|
|
<a name="3-2-6"></a><p> Choosing the option "Programmer" in the Oracle Client Installer from
|
||
|
|
the Oracle Client Installation CD is sufficient to build the plugin.
|
||
|
|
<p> Build the plugin as follows (here it is assumed that Oracle Client is
|
||
|
|
installed in <tt>C:\oracle</tt>):
|
||
|
|
<p> <pre>
|
||
|
|
set INCLUDE=%INCLUDE%;c:\oracle\oci\include
|
||
|
|
set LIB=%LIB%;c:\oracle\oci\lib\msvc
|
||
|
|
cd %QTDIR%\plugins\src\sqldrivers\oci
|
||
|
|
qmake -o Makefile oci.pro
|
||
|
|
nmake
|
||
|
|
</pre>
|
||
|
|
|
||
|
|
<p> When you run your application you will also need to add the <tt>oci.dll</tt>
|
||
|
|
path to your <tt>PATH</tt> environment variable:
|
||
|
|
<p> <pre>
|
||
|
|
set PATH=%PATH%;c:\oracle\bin
|
||
|
|
</pre>
|
||
|
|
|
||
|
|
<p> If you are not using a Microsoft compiler, replace <tt>nmake</tt> with <tt>make</tt> in the statement above.
|
||
|
|
<p> <a name="QODBC3"></a>
|
||
|
|
<h3> QODBC3 - Open Database Connectivity (ODBC)
|
||
|
|
</h3>
|
||
|
|
<a name="3-3"></a><p> <!-- index QODBC3 --><a name="QODBC3"></a>
|
||
|
|
<p> <h4> General information
|
||
|
|
</h4>
|
||
|
|
<a name="3-3-1"></a><p> ODBC is a general interface that allows you to connect to multiple
|
||
|
|
DBMS using a common interface. The QODBC3 driver allows you to connect
|
||
|
|
to an ODBC driver manager and access the available data sources. Note
|
||
|
|
that you also need to install and configure ODBC drivers for the ODBC
|
||
|
|
driver manager that is installed on your system. The QODBC3 plugin
|
||
|
|
then allows you to use these data sources in your Qt project.
|
||
|
|
<p> On Windows systems after 95 an ODBC driver manager should be installed
|
||
|
|
by default, for Unix systems there are some implementations which must
|
||
|
|
be installed first. Note that every client that uses your application
|
||
|
|
is required to have an ODBC driver manager installed, otherwise the
|
||
|
|
QODBC3 plugin will not work.
|
||
|
|
<p> Be aware that when connecting to an ODBC datasource you must pass in
|
||
|
|
the name of the ODBC datasource to the <a href="qsqldatabase.html#setDatabaseName">QSqlDatabase::setDatabaseName</a>()
|
||
|
|
function: not the actual database name.
|
||
|
|
<p> The QODBC3 Plugin needs an ODBC compliant driver manager version 2.0 or
|
||
|
|
later to work. Some ODBC drivers claim to be version 2.0 compliant,
|
||
|
|
but do not offer all the necessary functionality. The QODBC3 plugin
|
||
|
|
therefore checks whether the data source can be used after a
|
||
|
|
connection has been established and refuses to work if the check
|
||
|
|
fails. If you don't like this behaviour, you can remove the <tt>#define ODBC_CHECK_DRIVER</tt> line from the file <tt>qsql_odbc.cpp</tt>. Do this at
|
||
|
|
your own risk!
|
||
|
|
<p> If you experience very slow access of the ODBC datasource, make sure
|
||
|
|
that ODBC call tracing is turned off in the ODBC datasource manager.
|
||
|
|
<p> <h4> Unicode support
|
||
|
|
</h4>
|
||
|
|
<a name="3-3-2"></a><p> The QODBC3 Plugin will use the Unicode API if UNICODE is defined. On
|
||
|
|
Windows NT based systems, this is the default. Note that the ODBC
|
||
|
|
driver and the DBMS have to support Unicode as well.
|
||
|
|
<p> For the Oracle 9 ODBC driver (Windows), it is neccessary to check
|
||
|
|
"SQL_WCHAR support" in the ODBC driver manager otherwise Oracle
|
||
|
|
will convert all Unicode strings to local 8 bit.
|
||
|
|
<p> <h4> How to build the plugin on Unix/Linux
|
||
|
|
</h4>
|
||
|
|
<a name="3-3-3"></a><p> It is recommended that you use unixODBC. You can find the latest
|
||
|
|
version and ODBC drivers at <a href="http://www.unixodbc.org">http://www.unixodbc.org</a>.
|
||
|
|
You need the unixODBC header files and shared libraries.
|
||
|
|
<p> Tell <tt>qmake</tt> where to find the unixODBC header files and shared
|
||
|
|
libraries (here it is assumed that unixODBC is installed in
|
||
|
|
<tt>/usr/local/unixODBC</tt>) and run <tt>make</tt>:
|
||
|
|
<p> <pre>
|
||
|
|
cd $QTDIR/plugins/src/sqldrivers/odbc
|
||
|
|
qmake "INCLUDEPATH+=/usr/local/unixODBC/include" "LIBS+=-L/usr/local/unixODBC/lib -lodbc"
|
||
|
|
make
|
||
|
|
</pre>
|
||
|
|
|
||
|
|
<p> <h4> How to build the plugin on Windows
|
||
|
|
</h4>
|
||
|
|
<a name="3-3-4"></a><p> The ODBC header and include files should already be installed in the
|
||
|
|
right directories. You just have to build the plugin as follows:
|
||
|
|
<p> <pre>
|
||
|
|
cd %QTDIR%\plugins\src\sqldrivers\odbc
|
||
|
|
qmake -o Makefile odbc.pro
|
||
|
|
nmake
|
||
|
|
</pre>
|
||
|
|
|
||
|
|
<p> If you are not using a Microsoft compiler, replace <tt>nmake</tt> with <tt>make</tt> in the statement above.
|
||
|
|
<p> <a name="QPSQL7"></a>
|
||
|
|
<h3> QPSQL7 - PostgreSQL version 6 and 7
|
||
|
|
</h3>
|
||
|
|
<a name="3-4"></a><p> <!-- index QPSQL7 --><a name="QPSQL7"></a>
|
||
|
|
<p> <h4> General information
|
||
|
|
</h4>
|
||
|
|
<a name="3-4-1"></a><p> The QPSQL7 driver supports both version 6 and 7 of PostgreSQL. We
|
||
|
|
recommend compiling the plugin with a recent version of the PostgreSQL
|
||
|
|
client library (libpq) because it is more stable and still backwards
|
||
|
|
compatible.
|
||
|
|
<p> If you want to link the plugin against the libpq shipped with version
|
||
|
|
6 we recommend a recent version like PostgreSQL 6.5.3, otherwise a
|
||
|
|
connection to a version 7 server may not work.
|
||
|
|
<p> The driver auto-detects the server version of PostgreSQL after a
|
||
|
|
connection was successful. If the server is too old or the version
|
||
|
|
information cannot be determined a warning is issued.
|
||
|
|
<p> For more information about PostgreSQL visit <a href="http://www.postgresql.org">http://www.postgresql.org</a>.
|
||
|
|
<p> <h4> Unicode support
|
||
|
|
</h4>
|
||
|
|
<a name="3-4-2"></a><p> The QPSQL7 driver automatically detects whether the PostgreSQL
|
||
|
|
database you are connecting to supports Unicode or not. Unicode is
|
||
|
|
automatically used if the server supports it. Note that the driver
|
||
|
|
only supports the UTF-8 encoding. If your database uses any other
|
||
|
|
encoding, the server must be compiled with Unicode conversion
|
||
|
|
support.
|
||
|
|
<p> Unicode support was introduced in PostgreSQL version 7.1 and it will
|
||
|
|
only work if both the server and the client library have been compiled
|
||
|
|
with multibyte support. More information about how to set up a
|
||
|
|
multibyte enabled PostgreSQL server can be found in the PostgreSQL
|
||
|
|
Administrator Guide, Chapter 5.
|
||
|
|
<p> <h4> BLOB support
|
||
|
|
</h4>
|
||
|
|
<a name="3-4-3"></a><p> Binary Large Objects are supported through the <tt>BYTEA</tt> field type in
|
||
|
|
PostgreSQL versions >= 7.1. Fields of type <tt>OID</tt> can be read, but not
|
||
|
|
written. Use the PostgreSQL command <tt>lo_import</tt> to insert binary data
|
||
|
|
into <tt>OID</tt> fields.
|
||
|
|
<p> <h4> How to build the plugin on Unix/Linux
|
||
|
|
</h4>
|
||
|
|
<a name="3-4-4"></a><p> Just installing the pq client library and the corresponding header
|
||
|
|
files is not sufficient. You have to get the PostgreSQL source
|
||
|
|
distribution and run the configure script. If you've already installed
|
||
|
|
a binary distribution you don't need to build it. The source
|
||
|
|
distribution is needed because the QPSQL7 plugin relies on a couple of
|
||
|
|
header files that are usually not a part of the binary distribution.
|
||
|
|
<p> To make <tt>qmake</tt> find the PostgreSQL header files and shared
|
||
|
|
libraries, run <tt>qmake</tt> the following way (assuming that the
|
||
|
|
PostgreSQL sources can be found in <tt>/usr/src/psql</tt>):
|
||
|
|
<p> <pre>
|
||
|
|
cd $QTDIR/plugins/src/sqldrivers/psql
|
||
|
|
qmake -o Makefile "INCLUDEPATH+=/usr/src/psql/src/include /usr/src/psql/src/interfaces/libpq" "LIBS+=-L/usr/lib -lpq" psql.pro
|
||
|
|
make
|
||
|
|
</pre>
|
||
|
|
|
||
|
|
<p> <h4> How to build the plugin on Windows
|
||
|
|
</h4>
|
||
|
|
<a name="3-4-5"></a><p> Unpack and build the PostgreSQL source distribution as described in
|
||
|
|
the PostgreSQL documentation. Assuming the PostgreSQL sources resides
|
||
|
|
in <tt>C:\psql</tt>, build the plugin as follows:
|
||
|
|
<p> <pre>
|
||
|
|
cd %QTDIR%\plugins\src\sqldrivers\psql
|
||
|
|
qmake -o Makefile "INCLUDEPATH+=C:\psql\src\include C:\psql\src\interfaces\libpq" psql.pro
|
||
|
|
nmake
|
||
|
|
</pre>
|
||
|
|
|
||
|
|
<p> Remember to add the path to the <tt>libpq.dll</tt> library to your PATH
|
||
|
|
environment variable so that Windows can find it. In this case that
|
||
|
|
would be <tt>C:\psql\src\interfaces\libpq\Release</tt>. If you are not using a
|
||
|
|
Microsoft compiler, replace <tt>nmake</tt> with <tt>make</tt> in the statement
|
||
|
|
above.
|
||
|
|
<p> <a name="QTDS7"></a>
|
||
|
|
<h3> QTDS7 - Sybase Adaptive Server
|
||
|
|
</h3>
|
||
|
|
<a name="3-5"></a><p> <!-- index QTDS7 --><a name="QTDS7"></a>
|
||
|
|
<p> <h4> How to build the plugin on Unix/Linux
|
||
|
|
</h4>
|
||
|
|
<a name="3-5-1"></a><p> Under Unix, two libraries are available which support the TDS protocol:
|
||
|
|
<p> - FreeTDS, a free implementation of the TDS protocol
|
||
|
|
(<a href="http://www.freetds.org">http://www.freetds.org</a>). Note that FreeTDS is not yet stable,
|
||
|
|
so some functionality may not work as expected.
|
||
|
|
<p> - Sybase Open Client, available from <a href="http://www.sybase.com">http://www.sybase.com</a>.
|
||
|
|
Note for Linux users: Get the Open Client RPM from
|
||
|
|
<a href="http://linux.sybase.com">http://linux.sybase.com</a>.
|
||
|
|
<p> Regardless of which library you use, the shared object file
|
||
|
|
<tt>libsybdb.so</tt> is needed. Set the SYBASE environment variable to
|
||
|
|
point to the directory where you installed the client library and
|
||
|
|
execute <tt>qmake</tt>:
|
||
|
|
<p> <pre>
|
||
|
|
cd $QTDIR/plugins/src/sqldrivers/tds
|
||
|
|
qmake -o Makefile "INCLUDEPATH=$SYBASE/include" "LIBS=-L$SYBASE/lib -lsybdb"
|
||
|
|
make
|
||
|
|
</pre>
|
||
|
|
|
||
|
|
<p> <h4> How to build the plugin on Windows
|
||
|
|
</h4>
|
||
|
|
<a name="3-5-2"></a><p> You can either use the DB-Library supplied by Microsoft or the Sybase
|
||
|
|
Open Client (<a href="http://www.sybase.com">http://www.sybase.com</a>). You must include <tt>NTWDBLIB.LIB</tt> to build the plugin:
|
||
|
|
<p> <pre>
|
||
|
|
cd %QTDIR%\plugins\src\sqldrivers\tds
|
||
|
|
qmake -o Makefile "LIBS+=NTWDBLIB.LIB" tds.pro
|
||
|
|
nmake
|
||
|
|
</pre>
|
||
|
|
|
||
|
|
<p> By default the Microsoft library is used on Windows, if you want to force
|
||
|
|
the use of the Sybase Open Client, you must define
|
||
|
|
<tt>Q_USE_SYBASE</tt> in <tt>%QTDIR%\src\sql\drivers\tds\qsql_tds.cpp</tt>.
|
||
|
|
<p> <a name="QDB2"></a>
|
||
|
|
<h3> QDB2 - IBM DB2 Driver (v7.1 or higher)
|
||
|
|
</h3>
|
||
|
|
<a name="3-6"></a><p> <!-- index QDB2 --><a name="QDB2"></a>
|
||
|
|
<p> <h4> General information
|
||
|
|
</h4>
|
||
|
|
<a name="3-6-1"></a><p> The Qt DB2 plugin makes it possible to access IBM DB2 databases. It
|
||
|
|
has been tested with IBM DB2 v7.1 and 7.2. You have to install the IBM
|
||
|
|
DB2 development client library, which contains the header and library
|
||
|
|
files necessary for compiling the QDB2 plugin.
|
||
|
|
<p> The QDB2 driver supports prepared queries, reading/writing of Unicode
|
||
|
|
strings and reading/writing of BLOBs.
|
||
|
|
<p> We suggest using a forward-only query when calling stored procedures
|
||
|
|
in DB2 (see <a href="qsqlquery.html#setForwardOnly">QSqlQuery::setForwardOnly</a>()).
|
||
|
|
<p> <h4> How to build the plugin on Unix/Linux
|
||
|
|
</h4>
|
||
|
|
<a name="3-6-2"></a><p> <pre>
|
||
|
|
cd $QTDIR/plugins/src/sqldrivers/db2
|
||
|
|
qmake -o Makefile "INCLUDEPATH+=$DB2DIR/include" "LIBS+=-L$DB2DIR/lib -ldb2"
|
||
|
|
make
|
||
|
|
</pre>
|
||
|
|
|
||
|
|
<p> <h4> How to build the plugin on Windows
|
||
|
|
</h4>
|
||
|
|
<a name="3-6-3"></a><p> The DB2 header and include files should already be installed in the
|
||
|
|
right directories. You just have to build the plugin as follows:
|
||
|
|
<p> <pre>
|
||
|
|
cd %QTDIR%\plugins\src\sqldrivers\db2
|
||
|
|
qmake -o Makefile "INCLUDEPATH+=<DB2 home>/sqllib/include" "LIBS+=<DB2 home>/sqllib/lib/db2cli.lib"
|
||
|
|
nmake
|
||
|
|
</pre>
|
||
|
|
|
||
|
|
<p> If you are not using a Microsoft compiler, replace <tt>nmake</tt>
|
||
|
|
with <tt>make</tt> in the statement above.
|
||
|
|
<p> <a name="QSQLITE"></a>
|
||
|
|
<h3> QSQLITE - SQLite Driver
|
||
|
|
</h3>
|
||
|
|
<a name="3-7"></a><p> <!-- index QSQLITE --><a name="QSQLITE"></a>
|
||
|
|
<p> The Qt SQLite plugin makes it possible to access SQLite databases.
|
||
|
|
SQLite is an in-process database, meaning that it is not necessary
|
||
|
|
to have a database server. SQLite operates on a single file, which has
|
||
|
|
to be set as database name when opening a connection. If the file does
|
||
|
|
not exist, SQLite will try to create it. SQLite also supports in-memory
|
||
|
|
databases, simply pass ":memory:" as the database name.
|
||
|
|
<p> SQLite has some restrictions regarding multiple users and
|
||
|
|
multiple transactions. If you try to read/write on a resource from different
|
||
|
|
transactions, your application might freeze until one transaction commits
|
||
|
|
or rolls back.
|
||
|
|
<p> SQLite has no support for types, every value is treated as character data.
|
||
|
|
BLOBs are therefore not supported.
|
||
|
|
<p> You can find information about SQLite on <a href="http://www.sqlite.org">http://www.sqlite.org</a>.
|
||
|
|
<p> SQLite is shipped as third party library within Qt. It can be built by
|
||
|
|
passing the following parameters to the configure script:
|
||
|
|
<tt>-plugin-sql-sqlite</tt> (as plugin) or <tt>-qt-sql-sqlite</tt> (linked
|
||
|
|
directly into the Qt library).
|
||
|
|
<p> If you don't want to use the SQLite library shipped with Qt, you can
|
||
|
|
build it manually (replace <tt>$SQLITE</tt> by the directory where SQLite
|
||
|
|
resides):
|
||
|
|
<p> <pre>
|
||
|
|
cd $QTDIR/plugins/src/sqldrivers/sqlite
|
||
|
|
qmake -o Makefile "INCLUDEPATH+=$SQLITE/include" "LIBS+=-L$SQLITE/lib -lsqlite"
|
||
|
|
make
|
||
|
|
</pre>
|
||
|
|
|
||
|
|
<p> <a name="QIBASE"></a>
|
||
|
|
<h3> QIBASE - Borland Interbase Driver
|
||
|
|
</h3>
|
||
|
|
<a name="3-8"></a><p> <!-- index QIBASE --><a name="QIBASE"></a>
|
||
|
|
<p> <h4> General information
|
||
|
|
</h4>
|
||
|
|
<a name="3-8-1"></a><p> The Qt Interbase plugin makes it possible to access the Interbase and
|
||
|
|
Firebird databases. Interbase can either be used as a client/server or
|
||
|
|
without a server operating on local files. The database file must
|
||
|
|
exist before a connection can be established.
|
||
|
|
<p> Note that Interbase requires you to specify the full path to the
|
||
|
|
database file, no matter whether it is stored locally or on another
|
||
|
|
server.
|
||
|
|
<p> <pre>
|
||
|
|
myDatabase->setHostName("MyServer");
|
||
|
|
myDatabase->setDatabaseName("C:\\test.gdb");
|
||
|
|
</pre>
|
||
|
|
|
||
|
|
<p> You need the Interbase/Firebird development headers and libraries
|
||
|
|
to build this plugin.
|
||
|
|
<p> Due to the GPL, users of the Qt Open Source Edition are not allowed to link
|
||
|
|
this plugin to the commercial editions of Interbase. Please use Firebird
|
||
|
|
or the free edition of Interbase.
|
||
|
|
<p> <h4> How to build the plugin on Unix/Linux
|
||
|
|
</h4>
|
||
|
|
<a name="3-8-2"></a><p> The following assumes Interbase or Firebird is installed in
|
||
|
|
<tt>/opt/interbase</tt>:
|
||
|
|
<p> <pre>
|
||
|
|
cd $QTDIR/plugins/src/sqldrivers/ibase
|
||
|
|
qmake -o Makefile "INCLUDEPATH+=/opt/interbase/include" "LIBS+=-L/opt/interbase/lib" ibase.pro
|
||
|
|
make
|
||
|
|
</pre>
|
||
|
|
|
||
|
|
<p> <h4> How to build the plugin on Windows
|
||
|
|
</h4>
|
||
|
|
<a name="3-8-3"></a><p> The following assumes Interbase or Firebird is installed in
|
||
|
|
<tt>C:\interbase</tt>:
|
||
|
|
<p> <pre>
|
||
|
|
cd %QTDIR%\plugins\src\sqldrivers\ibase
|
||
|
|
qmake -o Makefile "INCLUDEPATH+=C:\interbase\include" ibase.pro
|
||
|
|
nmake
|
||
|
|
</pre>
|
||
|
|
|
||
|
|
<p> If you are not using a Microsoft compiler, replace <tt>nmake</tt>
|
||
|
|
with <tt>make</tt> in the statement above.
|
||
|
|
<p> Note that <tt>C:\interbase\bin</tt> must be in the PATH.
|
||
|
|
<p> <a name="troubleshooting"></a>
|
||
|
|
<h2> Troubleshooting
|
||
|
|
</h2>
|
||
|
|
<a name="4"></a><p> You should always use client libraries that have been compiled with
|
||
|
|
the same compiler as you are using for your project. If you cannot get
|
||
|
|
a source distibution to compile the client libraries yourself, you
|
||
|
|
must make sure that the pre-compiled library is compatible with
|
||
|
|
your compiler, otherwise you will get a lot of "undefined symbols"
|
||
|
|
errors. Some compilers have tools to convert libraries, e.g. Borland
|
||
|
|
ships the tool <tt>COFF2OMF.EXE</tt> to convert libraries that have been
|
||
|
|
generated with Microsoft Visual C++.
|
||
|
|
<p> If the compilation of a plugin succeeds but it cannot be loaded,
|
||
|
|
make sure that the following requirements are met:
|
||
|
|
<p> <ul>
|
||
|
|
<li> Ensure that you are using a shared Qt library; you cannot use the
|
||
|
|
plugins with a static build.
|
||
|
|
<li> Ensure that the environment variable <tt>QTDIR</tt> points to the right
|
||
|
|
directory. Go to the <tt>$QTDIR/plugins/sqldrivers</tt> directory and
|
||
|
|
make sure that the plugin exists in that directory.
|
||
|
|
<li> Ensure that the client libraries of the DBMS are available on the
|
||
|
|
system. On Unix, run the command <tt>ldd</tt> and pass the name of the
|
||
|
|
plugin as parameter, for example <tt>ldd libqsqlmysql.so</tt>. You will
|
||
|
|
get a warning if any of the client libraries couldn't be found.
|
||
|
|
On Windows, you can use the dependency walker of Visual Studio.
|
||
|
|
</ul>
|
||
|
|
<p> If you are experiencing problems with loading plugins, and see output
|
||
|
|
like this
|
||
|
|
<p> <pre>
|
||
|
|
QSqlDatabase warning: QMYSQL3 driver not loaded
|
||
|
|
QSqlDatabase: available drivers: QMYSQL3
|
||
|
|
</pre>
|
||
|
|
|
||
|
|
<p> the problem is probably that the plugin had the wrong build key. For
|
||
|
|
debugging purposes, remove the corresponding entry in the
|
||
|
|
$HOME/.qt/qt_plugins_(qtversion).rc file.
|
||
|
|
<p> The next time you try to load this plugin, it will give you a more detailed
|
||
|
|
error message.
|
||
|
|
<p> <a name="development"></a>
|
||
|
|
<h2> How to write your own database driver
|
||
|
|
</h2>
|
||
|
|
<a name="5"></a><p> <a href="qsqldatabase.html">QSqlDatabase</a> is responsible for loading and managing database driver
|
||
|
|
plugins. When a database is added (see <a href="qsqldatabase.html#addDatabase">QSqlDatabase::addDatabase</a>()),
|
||
|
|
the appropriate driver plugin is loaded (using <a href="qsqldriverplugin.html">QSqlDriverPlugin</a>).
|
||
|
|
QSqlDatabase relies on the driver plugin to provide interfaces for
|
||
|
|
<a href="qsqldriver.html">QSqlDriver</a> and <a href="qsqlresult.html">QSqlResult</a>.
|
||
|
|
<p> QSqlDriver is an abstract base class which defines the functionality
|
||
|
|
of a SQL database driver. This includes functions such as
|
||
|
|
<a href="qsqldriver.html#open">QSqlDriver::open</a>() and <a href="qsqldriver.html#close">QSqlDriver::close</a>(). QSqlDriver is responsible
|
||
|
|
for connecting to a database, establish the proper environment, etc.
|
||
|
|
In addition, QSqlDriver can create <a href="qsqlquery.html">QSqlQuery</a> objects appropriate for
|
||
|
|
the particular database API. QSqlDatabase forwards many of its
|
||
|
|
function calls directly to QSqlDriver which provides the concrete
|
||
|
|
implementation.
|
||
|
|
<p> QSqlResult is an abstract base class which defines the functionality
|
||
|
|
of a SQL database query. This includes statements such as <tt>SELECT</tt>,
|
||
|
|
<tt>UPDATE</tt>, and <tt>ALTER TABLE</tt>. QSqlResult contains functions such as
|
||
|
|
QSqlResult::next() and QSqlResult::value(). QSqlResult is responsible
|
||
|
|
for sending queries to the database, returning result data, etc.
|
||
|
|
QSqlQuery forwards many of its function calls directly to <a href="qsqlresult.html">QSqlResult</a>
|
||
|
|
which provides the concrete implementation.
|
||
|
|
<p> <a href="qsqldriver.html">QSqlDriver</a> and QSqlResult are closely connected. When implementing a
|
||
|
|
Qt SQL driver, both of these classes must to be subclassed and the
|
||
|
|
abstract virtual methods in each class must be implemented.
|
||
|
|
<p> To implement a Qt SQL driver as a plugin (so that it is recognized and
|
||
|
|
loaded by the Qt library at runtime), the driver must use the
|
||
|
|
<tt>Q_EXPORT_PLUGIN</tt> macro. Read the <a href="plugins-howto.html">Qt
|
||
|
|
Plugin</a> documentation for more information on this. You can
|
||
|
|
also check out how this is done in the SQL plugins that is provided
|
||
|
|
with Qt in <tt>QTDIR/plugins/src/sqldrivers</tt> and
|
||
|
|
<tt>QTDIR/src/sql/drivers</tt>.
|
||
|
|
<p> The following code can be used as a skeleton for a SQL driver:
|
||
|
|
<p> <pre>
|
||
|
|
class QNullResult : public <a href="qsqlresult.html">QSqlResult</a>
|
||
|
|
{
|
||
|
|
public:
|
||
|
|
QNullResult( const <a href="qsqldriver.html">QSqlDriver</a>* d ): <a href="qsqlresult.html">QSqlResult</a>( d ) {}
|
||
|
|
~QNullResult() {}
|
||
|
|
protected:
|
||
|
|
<a href="qvariant.html">QVariant</a> data( int ) { return QVariant(); }
|
||
|
|
bool reset ( const <a href="qstring.html">QString</a>& ) { return FALSE; }
|
||
|
|
bool fetch( int ) { return FALSE; }
|
||
|
|
bool fetchFirst() { return FALSE; }
|
||
|
|
bool fetchLast() { return FALSE; }
|
||
|
|
bool isNull( int ) { return FALSE; }
|
||
|
|
<a href="qsqlrecord.html">QSqlRecord</a> record() { return QSqlRecord(); }
|
||
|
|
int size() { return 0; }
|
||
|
|
int numRowsAffected() { return 0; }
|
||
|
|
};
|
||
|
|
|
||
|
|
class QNullDriver : public <a href="qsqldriver.html">QSqlDriver</a>
|
||
|
|
{
|
||
|
|
public:
|
||
|
|
QNullDriver(): <a href="qsqldriver.html">QSqlDriver</a>() {}
|
||
|
|
~QNullDriver() {}
|
||
|
|
bool hasFeature( DriverFeature ) const { return FALSE; }
|
||
|
|
bool open( const <a href="qstring.html">QString</a>&,
|
||
|
|
const <a href="qstring.html">QString</a>&,
|
||
|
|
const <a href="qstring.html">QString</a>&,
|
||
|
|
const <a href="qstring.html">QString</a>&,
|
||
|
|
int ) { return FALSE; }
|
||
|
|
void close() {}
|
||
|
|
<a href="qsqlquery.html">QSqlQuery</a> createQuery() const { return QSqlQuery( new QNullResult( this ) ); }
|
||
|
|
};
|
||
|
|
</pre>
|
||
|
|
|
||
|
|
<p>
|
||
|
|
<!-- eof -->
|
||
|
|
<p><address><hr><div align=center>
|
||
|
|
<table width=100% cellspacing=0 border=0><tr>
|
||
|
|
<td>Copyright © 2007
|
||
|
|
<a href="troll.html">Trolltech</a><td align=center><a href="trademarks.html">Trademarks</a>
|
||
|
|
<td align=right><div align=right>Qt 3.3.8</div>
|
||
|
|
</table></div></address></body>
|
||
|
|
</html>
|