diff options
Diffstat (limited to 'doc/src/sql-driver.qdoc')
| -rw-r--r-- | doc/src/sql-driver.qdoc | 762 |
1 files changed, 0 insertions, 762 deletions
diff --git a/doc/src/sql-driver.qdoc b/doc/src/sql-driver.qdoc deleted file mode 100644 index 764a8ed..0000000 --- a/doc/src/sql-driver.qdoc +++ /dev/null @@ -1,762 +0,0 @@ -/**************************************************************************** -** -** Copyright (C) 2009 Nokia Corporation and/or its subsidiary(-ies). -** Contact: Nokia Corporation (qt-info@nokia.com) -** -** This file is part of the documentation of the Qt Toolkit. -** -** $QT_BEGIN_LICENSE:LGPL$ -** No Commercial Usage -** This file contains pre-release code and may not be distributed. -** You may use this file in accordance with the terms and conditions -** contained in the Technology Preview License Agreement accompanying -** this package. -** -** GNU Lesser General Public License Usage -** Alternatively, this file may be used under the terms of the GNU Lesser -** General Public License version 2.1 as published by the Free Software -** Foundation and appearing in the file LICENSE.LGPL included in the -** packaging of this file. Please review the following information to -** ensure the GNU Lesser General Public License version 2.1 requirements -** will be met: http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html. -** -** In addition, as a special exception, Nokia gives you certain -** additional rights. These rights are described in the Nokia Qt LGPL -** Exception version 1.1, included in the file LGPL_EXCEPTION.txt in this -** package. -** -** If you have questions regarding the use of this file, please contact -** Nokia at qt-info@nokia.com. -** -** -** -** -** -** -** -** -** $QT_END_LICENSE$ -** -****************************************************************************/ - -/*! - \page sql-driver.html - \title SQL Database Drivers - \ingroup architecture - \brief How to configure and install QtSql drivers for supported databases. - - The QtSql module uses driver \l{How to Create Qt - Plugins}{plugins} to communicate with the different database - APIs. Since Qt's 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 - \l{#development}{writing your own drivers}. - - \tableofcontents - - \section1 Supported Databases - - The table below lists the drivers included with Qt. Due to - license incompatibilities with the GPL, not all of the plugins - are provided with Open Source Versions of Qt. - - \table - \header \o Driver name \o DBMS - \row \o \link #QDB2 QDB2\endlink \o IBM DB2 (version 7.1 and above) - \row \o \link #QIBASE QIBASE\endlink \o Borland InterBase - \row \o \link #QMYSQL QMYSQL\endlink \o MySQL - \row \o \link #QOCI QOCI\endlink \o Oracle Call Interface Driver - \row \o \link #QODBC QODBC\endlink - \o Open Database Connectivity (ODBC) - Microsoft SQL Server and other - ODBC-compliant databases - \row \o \link #QPSQL QPSQL\endlink \o PostgreSQL (versions 7.3 and above) - \row \o \link #QSQLITE2 QSQLITE2\endlink \o SQLite version 2 - \row \o \link #QSQLITE QSQLITE\endlink \o SQLite version 3 - \row \o \link #QTDS QTDS\endlink \o Sybase Adaptive Server - \endtable - - \bold{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. - - \target building - \section1 Building the Drivers Using Configure - - On Unix and Mac OS X, the Qt \c configure script tries to - automatically detect the available client libraries on your - machine. Run \c{configure -help} to see what drivers can be - built. You should get an output similar to this: - - \snippet doc/src/snippets/code/doc_src_sql-driver.qdoc 0 - - The \c 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 \c -I and \c -L - command-line options. 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 \c -I parameter doesn't accept spaces in - filenames, so use the 8.3 name instead; for example, 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 QMYSQL - \section2 QMYSQL for MySQL 4 and higher - - \section3 QMYSQL Stored Procedure Support - - MySQL 5 introduces stored procedure support at the SQL level, but no - API to control IN, OUT and INOUT parameters. Therefore, parameters - have to be set and read using SQL commands instead of QSqlQuery::bindValue(). - - Example stored procedure: - - \snippet doc/src/snippets/code/doc_src_sql-driver.qdoc 1 - - Source code to access the OUT values: - - \snippet doc/src/snippets/code/doc_src_sql-driver.qdoc 2 - - \bold{Note:} \c{@outval1} and \c{@outval2} are variables local to the current - connection and will not be affected by queries sent from another host - or connection. - - \section3 Embedded MySQL Server - - The MySQL embedded server is a drop-in replacement for the normal - client library. With the embedded MySQL server, a MySQL server is - not required to use MySQL functionality. - - To use the embedded MySQL server, simply link the Qt plugin to \c - libmysqld instead of libmysqlclient. This can be done by replacing - \c -lmysqlclient_r by \c -lmysqld in the \c qmake command in the - section below. - - Please refer to the MySQL documentation, chapter "libmysqld, the Embedded - MySQL Server Library" for more information about the MySQL embedded server. - - \section3 How to Build the QMYSQL Plugin on Unix and Mac OS X - - You need the MySQL header files and as well as the shared library - \c{libmysqlclient.so}. Depending on your Linux distribution you may - need to install a package which is usually called "mysql-devel". - - Tell \l qmake 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}: - - \snippet doc/src/snippets/code/doc_src_sql-driver.qdoc 3 - - After installing Qt, as described in the \l{Installing Qt on X11 - Platforms} document, you also need to install the plugin in the - standard location: - - \snippet doc/src/snippets/code/doc_src_sql-driver.qdoc 4 - - \section3 How to Build the QMYSQL Plugin on Windows - - You need to get the MySQL installation files. Run \c 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}): - - \snippet doc/src/snippets/code/doc_src_sql-driver.qdoc 5 - - If you are not using a Microsoft compiler, replace \c nmake with \c - make in the line above. - - \note This database plugin is not supported for Windows CE. - - \note Including \c{"-o Makefile"} as an argument to \l qmake to - tell it where to build the makefile can cause the plugin to be - built in release mode only. If you are expecting a debug version - to be built as well, don't use the \c{"-o Makefile"} option. - - \target QOCI - \section2 QOCI for the Oracle Call Interface (OCI) - - \section3 General Information about the OCI plugin - - The Qt OCI plugin supports Oracle 9i, 10g and higher. After - connecting to the Oracle server, the plugin will auto-detect the - database version and enable features accordingly. - - It's possible to connect to a Oracle database without a tnsnames.ora file. - This requires that the database SID is passed to the driver as the database - name and that a hostname is given. - - \section3 OCI User Authentication - - The Qt OCI plugin supports authentication using - external credentials (OCI_CRED_EXT). Usually, this means that the database - server will use the user authentication provided by the operating system - instead of its own authentication mechanism. - - Leave the username and password empty when opening a connection with - QSqlDatabase to use the external credentials authentication. - - \section3 OCI BLOB/LOB Support - - Binary Large Objects (BLOBs) can be read and written, but be aware - that this process may require a lot of memory. You should 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 QSqlTableModel, which uses a prepared - query to do this internally. - - \section3 How to Build the OCI Plugin on Unix and Mac OS X - - For Oracle 10g, all you need is the "Instant Client Package - Basic" and - "Instant Client Package - SDK". For Oracle prior to 10g, you require - the standard Oracle client and the SDK packages. - - Oracle library files required to build the driver: - - \list - \i \c libclntsh.so (all versions) - \i \c libwtc9.so (only Oracle 9) - \endlist - - Tell \c qmake where to find the Oracle header files and shared - libraries and run make: - - For Oracle version 9: - \snippet doc/src/snippets/code/doc_src_sql-driver.qdoc 6 - - For Oracle version 10, we assume that you installed the RPM packages of the - Instant Client Package SDK (you need to adjust the version number accordingly): - \snippet doc/src/snippets/code/doc_src_sql-driver.qdoc 7 - - \bold{Note:} If you are using the Oracle Instant Client package, - you will need to set LD_LIBRARY_PATH when building the OCI SQL plugin - and when running an applicaiton that uses the OCI SQL plugin. You can - avoid this requirement by setting and RPATH and listing all of the - libraries to link to. Here is an example: - \snippet doc/src/snippets/code/doc_src_sql-driver.qdoc 32 - - If you wish to build the OCI plugin manually with this method the procedure looks like this: - \snippet doc/src/snippets/code/doc_src_sql-driver.qdoc 33 - - \section3 How to Build the OCI 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}): - - \snippet doc/src/snippets/code/doc_src_sql-driver.qdoc 8 - - If you are not using a Microsoft compiler, replace \c nmake with \c - make in the line above. - - When you run your application you will also need to add the \c oci.dll - path to your \c PATH environment variable: - - \snippet doc/src/snippets/code/doc_src_sql-driver.qdoc 9 - - \bold{Note:} This database plugin is not supported for Windows CE. - - \target QODBC - \section2 QODBC for Open Database Connectivity (ODBC) - - \section3 General Information about the ODBC plugin - - ODBC is a general interface that allows you to connect to multiple - DBMSs using a common interface. The QODBC 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 QODBC plugin - then allows you to use these data sources in your Qt applications. - - \bold{Note:} You should use native drivers in preference to the ODBC - driver where they are available. ODBC support can be used as a fallback - for compliant databases if no native drivers are available. - - On Windows 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 - QODBC 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 rather than the actual database name. - - The QODBC 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 QODBC 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 behavior, you can remove the \c{#define - ODBC_CHECK_DRIVER} line from the file \c{qsql_odbc.cpp}. Do this at - your own risk! - - By default, Qt instructs the ODBC driver to behave as an ODBC 2.x - driver. However, for some \e{driver-manager/ODBC 3.x-driver} - combinations (e.g., \e{unixODBC/MaxDB ODBC}), telling the ODBC - driver to behave as a 2.x driver can cause the driver plugin to - have unexpected behavior. To avoid this problem, instruct the ODBC - driver to behave as a 3.x driver by - \l{QSqlDatabase::setConnectOptions()} {setting the connect option} - \c{"SQL_ATTR_ODBC_VERSION=SQL_OV_ODBC3"} before you - \l{QSqlDatabase::open()} {open your database connection}. Note - that this will affect multiple aspects of ODBC driver behavior, - e.g., the SQLSTATEs. Before setting this connect option, consult - your ODBC documentation about behavior differences you can expect. - - If you experience very slow access of the ODBC datasource, make sure - that ODBC call tracing is turned off in the ODBC datasource manager. - - Some drivers don't support scrollable cursors. In that case case only - queries in forwardOnly mode can be used successfully. - - \section3 ODBC Stored Procedure Support - - With Microsoft SQL Server the result set returned by a stored - procedure that uses the return statement, or returns multiple result - sets, will be accessible only if you set the query's forward only - mode to \e forward using \l QSqlQuery::setForwardOnly(). - - \snippet doc/src/snippets/code/doc_src_sql-driver.qdoc 10 - - \bold{Note:} The value returned by the stored procedure's return statement - is discarded. - - \section3 ODBC Unicode Support - - The QODBC 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 must also support Unicode. - - Some driver managers and drivers don't support UNICODE. To use the - QODBC plugin with such drivers it has to be compiled with the - Q_ODBC_VERSION_2 defined. - - 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 ODBC Plugin on Unix and Mac OS X - - 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}: - - \snippet doc/src/snippets/code/doc_src_sql-driver.qdoc 11 - - \section3 How to Build the ODBC 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: - - \snippet doc/src/snippets/code/doc_src_sql-driver.qdoc 12 - - If you are not using a Microsoft compiler, replace \c nmake with \c - make in the line above. - - \bold{Note:} This database plugin is not officially supported for Windows CE. - - \target QPSQL - \section2 QPSQL for PostgreSQL (Version 7.3 and Above) - - \section3 General Information about the QPSQL driver - - The QPSQL driver supports version 7.3 and higher of the PostgreSQL server. - We recommend that you use a client library from version 7.3.15, 7.4.13, - 8.0.8, 8.1.4 or more recent as these versions contain security fixes, and - as the QPSQL driver might not build with older versions of the client - library depending on your platform. - - For more information about PostgreSQL visit \l http://www.postgresql.org. - - \section3 QPSQL Unicode Support - - The QPSQL 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 QPSQL BLOB Support - - Binary Large Objects are supported through the \c BYTEA field type in - PostgreSQL server versions >= 7.1. - - \section3 How to Build the QPSQL Plugin on Unix and Mac OS X - - You need the PostgreSQL client library and headers installed. - - To make \c qmake find the PostgreSQL header files and shared - libraries, run \c qmake the following way (assuming that the - PostgreSQL client is installed in \c{/usr}): - - \snippet doc/src/snippets/code/doc_src_sql-driver.qdoc 13 - - After installing Qt, as described in the \l{Installing Qt on X11 Platforms} document, - you also need to install the plugin in the standard location: - - \snippet doc/src/snippets/code/doc_src_sql-driver.qdoc 14 - - \section3 How to Build the QPSQL Plugin on Windows - - Install the appropriate PostgreSQL developer libraries for your - compiler. Assuming that PostgreSQL was installed in \c{C:\psql}, - build the plugin as follows: - - \snippet doc/src/snippets/code/doc_src_sql-driver.qdoc 15 - - Users of MinGW may wish to consult the following online document: - \l{Compiling PostgreSQL On Native Win32 FAQ}. - - \bold{Note:} This database plugin is not supported for Windows CE. - - \target QTDS - \section2 QTDS for Sybase Adaptive Server - \section3 General Information about QTDS - - It is not possible to set the port with QSqlDatabase::setPort() due to limitations in the - Sybase client library. Refer to the Sybase documentation for information on how to set up - a Sybase client configuration file to enable connections to databases on non-default ports. - - \section3 How to Build the QDTS Plugin on Unix and Mac OS X - - Under Unix, two libraries are available which support the TDS protocol: - - \list - \i 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. - - \i 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}. - \endlist - - Regardless of which library you use, the shared object file - \c{libsybdb.so} is needed. Set the \c SYBASE environment variable to - point to the directory where you installed the client library and - execute \c{qmake}: - - \snippet doc/src/snippets/code/doc_src_sql-driver.qdoc 16 - - \section3 How to Build the QDTS 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: - - \snippet doc/src/snippets/code/doc_src_sql-driver.qdoc 17 - - 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}. If you - are not using a Microsoft compiler, replace \c nmake with \c make in - the line above. - - \bold{Note:} This database plugin is not supported for Windows CE. - - \target QDB2 - \section2 QDB2 for IBM DB2 (Version 7.1 and Above) - - \section3 General Information about QDB2 - - 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 must 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 QDB2 Plugin on Unix and Mac OS X - - \snippet doc/src/snippets/code/doc_src_sql-driver.qdoc 18 - - After installing Qt, as described in the \l{Installing Qt on X11 Platforms} document, - you also need to install the plugin in the standard location: - - \snippet doc/src/snippets/code/doc_src_sql-driver.qdoc 19 - - \section3 How to Build the QDB2 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: - - \snippet doc/src/snippets/code/doc_src_sql-driver.qdoc 20 - - If you are not using a Microsoft compiler, replace \c nmake - with \c make in the line above. - - \bold{Note:} This database plugin is not supported for Windows CE. - - \target QSQLITE2 - \section2 QSQLITE2 for SQLite Version 2 - - The Qt SQLite 2 plugin is offered for compatibility. Whenever - possible, use the \l{#QSQLITE}{version 3 plugin} instead. The - build instructions for version 3 apply to version 2 as well. - - \target QSQLITE - \section2 QSQLITE for SQLite (Version 3 and Above) - - \section3 General Information about QSQLITE - - The Qt SQLite plugin makes it possible to access SQLite - databases. SQLite is an in-process database, which means that it - is not necessary to have a database server. SQLite operates on a - single file, which must be set as the 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. The Qt SQLite driver will retry to write to a locked resource - until it runs into a timeout (see \c{QSQLITE_BUSY_TIMEOUT} - at QSqlDatabase::setConnectOptions()). - - In SQLite any column, with the exception of an INTEGER PRIMARY KEY column, - may be used to store any type of value. For instance, a column declared as - INTEGER may contain an integer value in one row and a text value in the - next. This is due to SQLite associating the type of a value with the value - itself rather than with the column it is stored in. A consequence of this - is that the type returned by QSqlField::type() only indicates the field's - recommended type. No assumption of the actual type should be made from - this and the type of the individual values should be checked. - - The driver is locked for updates while a select is executed. This - may cause problems when using QSqlTableModel because Qt's item views - fetch data as needed (with QSqlQuery::fetchMore() in the case of - QSqlTableModel). - - You can find information about SQLite on \l{http://www.sqlite.org}. - - \section3 How to Build the QSQLITE Plugin - - SQLite version 3 is included as a third-party library within Qt. - It can be built by passing the following parameters to the - configure script: \c{-plugin-sql-sqlite} (build as a plugin) or - \c{-qt-sql-sqlite} (linked directly into the Qt library). - - If you don't want to use the SQLite library included with Qt, you - can build it manually (replace \c $SQLITE by the directory where - SQLite resides): - - \snippet doc/src/snippets/code/doc_src_sql-driver.qdoc 21 - - After installing Qt, as described in the \l{Installing Qt on X11 Platforms} document, - you also need to install the plugin in the standard location: - - \snippet doc/src/snippets/code/doc_src_sql-driver.qdoc 22 - - On Windows: - - \snippet doc/src/snippets/code/doc_src_sql-driver.qdoc 23 - - \section3 QSQLITE File Format Compatibility - - SQLite minor releases sometimes break file format forward compatibility. - For example, SQLite 3.3 can read database files created with SQLite 3.2, - but databases created with SQLite 3.3 cannot be read by SQLite 3.2. - Please refer to the SQLite documentation and change logs for information about - file format compatibility between versions. - - Qt minor releases usually follow the SQLite minor releases, while Qt patch releases - follow SQLite patch releases. Patch releases are therefore both backward and forward - compatible. - - To force SQLite to use a specific file format, it is neccessary to build and - ship your own database plugin with your own SQLite library as illustrated above. - Some versions of SQLite can be forced to write a specific file format by setting - the \c{SQLITE_DEFAULT_FILE_FORMAT} define when building SQLite. - - \target QIBASE - \section2 QIBASE for Borland InterBase - - \section3 General Information about QIBASE - - 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 in which case it operates 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. - - \snippet doc/src/snippets/code/doc_src_sql-driver.qdoc 24 - - You need the InterBase/Firebird development headers and libraries - to build this plugin. - - Due to license incompatibilities with 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 QIBASE Unicode Support and Text Encoding - - By default the driver connects to the database using UNICODE_FSS. This can - be overridden by setting the ISC_DPB_LC_CTYPE parameter with - QSqlDatabase::setConnectOptions() before opening the connection. - - \snippet doc/src/snippets/code/doc_src_sql-driver.qdoc 25 - - If Qt doesn't support the given text encoding the driver will issue a - warning message and connect to the database using UNICODE_FSS. - - Note that if the text encoding set when connecting to the database is - not the same as in the database, problems with transliteration might arise. - - \section3 QIBASE Stored procedures - - InterBase/Firebird return OUT values as result set, so when calling stored - procedure, only IN values need to be bound via QSqlQuery::bindValue(). The - RETURN/OUT values can be retrieved via QSqlQuery::value(). Example: - - \snippet doc/src/snippets/code/doc_src_sql-driver.qdoc 26 - - \section3 How to Build the QIBASE Plugin on Unix and Mac OS X - - The following assumes InterBase or Firebird is installed in - \c{/opt/interbase}: - - If you are using InterBase: - - \snippet doc/src/snippets/code/doc_src_sql-driver.qdoc 27 - - If you are using Firebird, the Firebird library has to be set explicitly: - - \snippet doc/src/snippets/code/doc_src_sql-driver.qdoc 28 - - \section3 How to Build the QIBASE Plugin on Windows - - The following assumes InterBase or Firebird is installed in - \c{C:\interbase}: - - If you are using InterBase: - - \snippet doc/src/snippets/code/doc_src_sql-driver.qdoc 29 - - If you are using Firebird, the Firebird library has to be set explicitely: - - \snippet doc/src/snippets/code/doc_src_sql-driver.qdoc 30 - - If you are not using a Microsoft compiler, replace \c nmake - with \c make in the line above. - - Note that \c{C:\interbase\bin} must be in the \c PATH. - - \bold{Note:} This database plugin is not supported for Windows CE. - - \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 plugin is in the correct directory. You can use - QApplication::libraryPaths() to determine where Qt looks for plugins. - \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 Visual Studio's dependency walker. - \i Compile Qt with \c{QT_DEBUG_COMPONENT} defined to get very verbose - debug output when loading plugins. - \endlist - - If you experience plugin load problems and see output like this: - - \snippet doc/src/snippets/code/doc_src_sql-driver.qdoc 31 - - The problem is usually that the plugin had the wrong \l{How to - Create Qt Plugins#The Build Key}{build key}. This might require - removing an entry from the \l{How to Create Qt Plugins#The Plugin - Cache} {plugin cache}. Here is some more \l{How to Create Qt - Plugins#Debugging Plugins} {plugin debugging info}. - - \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} \c{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 Q_EXPORT_PLUGIN2() macro. Read \l{How to Create Qt - Plugins} for more information on this. You can also check out how - this is done in the SQL plugins that are provided with Qt in - \c{QTDIR/src/plugins/sqldrivers} and \c{QTDIR/src/sql/drivers}. - - The following code can be used as a skeleton for a SQL driver: - - \snippet doc/src/snippets/sqldatabase/sqldatabase.cpp 47 - \codeline - \snippet doc/src/snippets/sqldatabase/sqldatabase.cpp 48 -*/ |