diff options
Diffstat (limited to 'doc/sql-driver.doc')
| -rw-r--r-- | doc/sql-driver.doc | 739 |
1 files changed, 739 insertions, 0 deletions
diff --git a/doc/sql-driver.doc b/doc/sql-driver.doc new file mode 100644 index 0000000..0c96125 --- /dev/null +++ b/doc/sql-driver.doc @@ -0,0 +1,739 @@ +/**************************************************************************** +** +** Documentation for sql driver programming +** +** Copyright (C) 1992-2008 Trolltech ASA. All rights reserved. +** +** This file is part of the Qt GUI Toolkit. +** +** This file may be used under the terms of the GNU General +** Public License versions 2.0 or 3.0 as published by the Free +** Software Foundation and appearing in the files LICENSE.GPL2 +** and LICENSE.GPL3 included in the packaging of this file. +** Alternatively you may (at your option) use any later version +** of the GNU General Public License if such license has been +** publicly approved by Trolltech ASA (or its successors, if any) +** and the KDE Free Qt Foundation. +** +** Please review the following information to ensure GNU General +** Public Licensing requirements will be met: +** http://trolltech.com/products/qt/licenses/licensing/opensource/. +** If you are unsure which license is appropriate for your use, please +** review the following information: +** http://trolltech.com/products/qt/licenses/licensing/licensingoverview +** or contact the sales department at sales@trolltech.com. +** +** This file may be used under the terms of the Q Public License as +** defined by Trolltech ASA and appearing in the file LICENSE.QPL +** included in the packaging of this file. Licensees holding valid Qt +** Commercial licenses may use this file in accordance with the Qt +** Commercial License Agreement provided with the Software. +** +** This file is provided "AS IS" with NO WARRANTY OF ANY KIND, +** INCLUDING THE WARRANTIES OF DESIGN, MERCHANTABILITY AND FITNESS FOR +** A PARTICULAR PURPOSE. Trolltech reserves all rights not granted +** herein. +** +**********************************************************************/ + +/*! \page sql-driver.html + +\title SQL Module - Drivers + +\list +\i \link #Introduction Introduction\endlink +\i \link #building Building the drivers using configure\endlink +\i \link #buildingmanually Building the plugins manually\endlink + \list + \i \link #QDB2 QDB2\endlink - IBM DB2 Driver (v7.1 and higher) + \i \link #QIBASE QIBASE\endlink - Borland Interbase Driver + \i \link #QMYSQL3 QMYSQL3\endlink - MySQL Driver + \i \link #QOCI8 QOCI8\endlink - Oracle Call Interface Driver, version 8, 9 and 10 + \i \link #QODBC3 QODBC3\endlink - Open Database Connectivity Driver + \i \link #QPSQL7 QPSQL7\endlink - PostgreSQL v6.x and v7.x Driver + \i \link #QSQLITE QSQLITE\endlink - SQLite Driver + \i \link #QTDS7 QTDS7\endlink - Sybase Adaptive Server + \endlist +\i \link #troubleshooting Troubleshooting\endlink +\i \link #development How to write your own database driver\endlink +\endlist + +\target Introduction +\section1 Introduction + +The \link sql.html SQL Module\endlink uses driver \link +plugins-howto.html plugins\endlink 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 \link #development writing your own drivers\endlink. + +\e{Note:} 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. + +The drivers shipped with Qt are: +\list +\i \link #QDB2 QDB2\endlink - IBM DB2 Driver (v7.1 and higher) +\i \link #QIBASE QIBASE\endlink - Borland Interbase Driver +\i \link #QMYSQL3 QMYSQL3\endlink - MySQL Driver +\i \link #QOCI8 QOCI8\endlink - Oracle Call Interface Driver, version 8, 9 and 10 +\i \link #QODBC3 QODBC3\endlink - Open Database Connectivity Driver +\i \link #QPSQL7 QPSQL7\endlink - PostgreSQL v6.x and v7.x Driver +\i \link #QSQLITE QSQLITE\endlink - SQLite Driver +\i \link #QTDS7 QTDS7\endlink - Sybase Adaptive Server +\endlist + +Note that not all of the plugins are shipped with the Qt Open Source Edition +due to license incompatibilities with the GPL. + +\target building +\section1 Building the drivers using configure + +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: + +\code +Possible values for <driver>: [ mysql oci odbc psql tds ] +Auto-Detected on this system: [ mysql psql ] +\endcode + +Note that on Windows, the configure script doesn't do any +auto-detection. + +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 \c /usr/local/mysql (or in +\c{C:\mysql\include} on Windows), then pass the following parameter to +configure: \c -I/usr/local/mysql (or \c{-I C:\mysql\include} for +Windows). + +On Windows the -I parameter doesn't accept spaces in +filenames, so use the 8.3 name instead, i.e. use \c{C:\progra~1\mysql} +instead of \c{C:\program files\mysql}. + +Use the \c{-qt-sql-<driver>} parameter to build the database driver +statically into your Qt library or \c{-plugin-sql-<driver>} to build +the driver as a plugin. Look at the sections that follow for +additional information about required libraries. + +\target buildingmanually +\section1 Building the plugins manually + +\target QMYSQL3 +\section2 QMYSQL3 - MySQL 3.x and MySQL 4.x + +\keyword QMYSQL3 + +\section3 General information + +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. + +If you have a recent client library and connect to a +transaction-enabled MySQL server, a call to the +QSqlDriver::hasFeature( QSqlDriver::Transactions ) function returns +TRUE and SQL transactions can be used. + +If the plugin is compiled against MySQL 4.x client libraries, +transactions are enabled by default. + +You can find information about MySQL on \l http://www.mysql.com + +\section3 How to build the plugin on Unix/Linux + +You need the MySQL header files and as well as the shared library +\c{libmysqlclient.so}. Depending on your Linux distribution you need to +install a package which is usually called "mysql-devel". + +Tell \link qmake-manual.book qmake\endlink where to find the MySQL +header files and shared libraries (here it is assumed that MySQL is +installed in \c{/usr/local}) and run \c{make}: + +\code +cd $QTDIR/plugins/src/sqldrivers/mysql +qmake -o Makefile "INCLUDEPATH+=/usr/local/include" "LIBS+=-L/usr/local/lib -lmysqlclient" mysql.pro +make +\endcode + +\section3 How to build the plugin on Windows + +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 \c{C:\MYSQL}): + +\code +cd %QTDIR%\plugins\src\sqldrivers\mysql +qmake -o Makefile "INCLUDEPATH+=C:\MYSQL\INCLUDE" "LIBS+=C:\MYSQL\LIB\OPT\LIBMYSQL.LIB" mysql.pro +nmake +\endcode + +If you are not using a Microsoft compiler, replace \c nmake with \c +make in the statement above. + +\target QOCI8 +\section2 QOCI8 - Oracle Call Interface (OCI) + +\keyword QOCI8 + +\section3 General information + +The Qt OCI plugin supports Oracle 8, 9 and 10. After +connecting to the Oracle server, the plugin will auto-detect the +database version and enable features accordingly. + +\section3 Unicode support + +If the Oracle server supports Unicode, the OCI plugin will use UTF-8 +encoding to communicate with the server. + +\section3 BLOB/LOB support + +Binary Large Objects (BLOBs) can be read and written, but be aware +that this process may require a lot of memory. + +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 QSqlQuery::setForwardOnly()). + +Inserting BLOBs should be done using either a prepared query where the +BLOBs are bound to placeholders, or QSqlCursor which uses a prepared +query to do this internally (see $QTDIR/examples/sql/blob). + +\section3 Know problems + +When a query is in forward only mode a call to QSqlQuery::last() will +position the query on the last record and return TRUE, but subsequent +calls to QSqlQuery::value() will only return NULLs. + +\section3 How to build the plugin on Unix/Linux + +All files required to build driver should ship with the standard Oracle +Client install. + +Oracle library files required to build driver: + +\list +\i \c libclntsh.so (all versions) +\i \c libwtc8.so (only Oracle 8) or \c libwtc9.so (only Oracle 9) +\endlist + +Tell \c qmake where to find the Oracle header files and shared +libraries (it is assumed that the variable \c $ORACLE_HOME points to +the directory where Oracle is installed) and run make: + +If you are using Oracle 8: +\code +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 +\endcode + +For Oracle version 9: +\code +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 +\endcode + +For Oracle version 10: +\code +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 +\endcode + +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". + +\section3 How to build the plugin on Windows + +Choosing the option "Programmer" in the Oracle Client Installer from +the Oracle Client Installation CD is sufficient to build the plugin. + +Build the plugin as follows (here it is assumed that Oracle Client is +installed in \c{C:\oracle}): + +\code +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 +\endcode + +When you run your application you will also need to add the \c oci.dll +path to your \c PATH environment variable: + +\code +set PATH=%PATH%;c:\oracle\bin +\endcode + +If you are not using a Microsoft compiler, replace \c nmake with \c +make in the statement above. + +\target QODBC3 +\section2 QODBC3 - Open Database Connectivity (ODBC) + +\keyword QODBC3 + +\section3 General information + +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. + +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. + +Be aware that when connecting to an ODBC datasource you must pass in +the name of the ODBC datasource to the QSqlDatabase::setDatabaseName() +function: not the actual database name. + +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 \c{#define +ODBC_CHECK_DRIVER} line from the file \c{qsql_odbc.cpp}. Do this at +your own risk! + +If you experience very slow access of the ODBC datasource, make sure +that ODBC call tracing is turned off in the ODBC datasource manager. + +\section3 Unicode support + +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. + +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. + +\section3 How to build the plugin on Unix/Linux + +It is recommended that you use unixODBC. You can find the latest +version and ODBC drivers at \l http://www.unixodbc.org. +You need the unixODBC header files and shared libraries. + +Tell \c qmake where to find the unixODBC header files and shared +libraries (here it is assumed that unixODBC is installed in +\c{/usr/local/unixODBC}) and run \c{make}: + +\code +cd $QTDIR/plugins/src/sqldrivers/odbc +qmake "INCLUDEPATH+=/usr/local/unixODBC/include" "LIBS+=-L/usr/local/unixODBC/lib -lodbc" +make +\endcode + +\section3 How to build the plugin on Windows + +The ODBC header and include files should already be installed in the +right directories. You just have to build the plugin as follows: + +\code +cd %QTDIR%\plugins\src\sqldrivers\odbc +qmake -o Makefile odbc.pro +nmake +\endcode + +If you are not using a Microsoft compiler, replace \c nmake with \c +make in the statement above. + +\target QPSQL7 +\section2 QPSQL7 - PostgreSQL version 6 and 7 + +\keyword QPSQL7 + +\section3 General information + +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. + +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. + +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. + +For more information about PostgreSQL visit \l http://www.postgresql.org. + +\section3 Unicode support + +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. + +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. + +\section3 BLOB support + +Binary Large Objects are supported through the \c BYTEA field type in +PostgreSQL versions >= 7.1. Fields of type \c OID can be read, but not +written. Use the PostgreSQL command \c lo_import to insert binary data +into \c OID fields. + +\section3 How to build the plugin on Unix/Linux + +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. + +To make \c qmake find the PostgreSQL header files and shared +libraries, run \c qmake the following way (assuming that the +PostgreSQL sources can be found in \c{/usr/src/psql}): + +\code +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 +\endcode + +\section3 How to build the plugin on Windows + +Unpack and build the PostgreSQL source distribution as described in +the PostgreSQL documentation. Assuming the PostgreSQL sources resides +in \c{C:\psql}, build the plugin as follows: + +\code +cd %QTDIR%\plugins\src\sqldrivers\psql +qmake -o Makefile "INCLUDEPATH+=C:\psql\src\include C:\psql\src\interfaces\libpq" psql.pro +nmake +\endcode + +Remember to add the path to the \c{libpq.dll} library to your PATH +environment variable so that Windows can find it. In this case that +would be \c{C:\psql\src\interfaces\libpq\Release}. If you are not using a +Microsoft compiler, replace \c nmake with \c make in the statement +above. + +\target QTDS7 +\section2 QTDS7 - Sybase Adaptive Server + +\keyword QTDS7 + +\section3 How to build the plugin on Unix/Linux + +Under Unix, two libraries are available which support the TDS protocol: + +- FreeTDS, a free implementation of the TDS protocol + (\l{http://www.freetds.org}). Note that FreeTDS is not yet stable, + so some functionality may not work as expected. + +- Sybase Open Client, available from \l{http://www.sybase.com}. + Note for Linux users: Get the Open Client RPM from + \l{http://linux.sybase.com}. + +Regardless of which library you use, the shared object file +\c{libsybdb.so} is needed. Set the SYBASE environment variable to +point to the directory where you installed the client library and +execute \c{qmake}: + +\code +cd $QTDIR/plugins/src/sqldrivers/tds +qmake -o Makefile "INCLUDEPATH=$SYBASE/include" "LIBS=-L$SYBASE/lib -lsybdb" +make +\endcode + +\section3 How to build the plugin on Windows + +You can either use the DB-Library supplied by Microsoft or the Sybase +Open Client (\l{http://www.sybase.com}). You must include \c +NTWDBLIB.LIB to build the plugin: + +\code +cd %QTDIR%\plugins\src\sqldrivers\tds +qmake -o Makefile "LIBS+=NTWDBLIB.LIB" tds.pro +nmake +\endcode + +By default the Microsoft library is used on Windows, if you want to force +the use of the Sybase Open Client, you must define +\c Q_USE_SYBASE in \c{%QTDIR%\src\sql\drivers\tds\qsql_tds.cpp}. + +\target QDB2 +\section2 QDB2 - IBM DB2 Driver (v7.1 or higher) + +\keyword QDB2 + +\section3 General information + +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. + +The QDB2 driver supports prepared queries, reading/writing of Unicode +strings and reading/writing of BLOBs. + +We suggest using a forward-only query when calling stored procedures +in DB2 (see QSqlQuery::setForwardOnly()). + +\section3 How to build the plugin on Unix/Linux + +\code +cd $QTDIR/plugins/src/sqldrivers/db2 +qmake -o Makefile "INCLUDEPATH+=$DB2DIR/include" "LIBS+=-L$DB2DIR/lib -ldb2" +make +\endcode + +\section3 How to build the plugin on Windows + +The DB2 header and include files should already be installed in the +right directories. You just have to build the plugin as follows: + +\code +cd %QTDIR%\plugins\src\sqldrivers\db2 +qmake -o Makefile "INCLUDEPATH+=<DB2 home>/sqllib/include" "LIBS+=<DB2 home>/sqllib/lib/db2cli.lib" +nmake +\endcode + +If you are not using a Microsoft compiler, replace \c nmake +with \c make in the statement above. + +\target QSQLITE +\section2 QSQLITE - SQLite Driver + +\keyword QSQLITE + +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. + +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. + +SQLite has no support for types, every value is treated as character data. +BLOBs are therefore not supported. + +You can find information about SQLite on \l{http://www.sqlite.org}. + +SQLite is shipped as third party library within Qt. It can be built by +passing the following parameters to the configure script: +\c{-plugin-sql-sqlite} (as plugin) or \c{-qt-sql-sqlite} (linked +directly into the Qt library). + +If you don't want to use the SQLite library shipped with Qt, you can +build it manually (replace \c $SQLITE by the directory where SQLite +resides): + +\code +cd $QTDIR/plugins/src/sqldrivers/sqlite +qmake -o Makefile "INCLUDEPATH+=$SQLITE/include" "LIBS+=-L$SQLITE/lib -lsqlite" +make +\endcode + +\target QIBASE +\section2 QIBASE - Borland Interbase Driver + +\keyword QIBASE + +\section3 General information + +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. + +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. + +\code + myDatabase->setHostName("MyServer"); + myDatabase->setDatabaseName("C:\\test.gdb"); +\endcode + +You need the Interbase/Firebird development headers and libraries +to build this plugin. + +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. + +\section3 How to build the plugin on Unix/Linux + +The following assumes Interbase or Firebird is installed in +\c{/opt/interbase}: + +\code +cd $QTDIR/plugins/src/sqldrivers/ibase +qmake -o Makefile "INCLUDEPATH+=/opt/interbase/include" "LIBS+=-L/opt/interbase/lib" ibase.pro +make +\endcode + +\section3 How to build the plugin on Windows + +The following assumes Interbase or Firebird is installed in +\c{C:\interbase}: + +\code +cd %QTDIR%\plugins\src\sqldrivers\ibase +qmake -o Makefile "INCLUDEPATH+=C:\interbase\include" ibase.pro +nmake +\endcode + +If you are not using a Microsoft compiler, replace \c nmake +with \c make in the statement above. + +Note that \c{C:\interbase\bin} must be in the PATH. + +\target troubleshooting +\section1 Troubleshooting + +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 \c{COFF2OMF.EXE} to convert libraries that have been +generated with Microsoft Visual C++. + +If the compilation of a plugin succeeds but it cannot be loaded, +make sure that the following requirements are met: + +\list +\i Ensure that you are using a shared Qt library; you cannot use the + plugins with a static build. +\i Ensure that the environment variable \c QTDIR points to the right + directory. Go to the \c{$QTDIR/plugins/sqldrivers} directory and + make sure that the plugin exists in that directory. +\i Ensure that the client libraries of the DBMS are available on the + system. On Unix, run the command \c{ldd} and pass the name of the + plugin as parameter, for example \c{ldd libqsqlmysql.so}. 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. +\endlist + +If you are experiencing problems with loading plugins, and see output +like this + +\code +QSqlDatabase warning: QMYSQL3 driver not loaded +QSqlDatabase: available drivers: QMYSQL3 +\endcode + +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. + +The next time you try to load this plugin, it will give you a more detailed +error message. + +\target development +\section1 How to write your own database driver + +QSqlDatabase is responsible for loading and managing database driver +plugins. When a database is added (see QSqlDatabase::addDatabase()), +the appropriate driver plugin is loaded (using QSqlDriverPlugin). +QSqlDatabase relies on the driver plugin to provide interfaces for +QSqlDriver and QSqlResult. + +QSqlDriver is an abstract base class which defines the functionality +of a SQL database driver. This includes functions such as +QSqlDriver::open() and QSqlDriver::close(). QSqlDriver is responsible +for connecting to a database, establish the proper environment, etc. +In addition, QSqlDriver can create QSqlQuery objects appropriate for +the particular database API. QSqlDatabase forwards many of its +function calls directly to QSqlDriver which provides the concrete +implementation. + +QSqlResult is an abstract base class which defines the functionality +of a SQL database query. This includes statements such as \c{SELECT}, +\c{UPDATE}, and \c{ALTER TABLE}. 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 QSqlResult +which provides the concrete implementation. + +QSqlDriver 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. + +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 +\c Q_EXPORT_PLUGIN macro. Read the \link plugins-howto.html Qt +Plugin\endlink 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 \c{QTDIR/plugins/src/sqldrivers} and +\c{QTDIR/src/sql/drivers}. + +The following code can be used as a skeleton for a SQL driver: + +\code +class QNullResult : public QSqlResult +{ +public: + QNullResult( const QSqlDriver* d ): QSqlResult( d ) {} + ~QNullResult() {} +protected: + QVariant data( int ) { return QVariant(); } + bool reset ( const QString& ) { return FALSE; } + bool fetch( int ) { return FALSE; } + bool fetchFirst() { return FALSE; } + bool fetchLast() { return FALSE; } + bool isNull( int ) { return FALSE; } + QSqlRecord record() { return QSqlRecord(); } + int size() { return 0; } + int numRowsAffected() { return 0; } +}; + +class QNullDriver : public QSqlDriver +{ +public: + QNullDriver(): QSqlDriver() {} + ~QNullDriver() {} + bool hasFeature( DriverFeature ) const { return FALSE; } + bool open( const QString&, + const QString&, + const QString&, + const QString&, + int ) { return FALSE; } + void close() {} + QSqlQuery createQuery() const { return QSqlQuery( new QNullResult( this ) ); } +}; +\endcode + +*/ |