| 1 | <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN">
|
|---|
| 2 | <!-- /home/espenr/tmp/qt-3.3.8-espenr-2499/qt-x11-free-3.3.8/doc/sql-driver.doc:35 -->
|
|---|
| 3 | <html>
|
|---|
| 4 | <head>
|
|---|
| 5 | <meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
|
|---|
| 6 | <title>SQL Module - Drivers</title>
|
|---|
| 7 | <style type="text/css"><!--
|
|---|
| 8 | fn { margin-left: 1cm; text-indent: -1cm; }
|
|---|
| 9 | a:link { color: #004faf; text-decoration: none }
|
|---|
| 10 | a:visited { color: #672967; text-decoration: none }
|
|---|
| 11 | body { background: #ffffff; color: black; }
|
|---|
| 12 | --></style>
|
|---|
| 13 | </head>
|
|---|
| 14 | <body>
|
|---|
| 15 |
|
|---|
| 16 | <table border="0" cellpadding="0" cellspacing="0" width="100%">
|
|---|
| 17 | <tr bgcolor="#E5E5E5">
|
|---|
| 18 | <td valign=center>
|
|---|
| 19 | <a href="index.html">
|
|---|
| 20 | <font color="#004faf">Home</font></a>
|
|---|
| 21 | | <a href="classes.html">
|
|---|
| 22 | <font color="#004faf">All Classes</font></a>
|
|---|
| 23 | | <a href="mainclasses.html">
|
|---|
| 24 | <font color="#004faf">Main Classes</font></a>
|
|---|
| 25 | | <a href="annotated.html">
|
|---|
| 26 | <font color="#004faf">Annotated</font></a>
|
|---|
| 27 | | <a href="groups.html">
|
|---|
| 28 | <font color="#004faf">Grouped Classes</font></a>
|
|---|
| 29 | | <a href="functions.html">
|
|---|
| 30 | <font color="#004faf">Functions</font></a>
|
|---|
| 31 | </td>
|
|---|
| 32 | <td align="right" valign="center"><img src="logo32.png" align="right" width="64" height="32" border="0"></td></tr></table><h1 align=center>SQL Module - Drivers</h1>
|
|---|
| 33 |
|
|---|
| 34 |
|
|---|
| 35 | <p> <ul>
|
|---|
| 36 | <li> <a href="#Introduction">Introduction</a>
|
|---|
| 37 | <li> <a href="#building">Building the drivers using configure</a>
|
|---|
| 38 | <li> <a href="#buildingmanually">Building the plugins manually</a>
|
|---|
| 39 | <ul>
|
|---|
| 40 | <li> <a href="#QDB2">QDB2</a> - IBM DB2 Driver (v7.1 and higher)
|
|---|
| 41 | <li> <a href="#QIBASE">QIBASE</a> - Borland Interbase Driver
|
|---|
| 42 | <li> <a href="#QMYSQL3">QMYSQL3</a> - MySQL Driver
|
|---|
| 43 | <li> <a href="#QOCI8">QOCI8</a> - Oracle Call Interface Driver, version 8 and 9
|
|---|
| 44 | <li> <a href="#QODBC3">QODBC3</a> - Open Database Connectivity Driver
|
|---|
| 45 | <li> <a href="#QPSQL7">QPSQL7</a> - PostgreSQL v6.x and v7.x Driver
|
|---|
| 46 | <li> <a href="#QSQLITE">QSQLITE</a> - SQLite Driver
|
|---|
| 47 | <li> <a href="#QTDS7">QTDS7</a> - Sybase Adaptive Server
|
|---|
| 48 | </ul>
|
|---|
| 49 | <li> <a href="#troubleshooting">Troubleshooting</a>
|
|---|
| 50 | <li> <a href="#development">How to write your own database driver</a>
|
|---|
| 51 | </ul>
|
|---|
| 52 | <p> <a name="Introduction"></a>
|
|---|
| 53 | <h2> Introduction
|
|---|
| 54 | </h2>
|
|---|
| 55 | <a name="1"></a><p> The <a href="sql.html">SQL Module</a> uses driver <a href="plugins-howto.html">plugins</a> in order to communicate with
|
|---|
| 56 | different database APIs. Since the SQL Module API is
|
|---|
| 57 | database-independent, all database-specific code is contained within
|
|---|
| 58 | these drivers. Several drivers are supplied with Qt and other drivers
|
|---|
| 59 | can be added. The driver source code is supplied and can be used as a
|
|---|
| 60 | model for <a href="#development">writing your own drivers</a>.
|
|---|
| 61 | <p> <em>Note:</em> To build a driver plugin you need to have the appropriate
|
|---|
| 62 | client library for your Database Management System (DBMS). This provides
|
|---|
| 63 | access to the API exposed by the DBMS, and is typically shipped with it.
|
|---|
| 64 | Most installation programs also allow you to install "development
|
|---|
| 65 | libraries", and these are what you need. These libraries are responsible
|
|---|
| 66 | for the low-level communication with the DBMS.
|
|---|
| 67 | <p> The drivers shipped with Qt are:
|
|---|
| 68 | <ul>
|
|---|
| 69 | <li> <a href="#QDB2">QDB2</a> - IBM DB2 Driver (v7.1 and higher)
|
|---|
| 70 | <li> <a href="#QIBASE">QIBASE</a> - Borland Interbase Driver
|
|---|
| 71 | <li> <a href="#QMYSQL3">QMYSQL3</a> - MySQL Driver
|
|---|
| 72 | <li> <a href="#QOCI8">QOCI8</a> - Oracle Call Interface Driver, version 8, 9 and 10
|
|---|
| 73 | <li> <a href="#QODBC3">QODBC3</a> - Open Database Connectivity Driver
|
|---|
| 74 | <li> <a href="#QPSQL7">QPSQL7</a> - PostgreSQL v6.x and v7.x Driver
|
|---|
| 75 | <li> <a href="#QSQLITE">QSQLITE</a> - SQLite Driver
|
|---|
| 76 | <li> <a href="#QTDS7">QTDS7</a> - Sybase Adaptive Server
|
|---|
| 77 | </ul>
|
|---|
| 78 | <p> Note that not all of the plugins are shipped with the Qt Open Source Edition
|
|---|
| 79 | due to license incompatibilities with the GPL.
|
|---|
| 80 | <p> <a name="building"></a>
|
|---|
| 81 | <h2> Building the drivers using configure
|
|---|
| 82 | </h2>
|
|---|
| 83 | <a name="2"></a><p> The Qt configure script automatically detects the available client
|
|---|
| 84 | libraries on your machine. Run "configure -help" to see what drivers
|
|---|
| 85 | can be built. You should get an output similar to this:
|
|---|
| 86 | <p> <pre>
|
|---|
| 87 | Possible values for <driver>: [ mysql oci odbc psql tds ]
|
|---|
| 88 | Auto-Detected on this system: [ mysql psql ]
|
|---|
| 89 | </pre>
|
|---|
| 90 |
|
|---|
| 91 | <p> Note that on Windows, the configure script doesn't do any
|
|---|
| 92 | auto-detection.
|
|---|
| 93 | <p> The configure script cannot detect the neccessary libraries and include
|
|---|
| 94 | files if they are not in the standard paths, so it may be necessary to
|
|---|
| 95 | specify these paths using the "-I" and "-L" switches. For example, if
|
|---|
| 96 | your MySQL include files are installed in <tt>/usr/local/mysql</tt> (or in
|
|---|
| 97 | <tt>C:\mysql\include</tt>
|
|---|
| 98 |
|
|---|
| 99 | configure: <tt>-I/usr/local/mysql</tt> (or <tt>-I C:\mysql\include</tt>
|
|---|
| 100 |
|
|---|
| 101 | Windows).
|
|---|
| 102 | <p> On Windows the -I parameter doesn't accept spaces in
|
|---|
| 103 | filenames, so use the 8.3 name instead, i.e. use <tt>C:\progra~1\mysql</tt>
|
|---|
| 104 | instead of <tt>C:\program files\mysql</tt>.
|
|---|
| 105 | <p> Use the <tt>-qt-sql-<driver></tt> parameter to build the database driver
|
|---|
| 106 | statically into your Qt library or <tt>-plugin-sql-<driver></tt> to build
|
|---|
| 107 | the driver as a plugin. Look at the sections that follow for
|
|---|
| 108 | additional information about required libraries.
|
|---|
| 109 | <p> <a name="buildingmanually"></a>
|
|---|
| 110 | <h2> Building the plugins manually
|
|---|
| 111 | </h2>
|
|---|
| 112 | <a name="3"></a><p> <a name="QMYSQL3"></a>
|
|---|
| 113 | <h3> QMYSQL3 - MySQL 3.x and MySQL 4.x
|
|---|
| 114 | </h3>
|
|---|
| 115 | <a name="3-1"></a><p> <!-- index QMYSQL3 --><a name="QMYSQL3"></a>
|
|---|
| 116 | <p> <h4> General information
|
|---|
| 117 | </h4>
|
|---|
| 118 | <a name="3-1-1"></a><p> MySQL 3.x doesn't support SQL transactions by default. There are some
|
|---|
| 119 | backends which offer this functionality. Recent versions of the MySQL
|
|---|
| 120 | client libraries (>3.23.34) allow you to use transactions on those
|
|---|
| 121 | modified servers.
|
|---|
| 122 | <p> If you have a recent client library and connect to a
|
|---|
| 123 | transaction-enabled MySQL server, a call to the
|
|---|
| 124 | <a href="qsqldriver.html#hasFeature">QSqlDriver::hasFeature</a>( QSqlDriver::Transactions ) function returns
|
|---|
| 125 | TRUE and SQL transactions can be used.
|
|---|
| 126 | <p> If the plugin is compiled against MySQL 4.x client libraries,
|
|---|
| 127 | transactions are enabled by default.
|
|---|
| 128 | <p> You can find information about MySQL on <a href="http://www.mysql.com">http://www.mysql.com</a>
|
|---|
| 129 | <p> <h4> How to build the plugin on Unix/Linux
|
|---|
| 130 | </h4>
|
|---|
| 131 | <a name="3-1-2"></a><p> You need the MySQL header files and as well as the shared library
|
|---|
| 132 | <tt>libmysqlclient.so</tt>. Depending on your Linux distribution you need to
|
|---|
| 133 | install a package which is usually called "mysql-devel".
|
|---|
| 134 | <p> Tell <a href="qmake-manual.html">qmake</a> where to find the MySQL
|
|---|
| 135 | header files and shared libraries (here it is assumed that MySQL is
|
|---|
| 136 | installed in <tt>/usr/local</tt>) and run <tt>make</tt>:
|
|---|
| 137 | <p> <pre>
|
|---|
| 138 | cd $QTDIR/plugins/src/sqldrivers/mysql
|
|---|
| 139 | qmake -o Makefile "INCLUDEPATH+=/usr/local/include" "LIBS+=-L/usr/local/lib -lmysqlclient" mysql.pro
|
|---|
| 140 | make
|
|---|
| 141 | </pre>
|
|---|
| 142 |
|
|---|
| 143 | <p> <h4> How to build the plugin on Windows
|
|---|
| 144 | </h4>
|
|---|
| 145 | <a name="3-1-3"></a><p> You need to get the MySQL installation files. Run SETUP.EXE and
|
|---|
| 146 | choose "Custom Install". Install the "Libs & Include Files" Module.
|
|---|
| 147 | Build the plugin as follows (here it is assumed that MySQL is
|
|---|
| 148 | installed in <tt>C:\MYSQL</tt>):
|
|---|
| 149 | <p> <pre>
|
|---|
| 150 | cd %QTDIR%\plugins\src\sqldrivers\mysql
|
|---|
| 151 | qmake -o Makefile "INCLUDEPATH+=C:\MYSQL\INCLUDE" "LIBS+=C:\MYSQL\LIB\OPT\LIBMYSQL.LIB" mysql.pro
|
|---|
| 152 | nmake
|
|---|
| 153 | </pre>
|
|---|
| 154 |
|
|---|
| 155 | <p> If you are not using a Microsoft compiler, replace <tt>nmake</tt> with <tt>make</tt> in the statement above.
|
|---|
| 156 | <p> <a name="QOCI8"></a>
|
|---|
| 157 | <h3> QOCI8 - Oracle Call Interface (OCI)
|
|---|
| 158 | </h3>
|
|---|
| 159 | <a name="3-2"></a><p> <!-- index QOCI8 --><a name="QOCI8"></a>
|
|---|
| 160 | <p> <h4> General information
|
|---|
| 161 | </h4>
|
|---|
| 162 | <a name="3-2-1"></a><p> The Qt OCI plugin supports both Oracle 8 and Oracle 9. After
|
|---|
| 163 | connecting to the Oracle server, the plugin will auto-detect the
|
|---|
| 164 | database version and enable features accordingly.
|
|---|
| 165 | <p> <h4> Unicode support
|
|---|
| 166 | </h4>
|
|---|
| 167 | <a name="3-2-2"></a><p> If the Oracle server supports Unicode, the OCI plugin will use UTF-8
|
|---|
| 168 | encoding to communicate with the server.
|
|---|
| 169 | <p> <h4> BLOB/LOB support
|
|---|
| 170 | </h4>
|
|---|
| 171 | <a name="3-2-3"></a><p> Binary Large Objects (BLOBs) can be read and written, but be aware
|
|---|
| 172 | that this process may require a lot of memory.
|
|---|
| 173 | <p> Note that Oracle 9 doesn't support scrollable result sets with LOB
|
|---|
| 174 | columns, you have to use a forward only query to select LOB fields
|
|---|
| 175 | (see <a href="qsqlquery.html#setForwardOnly">QSqlQuery::setForwardOnly</a>()).
|
|---|
| 176 | <p> Inserting BLOBs should be done using either a prepared query where the
|
|---|
| 177 | BLOBs are bound to placeholders, or <a href="qsqlcursor.html">QSqlCursor</a> which uses a prepared
|
|---|
| 178 | query to do this internally (see $QTDIR/examples/sql/blob).
|
|---|
| 179 | <p> <h4> Know problems
|
|---|
| 180 | </h4>
|
|---|
| 181 | <a name="3-2-4"></a><p> When a query is in forward only mode a call to <a href="qsqlquery.html#last">QSqlQuery::last</a>() will
|
|---|
| 182 | position the query on the last record and return TRUE, but subsequent
|
|---|
| 183 | calls to <a href="qsqlquery.html#value">QSqlQuery::value</a>() will only return NULLs.
|
|---|
| 184 | <p> <h4> How to build the plugin on Unix/Linux
|
|---|
| 185 | </h4>
|
|---|
| 186 | <a name="3-2-5"></a><p> All files required to build driver should ship with the standard Oracle
|
|---|
| 187 | Client install.
|
|---|
| 188 | <p> Oracle library files required to build driver:
|
|---|
| 189 | <p> <ul>
|
|---|
| 190 | <li> <tt>libclntsh.so</tt> (all versions)
|
|---|
| 191 | <li> <tt>libwtc8.so</tt> (only Oracle 8) or <tt>libwtc9.so</tt> (only Oracle 9)
|
|---|
| 192 | </ul>
|
|---|
| 193 | <p> Tell <tt>qmake</tt> where to find the Oracle header files and shared
|
|---|
| 194 | libraries (it is assumed that the variable <tt>$ORACLE_HOME</tt> points to
|
|---|
| 195 | the directory where Oracle is installed) and run make:
|
|---|
| 196 | <p> If you are using Oracle 8:
|
|---|
| 197 | <pre>
|
|---|
| 198 | cd $QTDIR/plugins/src/sqldrivers/oci
|
|---|
| 199 | qmake -o Makefile "INCLUDEPATH+=$ORACLE_HOME/rdbms/public $ORACLE_HOME/rdbms/demo" "LIBS+=-L$ORACLE_HOME/lib -lclntsh -lwtc8" oci.pro
|
|---|
| 200 | make
|
|---|
| 201 | </pre>
|
|---|
| 202 |
|
|---|
| 203 | <p> For Oracle version 9:
|
|---|
| 204 | <pre>
|
|---|
| 205 | cd $QTDIR/plugins/src/sqldrivers/oci
|
|---|
| 206 | qmake -o Makefile "INCLUDEPATH+=$ORACLE_HOME/rdbms/public $ORACLE_HOME/rdbms/demo" "LIBS+=-L$ORACLE_HOME/lib -lclntsh -lwtc9" oci.pro
|
|---|
| 207 | make
|
|---|
| 208 | </pre>
|
|---|
| 209 |
|
|---|
| 210 | <p> For Oracle version 10:
|
|---|
| 211 | <pre>
|
|---|
| 212 | cd $QTDIR/plugins/src/sqldrivers/oci
|
|---|
| 213 | qmake -o Makefile "INCLUDEPATH+=$ORACLE_HOME/rdbms/public $ORACLE_HOME/rdbms/demo" "LIBS+=-L$ORACLE_HOME/lib -lclntsh" oci.pro
|
|---|
| 214 | make
|
|---|
| 215 | </pre>
|
|---|
| 216 |
|
|---|
| 217 | <p> Note that some versions of the OCI client libraries contain a bug
|
|---|
| 218 | that makes programs linked to these libraries segfault on exit. This
|
|---|
| 219 | only happens if the QOCI8 driver is compiled as a plugin. To work
|
|---|
| 220 | around this problem, either compile the driver into the Qt libray
|
|---|
| 221 | itself, or configure Qt with the option '-DQT_NO_LIBRARY_UNLOAD'.
|
|---|
| 222 | For Oracle 9, it is possible to link to the static OCI library by
|
|---|
| 223 | using "LIBS+=$ORACLE_HOME/lib/libclntst9.a".
|
|---|
| 224 | <p> <h4> How to build the plugin on Windows
|
|---|
| 225 | </h4>
|
|---|
| 226 | <a name="3-2-6"></a><p> Choosing the option "Programmer" in the Oracle Client Installer from
|
|---|
| 227 | the Oracle Client Installation CD is sufficient to build the plugin.
|
|---|
| 228 | <p> Build the plugin as follows (here it is assumed that Oracle Client is
|
|---|
| 229 | installed in <tt>C:\oracle</tt>):
|
|---|
| 230 | <p> <pre>
|
|---|
| 231 | set INCLUDE=%INCLUDE%;c:\oracle\oci\include
|
|---|
| 232 | set LIB=%LIB%;c:\oracle\oci\lib\msvc
|
|---|
| 233 | cd %QTDIR%\plugins\src\sqldrivers\oci
|
|---|
| 234 | qmake -o Makefile oci.pro
|
|---|
| 235 | nmake
|
|---|
| 236 | </pre>
|
|---|
| 237 |
|
|---|
| 238 | <p> When you run your application you will also need to add the <tt>oci.dll</tt>
|
|---|
| 239 | path to your <tt>PATH</tt> environment variable:
|
|---|
| 240 | <p> <pre>
|
|---|
| 241 | set PATH=%PATH%;c:\oracle\bin
|
|---|
| 242 | </pre>
|
|---|
| 243 |
|
|---|
| 244 | <p> If you are not using a Microsoft compiler, replace <tt>nmake</tt> with <tt>make</tt> in the statement above.
|
|---|
| 245 | <p> <a name="QODBC3"></a>
|
|---|
| 246 | <h3> QODBC3 - Open Database Connectivity (ODBC)
|
|---|
| 247 | </h3>
|
|---|
| 248 | <a name="3-3"></a><p> <!-- index QODBC3 --><a name="QODBC3"></a>
|
|---|
| 249 | <p> <h4> General information
|
|---|
| 250 | </h4>
|
|---|
| 251 | <a name="3-3-1"></a><p> ODBC is a general interface that allows you to connect to multiple
|
|---|
| 252 | DBMS using a common interface. The QODBC3 driver allows you to connect
|
|---|
| 253 | to an ODBC driver manager and access the available data sources. Note
|
|---|
| 254 | that you also need to install and configure ODBC drivers for the ODBC
|
|---|
| 255 | driver manager that is installed on your system. The QODBC3 plugin
|
|---|
| 256 | then allows you to use these data sources in your Qt project.
|
|---|
| 257 | <p> On Windows systems after 95 an ODBC driver manager should be installed
|
|---|
| 258 | by default, for Unix systems there are some implementations which must
|
|---|
| 259 | be installed first. Note that every client that uses your application
|
|---|
| 260 | is required to have an ODBC driver manager installed, otherwise the
|
|---|
| 261 | QODBC3 plugin will not work.
|
|---|
| 262 | <p> Be aware that when connecting to an ODBC datasource you must pass in
|
|---|
| 263 | the name of the ODBC datasource to the <a href="qsqldatabase.html#setDatabaseName">QSqlDatabase::setDatabaseName</a>()
|
|---|
| 264 | function: not the actual database name.
|
|---|
| 265 | <p> The QODBC3 Plugin needs an ODBC compliant driver manager version 2.0 or
|
|---|
| 266 | later to work. Some ODBC drivers claim to be version 2.0 compliant,
|
|---|
| 267 | but do not offer all the necessary functionality. The QODBC3 plugin
|
|---|
| 268 | therefore checks whether the data source can be used after a
|
|---|
| 269 | connection has been established and refuses to work if the check
|
|---|
| 270 | fails. If you don't like this behaviour, you can remove the <tt>#define ODBC_CHECK_DRIVER</tt> line from the file <tt>qsql_odbc.cpp</tt>. Do this at
|
|---|
| 271 | your own risk!
|
|---|
| 272 | <p> If you experience very slow access of the ODBC datasource, make sure
|
|---|
| 273 | that ODBC call tracing is turned off in the ODBC datasource manager.
|
|---|
| 274 | <p> <h4> Unicode support
|
|---|
| 275 | </h4>
|
|---|
| 276 | <a name="3-3-2"></a><p> The QODBC3 Plugin will use the Unicode API if UNICODE is defined. On
|
|---|
| 277 | Windows NT based systems, this is the default. Note that the ODBC
|
|---|
| 278 | driver and the DBMS have to support Unicode as well.
|
|---|
| 279 | <p> For the Oracle 9 ODBC driver (Windows), it is neccessary to check
|
|---|
| 280 | "SQL_WCHAR support" in the ODBC driver manager otherwise Oracle
|
|---|
| 281 | will convert all Unicode strings to local 8 bit.
|
|---|
| 282 | <p> <h4> How to build the plugin on Unix/Linux
|
|---|
| 283 | </h4>
|
|---|
| 284 | <a name="3-3-3"></a><p> It is recommended that you use unixODBC. You can find the latest
|
|---|
| 285 | version and ODBC drivers at <a href="http://www.unixodbc.org">http://www.unixodbc.org</a>.
|
|---|
| 286 | You need the unixODBC header files and shared libraries.
|
|---|
| 287 | <p> Tell <tt>qmake</tt> where to find the unixODBC header files and shared
|
|---|
| 288 | libraries (here it is assumed that unixODBC is installed in
|
|---|
| 289 | <tt>/usr/local/unixODBC</tt>) and run <tt>make</tt>:
|
|---|
| 290 | <p> <pre>
|
|---|
| 291 | cd $QTDIR/plugins/src/sqldrivers/odbc
|
|---|
| 292 | qmake "INCLUDEPATH+=/usr/local/unixODBC/include" "LIBS+=-L/usr/local/unixODBC/lib -lodbc"
|
|---|
| 293 | make
|
|---|
| 294 | </pre>
|
|---|
| 295 |
|
|---|
| 296 | <p> <h4> How to build the plugin on Windows
|
|---|
| 297 | </h4>
|
|---|
| 298 | <a name="3-3-4"></a><p> The ODBC header and include files should already be installed in the
|
|---|
| 299 | right directories. You just have to build the plugin as follows:
|
|---|
| 300 | <p> <pre>
|
|---|
| 301 | cd %QTDIR%\plugins\src\sqldrivers\odbc
|
|---|
| 302 | qmake -o Makefile odbc.pro
|
|---|
| 303 | nmake
|
|---|
| 304 | </pre>
|
|---|
| 305 |
|
|---|
| 306 | <p> If you are not using a Microsoft compiler, replace <tt>nmake</tt> with <tt>make</tt> in the statement above.
|
|---|
| 307 | <p> <a name="QPSQL7"></a>
|
|---|
| 308 | <h3> QPSQL7 - PostgreSQL version 6 and 7
|
|---|
| 309 | </h3>
|
|---|
| 310 | <a name="3-4"></a><p> <!-- index QPSQL7 --><a name="QPSQL7"></a>
|
|---|
| 311 | <p> <h4> General information
|
|---|
| 312 | </h4>
|
|---|
| 313 | <a name="3-4-1"></a><p> The QPSQL7 driver supports both version 6 and 7 of PostgreSQL. We
|
|---|
| 314 | recommend compiling the plugin with a recent version of the PostgreSQL
|
|---|
| 315 | client library (libpq) because it is more stable and still backwards
|
|---|
| 316 | compatible.
|
|---|
| 317 | <p> If you want to link the plugin against the libpq shipped with version
|
|---|
| 318 | 6 we recommend a recent version like PostgreSQL 6.5.3, otherwise a
|
|---|
| 319 | connection to a version 7 server may not work.
|
|---|
| 320 | <p> The driver auto-detects the server version of PostgreSQL after a
|
|---|
| 321 | connection was successful. If the server is too old or the version
|
|---|
| 322 | information cannot be determined a warning is issued.
|
|---|
| 323 | <p> For more information about PostgreSQL visit <a href="http://www.postgresql.org">http://www.postgresql.org</a>.
|
|---|
| 324 | <p> <h4> Unicode support
|
|---|
| 325 | </h4>
|
|---|
| 326 | <a name="3-4-2"></a><p> The QPSQL7 driver automatically detects whether the PostgreSQL
|
|---|
| 327 | database you are connecting to supports Unicode or not. Unicode is
|
|---|
| 328 | automatically used if the server supports it. Note that the driver
|
|---|
| 329 | only supports the UTF-8 encoding. If your database uses any other
|
|---|
| 330 | encoding, the server must be compiled with Unicode conversion
|
|---|
| 331 | support.
|
|---|
| 332 | <p> Unicode support was introduced in PostgreSQL version 7.1 and it will
|
|---|
| 333 | only work if both the server and the client library have been compiled
|
|---|
| 334 | with multibyte support. More information about how to set up a
|
|---|
| 335 | multibyte enabled PostgreSQL server can be found in the PostgreSQL
|
|---|
| 336 | Administrator Guide, Chapter 5.
|
|---|
| 337 | <p> <h4> BLOB support
|
|---|
| 338 | </h4>
|
|---|
| 339 | <a name="3-4-3"></a><p> Binary Large Objects are supported through the <tt>BYTEA</tt> field type in
|
|---|
| 340 | PostgreSQL versions >= 7.1. Fields of type <tt>OID</tt> can be read, but not
|
|---|
| 341 | written. Use the PostgreSQL command <tt>lo_import</tt> to insert binary data
|
|---|
| 342 | into <tt>OID</tt> fields.
|
|---|
| 343 | <p> <h4> How to build the plugin on Unix/Linux
|
|---|
| 344 | </h4>
|
|---|
| 345 | <a name="3-4-4"></a><p> Just installing the pq client library and the corresponding header
|
|---|
| 346 | files is not sufficient. You have to get the PostgreSQL source
|
|---|
| 347 | distribution and run the configure script. If you've already installed
|
|---|
| 348 | a binary distribution you don't need to build it. The source
|
|---|
| 349 | distribution is needed because the QPSQL7 plugin relies on a couple of
|
|---|
| 350 | header files that are usually not a part of the binary distribution.
|
|---|
| 351 | <p> To make <tt>qmake</tt> find the PostgreSQL header files and shared
|
|---|
| 352 | libraries, run <tt>qmake</tt> the following way (assuming that the
|
|---|
| 353 | PostgreSQL sources can be found in <tt>/usr/src/psql</tt>):
|
|---|
| 354 | <p> <pre>
|
|---|
| 355 | cd $QTDIR/plugins/src/sqldrivers/psql
|
|---|
| 356 | qmake -o Makefile "INCLUDEPATH+=/usr/src/psql/src/include /usr/src/psql/src/interfaces/libpq" "LIBS+=-L/usr/lib -lpq" psql.pro
|
|---|
| 357 | make
|
|---|
| 358 | </pre>
|
|---|
| 359 |
|
|---|
| 360 | <p> <h4> How to build the plugin on Windows
|
|---|
| 361 | </h4>
|
|---|
| 362 | <a name="3-4-5"></a><p> Unpack and build the PostgreSQL source distribution as described in
|
|---|
| 363 | the PostgreSQL documentation. Assuming the PostgreSQL sources resides
|
|---|
| 364 | in <tt>C:\psql</tt>, build the plugin as follows:
|
|---|
| 365 | <p> <pre>
|
|---|
| 366 | cd %QTDIR%\plugins\src\sqldrivers\psql
|
|---|
| 367 | qmake -o Makefile "INCLUDEPATH+=C:\psql\src\include C:\psql\src\interfaces\libpq" psql.pro
|
|---|
| 368 | nmake
|
|---|
| 369 | </pre>
|
|---|
| 370 |
|
|---|
| 371 | <p> Remember to add the path to the <tt>libpq.dll</tt> library to your PATH
|
|---|
| 372 | environment variable so that Windows can find it. In this case that
|
|---|
| 373 | would be <tt>C:\psql\src\interfaces\libpq\Release</tt>. If you are not using a
|
|---|
| 374 | Microsoft compiler, replace <tt>nmake</tt> with <tt>make</tt> in the statement
|
|---|
| 375 | above.
|
|---|
| 376 | <p> <a name="QTDS7"></a>
|
|---|
| 377 | <h3> QTDS7 - Sybase Adaptive Server
|
|---|
| 378 | </h3>
|
|---|
| 379 | <a name="3-5"></a><p> <!-- index QTDS7 --><a name="QTDS7"></a>
|
|---|
| 380 | <p> <h4> How to build the plugin on Unix/Linux
|
|---|
| 381 | </h4>
|
|---|
| 382 | <a name="3-5-1"></a><p> Under Unix, two libraries are available which support the TDS protocol:
|
|---|
| 383 | <p> - FreeTDS, a free implementation of the TDS protocol
|
|---|
| 384 | (<a href="http://www.freetds.org">http://www.freetds.org</a>). Note that FreeTDS is not yet stable,
|
|---|
| 385 | so some functionality may not work as expected.
|
|---|
| 386 | <p> - Sybase Open Client, available from <a href="http://www.sybase.com">http://www.sybase.com</a>.
|
|---|
| 387 | Note for Linux users: Get the Open Client RPM from
|
|---|
| 388 | <a href="http://linux.sybase.com">http://linux.sybase.com</a>.
|
|---|
| 389 | <p> Regardless of which library you use, the shared object file
|
|---|
| 390 | <tt>libsybdb.so</tt> is needed. Set the SYBASE environment variable to
|
|---|
| 391 | point to the directory where you installed the client library and
|
|---|
| 392 | execute <tt>qmake</tt>:
|
|---|
| 393 | <p> <pre>
|
|---|
| 394 | cd $QTDIR/plugins/src/sqldrivers/tds
|
|---|
| 395 | qmake -o Makefile "INCLUDEPATH=$SYBASE/include" "LIBS=-L$SYBASE/lib -lsybdb"
|
|---|
| 396 | make
|
|---|
| 397 | </pre>
|
|---|
| 398 |
|
|---|
| 399 | <p> <h4> How to build the plugin on Windows
|
|---|
| 400 | </h4>
|
|---|
| 401 | <a name="3-5-2"></a><p> You can either use the DB-Library supplied by Microsoft or the Sybase
|
|---|
| 402 | Open Client (<a href="http://www.sybase.com">http://www.sybase.com</a>). You must include <tt>NTWDBLIB.LIB</tt> to build the plugin:
|
|---|
| 403 | <p> <pre>
|
|---|
| 404 | cd %QTDIR%\plugins\src\sqldrivers\tds
|
|---|
| 405 | qmake -o Makefile "LIBS+=NTWDBLIB.LIB" tds.pro
|
|---|
| 406 | nmake
|
|---|
| 407 | </pre>
|
|---|
| 408 |
|
|---|
| 409 | <p> By default the Microsoft library is used on Windows, if you want to force
|
|---|
| 410 | the use of the Sybase Open Client, you must define
|
|---|
| 411 | <tt>Q_USE_SYBASE</tt> in <tt>%QTDIR%\src\sql\drivers\tds\qsql_tds.cpp</tt>.
|
|---|
| 412 | <p> <a name="QDB2"></a>
|
|---|
| 413 | <h3> QDB2 - IBM DB2 Driver (v7.1 or higher)
|
|---|
| 414 | </h3>
|
|---|
| 415 | <a name="3-6"></a><p> <!-- index QDB2 --><a name="QDB2"></a>
|
|---|
| 416 | <p> <h4> General information
|
|---|
| 417 | </h4>
|
|---|
| 418 | <a name="3-6-1"></a><p> The Qt DB2 plugin makes it possible to access IBM DB2 databases. It
|
|---|
| 419 | has been tested with IBM DB2 v7.1 and 7.2. You have to install the IBM
|
|---|
| 420 | DB2 development client library, which contains the header and library
|
|---|
| 421 | files necessary for compiling the QDB2 plugin.
|
|---|
| 422 | <p> The QDB2 driver supports prepared queries, reading/writing of Unicode
|
|---|
| 423 | strings and reading/writing of BLOBs.
|
|---|
| 424 | <p> We suggest using a forward-only query when calling stored procedures
|
|---|
| 425 | in DB2 (see <a href="qsqlquery.html#setForwardOnly">QSqlQuery::setForwardOnly</a>()).
|
|---|
| 426 | <p> <h4> How to build the plugin on Unix/Linux
|
|---|
| 427 | </h4>
|
|---|
| 428 | <a name="3-6-2"></a><p> <pre>
|
|---|
| 429 | cd $QTDIR/plugins/src/sqldrivers/db2
|
|---|
| 430 | qmake -o Makefile "INCLUDEPATH+=$DB2DIR/include" "LIBS+=-L$DB2DIR/lib -ldb2"
|
|---|
| 431 | make
|
|---|
| 432 | </pre>
|
|---|
| 433 |
|
|---|
| 434 | <p> <h4> How to build the plugin on Windows
|
|---|
| 435 | </h4>
|
|---|
| 436 | <a name="3-6-3"></a><p> The DB2 header and include files should already be installed in the
|
|---|
| 437 | right directories. You just have to build the plugin as follows:
|
|---|
| 438 | <p> <pre>
|
|---|
| 439 | cd %QTDIR%\plugins\src\sqldrivers\db2
|
|---|
| 440 | qmake -o Makefile "INCLUDEPATH+=<DB2 home>/sqllib/include" "LIBS+=<DB2 home>/sqllib/lib/db2cli.lib"
|
|---|
| 441 | nmake
|
|---|
| 442 | </pre>
|
|---|
| 443 |
|
|---|
| 444 | <p> If you are not using a Microsoft compiler, replace <tt>nmake</tt>
|
|---|
| 445 | with <tt>make</tt> in the statement above.
|
|---|
| 446 | <p> <a name="QSQLITE"></a>
|
|---|
| 447 | <h3> QSQLITE - SQLite Driver
|
|---|
| 448 | </h3>
|
|---|
| 449 | <a name="3-7"></a><p> <!-- index QSQLITE --><a name="QSQLITE"></a>
|
|---|
| 450 | <p> The Qt SQLite plugin makes it possible to access SQLite databases.
|
|---|
| 451 | SQLite is an in-process database, meaning that it is not necessary
|
|---|
| 452 | to have a database server. SQLite operates on a single file, which has
|
|---|
| 453 | to be set as database name when opening a connection. If the file does
|
|---|
| 454 | not exist, SQLite will try to create it. SQLite also supports in-memory
|
|---|
| 455 | databases, simply pass ":memory:" as the database name.
|
|---|
| 456 | <p> SQLite has some restrictions regarding multiple users and
|
|---|
| 457 | multiple transactions. If you try to read/write on a resource from different
|
|---|
| 458 | transactions, your application might freeze until one transaction commits
|
|---|
| 459 | or rolls back.
|
|---|
| 460 | <p> SQLite has no support for types, every value is treated as character data.
|
|---|
| 461 | BLOBs are therefore not supported.
|
|---|
| 462 | <p> You can find information about SQLite on <a href="http://www.sqlite.org">http://www.sqlite.org</a>.
|
|---|
| 463 | <p> SQLite is shipped as third party library within Qt. It can be built by
|
|---|
| 464 | passing the following parameters to the configure script:
|
|---|
| 465 | <tt>-plugin-sql-sqlite</tt> (as plugin) or <tt>-qt-sql-sqlite</tt> (linked
|
|---|
| 466 | directly into the Qt library).
|
|---|
| 467 | <p> If you don't want to use the SQLite library shipped with Qt, you can
|
|---|
| 468 | build it manually (replace <tt>$SQLITE</tt> by the directory where SQLite
|
|---|
| 469 | resides):
|
|---|
| 470 | <p> <pre>
|
|---|
| 471 | cd $QTDIR/plugins/src/sqldrivers/sqlite
|
|---|
| 472 | qmake -o Makefile "INCLUDEPATH+=$SQLITE/include" "LIBS+=-L$SQLITE/lib -lsqlite"
|
|---|
| 473 | make
|
|---|
| 474 | </pre>
|
|---|
| 475 |
|
|---|
| 476 | <p> <a name="QIBASE"></a>
|
|---|
| 477 | <h3> QIBASE - Borland Interbase Driver
|
|---|
| 478 | </h3>
|
|---|
| 479 | <a name="3-8"></a><p> <!-- index QIBASE --><a name="QIBASE"></a>
|
|---|
| 480 | <p> <h4> General information
|
|---|
| 481 | </h4>
|
|---|
| 482 | <a name="3-8-1"></a><p> The Qt Interbase plugin makes it possible to access the Interbase and
|
|---|
| 483 | Firebird databases. Interbase can either be used as a client/server or
|
|---|
| 484 | without a server operating on local files. The database file must
|
|---|
| 485 | exist before a connection can be established.
|
|---|
| 486 | <p> Note that Interbase requires you to specify the full path to the
|
|---|
| 487 | database file, no matter whether it is stored locally or on another
|
|---|
| 488 | server.
|
|---|
| 489 | <p> <pre>
|
|---|
| 490 | myDatabase->setHostName("MyServer");
|
|---|
| 491 | myDatabase->setDatabaseName("C:\\test.gdb");
|
|---|
| 492 | </pre>
|
|---|
| 493 |
|
|---|
| 494 | <p> You need the Interbase/Firebird development headers and libraries
|
|---|
| 495 | to build this plugin.
|
|---|
| 496 | <p> Due to the GPL, users of the Qt Open Source Edition are not allowed to link
|
|---|
| 497 | this plugin to the commercial editions of Interbase. Please use Firebird
|
|---|
| 498 | or the free edition of Interbase.
|
|---|
| 499 | <p> <h4> How to build the plugin on Unix/Linux
|
|---|
| 500 | </h4>
|
|---|
| 501 | <a name="3-8-2"></a><p> The following assumes Interbase or Firebird is installed in
|
|---|
| 502 | <tt>/opt/interbase</tt>:
|
|---|
| 503 | <p> <pre>
|
|---|
| 504 | cd $QTDIR/plugins/src/sqldrivers/ibase
|
|---|
| 505 | qmake -o Makefile "INCLUDEPATH+=/opt/interbase/include" "LIBS+=-L/opt/interbase/lib" ibase.pro
|
|---|
| 506 | make
|
|---|
| 507 | </pre>
|
|---|
| 508 |
|
|---|
| 509 | <p> <h4> How to build the plugin on Windows
|
|---|
| 510 | </h4>
|
|---|
| 511 | <a name="3-8-3"></a><p> The following assumes Interbase or Firebird is installed in
|
|---|
| 512 | <tt>C:\interbase</tt>:
|
|---|
| 513 | <p> <pre>
|
|---|
| 514 | cd %QTDIR%\plugins\src\sqldrivers\ibase
|
|---|
| 515 | qmake -o Makefile "INCLUDEPATH+=C:\interbase\include" ibase.pro
|
|---|
| 516 | nmake
|
|---|
| 517 | </pre>
|
|---|
| 518 |
|
|---|
| 519 | <p> If you are not using a Microsoft compiler, replace <tt>nmake</tt>
|
|---|
| 520 | with <tt>make</tt> in the statement above.
|
|---|
| 521 | <p> Note that <tt>C:\interbase\bin</tt> must be in the PATH.
|
|---|
| 522 | <p> <a name="troubleshooting"></a>
|
|---|
| 523 | <h2> Troubleshooting
|
|---|
| 524 | </h2>
|
|---|
| 525 | <a name="4"></a><p> You should always use client libraries that have been compiled with
|
|---|
| 526 | the same compiler as you are using for your project. If you cannot get
|
|---|
| 527 | a source distibution to compile the client libraries yourself, you
|
|---|
| 528 | must make sure that the pre-compiled library is compatible with
|
|---|
| 529 | your compiler, otherwise you will get a lot of "undefined symbols"
|
|---|
| 530 | errors. Some compilers have tools to convert libraries, e.g. Borland
|
|---|
| 531 | ships the tool <tt>COFF2OMF.EXE</tt> to convert libraries that have been
|
|---|
| 532 | generated with Microsoft Visual C++.
|
|---|
| 533 | <p> If the compilation of a plugin succeeds but it cannot be loaded,
|
|---|
| 534 | make sure that the following requirements are met:
|
|---|
| 535 | <p> <ul>
|
|---|
| 536 | <li> Ensure that you are using a shared Qt library; you cannot use the
|
|---|
| 537 | plugins with a static build.
|
|---|
| 538 | <li> Ensure that the environment variable <tt>QTDIR</tt> points to the right
|
|---|
| 539 | directory. Go to the <tt>$QTDIR/plugins/sqldrivers</tt> directory and
|
|---|
| 540 | make sure that the plugin exists in that directory.
|
|---|
| 541 | <li> Ensure that the client libraries of the DBMS are available on the
|
|---|
| 542 | system. On Unix, run the command <tt>ldd</tt> and pass the name of the
|
|---|
| 543 | plugin as parameter, for example <tt>ldd libqsqlmysql.so</tt>. You will
|
|---|
| 544 | get a warning if any of the client libraries couldn't be found.
|
|---|
| 545 | On Windows, you can use the dependency walker of Visual Studio.
|
|---|
| 546 | </ul>
|
|---|
| 547 | <p> If you are experiencing problems with loading plugins, and see output
|
|---|
| 548 | like this
|
|---|
| 549 | <p> <pre>
|
|---|
| 550 | QSqlDatabase warning: QMYSQL3 driver not loaded
|
|---|
| 551 | QSqlDatabase: available drivers: QMYSQL3
|
|---|
| 552 | </pre>
|
|---|
| 553 |
|
|---|
| 554 | <p> the problem is probably that the plugin had the wrong build key. For
|
|---|
| 555 | debugging purposes, remove the corresponding entry in the
|
|---|
| 556 | $HOME/.qt/qt_plugins_(qtversion).rc file.
|
|---|
| 557 | <p> The next time you try to load this plugin, it will give you a more detailed
|
|---|
| 558 | error message.
|
|---|
| 559 | <p> <a name="development"></a>
|
|---|
| 560 | <h2> How to write your own database driver
|
|---|
| 561 | </h2>
|
|---|
| 562 | <a name="5"></a><p> <a href="qsqldatabase.html">QSqlDatabase</a> is responsible for loading and managing database driver
|
|---|
| 563 | plugins. When a database is added (see <a href="qsqldatabase.html#addDatabase">QSqlDatabase::addDatabase</a>()),
|
|---|
| 564 | the appropriate driver plugin is loaded (using <a href="qsqldriverplugin.html">QSqlDriverPlugin</a>).
|
|---|
| 565 | QSqlDatabase relies on the driver plugin to provide interfaces for
|
|---|
| 566 | <a href="qsqldriver.html">QSqlDriver</a> and <a href="qsqlresult.html">QSqlResult</a>.
|
|---|
| 567 | <p> QSqlDriver is an abstract base class which defines the functionality
|
|---|
| 568 | of a SQL database driver. This includes functions such as
|
|---|
| 569 | <a href="qsqldriver.html#open">QSqlDriver::open</a>() and <a href="qsqldriver.html#close">QSqlDriver::close</a>(). QSqlDriver is responsible
|
|---|
| 570 | for connecting to a database, establish the proper environment, etc.
|
|---|
| 571 | In addition, QSqlDriver can create <a href="qsqlquery.html">QSqlQuery</a> objects appropriate for
|
|---|
| 572 | the particular database API. QSqlDatabase forwards many of its
|
|---|
| 573 | function calls directly to QSqlDriver which provides the concrete
|
|---|
| 574 | implementation.
|
|---|
| 575 | <p> QSqlResult is an abstract base class which defines the functionality
|
|---|
| 576 | of a SQL database query. This includes statements such as <tt>SELECT</tt>,
|
|---|
| 577 | <tt>UPDATE</tt>, and <tt>ALTER TABLE</tt>. QSqlResult contains functions such as
|
|---|
| 578 | QSqlResult::next() and QSqlResult::value(). QSqlResult is responsible
|
|---|
| 579 | for sending queries to the database, returning result data, etc.
|
|---|
| 580 | QSqlQuery forwards many of its function calls directly to <a href="qsqlresult.html">QSqlResult</a>
|
|---|
| 581 | which provides the concrete implementation.
|
|---|
| 582 | <p> <a href="qsqldriver.html">QSqlDriver</a> and QSqlResult are closely connected. When implementing a
|
|---|
| 583 | Qt SQL driver, both of these classes must to be subclassed and the
|
|---|
| 584 | abstract virtual methods in each class must be implemented.
|
|---|
| 585 | <p> To implement a Qt SQL driver as a plugin (so that it is recognized and
|
|---|
| 586 | loaded by the Qt library at runtime), the driver must use the
|
|---|
| 587 | <tt>Q_EXPORT_PLUGIN</tt> macro. Read the <a href="plugins-howto.html">Qt
|
|---|
| 588 | Plugin</a> documentation for more information on this. You can
|
|---|
| 589 | also check out how this is done in the SQL plugins that is provided
|
|---|
| 590 | with Qt in <tt>QTDIR/plugins/src/sqldrivers</tt> and
|
|---|
| 591 | <tt>QTDIR/src/sql/drivers</tt>.
|
|---|
| 592 | <p> The following code can be used as a skeleton for a SQL driver:
|
|---|
| 593 | <p> <pre>
|
|---|
| 594 | class QNullResult : public <a href="qsqlresult.html">QSqlResult</a>
|
|---|
| 595 | {
|
|---|
| 596 | public:
|
|---|
| 597 | QNullResult( const <a href="qsqldriver.html">QSqlDriver</a>* d ): <a href="qsqlresult.html">QSqlResult</a>( d ) {}
|
|---|
| 598 | ~QNullResult() {}
|
|---|
| 599 | protected:
|
|---|
| 600 | <a href="qvariant.html">QVariant</a> data( int ) { return QVariant(); }
|
|---|
| 601 | bool reset ( const <a href="qstring.html">QString</a>& ) { return FALSE; }
|
|---|
| 602 | bool fetch( int ) { return FALSE; }
|
|---|
| 603 | bool fetchFirst() { return FALSE; }
|
|---|
| 604 | bool fetchLast() { return FALSE; }
|
|---|
| 605 | bool isNull( int ) { return FALSE; }
|
|---|
| 606 | <a href="qsqlrecord.html">QSqlRecord</a> record() { return QSqlRecord(); }
|
|---|
| 607 | int size() { return 0; }
|
|---|
| 608 | int numRowsAffected() { return 0; }
|
|---|
| 609 | };
|
|---|
| 610 |
|
|---|
| 611 | class QNullDriver : public <a href="qsqldriver.html">QSqlDriver</a>
|
|---|
| 612 | {
|
|---|
| 613 | public:
|
|---|
| 614 | QNullDriver(): <a href="qsqldriver.html">QSqlDriver</a>() {}
|
|---|
| 615 | ~QNullDriver() {}
|
|---|
| 616 | bool hasFeature( DriverFeature ) const { return FALSE; }
|
|---|
| 617 | bool open( const <a href="qstring.html">QString</a>&,
|
|---|
| 618 | const <a href="qstring.html">QString</a>&,
|
|---|
| 619 | const <a href="qstring.html">QString</a>&,
|
|---|
| 620 | const <a href="qstring.html">QString</a>&,
|
|---|
| 621 | int ) { return FALSE; }
|
|---|
| 622 | void close() {}
|
|---|
| 623 | <a href="qsqlquery.html">QSqlQuery</a> createQuery() const { return QSqlQuery( new QNullResult( this ) ); }
|
|---|
| 624 | };
|
|---|
| 625 | </pre>
|
|---|
| 626 |
|
|---|
| 627 | <p>
|
|---|
| 628 | <!-- eof -->
|
|---|
| 629 | <p><address><hr><div align=center>
|
|---|
| 630 | <table width=100% cellspacing=0 border=0><tr>
|
|---|
| 631 | <td>Copyright © 2007
|
|---|
| 632 | <a href="troll.html">Trolltech</a><td align=center><a href="trademarks.html">Trademarks</a>
|
|---|
| 633 | <td align=right><div align=right>Qt 3.3.8</div>
|
|---|
| 634 | </table></div></address></body>
|
|---|
| 635 | </html>
|
|---|
