1 /****************************************************************************
3 ** Copyright (C) 2011 Nokia Corporation and/or its subsidiary(-ies).
4 ** All rights reserved.
5 ** Contact: Nokia Corporation (qt-info@nokia.com)
7 ** This file is part of the documentation of the Qt Toolkit.
9 ** $QT_BEGIN_LICENSE:FDL$
10 ** GNU Free Documentation License
11 ** Alternatively, this file may be used under the terms of the GNU Free
12 ** Documentation License version 1.3 as published by the Free Software
13 ** Foundation and appearing in the file included in the packaging of
17 ** Alternatively, this file may be used in accordance with the terms
18 ** and conditions contained in a signed written agreement between you
26 ****************************************************************************/
30 \title SQL Database Drivers
31 \brief How to configure and install QtSql drivers for supported databases.
35 The QtSql module uses driver \l{How to Create Qt
36 Plugins}{plugins} to communicate with the different database
37 APIs. Since Qt's SQL Module API is database-independent, all
38 database-specific code is contained within these drivers. Several
39 drivers are supplied with Qt and other drivers can be added. The
40 driver source code is supplied and can be used as a model for
41 \l{#development}{writing your own drivers}.
45 \section1 Supported Databases
47 The table below lists the drivers included with Qt. Due to
48 license incompatibilities with the GPL, not all of the plugins
49 are provided with Open Source Versions of Qt.
52 \header \o Driver name \o DBMS
53 \row \o \link #QDB2 QDB2\endlink \o IBM DB2 (version 7.1 and above)
54 \row \o \link #QIBASE QIBASE\endlink \o Borland InterBase
55 \row \o \link #QMYSQL QMYSQL\endlink \o MySQL
56 \row \o \link #QOCI QOCI\endlink \o Oracle Call Interface Driver
57 \row \o \link #QODBC QODBC\endlink
58 \o Open Database Connectivity (ODBC) - Microsoft SQL Server and other
59 ODBC-compliant databases
60 \row \o \link #QPSQL QPSQL\endlink \o PostgreSQL (versions 7.3 and above)
61 \row \o \link #QSQLITE2 QSQLITE2\endlink \o SQLite version 2
62 \row \o \link #QSQLITE QSQLITE\endlink \o SQLite version 3
63 \row \o \link #QTDS QTDS\endlink \o Sybase Adaptive Server \note obsolete from Qt 4.7
66 SQLite is the in-process database system with the best test coverage
67 and support on all platforms. Oracle via OCI, and PostreSQL and MySQL
68 through either ODBC or a native driver are well-tested on Windows and
69 Linux. The completeness of the support for other systems depends on the
70 availability and quality of client libraries.
72 \bold{Note:} To build a driver plugin you need to have the appropriate
73 client library for your Database Management System (DBMS). This provides
74 access to the API exposed by the DBMS, and is typically shipped with it.
75 Most installation programs also allow you to install "development
76 libraries", and these are what you need. These libraries are responsible
77 for the low-level communication with the DBMS.
80 \section1 Building the Drivers Using Configure
82 On Unix and Mac OS X, the Qt \c configure script tries to
83 automatically detect the available client libraries on your
84 machine. Run \c{configure -help} to see what drivers can be
85 built. You should get an output similar to this:
87 \snippet doc/src/snippets/code/doc_src_sql-driver.qdoc 0
89 The \c configure script cannot detect the neccessary libraries
90 and include files if they are not in the standard paths, so it
91 may be necessary to specify these paths using the \c -I and \c -L
92 command-line options. For example, if your MySQL include files
93 are installed in \c /usr/local/mysql (or in \c{C:\mysql\include}
94 on Windows), then pass the following parameter to configure: \c
95 -I/usr/local/mysql (or \c{-I C:\mysql\include} for Windows).
97 On Windows the \c -I parameter doesn't accept spaces in
98 filenames, so use the 8.3 name instead; for example, use
99 \c{C:\progra~1\mysql} instead of \c{C:\Program Files\mysql}.
101 Use the \c{-qt-sql-<driver>} parameter to build the database driver
102 statically into your Qt library or \c{-plugin-sql-<driver>} to build
103 the driver as a plugin. Look at the sections that follow for
104 additional information about required libraries.
106 \target buildingmanually
107 \section1 Building the Plugins Manually
110 \section2 QMYSQL for MySQL 4 and higher
112 \section3 QMYSQL Stored Procedure Support
114 MySQL 5 introduces stored procedure support at the SQL level, but no
115 API to control IN, OUT and INOUT parameters. Therefore, parameters
116 have to be set and read using SQL commands instead of QSqlQuery::bindValue().
118 Example stored procedure:
120 \snippet doc/src/snippets/code/doc_src_sql-driver.qdoc 1
122 Source code to access the OUT values:
124 \snippet doc/src/snippets/code/doc_src_sql-driver.cpp 2
126 \bold{Note:} \c{@outval1} and \c{@outval2} are variables local to the current
127 connection and will not be affected by queries sent from another host
130 \section3 Embedded MySQL Server
132 The MySQL embedded server is a drop-in replacement for the normal
133 client library. With the embedded MySQL server, a MySQL server is
134 not required to use MySQL functionality.
136 To use the embedded MySQL server, simply link the Qt plugin to \c
137 libmysqld instead of libmysqlclient. This can be done by replacing
138 \c -lmysqlclient_r by \c -lmysqld in the \c qmake command in the
141 Please refer to the MySQL documentation, chapter "libmysqld, the Embedded
142 MySQL Server Library" for more information about the MySQL embedded server.
144 \section3 How to Build the QMYSQL Plugin on Unix and Mac OS X
146 You need the MySQL header files and as well as the shared library
147 \c{libmysqlclient.so}. Depending on your Linux distribution you may
148 need to install a package which is usually called "mysql-devel".
150 Tell \l qmake where to find the MySQL header files and shared
151 libraries (here it is assumed that MySQL is installed in
152 \c{/usr/local}) and run \c{make}:
154 \snippet doc/src/snippets/code/doc_src_sql-driver.qdoc 3
156 After installing Qt, as described in the \l{Installing Qt for X11
157 Platforms} document, you also need to install the plugin in the
160 \snippet doc/src/snippets/code/doc_src_sql-driver.qdoc 4
162 \section3 How to Build the QMYSQL Plugin on Windows
164 You need to get the MySQL installation files. Run \c SETUP.EXE and
165 choose "Custom Install". Install the "Libs & Include Files" Module.
166 Build the plugin as follows (here it is assumed that MySQL is
167 installed in \c{C:\MySQL}):
169 \snippet doc/src/snippets/code/doc_src_sql-driver.qdoc 5
171 If you are not using a Microsoft compiler, replace \c nmake with \c
172 make in the line above.
174 \note This database plugin is not supported for Windows CE.
176 \note Including \c{"-o Makefile"} as an argument to \l qmake to
177 tell it where to build the makefile can cause the plugin to be
178 built in release mode only. If you are expecting a debug version
179 to be built as well, don't use the \c{"-o Makefile"} option.
181 \section3 How to build the MySQL driver for MinGW users
183 The following steps have been used successfully for WinXP SP3. In
184 this example, Qt 4.6.2 is shown.
188 \o Download the following components:
190 \o \c{MinGW-5.1.6.exe}
191 \o \c{mingw-utils-0.3.tar.gz}
192 \o Qt sources, e.g. \c{qt-everywhere-opensource-src-4.6.2.zip}
193 \o \c{mysql-5.1.35-win32.msi}
196 \o Install \c{MinGW-5.1.6.exe} in, e.g. \c{C:\MinGW}.
198 \o Extract \c{mingw-utils-0.3.tar.gz} into, e.g. \c{C:\MinGW}.
200 \o Add the path for \c{MinGW-5.1.6.exe} to your \c{PATH} variable,
201 e.g. \c{C:\MinGW\bin;}
203 \o Extract the Qt sources, (\c{qt-everywhere-opensource-src-4.6.2.zip}),
204 into, e.g. \c{C:\Qt}.
206 \o Add the path for the eventual Qt binary to your \c{PATH} variable,
207 e.g. \c{C:\Qt\4.6.2\bin;}.
209 \o Install MySQL (\c{mysql-5.1.35-win32.msi}), customizing the
210 components. Select only the headers and libraries. Install in,
211 e.g. \c{C:\MySQL\MySQL51}.
213 \o Open the DOS prompt, go to \c{C:\MySQL\MySQL51\lib\opt}, and run
214 the following commands:
216 \o \c{reimp -d libmysql.lib}
217 \o \c{dlltool -k -d libmysql.def -l libmysql.a}
220 \o Open the DOS prompt, go to \c{C:\Qt\4.6.2} and run the following commands:
222 \o \c{configure.exe -debug-and-release -platform win32-g++ -qt-sql-mysql
223 -l mysql -I C:\MySQL\MySQL51\include -L C:\MySQL\MySQL51\lib\opt}
224 \o \c{mingw32-make sub-src}
226 This step takes a long time.
228 \o Open the DOS prompt, go to
229 \c{C:\Qt\4.6.2\src\plugins\sqldrivers\mysql} and run the
232 \o \c{qmake "INCLUDEPATH+=C:\MySQL\MySQL51\include" "LIBS+=-L. mysql" mysql.pro}
235 \o Now the following libraries are ready in \c{C:\Qt\4.6.2\plugins\sqldrivers}.
237 \o \c{libqsqlmysql4.a}
238 \o \c{libqsqlmysqld4.a}
239 \o \c{qsqlmysql4.dll}
240 \o \c{qsqlmysqld4.dll}
242 To use the SDK and QtCreator directly, copy these libraries to
243 your \c{C:\Qt\...\qt\plugins\sqldrivers\}, and copy
244 \c{C:\MySQL\MySQL51\lib\opt\libmysql.dll} to your \c{C:\Qt\...\qt\bin\}.
249 \section2 QOCI for the Oracle Call Interface (OCI)
251 \section3 General Information about the OCI plugin
253 The Qt OCI plugin supports Oracle 9i, 10g and higher. After
254 connecting to the Oracle server, the plugin will auto-detect the
255 database version and enable features accordingly.
257 It's possible to connect to a Oracle database without a tnsnames.ora file.
258 This requires that the database SID is passed to the driver as the database
259 name and that a hostname is given.
261 \section3 OCI User Authentication
263 The Qt OCI plugin supports authentication using
264 external credentials (OCI_CRED_EXT). Usually, this means that the database
265 server will use the user authentication provided by the operating system
266 instead of its own authentication mechanism.
268 Leave the username and password empty when opening a connection with
269 QSqlDatabase to use the external credentials authentication.
271 \section3 OCI BLOB/LOB Support
273 Binary Large Objects (BLOBs) can be read and written, but be aware
274 that this process may require a lot of memory. You should use a forward
275 only query to select LOB fields (see QSqlQuery::setForwardOnly()).
277 Inserting BLOBs should be done using either a prepared query where the
278 BLOBs are bound to placeholders or QSqlTableModel, which uses a prepared
279 query to do this internally.
281 \section3 How to Build the OCI Plugin on Unix and Mac OS X
283 For Oracle 10g, all you need is the "Instant Client Package - Basic" and
284 "Instant Client Package - SDK". For Oracle prior to 10g, you require
285 the standard Oracle client and the SDK packages.
287 Oracle library files required to build the driver:
290 \i \c libclntsh.so (all versions)
291 \i \c libwtc9.so (only Oracle 9)
294 Tell \c qmake where to find the Oracle header files and shared
295 libraries and run make:
297 For Oracle version 9:
298 \snippet doc/src/snippets/code/doc_src_sql-driver.qdoc 6
300 For Oracle version 10, we assume that you installed the RPM packages of the
301 Instant Client Package SDK (you need to adjust the version number accordingly):
302 \snippet doc/src/snippets/code/doc_src_sql-driver.qdoc 7
304 \bold{Note:} If you are using the Oracle Instant Client package,
305 you will need to set LD_LIBRARY_PATH when building the OCI SQL plugin
306 and when running an applicaiton that uses the OCI SQL plugin. You can
307 avoid this requirement by setting and RPATH and listing all of the
308 libraries to link to. Here is an example:
309 \snippet doc/src/snippets/code/doc_src_sql-driver.qdoc 32
311 If you wish to build the OCI plugin manually with this method the procedure looks like this:
312 \snippet doc/src/snippets/code/doc_src_sql-driver.qdoc 33
314 \section3 How to Build the OCI Plugin on Windows
316 Choosing the option "Programmer" in the Oracle Client Installer from
317 the Oracle Client Installation CD is generally sufficient to build the
318 plugin. For some versions of Oracle Client, you may also need to select
319 the "Call Interface (OCI)" option if it is available.
321 Build the plugin as follows (here it is assumed that Oracle Client is
322 installed in \c{C:\oracle}):
324 \snippet doc/src/snippets/code/doc_src_sql-driver.qdoc 8
326 If you are not using a Microsoft compiler, replace \c nmake with \c
327 make in the line above.
329 When you run your application you will also need to add the \c oci.dll
330 path to your \c PATH environment variable:
332 \snippet doc/src/snippets/code/doc_src_sql-driver.qdoc 9
334 \bold{Note:} This database plugin is not supported for Windows CE.
337 \section2 QODBC for Open Database Connectivity (ODBC)
339 \section3 General Information about the ODBC plugin
341 ODBC is a general interface that allows you to connect to multiple
342 DBMSs using a common interface. The QODBC driver allows you to connect
343 to an ODBC driver manager and access the available data sources. Note
344 that you also need to install and configure ODBC drivers for the ODBC
345 driver manager that is installed on your system. The QODBC plugin
346 then allows you to use these data sources in your Qt applications.
348 \bold{Note:} You should use native drivers in preference to the ODBC
349 driver where they are available. ODBC support can be used as a fallback
350 for compliant databases if no native drivers are available.
352 On Windows an ODBC driver manager should be installed by default.
353 For Unix systems there are some implementations which must be
354 installed first. Note that every client that uses your application is
355 required to have an ODBC driver manager installed, otherwise the
356 QODBC plugin will not work.
358 Be aware that when connecting to an ODBC datasource you must pass in
359 the name of the ODBC datasource to the QSqlDatabase::setDatabaseName()
360 function rather than the actual database name.
362 The QODBC Plugin needs an ODBC compliant driver manager version 2.0 or
363 later to work. Some ODBC drivers claim to be version 2.0 compliant,
364 but do not offer all the necessary functionality. The QODBC plugin
365 therefore checks whether the data source can be used after a
366 connection has been established and refuses to work if the check
367 fails. If you don't like this behavior, you can remove the \c{#define
368 ODBC_CHECK_DRIVER} line from the file \c{qsql_odbc.cpp}. Do this at
371 By default, Qt instructs the ODBC driver to behave as an ODBC 2.x
372 driver. However, for some \e{driver-manager/ODBC 3.x-driver}
373 combinations (e.g., \e{unixODBC/MaxDB ODBC}), telling the ODBC
374 driver to behave as a 2.x driver can cause the driver plugin to
375 have unexpected behavior. To avoid this problem, instruct the ODBC
376 driver to behave as a 3.x driver by
377 \l{QSqlDatabase::setConnectOptions()} {setting the connect option}
378 \c{"SQL_ATTR_ODBC_VERSION=SQL_OV_ODBC3"} before you
379 \l{QSqlDatabase::open()} {open your database connection}. Note
380 that this will affect multiple aspects of ODBC driver behavior,
381 e.g., the SQLSTATEs. Before setting this connect option, consult
382 your ODBC documentation about behavior differences you can expect.
384 If you experience very slow access of the ODBC datasource, make sure
385 that ODBC call tracing is turned off in the ODBC datasource manager.
387 Some drivers don't support scrollable cursors. In that case case only
388 queries in forwardOnly mode can be used successfully.
390 \section3 ODBC Stored Procedure Support
392 With Microsoft SQL Server the result set returned by a stored
393 procedure that uses the return statement, or returns multiple result
394 sets, will be accessible only if you set the query's forward only
395 mode to \e forward using \l QSqlQuery::setForwardOnly().
397 \snippet doc/src/snippets/code/doc_src_sql-driver.cpp 10
399 \bold{Note:} The value returned by the stored procedure's return statement
402 \section3 ODBC Unicode Support
404 The QODBC Plugin will use the Unicode API if UNICODE is defined. On
405 Windows NT based systems, this is the default. Note that the ODBC
406 driver and the DBMS must also support Unicode.
408 Some driver managers and drivers don't support UNICODE. To use the
409 QODBC plugin with such drivers it has to be compiled with the
410 Q_ODBC_VERSION_2 defined.
412 For the Oracle 9 ODBC driver (Windows), it is neccessary to check
413 "SQL_WCHAR support" in the ODBC driver manager otherwise Oracle
414 will convert all Unicode strings to local 8-bit.
416 \section3 How to Build the ODBC Plugin on Unix and Mac OS X
418 It is recommended that you use unixODBC. You can find the latest
419 version and ODBC drivers at \l http://www.unixodbc.org.
420 You need the unixODBC header files and shared libraries.
422 Tell \c qmake where to find the unixODBC header files and shared
423 libraries (here it is assumed that unixODBC is installed in
424 \c{/usr/local/unixODBC}) and run \c{make}:
426 \snippet doc/src/snippets/code/doc_src_sql-driver.qdoc 11
428 \section3 How to Build the ODBC Plugin on Windows
430 The ODBC header and include files should already be installed in the
431 right directories. You just have to build the plugin as follows:
433 \snippet doc/src/snippets/code/doc_src_sql-driver.qdoc 12
435 If you are not using a Microsoft compiler, replace \c nmake with \c
436 make in the line above.
438 \bold{Note:} This database plugin is not officially supported for Windows CE.
441 \section2 QPSQL for PostgreSQL (Version 7.3 and Above)
443 \section3 General Information about the QPSQL driver
445 The QPSQL driver supports version 7.3 and higher of the PostgreSQL server.
446 We recommend that you use a client library from version 7.3.15, 7.4.13,
447 8.0.8, 8.1.4 or more recent as these versions contain security fixes, and
448 as the QPSQL driver might not build with older versions of the client
449 library depending on your platform.
451 For more information about PostgreSQL visit \l http://www.postgresql.org.
453 \section3 QPSQL Unicode Support
455 The QPSQL driver automatically detects whether the PostgreSQL
456 database you are connecting to supports Unicode or not. Unicode is
457 automatically used if the server supports it. Note that the driver
458 only supports the UTF-8 encoding. If your database uses any other
459 encoding, the server must be compiled with Unicode conversion
462 Unicode support was introduced in PostgreSQL version 7.1 and it will
463 only work if both the server and the client library have been compiled
464 with multibyte support. More information about how to set up a
465 multibyte enabled PostgreSQL server can be found in the PostgreSQL
466 Administrator Guide, Chapter 5.
468 \section3 QPSQL BLOB Support
470 Binary Large Objects are supported through the \c BYTEA field type in
471 PostgreSQL server versions >= 7.1.
473 \section3 How to Build the QPSQL Plugin on Unix and Mac OS X
475 You need the PostgreSQL client library and headers installed.
477 To make \c qmake find the PostgreSQL header files and shared
478 libraries, run \c qmake the following way (assuming that the
479 PostgreSQL client is installed in \c{/usr}):
481 \snippet doc/src/snippets/code/doc_src_sql-driver.qdoc 13
483 After installing Qt, as described in the \l{Installing Qt for X11 Platforms} document,
484 you also need to install the plugin in the standard location:
486 \snippet doc/src/snippets/code/doc_src_sql-driver.qdoc 14
488 \section3 How to Build the QPSQL Plugin on Windows
490 Install the appropriate PostgreSQL developer libraries for your
491 compiler. Assuming that PostgreSQL was installed in \c{C:\psql},
492 build the plugin as follows:
494 \snippet doc/src/snippets/code/doc_src_sql-driver.qdoc 15
496 Users of MinGW may wish to consult the following online document:
497 \l{Compiling PostgreSQL On Native Win32 FAQ}.
499 \bold{Note:} This database plugin is not supported for Windows CE.
502 \section2 QTDS for Sybase Adaptive Server
504 \note TDS is no longer used by MS Sql Server, and is superceded by
505 \l{QODBC}{ODBC}. QTDS is obsolete from Qt 4.7.
507 \section3 General Information about QTDS
509 It is not possible to set the port with QSqlDatabase::setPort() due to limitations in the
510 Sybase client library. Refer to the Sybase documentation for information on how to set up
511 a Sybase client configuration file to enable connections to databases on non-default ports.
513 \section3 How to Build the QTDS Plugin on Unix and Mac OS X
515 Under Unix, two libraries are available which support the TDS protocol:
518 \i FreeTDS, a free implementation of the TDS protocol
519 (\l{http://www.freetds.org}). Note that FreeTDS is not yet stable,
520 so some functionality may not work as expected.
522 \i Sybase Open Client, available from \l{http://www.sybase.com}.
523 Note for Linux users: Get the Open Client RPM from
524 \l{http://linux.sybase.com}.
527 Regardless of which library you use, the shared object file
528 \c{libsybdb.so} is needed. Set the \c SYBASE environment variable to
529 point to the directory where you installed the client library and
532 \snippet doc/src/snippets/code/doc_src_sql-driver.qdoc 16
534 \section3 How to Build the QDTS Plugin on Windows
536 You can either use the DB-Library supplied by Microsoft or the Sybase
537 Open Client (\l{http://www.sybase.com}). You must include \c
538 NTWDBLIB.LIB to build the plugin:
540 \snippet doc/src/snippets/code/doc_src_sql-driver.qdoc 17
542 By default the Microsoft library is used on Windows, if you want to
543 force the use of the Sybase Open Client, you must define \c
544 Q_USE_SYBASE in \c{%QTDIR%\src\sql\drivers\tds\qsql_tds.cpp}. If you
545 are not using a Microsoft compiler, replace \c nmake with \c make in
548 \bold{Note:} This database plugin is not supported for Windows CE.
551 \section2 QDB2 for IBM DB2 (Version 7.1 and Above)
553 \section3 General Information about QDB2
555 The Qt DB2 plugin makes it possible to access IBM DB2 databases. It
556 has been tested with IBM DB2 v7.1 and 7.2. You must install the IBM
557 DB2 development client library, which contains the header and library
558 files necessary for compiling the QDB2 plugin.
560 The QDB2 driver supports prepared queries, reading/writing of Unicode
561 strings and reading/writing of BLOBs.
563 We suggest using a forward-only query when calling stored procedures
564 in DB2 (see QSqlQuery::setForwardOnly()).
566 \section3 How to Build the QDB2 Plugin on Unix and Mac OS X
568 \snippet doc/src/snippets/code/doc_src_sql-driver.qdoc 18
570 After installing Qt, as described in the \l{Installing Qt for X11 Platforms} document,
571 you also need to install the plugin in the standard location:
573 \snippet doc/src/snippets/code/doc_src_sql-driver.qdoc 19
575 \section3 How to Build the QDB2 Plugin on Windows
577 The DB2 header and include files should already be installed in the
578 right directories. You just have to build the plugin as follows:
580 \snippet doc/src/snippets/code/doc_src_sql-driver.qdoc 20
582 If you are not using a Microsoft compiler, replace \c nmake
583 with \c make in the line above.
585 \bold{Note:} This database plugin is not supported for Windows CE.
588 \section2 QSQLITE2 for SQLite Version 2
590 The Qt SQLite 2 plugin is offered for compatibility. Whenever
591 possible, use the \l{#QSQLITE}{version 3 plugin} instead. The
592 build instructions for version 3 apply to version 2 as well.
595 \section2 QSQLITE for SQLite (Version 3 and Above)
597 \section3 General Information about QSQLITE
599 The Qt SQLite plugin makes it possible to access SQLite
600 databases. SQLite is an in-process database, which means that it
601 is not necessary to have a database server. SQLite operates on a
602 single file, which must be set as the database name when opening
603 a connection. If the file does not exist, SQLite will try to
604 create it. SQLite also supports in-memory databases, simply pass
605 ":memory:" as the database name.
607 SQLite has some restrictions regarding multiple users and
608 multiple transactions. If you try to read/write on a resource from different
609 transactions, your application might freeze until one transaction commits
610 or rolls back. The Qt SQLite driver will retry to write to a locked resource
611 until it runs into a timeout (see \c{QSQLITE_BUSY_TIMEOUT}
612 at QSqlDatabase::setConnectOptions()).
614 In SQLite any column, with the exception of an INTEGER PRIMARY KEY column,
615 may be used to store any type of value. For instance, a column declared as
616 INTEGER may contain an integer value in one row and a text value in the
617 next. This is due to SQLite associating the type of a value with the value
618 itself rather than with the column it is stored in. A consequence of this
619 is that the type returned by QSqlField::type() only indicates the field's
620 recommended type. No assumption of the actual type should be made from
621 this and the type of the individual values should be checked.
623 The driver is locked for updates while a select is executed. This
624 may cause problems when using QSqlTableModel because Qt's item views
625 fetch data as needed (with QSqlQuery::fetchMore() in the case of
628 You can find information about SQLite on \l{http://www.sqlite.org}.
630 \section3 How to Build the QSQLITE Plugin
632 SQLite version 3 is included as a third-party library within Qt.
633 It can be built by passing the following parameters to the
634 configure script: \c{-plugin-sql-sqlite} (build as a plugin) or
635 \c{-qt-sql-sqlite} (linked directly into the Qt library).
637 If you don't want to use the SQLite library included with Qt, you
638 can build it manually (replace \c $SQLITE by the directory where
641 \snippet doc/src/snippets/code/doc_src_sql-driver.qdoc 21
643 After installing Qt, as described in the \l{Installing Qt for X11 Platforms} document,
644 you also need to install the plugin in the standard location:
646 \snippet doc/src/snippets/code/doc_src_sql-driver.qdoc 22
650 \snippet doc/src/snippets/code/doc_src_sql-driver.qdoc 23
652 \section3 QSQLITE File Format Compatibility
654 SQLite minor releases sometimes break file format forward compatibility.
655 For example, SQLite 3.3 can read database files created with SQLite 3.2,
656 but databases created with SQLite 3.3 cannot be read by SQLite 3.2.
657 Please refer to the SQLite documentation and change logs for information about
658 file format compatibility between versions.
660 Qt minor releases usually follow the SQLite minor releases, while Qt patch releases
661 follow SQLite patch releases. Patch releases are therefore both backward and forward
664 To force SQLite to use a specific file format, it is neccessary to build and
665 ship your own database plugin with your own SQLite library as illustrated above.
666 Some versions of SQLite can be forced to write a specific file format by setting
667 the \c{SQLITE_DEFAULT_FILE_FORMAT} define when building SQLite.
670 \section2 QIBASE for Borland InterBase
672 \section3 General Information about QIBASE
674 The Qt InterBase plugin makes it possible to access the InterBase and
675 Firebird databases. InterBase can either be used as a client/server or
676 without a server in which case it operates on local files. The
677 database file must exist before a connection can be established. Firebird
678 must be used with a server configuration.
680 Note that InterBase requires you to specify the full path to the
681 database file, no matter whether it is stored locally or on another
684 \snippet doc/src/snippets/code/doc_src_sql-driver.cpp 24
686 You need the InterBase/Firebird development headers and libraries
687 to build this plugin.
689 Due to license incompatibilities with the GPL, users of the Qt Open Source
690 Edition are not allowed to link this plugin to the commercial editions of
691 InterBase. Please use Firebird or the free edition of InterBase.
693 \section3 QIBASE Unicode Support and Text Encoding
695 By default the driver connects to the database using UNICODE_FSS. This can
696 be overridden by setting the ISC_DPB_LC_CTYPE parameter with
697 QSqlDatabase::setConnectOptions() before opening the connection.
699 \snippet doc/src/snippets/code/doc_src_sql-driver.cpp 25
701 If Qt doesn't support the given text encoding the driver will issue a
702 warning message and connect to the database using UNICODE_FSS.
704 Note that if the text encoding set when connecting to the database is
705 not the same as in the database, problems with transliteration might arise.
707 \section3 QIBASE Stored procedures
709 InterBase/Firebird return OUT values as result set, so when calling stored
710 procedure, only IN values need to be bound via QSqlQuery::bindValue(). The
711 RETURN/OUT values can be retrieved via QSqlQuery::value(). Example:
713 \snippet doc/src/snippets/code/doc_src_sql-driver.cpp 26
715 \section3 How to Build the QIBASE Plugin on Unix and Mac OS X
717 The following assumes InterBase or Firebird is installed in
720 If you are using InterBase:
722 \snippet doc/src/snippets/code/doc_src_sql-driver.qdoc 27
724 If you are using Firebird, the Firebird library has to be set explicitly:
726 \snippet doc/src/snippets/code/doc_src_sql-driver.qdoc 28
728 \section3 How to Build the QIBASE Plugin on Windows
730 The following assumes InterBase or Firebird is installed in
733 If you are using InterBase:
735 \snippet doc/src/snippets/code/doc_src_sql-driver.qdoc 29
737 If you are using Firebird, the Firebird library has to be set explicitely:
739 \snippet doc/src/snippets/code/doc_src_sql-driver.qdoc 30
741 If you are not using a Microsoft compiler, replace \c nmake
742 with \c make in the line above.
744 Note that \c{C:\interbase\bin} must be in the \c PATH.
746 \bold{Note:} This database plugin is not supported for Windows CE.
748 \target troubleshooting
749 \section1 Troubleshooting
751 You should always use client libraries that have been compiled with
752 the same compiler as you are using for your project. If you cannot get
753 a source distibution to compile the client libraries yourself, you
754 must make sure that the pre-compiled library is compatible with
755 your compiler, otherwise you will get a lot of "undefined symbols"
756 errors. Some compilers have tools to convert libraries, e.g. Borland
757 ships the tool \c{COFF2OMF.EXE} to convert libraries that have been
758 generated with Microsoft Visual C++.
760 If the compilation of a plugin succeeds but it cannot be loaded,
761 make sure that the following requirements are met:
764 \i Ensure that you are using a shared Qt library; you cannot use the
765 plugins with a static build.
766 \i Ensure that the plugin is in the correct directory. You can use
767 QApplication::libraryPaths() to determine where Qt looks for plugins.
768 \i Ensure that the client libraries of the DBMS are available on the
769 system. On Unix, run the command \c{ldd} and pass the name of the
770 plugin as parameter, for example \c{ldd libqsqlmysql.so}. You will
771 get a warning if any of the client libraries couldn't be found.
772 On Windows, you can use Visual Studio's dependency walker.
773 \i Compile Qt with \c{QT_DEBUG_COMPONENT} defined to get very verbose
774 debug output when loading plugins.
777 Make sure you have followed the guide to \l{Deploying Plugins}.
778 If you experience plugin load problems and see output like this:
780 \snippet doc/src/snippets/code/doc_src_sql-driver.cpp 31
782 the problem is usually that the plugin had the wrong \l{Deploying
783 Plugins#The Build Key}{build key}. This might require removing an
784 entry from the \l{Deploying Plugins#The Plugin Cache} {plugin cache}.
787 \section1 How to Write Your Own Database Driver
789 QSqlDatabase is responsible for loading and managing database driver
790 plugins. When a database is added (see QSqlDatabase::addDatabase()),
791 the appropriate driver plugin is loaded (using QSqlDriverPlugin).
792 QSqlDatabase relies on the driver plugin to provide interfaces for
793 QSqlDriver and QSqlResult.
795 QSqlDriver is an abstract base class which defines the functionality
796 of a SQL database driver. This includes functions such as
797 QSqlDriver::open() and QSqlDriver::close(). QSqlDriver is responsible
798 for connecting to a database, establish the proper environment, etc.
799 In addition, QSqlDriver can create QSqlQuery objects appropriate for
800 the particular database API. QSqlDatabase forwards many of its
801 function calls directly to QSqlDriver which provides the concrete
804 QSqlResult is an abstract base class which defines the functionality
805 of a SQL database query. This includes statements such as \c{SELECT},
806 \c{UPDATE}, and \c{ALTER} \c{TABLE}. QSqlResult contains functions
807 such as QSqlResult::next() and QSqlResult::value(). QSqlResult is
808 responsible for sending queries to the database, returning result
809 data, etc. QSqlQuery forwards many of its function calls directly to
810 QSqlResult which provides the concrete implementation.
812 QSqlDriver and QSqlResult are closely connected. When implementing a
813 Qt SQL driver, both of these classes must to be subclassed and the
814 abstract virtual methods in each class must be implemented.
816 To implement a Qt SQL driver as a plugin (so that it is
817 recognized and loaded by the Qt library at runtime), the driver
818 must use the Q_EXPORT_PLUGIN2() macro. Read \l{How to Create Qt
819 Plugins} for more information on this. You can also check out how
820 this is done in the SQL plugins that are provided with Qt in
821 \c{QTDIR/src/plugins/sqldrivers} and \c{QTDIR/src/sql/drivers}.
823 The following code can be used as a skeleton for a SQL driver:
825 \snippet doc/src/snippets/sqldatabase/sqldatabase.cpp 47
827 \snippet doc/src/snippets/sqldatabase/sqldatabase.cpp 48