diff options
| author | Casper van Donderen <casper.vandonderen@nokia.com> | 2012-04-27 15:18:27 +0200 |
|---|---|---|
| committer | Qt by Nokia <qt-info@nokia.com> | 2012-04-28 13:53:46 +0200 |
| commit | 00b961c37f82977615ab9c4d03e185229cc55154 (patch) | |
| tree | bc9012d3ac08c19f2a66b5733dd8450506742243 /src/sql | |
| parent | 82fa92b23cca834481571f0b0a5d66bc33a672e9 (diff) | |
Doc: Fix most qdoc errors in QtSql.
- Move 2 images from qtdoc.
- Add "make docs" command for qtsql
- Fix qdoc command usage errors.
Change-Id: Id2f0548d09ed8f77b2317863d443c19d1cccdd83
Reviewed-by: Lars Knoll <lars.knoll@nokia.com>
Diffstat (limited to 'src/sql')
35 files changed, 3667 insertions, 167 deletions
diff --git a/src/sql/doc/doc.pri b/src/sql/doc/doc.pri new file mode 100644 index 0000000000..2bc2e005d4 --- /dev/null +++ b/src/sql/doc/doc.pri @@ -0,0 +1,3 @@ +qtPrepareTool(QDOC, qdoc) +docs.commands += $$QDOC $$QT.sql.sources/doc/qtsql.qdocconf +QMAKE_EXTRA_TARGETS += docs diff --git a/src/sql/doc/images/foreignkeys.png b/src/sql/doc/images/foreignkeys.png Binary files differnew file mode 100644 index 0000000000..7a6a19bb43 --- /dev/null +++ b/src/sql/doc/images/foreignkeys.png diff --git a/src/sql/doc/images/insertrowinmodelview.png b/src/sql/doc/images/insertrowinmodelview.png Binary files differnew file mode 100644 index 0000000000..bddc401ad2 --- /dev/null +++ b/src/sql/doc/images/insertrowinmodelview.png diff --git a/src/sql/doc/images/noforeignkeys.png b/src/sql/doc/images/noforeignkeys.png Binary files differnew file mode 100644 index 0000000000..62a4452277 --- /dev/null +++ b/src/sql/doc/images/noforeignkeys.png diff --git a/src/sql/doc/images/qdatawidgetmapper-simple.png b/src/sql/doc/images/qdatawidgetmapper-simple.png Binary files differnew file mode 100644 index 0000000000..784a433c0b --- /dev/null +++ b/src/sql/doc/images/qdatawidgetmapper-simple.png diff --git a/src/sql/doc/images/relationaltable.png b/src/sql/doc/images/relationaltable.png Binary files differnew file mode 100644 index 0000000000..bdfd40f703 --- /dev/null +++ b/src/sql/doc/images/relationaltable.png diff --git a/src/sql/doc/qtsql.qdocconf b/src/sql/doc/qtsql.qdocconf new file mode 100644 index 0000000000..85e0cfc9f1 --- /dev/null +++ b/src/sql/doc/qtsql.qdocconf @@ -0,0 +1,92 @@ +include(../../../doc/global/qt-cpp-ignore.qdocconf) + +project = QtSql +description = Qt SQL Reference Documentation +url = http://qt-project.org/doc/qt-5.0/qtsql +version = 5.0.0 + +sourceencoding = UTF-8 +outputencoding = UTF-8 +naturallanguage = en_US +qhp.projects = QtSql + +qhp.QtCore.file = qtsql.qhp +qhp.Qt.namespace = org.qt-project.qtsql.500 +qhp.Qt.virtualFolder = qdoc +qhp.Qt.indexTitle = Qt SQL Reference Documentation +qhp.Qt.indexRoot = + +qhp.Qt.filterAttributes = qtsql 5.0.0 qtrefdoc +qhp.Qt.customFilters.Qt.name = QtSql 5.0.0 +qhp.Qt.customFilters.Qt.filterAttributes = qtsql 5.0.0 +qhp.Qt.subprojects = classes overviews examples +qhp.Qt.subprojects.classes.title = Classes +qhp.Qt.subprojects.classes.indexTitle = Qt SQL's Classes +qhp.Qt.subprojects.classes.selectors = class fake:headerfile +qhp.Qt.subprojects.classes.sortPages = true +qhp.Qt.subprojects.overviews.title = Overviews +qhp.Qt.subprojects.overviews.indexTitle = All Overviews and HOWTOs +qhp.Qt.subprojects.overviews.selectors = fake:page,group,module +qhp.Qt.subprojects.examples.title = Qt Core Tutorials and Examples +qhp.Qt.subprojects.examples.indexTitle = Qt Core Examples +qhp.Qt.subprojects.examples.selectors = fake:example + +dita.metadata.default.author = Qt Project +dita.metadata.default.permissions = all +dita.metadata.default.publisher = Qt Project +dita.metadata.default.copyryear = 2012 +dita.metadata.default.copyrholder = Nokia +dita.metadata.default.audience = programmer + +sources.fileextensions = "*.c++ *.cc *.cpp *.cxx *.mm *.qml *.qdoc" +headers.fileextensions = "*.ch *.h *.h++ *.hh *.hpp *.hxx" + +examples.fileextensions = "*.cpp *.h *.js *.xq *.svg *.xml *.ui *.qhp *.qhcp *.qml *.css" +examples.imageextensions = "*.png" + +outputdir = ../../../doc/qtsql +tagfile = ../../../doc/qtsql/qtsql.tags + +HTML.generatemacrefs = "true" +HTML.nobreadcrumbs = "true" + +HTML.templatedir = . + +HTML.stylesheets = ../../../doc/global/style/offline.css + +HTML.headerstyles = \ + " <link rel=\"stylesheet\" type=\"text/css\" href=\"style/offline.css\" />\n" + +HTML.endheader = \ + "</head>\n" \ + +defines = Q_QDOC \ + QT_.*_SUPPORT \ + QT_.*_LIB \ + QT_COMPAT \ + QT_KEYPAD_NAVIGATION \ + QT_NO_EGL \ + Q_WS_.* \ + Q_OS_.* \ + Q_BYTE_ORDER \ + QT_DEPRECATED \ + QT_DEPRECATED_* \ + Q_NO_USING_KEYWORD \ + __cplusplus \ + Q_COMPILER_INITIALIZER_LISTS + +versionsym = QT_VERSION_STR + +codeindent = 1 + +depends += qtcore + +headerdirs += .. + +sourcedirs += .. + +exampledirs += ../../../examples \ + ../ \ + snippets + +imagedirs += images diff --git a/src/sql/doc/snippets/code/doc_src_qtsql.cpp b/src/sql/doc/snippets/code/doc_src_qtsql.cpp new file mode 100644 index 0000000000..88b80ba710 --- /dev/null +++ b/src/sql/doc/snippets/code/doc_src_qtsql.cpp @@ -0,0 +1,43 @@ +/**************************************************************************** +** +** Copyright (C) 2012 Nokia Corporation and/or its subsidiary(-ies). +** Contact: http://www.qt-project.org/ +** +** This file is part of the documentation of the Qt Toolkit. +** +** $QT_BEGIN_LICENSE:BSD$ +** You may use this file under the terms of the BSD license as follows: +** +** "Redistribution and use in source and binary forms, with or without +** modification, are permitted provided that the following conditions are +** met: +** * Redistributions of source code must retain the above copyright +** notice, this list of conditions and the following disclaimer. +** * Redistributions in binary form must reproduce the above copyright +** notice, this list of conditions and the following disclaimer in +** the documentation and/or other materials provided with the +** distribution. +** * Neither the name of Nokia Corporation and its Subsidiary(-ies) nor +** the names of its contributors may be used to endorse or promote +** products derived from this software without specific prior written +** permission. +** +** THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS +** "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT +** LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR +** A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT +** OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +** SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT +** LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, +** DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY +** THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT +** (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE +** OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE." +** +** $QT_END_LICENSE$ +** +****************************************************************************/ + +//! [0] +#include <QtSql> +//! [0] diff --git a/src/sql/doc/snippets/code/doc_src_qtsql.pro b/src/sql/doc/snippets/code/doc_src_qtsql.pro new file mode 100644 index 0000000000..1fb8e4dea3 --- /dev/null +++ b/src/sql/doc/snippets/code/doc_src_qtsql.pro @@ -0,0 +1,3 @@ +#! [1] +QT += sql +#! [1] diff --git a/src/sql/doc/snippets/code/doc_src_sql-driver.cpp b/src/sql/doc/snippets/code/doc_src_sql-driver.cpp new file mode 100644 index 0000000000..5ad00eae3c --- /dev/null +++ b/src/sql/doc/snippets/code/doc_src_sql-driver.cpp @@ -0,0 +1,82 @@ +/**************************************************************************** +** +** Copyright (C) 2012 Nokia Corporation and/or its subsidiary(-ies). +** Contact: http://www.qt-project.org/ +** +** This file is part of the documentation of the Qt Toolkit. +** +** $QT_BEGIN_LICENSE:BSD$ +** You may use this file under the terms of the BSD license as follows: +** +** "Redistribution and use in source and binary forms, with or without +** modification, are permitted provided that the following conditions are +** met: +** * Redistributions of source code must retain the above copyright +** notice, this list of conditions and the following disclaimer. +** * Redistributions in binary form must reproduce the above copyright +** notice, this list of conditions and the following disclaimer in +** the documentation and/or other materials provided with the +** distribution. +** * Neither the name of Nokia Corporation and its Subsidiary(-ies) nor +** the names of its contributors may be used to endorse or promote +** products derived from this software without specific prior written +** permission. +** +** THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS +** "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT +** LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR +** A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT +** OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +** SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT +** LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, +** DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY +** THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT +** (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE +** OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE." +** +** $QT_END_LICENSE$ +** +****************************************************************************/ + +//! [2] +QSqlQuery q; +q.exec("call qtestproc (@outval1, @outval2)"); +q.exec("select @outval1, @outval2"); +q.next(); +qDebug() << q.value(0) << q.value(1); // outputs "42" and "43" +//! [2] + + +//! [10] +// STORED_PROC uses the return statement or returns multiple result sets +QSqlQuery query; +query.setForwardOnly(true); +query.exec("{call STORED_PROC}"); +//! [10] + + +//! [24] +db.setHostName("MyServer"); +db.setDatabaseName("C:\\test.gdb"); +//! [24] + + +//! [25] +// connect to database using the Latin-1 character set +db.setConnectOptions("ISC_DPB_LC_CTYPE=Latin1"); +db.open(); +//! [25] + + +//! [26] +QSqlQuery q; +q.exec("execute procedure my_procedure"); +q.next(); +qDebug() << q.value(0); // outputs the first RETURN/OUT value +//! [26] + + +//! [31] +QSqlDatabase: QMYSQL driver not loaded +QSqlDatabase: available drivers: QMYSQL +//! [31] diff --git a/src/sql/doc/snippets/code/doc_src_sql-driver.qdoc b/src/sql/doc/snippets/code/doc_src_sql-driver.qdoc new file mode 100644 index 0000000000..3fe8d6fbbd --- /dev/null +++ b/src/sql/doc/snippets/code/doc_src_sql-driver.qdoc @@ -0,0 +1,235 @@ +/**************************************************************************** +** +** Copyright (C) 2012 Nokia Corporation and/or its subsidiary(-ies). +** Contact: http://www.qt-project.org/ +** +** This file is part of the documentation of the Qt Toolkit. +** +** $QT_BEGIN_LICENSE:BSD$ +** You may use this file under the terms of the BSD license as follows: +** +** "Redistribution and use in source and binary forms, with or without +** modification, are permitted provided that the following conditions are +** met: +** * Redistributions of source code must retain the above copyright +** notice, this list of conditions and the following disclaimer. +** * Redistributions in binary form must reproduce the above copyright +** notice, this list of conditions and the following disclaimer in +** the documentation and/or other materials provided with the +** distribution. +** * Neither the name of Nokia Corporation and its Subsidiary(-ies) nor +** the names of its contributors may be used to endorse or promote +** products derived from this software without specific prior written +** permission. +** +** THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS +** "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT +** LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR +** A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT +** OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +** SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT +** LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, +** DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY +** THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT +** (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE +** OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE." +** +** $QT_END_LICENSE$ +** +****************************************************************************/ + +//! [0] +-no-sql-<driver> ... Disable SQL <driver> entirely. +-qt-sql-<driver> ... Enable a SQL <driver> in the Qt Library, by default + none are turned on. +-plugin-sql-<driver> Enable SQL <driver> as a plugin to be linked to + at run time. + + Possible values for <driver>: + [ db2 ibase mysql oci odbc psql sqlite sqlite2 tds ] +//! [0] + + +//! [1] +create procedure qtestproc (OUT param1 INT, OUT param2 INT) +BEGIN + set param1 = 42; + set param2 = 43; +END +//! [1] + + +//! [3] +cd $QTDIR/src/plugins/sqldrivers/mysql +qmake "INCLUDEPATH+=/usr/local/include" "LIBS+=-L/usr/local/lib -lmysqlclient_r" mysql.pro +make +//! [3] + + +//! [4] +cd $QTDIR/src/plugins/sqldrivers/mysql +make install +//! [4] + + +//! [5] +cd %QTDIR%\src\plugins\sqldrivers\mysql +qmake "INCLUDEPATH+=C:\MySQL\include" "LIBS+=C:\MYSQL\MySQL Server <version>\lib\opt\libmysql.lib" mysql.pro +nmake +//! [5] + + +//! [6] +cd $QTDIR/src/plugins/sqldrivers/oci +qmake "INCLUDEPATH+=$ORACLE_HOME/rdbms/public $ORACLE_HOME/rdbms/demo" "LIBS+=-L$ORACLE_HOME/lib -lclntsh -lwtc9" oci.pro +make +//! [6] + + +//! [7] +cd $QTDIR/src/plugins/sqldrivers/oci +qmake "INCLUDEPATH+=/usr/include/oracle/10.1.0.3/client/" "LIBS+=-L/usr/lib/oracle/10.1.0.3/client/lib -lclntsh" oci.pro +make +//! [7] + + +//! [8] +set INCLUDE=%INCLUDE%;c:\oracle\oci\include +set LIB=%LIB%;c:\oracle\oci\lib\msvc +cd %QTDIR%\src\plugins\sqldrivers\oci +qmake oci.pro +nmake +//! [8] + + +//! [9] +set PATH=%PATH%;c:\oracle\bin +//! [9] + + +//! [11] +cd $QTDIR/src/plugins/sqldrivers/odbc +qmake "INCLUDEPATH+=/usr/local/unixODBC/include" "LIBS+=-L/usr/local/unixODBC/lib -lodbc" +make +//! [11] + + +//! [12] +cd %QTDIR%\src\plugins\sqldrivers\odbc +qmake odbc.pro +nmake +//! [12] + + +//! [13] +cd $QTDIR/src/plugins/sqldrivers/psql +qmake "INCLUDEPATH+=/usr/include/pgsql" "LIBS+=-L/usr/lib -lpq" psql.pro +make +//! [13] + + +//! [14] +cd $QTDIR/src/plugins/sqldrivers/psql +make install +//! [14] + + +//! [15] +cd %QTDIR%\src\plugins\sqldrivers\psql +qmake "INCLUDEPATH+=C:\psql\include" "LIBS+=C:\psql\lib\ms\libpq.lib" psql.pro +nmake +//! [15] + + +//! [16] +cd $QTDIR/src/plugins/sqldrivers/tds +qmake "INCLUDEPATH=$SYBASE/include" "LIBS=-L$SYBASE/lib -lsybdb" +make +//! [16] + + +//! [17] +cd %QTDIR%\src\plugins\sqldrivers\tds +qmake "LIBS+=NTWDBLIB.LIB" tds.pro +nmake +//! [17] + + +//! [18] +cd $QTDIR/src/plugins/sqldrivers/db2 +qmake "INCLUDEPATH+=$DB2DIR/include" "LIBS+=-L$DB2DIR/lib -ldb2" +make +//! [18] + + +//! [19] +cd $QTDIR/src/plugins/sqldrivers/db2 +make install +//! [19] + + +//! [20] +cd %QTDIR%\src\plugins\sqldrivers\db2 +qmake "INCLUDEPATH+=<DB2 home>/sqllib/include" "LIBS+=<DB2 home>/sqllib/lib/db2cli.lib" +nmake +//! [20] + + +//! [21] +cd $QTDIR/src/plugins/sqldrivers/sqlite +qmake "INCLUDEPATH+=$SQLITE/include" "LIBS+=-L$SQLITE/lib -lsqlite" +make +//! [21] + + +//! [22] +cd $QTDIR/src/plugins/sqldrivers/sqlite +make install +//! [22] + + +//! [23] +cd %QTDIR%\src\plugins\sqldrivers\sqlite +qmake "INCLUDEPATH+=C:\SQLITE\INCLUDE" "LIBS+=C:\SQLITE\LIB\SQLITE3.LIB" sqlite.pro +nmake +//! [23] + + +//! [27] +cd $QTDIR/src/plugins/sqldrivers/ibase +qmake "INCLUDEPATH+=/opt/interbase/include" "LIBS+=-L/opt/interbase/lib" ibase.pro +make +//! [27] + + +//! [28] +cd $QTDIR/src/plugins/sqldrivers/ibase +qmake "INCLUDEPATH+=/opt/interbase/include" "LIBS+=-L/opt/interbase/lib -lfbclient" ibase.pro +make +//! [28] + + +//! [29] +cd %QTDIR%\src\plugins\sqldrivers\ibase +qmake "INCLUDEPATH+=C:\interbase\include" ibase.pro +nmake +//! [29] + + +//! [30] +cd %QTDIR%\src\plugins\sqldrivers\ibase +qmake "INCLUDEPATH+=C:\interbase\include" "LIBS+=-lfbclient" ibase.pro +nmake +//! [30] + + +//! [32] +configure -I /usr/include/oracle/10.1.0.3/client -L /usr/lib/oracle/10.1.0.3/client/lib -R /usr/lib/oracle/10.1.0.3/client/lib -lclntsh -lnnz10 +make +//! [32] + +//! [33] +cd $QTDIR/src/plugins/sqldrivers/oci +qmake "INCLUDEPATH+=/usr/include/oracle/10.1.0.3/client" "LIBS+=-L/usr/lib/oracle/10.1.0.3/client/lib -Wl,-rpath,/usr/lib/oracle/10.1.0.3/client/lib -lclntsh -lnnz10" oci.pro +make +//! [33] diff --git a/src/sql/doc/snippets/code/src_sql_kernel_qsqldatabase.cpp b/src/sql/doc/snippets/code/src_sql_kernel_qsqldatabase.cpp new file mode 100644 index 0000000000..d181b6eb14 --- /dev/null +++ b/src/sql/doc/snippets/code/src_sql_kernel_qsqldatabase.cpp @@ -0,0 +1,135 @@ +/**************************************************************************** +** +** Copyright (C) 2012 Nokia Corporation and/or its subsidiary(-ies). +** Contact: http://www.qt-project.org/ +** +** This file is part of the documentation of the Qt Toolkit. +** +** $QT_BEGIN_LICENSE:BSD$ +** You may use this file under the terms of the BSD license as follows: +** +** "Redistribution and use in source and binary forms, with or without +** modification, are permitted provided that the following conditions are +** met: +** * Redistributions of source code must retain the above copyright +** notice, this list of conditions and the following disclaimer. +** * Redistributions in binary form must reproduce the above copyright +** notice, this list of conditions and the following disclaimer in +** the documentation and/or other materials provided with the +** distribution. +** * Neither the name of Nokia Corporation and its Subsidiary(-ies) nor +** the names of its contributors may be used to endorse or promote +** products derived from this software without specific prior written +** permission. +** +** THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS +** "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT +** LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR +** A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT +** OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +** SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT +** LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, +** DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY +** THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT +** (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE +** OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE." +** +** $QT_END_LICENSE$ +** +****************************************************************************/ + +//! [0] +// WRONG +QSqlDatabase db = QSqlDatabase::database("sales"); +QSqlQuery query("SELECT NAME, DOB FROM EMPLOYEES", db); +QSqlDatabase::removeDatabase("sales"); // will output a warning + +// "db" is now a dangling invalid database connection, +// "query" contains an invalid result set +//! [0] + + +//! [1] +{ + QSqlDatabase db = QSqlDatabase::database("sales"); + QSqlQuery query("SELECT NAME, DOB FROM EMPLOYEES", db); +} +// Both "db" and "query" are destroyed because they are out of scope +QSqlDatabase::removeDatabase("sales"); // correct +//! [1] + + +//! [2] +QSqlDatabase::registerSqlDriver("MYDRIVER", + new QSqlDriverCreator<MyDatabaseDriver>); +QSqlDatabase db = QSqlDatabase::addDatabase("MYDRIVER"); +//! [2] + + +//! [3] +... +db = QSqlDatabase::addDatabase("QODBC"); +db.setDatabaseName("DRIVER={Microsoft Access Driver (*.mdb)};FIL={MS Access};DBQ=myaccessfile.mdb"); +if (db.open()) { + // success! +} +... +//! [3] + + +//! [4] +... +// MySQL connection +db.setConnectOptions("CLIENT_SSL=1;CLIENT_IGNORE_SPACE=1"); // use an SSL connection to the server +if (!db.open()) { + db.setConnectOptions(); // clears the connect option string + ... +} +... +// PostgreSQL connection +db.setConnectOptions("requiressl=1"); // enable PostgreSQL SSL connections +if (!db.open()) { + db.setConnectOptions(); // clear options + ... +} +... +// ODBC connection +db.setConnectOptions("SQL_ATTR_ACCESS_MODE=SQL_MODE_READ_ONLY;SQL_ATTR_TRACE=SQL_OPT_TRACE_ON"); // set ODBC options +if (!db.open()) { + db.setConnectOptions(); // don't try to set this option + ... +} +//! [4] + + +//! [5] +#include "qtdir/src/sql/drivers/psql/qsql_psql.cpp" +//! [5] + + +//! [6] +PGconn *con = PQconnectdb("host=server user=bart password=simpson dbname=springfield"); +QPSQLDriver *drv = new QPSQLDriver(con); +QSqlDatabase db = QSqlDatabase::addDatabase(drv); // becomes the new default connection +QSqlQuery query; +query.exec("SELECT NAME, ID FROM STAFF"); +... +//! [6] + + +//! [7] +unix:LIBS += -lpq +win32:LIBS += libpqdll.lib +//! [7] + + +//! [8] +QSqlDatabase db; +qDebug() << db.isValid(); // Returns false + +db = QSqlDatabase::database("sales"); +qDebug() << db.isValid(); // Returns true if "sales" connection exists + +QSqlDatabase::removeDatabase("sales"); +qDebug() << db.isValid(); // Returns false +//! [8] diff --git a/src/sql/doc/snippets/code/src_sql_kernel_qsqldriver.cpp b/src/sql/doc/snippets/code/src_sql_kernel_qsqldriver.cpp new file mode 100644 index 0000000000..254a35aba2 --- /dev/null +++ b/src/sql/doc/snippets/code/src_sql_kernel_qsqldriver.cpp @@ -0,0 +1,64 @@ +/**************************************************************************** +** +** Copyright (C) 2012 Nokia Corporation and/or its subsidiary(-ies). +** Contact: http://www.qt-project.org/ +** +** This file is part of the documentation of the Qt Toolkit. +** +** $QT_BEGIN_LICENSE:BSD$ +** You may use this file under the terms of the BSD license as follows: +** +** "Redistribution and use in source and binary forms, with or without +** modification, are permitted provided that the following conditions are +** met: +** * Redistributions of source code must retain the above copyright +** notice, this list of conditions and the following disclaimer. +** * Redistributions in binary form must reproduce the above copyright +** notice, this list of conditions and the following disclaimer in +** the documentation and/or other materials provided with the +** distribution. +** * Neither the name of Nokia Corporation and its Subsidiary(-ies) nor +** the names of its contributors may be used to endorse or promote +** products derived from this software without specific prior written +** permission. +** +** THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS +** "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT +** LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR +** A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT +** OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +** SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT +** LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, +** DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY +** THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT +** (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE +** OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE." +** +** $QT_END_LICENSE$ +** +****************************************************************************/ + +//! [0] +QSqlDatabase db = ...; +QVariant v = db.driver()->handle(); +if (v.isValid() && qstrcmp(v.typeName(), "sqlite3*")==0) { + // v.data() returns a pointer to the handle + sqlite3 *handle = *static_cast<sqlite3 **>(v.data()); + if (handle != 0) { // check that it is not NULL + ... + } +} +//! [0] + + +//! [1] +if (v.typeName() == "PGconn*") { + PGconn *handle = *static_cast<PGconn **>(v.data()); + if (handle != 0) ... +} + +if (v.typeName() == "MYSQL*") { + MYSQL *handle = *static_cast<MYSQL **>(v.data()); + if (handle != 0) ... +} +//! [1] diff --git a/src/sql/doc/snippets/code/src_sql_kernel_qsqlerror.cpp b/src/sql/doc/snippets/code/src_sql_kernel_qsqlerror.cpp new file mode 100644 index 0000000000..9914206193 --- /dev/null +++ b/src/sql/doc/snippets/code/src_sql_kernel_qsqlerror.cpp @@ -0,0 +1,46 @@ +/**************************************************************************** +** +** Copyright (C) 2012 Nokia Corporation and/or its subsidiary(-ies). +** Contact: http://www.qt-project.org/ +** +** This file is part of the documentation of the Qt Toolkit. +** +** $QT_BEGIN_LICENSE:BSD$ +** You may use this file under the terms of the BSD license as follows: +** +** "Redistribution and use in source and binary forms, with or without +** modification, are permitted provided that the following conditions are +** met: +** * Redistributions of source code must retain the above copyright +** notice, this list of conditions and the following disclaimer. +** * Redistributions in binary form must reproduce the above copyright +** notice, this list of conditions and the following disclaimer in +** the documentation and/or other materials provided with the +** distribution. +** * Neither the name of Nokia Corporation and its Subsidiary(-ies) nor +** the names of its contributors may be used to endorse or promote +** products derived from this software without specific prior written +** permission. +** +** THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS +** "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT +** LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR +** A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT +** OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +** SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT +** LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, +** DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY +** THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT +** (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE +** OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE." +** +** $QT_END_LICENSE$ +** +****************************************************************************/ + +//! [0] +QSqlQueryModel model; +model.setQuery("select * from myTable"); +if (model.lastError().isValid()) + qDebug() << model.lastError(); +//! [0] diff --git a/src/sql/doc/snippets/code/src_sql_kernel_qsqlquery.cpp b/src/sql/doc/snippets/code/src_sql_kernel_qsqlquery.cpp new file mode 100644 index 0000000000..c540f8bd59 --- /dev/null +++ b/src/sql/doc/snippets/code/src_sql_kernel_qsqlquery.cpp @@ -0,0 +1,80 @@ +/**************************************************************************** +** +** Copyright (C) 2012 Nokia Corporation and/or its subsidiary(-ies). +** Contact: http://www.qt-project.org/ +** +** This file is part of the documentation of the Qt Toolkit. +** +** $QT_BEGIN_LICENSE:BSD$ +** You may use this file under the terms of the BSD license as follows: +** +** "Redistribution and use in source and binary forms, with or without +** modification, are permitted provided that the following conditions are +** met: +** * Redistributions of source code must retain the above copyright +** notice, this list of conditions and the following disclaimer. +** * Redistributions in binary form must reproduce the above copyright +** notice, this list of conditions and the following disclaimer in +** the documentation and/or other materials provided with the +** distribution. +** * Neither the name of Nokia Corporation and its Subsidiary(-ies) nor +** the names of its contributors may be used to endorse or promote +** products derived from this software without specific prior written +** permission. +** +** THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS +** "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT +** LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR +** A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT +** OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +** SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT +** LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, +** DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY +** THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT +** (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE +** OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE." +** +** $QT_END_LICENSE$ +** +****************************************************************************/ + +//! [0] +SELECT forename, surname FROM people; +//! [0] + + +//! [1] +QSqlQuery q("select * from employees"); +QSqlRecord rec = q.record(); + +qDebug() << "Number of columns: " << rec.count(); + +int nameCol = rec.indexOf("name"); // index of the field "name" +while (q.next()) + qDebug() << q.value(nameCol).toString(); // output all names +//! [1] + + +//! [2] +QSqlQuery q; +q.prepare("insert into myTable values (?, ?)"); + +QVariantList ints; +ints << 1 << 2 << 3 << 4; +q.addBindValue(ints); + +QVariantList names; +names << "Harald" << "Boris" << "Trond" << QVariant(QVariant::String); +q.addBindValue(names); + +if (!q.execBatch()) + qDebug() << q.lastError(); +//! [2] + + +//! [3] +1 Harald +2 Boris +3 Trond +4 NULL +//! [3] diff --git a/src/sql/doc/snippets/code/src_sql_kernel_qsqlresult.cpp b/src/sql/doc/snippets/code/src_sql_kernel_qsqlresult.cpp new file mode 100644 index 0000000000..773af85ab9 --- /dev/null +++ b/src/sql/doc/snippets/code/src_sql_kernel_qsqlresult.cpp @@ -0,0 +1,85 @@ +/**************************************************************************** +** +** Copyright (C) 2012 Nokia Corporation and/or its subsidiary(-ies). +** Contact: http://www.qt-project.org/ +** +** This file is part of the documentation of the Qt Toolkit. +** +** $QT_BEGIN_LICENSE:BSD$ +** You may use this file under the terms of the BSD license as follows: +** +** "Redistribution and use in source and binary forms, with or without +** modification, are permitted provided that the following conditions are +** met: +** * Redistributions of source code must retain the above copyright +** notice, this list of conditions and the following disclaimer. +** * Redistributions in binary form must reproduce the above copyright +** notice, this list of conditions and the following disclaimer in +** the documentation and/or other materials provided with the +** distribution. +** * Neither the name of Nokia Corporation and its Subsidiary(-ies) nor +** the names of its contributors may be used to endorse or promote +** products derived from this software without specific prior written +** permission. +** +** THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS +** "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT +** LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR +** A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT +** OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +** SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT +** LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, +** DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY +** THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT +** (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE +** OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE." +** +** $QT_END_LICENSE$ +** +****************************************************************************/ + +//! [0] +QSqlQuery q; +q.prepare("insert into test (i1, i2, s) values (?, ?, ?)"); + +QVariantList col1; +QVariantList col2; +QVariantList col3; + +col1 << 1 << 3; +col2 << 2 << 4; +col3 << "hello" << "world"; + +q.bindValue(0, col1); +q.bindValue(1, col2); +q.bindValue(2, col3); + +if (!q.execBatch()) + qDebug() << q.lastError(); +//! [0] + + +//! [1] +QSqlQuery query = ... +QVariant v = query.result()->handle(); +if (v.isValid() && qstrcmp(v.typeName(), "sqlite3_stmt*")) { + // v.data() returns a pointer to the handle + sqlite3_stmt *handle = *static_cast<sqlite3_stmt **>(v.data()); + if (handle != 0) { // check that it is not NULL + ... + } +} +//! [1] + + +//! [2] +if (v.typeName() == "PGresult*") { + PGresult *handle = *static_cast<PGresult **>(v.data()); + if (handle != 0) ... +} + +if (v.typeName() == "MYSQL_STMT*") { + MYSQL_STMT *handle = *static_cast<MYSQL_STMT **>(v.data()); + if (handle != 0) ... +} +//! [2] diff --git a/src/sql/doc/snippets/code/src_sql_models_qsqlquerymodel.cpp b/src/sql/doc/snippets/code/src_sql_models_qsqlquerymodel.cpp new file mode 100644 index 0000000000..71c96b0207 --- /dev/null +++ b/src/sql/doc/snippets/code/src_sql_models_qsqlquerymodel.cpp @@ -0,0 +1,52 @@ +/**************************************************************************** +** +** Copyright (C) 2012 Nokia Corporation and/or its subsidiary(-ies). +** Contact: http://www.qt-project.org/ +** +** This file is part of the documentation of the Qt Toolkit. +** +** $QT_BEGIN_LICENSE:BSD$ +** You may use this file under the terms of the BSD license as follows: +** +** "Redistribution and use in source and binary forms, with or without +** modification, are permitted provided that the following conditions are +** met: +** * Redistributions of source code must retain the above copyright +** notice, this list of conditions and the following disclaimer. +** * Redistributions in binary form must reproduce the above copyright +** notice, this list of conditions and the following disclaimer in +** the documentation and/or other materials provided with the +** distribution. +** * Neither the name of Nokia Corporation and its Subsidiary(-ies) nor +** the names of its contributors may be used to endorse or promote +** products derived from this software without specific prior written +** permission. +** +** THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS +** "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT +** LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR +** A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT +** OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +** SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT +** LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, +** DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY +** THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT +** (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE +** OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE." +** +** $QT_END_LICENSE$ +** +****************************************************************************/ + +//! [0] +while (myModel->canFetchMore()) + myModel->fetchMore(); +//! [0] + + +//! [1] +QSqlQueryModel model; +model.setQuery("select * from MyTable"); +if (model.lastError().isValid()) + qDebug() << model.lastError(); +//! [1] diff --git a/src/sql/doc/snippets/sqldatabase/sqldatabase.cpp b/src/sql/doc/snippets/sqldatabase/sqldatabase.cpp new file mode 100644 index 0000000000..81f806309a --- /dev/null +++ b/src/sql/doc/snippets/sqldatabase/sqldatabase.cpp @@ -0,0 +1,559 @@ +/**************************************************************************** +** +** Copyright (C) 2012 Nokia Corporation and/or its subsidiary(-ies). +** Contact: http://www.qt-project.org/ +** +** This file is part of the documentation of the Qt Toolkit. +** +** $QT_BEGIN_LICENSE:BSD$ +** You may use this file under the terms of the BSD license as follows: +** +** "Redistribution and use in source and binary forms, with or without +** modification, are permitted provided that the following conditions are +** met: +** * Redistributions of source code must retain the above copyright +** notice, this list of conditions and the following disclaimer. +** * Redistributions in binary form must reproduce the above copyright +** notice, this list of conditions and the following disclaimer in +** the documentation and/or other materials provided with the +** distribution. +** * Neither the name of Nokia Corporation and its Subsidiary(-ies) nor +** the names of its contributors may be used to endorse or promote +** products derived from this software without specific prior written +** permission. +** +** THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS +** "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT +** LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR +** A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT +** OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +** SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT +** LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, +** DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY +** THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT +** (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE +** OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE." +** +** $QT_END_LICENSE$ +** +****************************************************************************/ + +#include <QtGui> +#include <QtSql> + +#include <iostream> + +using namespace std; + +QString tr(const char *text) +{ + return QApplication::translate(text, text); +} + +void QSqlDatabase_snippets() +{ + { +//! [0] + QSqlDatabase db = QSqlDatabase::addDatabase("QPSQL"); + db.setHostName("acidalia"); + db.setDatabaseName("customdb"); + db.setUserName("mojito"); + db.setPassword("J0a1m8"); + bool ok = db.open(); +//! [0] + Q_UNUSED(ok); + } + + { +//! [1] + QSqlDatabase db = QSqlDatabase::database(); +//! [1] + } +} + +void QSqlField_snippets() +{ +#if 0 + { +//! [2] + QSqlField field("age", QVariant::Int); + field.setValue(QPixmap()); // WRONG +//! [2] + } +#endif + + { +//! [3] + QSqlField field("age", QVariant::Int); + field.setValue(QString("123")); // casts QString to int +//! [3] + } + + { +//! [4] + QSqlQuery query; +//! [4] //! [5] + QSqlRecord record = query.record(); +//! [5] //! [6] + QSqlField field = record.field("country"); +//! [6] + } +} + +void doSomething(const QString &) +{ +} + +void QSqlQuery_snippets() +{ + { + // typical loop +//! [7] + QSqlQuery query("SELECT country FROM artist"); + while (query.next()) { + QString country = query.value(0).toString(); + doSomething(country); + } +//! [7] + } + + { + // field index lookup +//! [8] + QSqlQuery query("SELECT * FROM artist"); + int fieldNo = query.record().indexOf("country"); + while (query.next()) { + QString country = query.value(fieldNo).toString(); + doSomething(country); + } +//! [8] + } + + { + // named with named +//! [9] + QSqlQuery query; + query.prepare("INSERT INTO person (id, forename, surname) " + "VALUES (:id, :forename, :surname)"); + query.bindValue(":id", 1001); + query.bindValue(":forename", "Bart"); + query.bindValue(":surname", "Simpson"); + query.exec(); +//! [9] + } + + { + // positional with named +//! [10] + QSqlQuery query; + query.prepare("INSERT INTO person (id, forename, surname) " + "VALUES (:id, :forename, :surname)"); + query.bindValue(0, 1001); + query.bindValue(1, "Bart"); + query.bindValue(2, "Simpson"); + query.exec(); +//! [10] + } + + { + // positional 1 +//! [11] + QSqlQuery query; + query.prepare("INSERT INTO person (id, forename, surname) " + "VALUES (?, ?, ?)"); + query.bindValue(0, 1001); + query.bindValue(1, "Bart"); + query.bindValue(2, "Simpson"); + query.exec(); +//! [11] + } + + { + // positional 2 +//! [12] + QSqlQuery query; + query.prepare("INSERT INTO person (id, forename, surname) " + "VALUES (?, ?, ?)"); + query.addBindValue(1001); + query.addBindValue("Bart"); + query.addBindValue("Simpson"); + query.exec(); +//! [12] + } + + { + // stored +//! [13] + QSqlQuery query; + query.prepare("CALL AsciiToInt(?, ?)"); + query.bindValue(0, "A"); + query.bindValue(1, 0, QSql::Out); + query.exec(); + int i = query.boundValue(1).toInt(); // i is 65 +//! [13] + Q_UNUSED(i); + } + + QSqlQuery query; + + { + // examine with named binding +//! [14] + QMapIterator<QString, QVariant> i(query.boundValues()); + while (i.hasNext()) { + i.next(); + cout << i.key().toAscii().data() << ": " + << i.value().toString().toAscii().data() << endl; + } +//! [14] + } + + { + // examine with positional binding +//! [15] + QList<QVariant> list = query.boundValues().values(); + for (int i = 0; i < list.size(); ++i) + cout << i << ": " << list.at(i).toString().toAscii().data() << endl; +//! [15] + } +} + +void QSqlQueryModel_snippets() +{ + { +//! [16] + QSqlQueryModel *model = new QSqlQueryModel; + model->setQuery("SELECT name, salary FROM employee"); + model->setHeaderData(0, Qt::Horizontal, tr("Name")); + model->setHeaderData(1, Qt::Horizontal, tr("Salary")); + +//! [17] + QTableView *view = new QTableView; +//! [17] //! [18] + view->setModel(model); +//! [18] //! [19] + view->show(); +//! [16] //! [19] //! [20] + view->setEditTriggers(QAbstractItemView::NoEditTriggers); +//! [20] + } + +//! [21] + QSqlQueryModel model; + model.setQuery("SELECT * FROM employee"); + int salary = model.record(4).value("salary").toInt(); +//! [21] + Q_UNUSED(salary); + + { +//! [22] + int salary = model.data(model.index(4, 2)).toInt(); +//! [22] + Q_UNUSED(salary); + } + + for (int row = 0; row < model.rowCount(); ++row) { + for (int col = 0; col < model.columnCount(); ++col) { + qDebug() << model.data(model.index(row, col)); + } + } +} + +class MyModel : public QSqlQueryModel +{ +public: + QVariant data(const QModelIndex &item, int role) const; + + int m_specialColumnNo; +}; + +//! [23] +QVariant MyModel::data(const QModelIndex &item, int role) const +{ + if (item.column() == m_specialColumnNo) { + // handle column separately + } + return QSqlQueryModel::data(item, role); +} +//! [23] + +void QSqlTableModel_snippets() +{ +//! [24] + QSqlTableModel *model = new QSqlTableModel(parentObject, database); + model->setTable("employee"); + model->setEditStrategy(QSqlTableModel::OnManualSubmit); + model->select(); + model->setHeaderData(0, Qt::Horizontal, tr("Name")); + model->setHeaderData(1, Qt::Horizontal, tr("Salary")); + + QTableView *view = new QTableView; + view->setModel(model); + view->hideColumn(0); // don't show the ID + view->show(); +//! [24] + + { +//! [25] + QSqlTableModel model; + model.setTable("employee"); + QString name = model.record(4).value("name").toString(); +//! [25] + } +} + +void sql_intro_snippets() +{ + { +//! [26] + QSqlDatabase db = QSqlDatabase::addDatabase("QMYSQL"); + db.setHostName("bigblue"); + db.setDatabaseName("flightdb"); + db.setUserName("acarlson"); + db.setPassword("1uTbSbAs"); + bool ok = db.open(); +//! [26] + Q_UNUSED(ok); + } + + { +//! [27] + QSqlDatabase firstDB = QSqlDatabase::addDatabase("QMYSQL", "first"); + QSqlDatabase secondDB = QSqlDatabase::addDatabase("QMYSQL", "second"); +//! [27] + } + + { +//! [28] + QSqlDatabase defaultDB = QSqlDatabase::database(); +//! [28] //! [29] + QSqlDatabase firstDB = QSqlDatabase::database("first"); +//! [29] //! [30] + QSqlDatabase secondDB = QSqlDatabase::database("second"); +//! [30] + } + + { + // SELECT1 +//! [31] + QSqlQuery query; + query.exec("SELECT name, salary FROM employee WHERE salary > 50000"); +//! [31] + +//! [32] + while (query.next()) { + QString name = query.value(0).toString(); + int salary = query.value(1).toInt(); + qDebug() << name << salary; + } +//! [32] + } + + { + // FEATURE +//! [33] + QSqlQuery query; + int numRows; + query.exec("SELECT name, salary FROM employee WHERE salary > 50000"); + + QSqlDatabase defaultDB = QSqlDatabase::database(); + if (defaultDB.driver()->hasFeature(QSqlDriver::QuerySize)) { + numRows = query.size(); + } else { + // this can be very slow + query.last(); + numRows = query.at() + 1; + } +//! [33] + } + + { + // INSERT1 +//! [34] + QSqlQuery query; + query.exec("INSERT INTO employee (id, name, salary) " + "VALUES (1001, 'Thad Beaumont', 65000)"); +//! [34] + } + + { + // NAMED BINDING +//! [35] + QSqlQuery query; + query.prepare("INSERT INTO employee (id, name, salary) " + "VALUES (:id, :name, :salary)"); + query.bindValue(":id", 1001); + query.bindValue(":name", "Thad Beaumont"); + query.bindValue(":salary", 65000); + query.exec(); +//! [35] + } + + { + // POSITIONAL BINDING +//! [36] + QSqlQuery query; + query.prepare("INSERT INTO employee (id, name, salary) " + "VALUES (?, ?, ?)"); + query.addBindValue(1001); + query.addBindValue("Thad Beaumont"); + query.addBindValue(65000); + query.exec(); +//! [36] + } + + { + // UPDATE1 +//! [37] + QSqlQuery query; + query.exec("UPDATE employee SET salary = 70000 WHERE id = 1003"); +//! [37] + } + + { + // DELETE1 +//! [38] + QSqlQuery query; + query.exec("DELETE FROM employee WHERE id = 1007"); +//! [38] + } + + { + // TRANSACTION +//! [39] + QSqlDatabase::database().transaction(); + QSqlQuery query; + query.exec("SELECT id FROM employee WHERE name = 'Torild Halvorsen'"); + if (query.next()) { + int employeeId = query.value(0).toInt(); + query.exec("INSERT INTO project (id, name, ownerid) " + "VALUES (201, 'Manhattan Project', " + + QString::number(employeeId) + ')'); + } + QSqlDatabase::database().commit(); +//! [39] + } + + { + // SQLQUERYMODEL1 +//! [40] + QSqlQueryModel model; + model.setQuery("SELECT * FROM employee"); + + for (int i = 0; i < model.rowCount(); ++i) { + int id = model.record(i).value("id").toInt(); + QString name = model.record(i).value("name").toString(); + qDebug() << id << name; + } +//! [40] + } + + { + // SQLTABLEMODEL1 +//! [41] + QSqlTableModel model; + model.setTable("employee"); + model.setFilter("salary > 50000"); + model.setSort(2, Qt::DescendingOrder); + model.select(); + + for (int i = 0; i < model.rowCount(); ++i) { + QString name = model.record(i).value("name").toString(); + int salary = model.record(i).value("salary").toInt(); + qDebug() << name << salary; + } +//! [41] + } + + { + // SQLTABLEMODEL2 + QSqlTableModel model; + model.setTable("employee"); + +//! [42] + for (int i = 0; i < model.rowCount(); ++i) { + QSqlRecord record = model.record(i); + double salary = record.value("salary").toInt(); + salary *= 1.1; + record.setValue("salary", salary); + model.setRecord(i, record); + } + model.submitAll(); +//! [42] + + // SQLTABLEMODEL3 + int row = 1; + int column = 2; +//! [43] + model.setData(model.index(row, column), 75000); + model.submitAll(); +//! [43] + + // SQLTABLEMODEL4 +//! [44] + model.insertRows(row, 1); + model.setData(model.index(row, 0), 1013); + model.setData(model.index(row, 1), "Peter Gordon"); + model.setData(model.index(row, 2), 68500); + model.submitAll(); +//! [44] + +//! [45] + model.removeRows(row, 5); +//! [45] //! [46] + model.submitAll(); +//! [46] + } +} + +//! [47] +class XyzResult : public QSqlResult +{ +public: + XyzResult(const QSqlDriver *driver) + : QSqlResult(driver) {} + ~XyzResult() {} + +protected: + QVariant data(int /* index */) { return QVariant(); } + bool isNull(int /* index */) { return false; } + bool reset(const QString & /* query */) { return false; } + bool fetch(int /* index */) { return false; } + bool fetchFirst() { return false; } + bool fetchLast() { return false; } + int size() { return 0; } + int numRowsAffected() { return 0; } + QSqlRecord record() const { return QSqlRecord(); } +}; +//! [47] + +//! [48] +class XyzDriver : public QSqlDriver +{ +public: + XyzDriver() {} + ~XyzDriver() {} + + bool hasFeature(DriverFeature /* feature */) const { return false; } + bool open(const QString & /* db */, const QString & /* user */, + const QString & /* password */, const QString & /* host */, + int /* port */, const QString & /* options */) + { return false; } + void close() {} + QSqlResult *createResult() const { return new XyzResult(this); } +}; +//! [48] + +int main(int argc, char **argv) +{ + QApplication app(argc, argv); + + QSqlDatabase_snippets(); + QSqlField_snippets(); + QSqlQuery_snippets(); + QSqlQueryModel_snippets(); + QSqlTableModel_snippets(); + + XyzDriver driver; + XyzResult result(&driver); +} diff --git a/src/sql/doc/src/qsqldatatype-table.qdoc b/src/sql/doc/src/qsqldatatype-table.qdoc new file mode 100644 index 0000000000..a7e03cf28f --- /dev/null +++ b/src/sql/doc/src/qsqldatatype-table.qdoc @@ -0,0 +1,570 @@ +/**************************************************************************** +** +** Copyright (C) 2012 Nokia Corporation and/or its subsidiary(-ies). +** Contact: http://www.qt-project.org/ +** +** This file is part of the documentation of the Qt Toolkit. +** +** $QT_BEGIN_LICENSE:FDL$ +** GNU Free Documentation License +** Alternatively, this file may be used under the terms of the GNU Free +** Documentation License version 1.3 as published by the Free Software +** Foundation and appearing in the file included in the packaging of +** this file. +** +** Other Usage +** Alternatively, this file may be used in accordance with the terms +** and conditions contained in a signed written agreement between you +** and Nokia. +** +** +** +** +** +** $QT_END_LICENSE$ +** +****************************************************************************/ + +/*! + \page sql-types.html + \title Data Types for Qt-supported Database Systems + \brief Recommended data types for database systems + + \ingroup qt-sql + + \section1 Recommended Data Types for Qt-Supported Database Systems + + This table shows the recommended data types for extracting data from + the databases supported in Qt. Note that types used in Qt are not + necessarily valid as input types to a specific database + system. e.g., A double might work perfectly as input for floating + point records in a particular database, but not necessarily as a + storage format for output from that database, because it would be + stored with 64-bit precision in C++. + + \tableofcontents + + \section2 IBM DB2 Data Types + + \table 90% + \header + \li IBM DB2 data type + \li SQL type description + \li Recommended input (C++ or Qt data type) + \row + \li SMALLINT + \li 16-bit signed integer + \li typedef qint16 + \row + \li INTEGER + \li 32-bit signed integer + \li typedef qint32 + \row + \li BIGINT + \li 64-bit signed integer + \li typedef qint64 + \row + \li REAL + \li 32-bit Single-precision floating point + \li By default mapping to QString + \row + \li DOUBLE PRECISION + \li 64-bit Double-precision floating point + \li By default mapping to QString + \row + \li FLOAT + \li 64-bit Double-precision floating point + \li By default mapping to QString + \row + \li CHAR + \li Fixed-length, null-terminated character string + \li Mapped to QString + \row + \li VARCHAR + \li Null-terminated varying length string + \li Mapped to QString + \row + \li LONG VARCHAR + \li Not null-terminated varying length character string + \li Mapped to QString + \row + \li BLOB + \li Not null-terminated varying binary string with 4-byte string + length indicator + \li Mapped to QByteArray + \row + \li CLOB + \li Character large string object + \li Mapped to QString + \row + \li DATE + \li Null-terminated character string of the following format: + yyyy-mm-dd + \li Mapped to QDate + \row + \li TIME + \li Null-terminated character string of the following format: hh.mm.ss + \li Mapped to QTime + \row + \li TIMESTAMP + \li Null-terminated character string of the following format: yyyy-mm-dd-hh.mm.ss.nnnnnn + \li Mapped to QDateTime + \endtable + + \section2 Borland InterBase Data Types + + \table 90% + \header + \li Borland InterBase data type + \li SQL type description + \li Recommended input (C++ or Qt data type) + \row + \li BOOLEAN + \li Boolean + \li bool + \row + \li TINYINT + \li 8 bit signed integer + \li typedef qint8 + \row + \li SMALLINT + \li 16-bit signed integer + \li typedef qint16 + \row + \li INTEGER + \li 32-bit signed integer + \li typedef qint32 + \row + \li BIGINT LONG + \li 64-bit signed integer + \li typedef qint64 + \row + \li REAL FLOAT + \li 32-bit floating point + \li By default mapping to QString + \row + \li FLOAT + \li 64-bit floating point + \li By default mapping to QString + \row + \li DOUBLE + \li 64-bit floating point + \li By default mapping to QString + \row + \li DOUBLE PRECISION + \li 64-bit Double-precision floating point + \li By default mapping to QString + \row + \li VARCHAR STRING + \li Character string, Unicode + \li Mapped to QString + \row + \li CLOB + \li Character large string object + \li Mapped to QString + \row + \li DATE + \li Displays date. Format: 'yyyy-mm-dd' + \li Mapped to QDate + \row + \li TIME + \li Displays time. Format is 'hh:mm:ss' in 24-hour format + \li Mapped to QTime + \row + \li TIMESTAMP + \li Displays a timestamp. Format is 'yyyy-mm-dd hh:mm:ss' + \li Mapped to QDateTime + \endtable + + \section2 MySQL Data Types + + \table 90% + \header + \li MySQL data type + \li SQL type description + \li Recommended input (C++ or Qt data type) + \row + \li TINYINT + \li 8 bit signed integer + \li typedef qint8 + \row + \li TINYINT UNSIGNED + \li 8 bit unsigned integer + \li typedef quint8 + \row + \li SMALLINT + \li 16-bit signed integer + \li typedef qint16 + \row + \li SMALLINT UNSIGNED + \li 16-bit unsigned integer + \li typedef quint16 + \row + \li INT + \li 32-bit signed integer + \li typedef qint32 + \row + \li INT UNSIGNED + \li 32-bit unsigned integer + \li typedef quint32 + \row + \li BIGINT + \li 64-bit signed integer + \li typedef qint64 + \row + \li FLOAT + \li 32-bit Floating Point + \li By default mapping to QString + \row + \li DOUBLE + \li 64-bit Floating Point + \li By default mapping to QString + \row + \li CHAR + \li Character string + \li Mapped to QString + \row + \li VARCHAR + \li Character string + \li Mapped to QString + \row + \li TINYTEXT + \li Character string + \li Mapped to QString + \row + \li TEXT + \li Character string + \li Mapped to QString + \row + \li MEDIUMTEXT + \li Character string + \li Mapped to QString + \row + \li LONGTEXT + \li Character string + \li Mapped to QString + \row + \li CLOB + \li Character large string object + \li Mapped to QString + \row + \li all BLOB types + \li BLOB + \li Mapped to QByteArray + \row + \li DATE + \li Date without Time + \li Mapped to QDate + \row + \li DATETIME + \li Date and Time + \li Mapped to QDateTime + \row + \li TIMESTAMP + \li Date and Time + \li Mapped to QDateTime + \row + \li TIME + \li Time + \li Mapped to QTime + \row + \li YEAR + \li Year (int) + \li Mapped to QDateTime + \row + \li ENUM + \li Enumeration of Value Set + \li Mapped to QString + \endtable + + \section2 Oracle Call Interface Data Types + + \table 90% + \header + \li Oracle Call Interface data type + \li SQL type description + \li Recommended input (C++ or Qt data type) + \row + \li NUMBER + \li FLOAT, DOUBLE, PRECISIONc REAL + \li By default mapping to QString + \row + \li NUMBER(38) + \li INTEGER INT SMALLINT + \li typedef qint8/16/32/64 + \row + \li NUMBER(p,s) + \li NUMERIC(p,s) DECIMAL(p,s)a + \li By default mapping to QString + \row + \li NVARCHAR2(n) + \li Character string (NATIONAL CHARACTER VARYING(n) NATIONAL + CHAR VARYING(n) NCHAR VARYING(n)) + \li Mapped to QString + \row + \li NCHAR(n) + \li Character string (NATIONAL CHARACTER(n) NATIONAL CHAR(n) + NCHAR(n)) + \li Mapped to QString + \row + \li CHAR(n) + \li Character string (CHARACTER(n) CHAR(n)) + \li Mapped to QString + \row + \li CLOB + \li Character large string object + \li Mapped to QString + \row + \li BLOB + \li A binary large object + \li Mapped to QByteArray + \row + \li TIMESTAMP + \li Year, month, and day values of date, as well as hour, minute, + and second values of time + \li Mapped to QDateTime + \endtable + + \section2 ODBC Data Types + + \table 90% + \header + \li ODBC data type + \li SQL type description + \li Recommended input (C++ or Qt data type) + \row + \li BIT + \li Boolean + \li BOOL + \row + \li TINYINT + \li 8 bit integer + \li typedef qint8 + \row + \li SMALLINT + \li 16-bit signed integer + \li typedef qint16 + \row + \li INTEGER + \li 32-bit signed integer + \li typedef qint32 + \row + \li BIGINT + \li 64-bit signed integer + \li typedef qint64 + \row + \li REAL + \li 32-bit Single-precision floating point + \li By default mapping to QString + \row + \li FLOAT + \li 64-bit Double floating point + \li By default mapping to QString + \row + \li DOUBLE + \li 64-bit Double floating point + \li By default mapping to QString + \row + \li CHAR + \li Character string + \li Mapped to QString + \row + \li VARCHAR + \li Character string + \li Mapped to QString + \row + \li LONGVARCHAR + \li Character string + \li Mapped to QString + \row + \li CLOB + \li Character large string object + \li Mapped to QString + \row + \li DATE + \li Character string + \li Mapped to QDate + \row + \li TIME + \li Character Time, Character string + \li Mapped to QTime + \row + \li TIMESTAMP + \li Character Time, Character string + \li Mapped to QDateTime + \endtable + + \section2 PostgreSQL Data Types + + \table 90% + \header + \li PostgreSQL data type + \li SQL type description + \li Recommended input (C++ or Qt data type) + \row + \li BOOLEAN + \li Boolean + \li bool + \row + \li SMALLINT + \li 16-bit signed integer + \li typedef qint16 + \row + \li INTEGER + \li 32-bit signed integer + \li typedef qint32 + \row + \li BIGINT + \li 64-bit signed integer + \li typedef qint64 + \row + \li REAL + \li 32-bit variable-precision floating point + \li By default mapping to QString + \row + \li DOUBLE PRECISION + \li 64-bit variable-precision floating point + \li By default mapping to QString + \row + \li DECIMAL VARIABLE + \li user-specified precision, exact + \li Mapped to QString + \row + \li NUMERIC VARIABLE + \li user-specified precision, exact + \li Mapped to QString + \row + \li VARCHAR + \li variable-length character string + \li Mapped to QString + \row + \li CHARACTER + \li Character string of fixed-length + \li Mapped to QString + \row + \li TEXT + \li Character string of variable-length + \li Mapped to QString + \row + \li CLOB + \li Character large string object + \li Mapped to QString + \row + \li TIMESTAMP + \li 8 bytes, both date and time + \li Mapped to QDateTime + \row + \li TIMESTAMP + \li 8 bytes, both date and time, with time zone + \li Mapped to QDateTime + \row + \li DATE + \li 4 bytes, dates only + \li Mapped to QDate + \row + \li TIME + \li 8 bytes, times of day only 00:00:00.00 - 23:59:59.99 + \li Mapped to QTime + \row + \li TIME + \li 12 bytes times of day only, with time zone 00:00:00.00+12 + \li Mapped to QDateTime + \endtable + + \section2 QSQLITE SQLite version 3 Data Types + + \table 90% + \header + \li QSQLITE SQLite version 3 data type + \li SQL type description + \li Recommended input (C++ or Qt data type) + \row + \li NULL + \li NULL value. + \li NULL + \row + \li INTEGER + \li Signed integer, stored in 8, 16, 24, 32, 48, or 64-bits + depending on the magnitude of the value. + \li typedef qint8/16/32/64 + \row + \li REAL + \li 64-bit floating point value. + \li By default mapping to QString + \row + \li TEXT + \li Character string (UTF-8, UTF-16BE or UTF-16-LE). + \li Mapped to QString + \row + \li CLOB + \li Character large string object + \li Mapped to QString + \row + \li BLOB + \li The value is a BLOB of data, stored exactly as it was input. + \li Mapped to QByteArray + \endtable + + \section2 Sybase Adaptive Server Data Types + + \table 90% + \header + \li Sybase Adaptive Server data type + \li SQL type description + \li Recommended input (C++ or Qt data type) + \row + \li BINARY + \li Describes a fixed-length binary value up to 255 bytes in size. + \li Mapped to QByteArray + \row + \li CHAR + \li Character String + \li Mapped to QString + \row + \li DATETIME + \li Date and time. Range: 1753-01-01 00:00:00 through 9999-12-31 23:59:59. + \li Mapped to QDateTime + \row + \li NCHAR + \li Character String of fixed length + \li Mapped to QString + \row + \li NVARACHAR + \li Character String of variable length + \li Mapped to QString + \row + \li VARCHAR + \li Character String of fixed length + \li Mapped to QString + \row + \li CLOB + \li Character large string object + \li Mapped to QString + \row + \li TIMESTAMP + \li A unique number within a database + \li Mapped to QString + \row + \li SMALLDATETIME + \li Date and time. Range: 1900-01-01 00:00 through 2079-12-31 23:59 + \li Mapped to QDateTime + \row + \li UNICHAR + \li Character String of fixed length.(Unicode) + \li Mapped to QString + \row + \li UNIVARCHAR + \li Character String of variable length.(Unicode) + \li Mapped to QString + \row + \li VARBINARY + \li Describes a variable-length binary value up to 255 bytes in size + \li Mapped to QByteArray + \endtable + + \section2 SQLite Version 2 + + SQLite version 2 is "typeless". This means that you can store any kind of + data you want in any column of any table, regardless of the declared + data type of that column. We recommend that you map the data to QString. +*/ diff --git a/src/sql/doc/src/qtsql.qdoc b/src/sql/doc/src/qtsql.qdoc new file mode 100644 index 0000000000..594a812bb9 --- /dev/null +++ b/src/sql/doc/src/qtsql.qdoc @@ -0,0 +1,45 @@ +/**************************************************************************** +** +** Copyright (C) 2012 Nokia Corporation and/or its subsidiary(-ies). +** Contact: http://www.qt-project.org/ +** +** This file is part of the documentation of the Qt Toolkit. +** +** $QT_BEGIN_LICENSE:FDL$ +** GNU Free Documentation License +** Alternatively, this file may be used under the terms of the GNU Free +** Documentation License version 1.3 as published by the Free Software +** Foundation and appearing in the file included in the packaging of +** this file. +** +** Other Usage +** Alternatively, this file may be used in accordance with the terms +** and conditions contained in a signed written agreement between you +** and Nokia. +** +** +** +** +** +** $QT_END_LICENSE$ +** +****************************************************************************/ + +/*! + \module QtSql + \title Qt SQL Module + \ingroup modules + + To include the definitions of the module's classes, use the + following directive: + + \snippet code/doc_src_qtsql.cpp 0 + + To link against the module, add this line to your \l qmake \c + .pro file: + + \snippet code/doc_src_qtsql.pro 1 + + See the \l{SQL Programming} guide for information about using this + module in your applications. +*/ diff --git a/src/sql/doc/src/sql-driver.qdoc b/src/sql/doc/src/sql-driver.qdoc new file mode 100644 index 0000000000..7311416563 --- /dev/null +++ b/src/sql/doc/src/sql-driver.qdoc @@ -0,0 +1,830 @@ +/**************************************************************************** +** +** Copyright (C) 2012 Nokia Corporation and/or its subsidiary(-ies). +** Contact: http://www.qt-project.org/ +** +** This file is part of the documentation of the Qt Toolkit. +** +** $QT_BEGIN_LICENSE:FDL$ +** GNU Free Documentation License +** Alternatively, this file may be used under the terms of the GNU Free +** Documentation License version 1.3 as published by the Free Software +** Foundation and appearing in the file included in the packaging of +** this file. +** +** Other Usage +** Alternatively, this file may be used in accordance with the terms +** and conditions contained in a signed written agreement between you +** and Nokia. +** +** +** +** +** +** $QT_END_LICENSE$ +** +****************************************************************************/ + +/*! + \page sql-driver.html + \title SQL Database Drivers + \brief How to configure and install Qt SQL drivers for supported databases. + + \ingroup qt-sql + + The Qt SQL 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 \li Driver name \li DBMS + \row \li \link #QDB2 QDB2\endlink \li IBM DB2 (version 7.1 and above) + \row \li \link #QIBASE QIBASE\endlink \li Borland InterBase + \row \li \link #QMYSQL QMYSQL\endlink \li MySQL + \row \li \link #QOCI QOCI\endlink \li Oracle Call Interface Driver + \row \li \link #QODBC QODBC\endlink + \li Open Database Connectivity (ODBC) - Microsoft SQL Server and other + ODBC-compliant databases + \row \li \link #QPSQL QPSQL\endlink \li PostgreSQL (versions 7.3 and above) + \row \li \link #QSQLITE2 QSQLITE2\endlink \li SQLite version 2 + \row \li \link #QSQLITE QSQLITE\endlink \li SQLite version 3 + \row \li \link #QTDS QTDS\endlink \li Sybase Adaptive Server \note obsolete from Qt 4.7 + \endtable + + SQLite is the in-process database system with the best test coverage + and support on all platforms. Oracle via OCI, and PostreSQL and MySQL + through either ODBC or a native driver are well-tested on Windows and + Linux. The completeness of the support for other systems depends on the + availability and quality of client libraries. + + \b{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 code/doc_src_sql-driver.qdoc 0 + + The \c configure script cannot detect the necessary 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 code/doc_src_sql-driver.qdoc 1 + + Source code to access the OUT values: + + \snippet code/doc_src_sql-driver.cpp 2 + + \b{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 code/doc_src_sql-driver.qdoc 3 + + After installing Qt, as described in the \l{Installing Qt for X11 + Platforms} document, you also need to install the plugin in the + standard location: + + \snippet 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 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. + + \section3 How to build the MySQL driver for MinGW users + + The following steps have been used successfully for WinXP SP3. In + this example, Qt 4.6.2 is shown. + + \list + + \li Download the following components: + \list + \li \c{MinGW-5.1.6.exe} + \li \c{mingw-utils-0.3.tar.gz} + \li Qt sources, e.g. \c{qt-everywhere-opensource-src-4.6.2.zip} + \li \c{mysql-5.1.35-win32.msi} + \endlist + + \li Install \c{MinGW-5.1.6.exe} in, e.g. \c{C:\MinGW}. + + \li Extract \c{mingw-utils-0.3.tar.gz} into, e.g. \c{C:\MinGW}. + + \li Add the path for \c{MinGW-5.1.6.exe} to your \c{PATH} variable, + e.g. \c{C:\MinGW\bin;} + + \li Extract the Qt sources, (\c{qt-everywhere-opensource-src-4.6.2.zip}), + into, e.g. \c{C:\Qt}. + + \li Add the path for the eventual Qt binary to your \c{PATH} variable, + e.g. \c{C:\Qt\4.6.2\bin;}. + + \li Install MySQL (\c{mysql-5.1.35-win32.msi}), customizing the + components. Select only the headers and libraries. Install in, + e.g. \c{C:\MySQL\MySQL51}. + + \li Open the DOS prompt, go to \c{C:\MySQL\MySQL51\lib\opt}, and run + the following commands: + \list + \li \c{reimp -d libmysql.lib} + \li \c{dlltool -k -d libmysql.def -l libmysql.a} + \endlist + + \li Open the DOS prompt, go to \c{C:\Qt\4.6.2} and run the following commands: + \list + \li \c{configure.exe -debug-and-release -platform win32-g++ -qt-sql-mysql + -l mysql -I C:\MySQL\MySQL51\include -L C:\MySQL\MySQL51\lib\opt} + \li \c{mingw32-make sub-src} + \endlist + This step takes a long time. + + \li Open the DOS prompt, go to + \c{C:\Qt\4.6.2\src\plugins\sqldrivers\mysql} and run the + following command: + \list + \li \c{qmake "INCLUDEPATH+=C:\MySQL\MySQL51\include" "LIBS+=-L. mysql" mysql.pro} + \endlist + + \li Now the following libraries are ready in \c{C:\Qt\4.6.2\plugins\sqldrivers}. + \list + \li \c{libqsqlmysql4.a} + \li \c{libqsqlmysqld4.a} + \li \c{qsqlmysql4.dll} + \li \c{qsqlmysqld4.dll} + \endlist + To use the SDK and QtCreator directly, copy these libraries to + your \c{C:\Qt\...\qt\plugins\sqldrivers\}, and copy + \c{C:\MySQL\MySQL51\lib\opt\libmysql.dll} to your \c{C:\Qt\...\qt\bin\}. + + \endlist + + \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 + \li \c libclntsh.so (all versions) + \li \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 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 code/doc_src_sql-driver.qdoc 7 + + \b{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 application 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 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 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 generally sufficient to build the + plugin. For some versions of Oracle Client, you may also need to select + the "Call Interface (OCI)" option if it is available. + + Build the plugin as follows (here it is assumed that Oracle Client is + installed in \c{C:\oracle}): + + \snippet 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 code/doc_src_sql-driver.qdoc 9 + + \b{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. + + \b{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 code/doc_src_sql-driver.cpp 10 + + \b{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 necessary 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 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 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. + + \b{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 code/doc_src_sql-driver.qdoc 13 + + After installing Qt, as described in the \l{Installing Qt for X11 Platforms} document, + you also need to install the plugin in the standard location: + + \snippet 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 code/doc_src_sql-driver.qdoc 15 + + Users of MinGW may wish to consult the following online document: + \l{PostgreSQL MinGW/Native Windows}. + + \b{Note:} This database plugin is not supported for Windows CE. + + \target QTDS + \section2 QTDS for Sybase Adaptive Server + + \note TDS is no longer used by MS Sql Server, and is superceded by + \l{QODBC}{ODBC}. QTDS is obsolete from Qt 4.7. + + \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 QTDS Plugin on Unix and Mac OS X + + Under Unix, two libraries are available which support the TDS protocol: + + \list + \li 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. + + \li 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 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 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. + + \b{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 code/doc_src_sql-driver.qdoc 18 + + After installing Qt, as described in the \l{Installing Qt for X11 Platforms} document, + you also need to install the plugin in the standard location: + + \snippet 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 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. + + \b{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 pass \c{-system-sqlite} to the configure script to use sqlite + libraries in the operating system. Alternatively, you can build + it manually (replace \c $SQLITE with the directory where + SQLite resides): + + \snippet code/doc_src_sql-driver.qdoc 21 + + After installing Qt, as described in the \l{Installing Qt for X11 Platforms} document, + you also need to install the plugin in the standard location: + + \snippet code/doc_src_sql-driver.qdoc 22 + + On Windows: + + \snippet 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 necessary 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. Firebird + must be used with a server configuration. + + 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 code/doc_src_sql-driver.cpp 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 code/doc_src_sql-driver.cpp 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 code/doc_src_sql-driver.cpp 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 code/doc_src_sql-driver.qdoc 27 + + If you are using Firebird, the Firebird library has to be set explicitly: + + \snippet 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 code/doc_src_sql-driver.qdoc 29 + + If you are using Firebird, the Firebird library has to be set explicitly: + + \snippet 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. + + \b{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 + \li Ensure that you are using a shared Qt library; you cannot use the + plugins with a static build. + \li Ensure that the plugin is in the correct directory. You can use + QApplication::libraryPaths() to determine where Qt looks for plugins. + \li 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. + \li Compile Qt with \c{QT_DEBUG_COMPONENT} defined to get very verbose + debug output when loading plugins. + \endlist + + Make sure you have followed the guide to \l{Deploying Plugins}. + If you experience plugin load problems and see output like this: + + \snippet code/doc_src_sql-driver.cpp 31 + + the problem is usually that the plugin had the wrong \l{Deploying + Plugins#The Build Key}{build key}. This might require removing an + entry from the \l{Deploying Plugins#The Plugin Cache} {plugin cache}. + + \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 sqldatabase/sqldatabase.cpp 47 + \codeline + \snippet sqldatabase/sqldatabase.cpp 48 +*/ diff --git a/src/sql/doc/src/sql-programming.qdoc b/src/sql/doc/src/sql-programming.qdoc new file mode 100644 index 0000000000..53f89e72c9 --- /dev/null +++ b/src/sql/doc/src/sql-programming.qdoc @@ -0,0 +1,609 @@ +/**************************************************************************** +** +** Copyright (C) 2012 Nokia Corporation and/or its subsidiary(-ies). +** Contact: http://www.qt-project.org/ +** +** This file is part of the documentation of the Qt Toolkit. +** +** $QT_BEGIN_LICENSE:FDL$ +** GNU Free Documentation License +** Alternatively, this file may be used under the terms of the GNU Free +** Documentation License version 1.3 as published by the Free Software +** Foundation and appearing in the file included in the packaging of +** this file. +** +** Other Usage +** Alternatively, this file may be used in accordance with the terms +** and conditions contained in a signed written agreement between you +** and Nokia. +** +** +** +** +** +** $QT_END_LICENSE$ +** +****************************************************************************/ + +/*! + \group database + \title Database Classes + + \brief Database related classes, e.g. for SQL databases. +*/ + +/*! + \page sql-programming.html + \title SQL Programming + \ingroup qt-sql + \nextpage Connecting to Databases + + \brief Database integration for Qt applications. + + This overview assumes that you have at least a basic knowledge of + SQL. You should be able to understand simple \c SELECT, \c + INSERT, \c UPDATE, and \c DELETE statements. Although the \l + QSqlTableModel class provides an interface to database browsing + and editing that does not require a knowledge of SQL, a basic + understanding of SQL is highly recommended. A standard text + covering SQL databases is \e {An Introduction to Database Systems} + (7th Ed.) by C. J. Date, ISBN 0201385902. + + \section1 Topics: + + \list + \li \l{Database Classes} + \li \l{Connecting to Databases} + \list + \li \l{SQL Database Drivers} + \endlist + \li \l{Executing SQL Statements} + \list + \li \l{Data Types for Qt-supported Database Systems} + \endlist + \li \l{Using the SQL Model Classes} + \li \l{Presenting Data in a Table View} + \li \l{Creating Data-Aware Forms} + \endlist + + \section1 Database Classes + + These classes provide access to SQL databases. + + \annotatedlist database + + The SQL classes are divided into three layers: + + \section2 Driver Layer + + This comprises the classes QSqlDriver, QSqlDriverCreator<T>, + QSqlDriverCreatorBase, QSqlDriverPlugin, and QSqlResult. + + This layer provides the low-level bridge between the specific databases + and the SQL API layer. See \l{SQL Database Drivers} for more information. + + \section2 SQL API Layer + + These classes provide access to databases. Connections + are made using the QSqlDatabase class. Database + interaction is achieved by using the QSqlQuery class. + In addition to QSqlDatabase and QSqlQuery, the SQL API + layer is supported by QSqlError, QSqlField, QSqlIndex, + and QSqlRecord. + + \section2 User Interface Layer + + These classes link the data from a database to data-aware widgets. + They include QSqlQueryModel, QSqlTableModel, and QSqlRelationalTableModel. + These classes are designed to work with Qt's + \l{Model/View Programming}{model/view framework}. + + Note that to use any of these classes, a QCoreApplication object + must have been instantiated first. +*/ + +/*! + \page sql-connecting.html + \title Connecting to Databases + \ingroup qt-sql + + \contentspage SQL Programming + \previouspage SQL Programming + \nextpage Executing SQL Statements + + To access a database with QSqlQuery or QSqlQueryModel, create and + open one or more database connections. Database connections are + normally identified by connection name, \e{not} by database name. + You can have multiple connections to the same database. + QSqlDatabase also supports the concept of a \e{default} + connection, which is an unnamed connection. When calling QSqlQuery + or QSqlQueryModel member functions that take a connection name + argument, if you don't pass a connection name, the default + connection will be used. Creating a default connection is + convenient when your application only requires one database + connection. + + Note the difference between creating a connection and opening it. + Creating a connection involves creating an instance of class + QSqlDatabase. The connection is not usable until it is opened. The + following snippet shows how to create a \e{default} connection + and then open it: + + \snippet sqldatabase/sqldatabase.cpp 26 + + The first line creates the connection object, and the last line + opens it for use. In between, we initialize some connection + information, including the \l{QSqlDatabase::setDatabaseName()} + {database name}, the \l{QSqlDatabase::setHostName()} {host name}, + the \l{QSqlDatabase::setUserName()} {user name}, and the + \l{QSqlDatabase::setPassword()} {password}. In this case, we are + connecting to the MySQL database \c{flightdb} on the host + \c{bigblue}. The \c{"QMYSQL"} argument to + \l{QSqlDatabase::addDatabase()} {addDatabase()} specifies the type + of database driver to use for the connection. The set of database + drivers included with Qt are shown in the table of \l{SQL Database + Drivers#Supported Databases} {supported database drivers}. + + The connection in the snippet will be the \e{default} connection, + because we don't pass the second argument to + \l{QSqlDatabase::addDatabase()} {addDatabase()}, which is the + connection name. For example, here we establish two MySQL database + connections named \c{"first"} and \c{"second"}: + + \snippet sqldatabase/sqldatabase.cpp 27 + + After these connections have been initialized, \l{QSqlDatabase::} + {open()} for each one to establish the live connections. If the + \l{QSqlDatabase::} {open()} fails, it returns false. In that case, + call QSqlDatabase::lastError() to get error information. + + Once a connection is established, we can call the static function + QSqlDatabase::database() from anywhere with a connection name to + get a pointer to that database connection. If we don't pass a + connection name, it will return the default connection. For + example: + + \snippet sqldatabase/sqldatabase.cpp 28 + \snippet sqldatabase/sqldatabase.cpp 29 + \snippet sqldatabase/sqldatabase.cpp 30 + + To remove a database connection, first close the database using + QSqlDatabase::close(), then remove it using the static method + QSqlDatabase::removeDatabase(). +*/ + +/*! + \page sql-sqlstatements.html + \title Executing SQL Statements + \ingroup qt-sql + + \previouspage Connecting to Databases + \contentspage SQL Programming + \nextpage Using the SQL Model Classes + + + The QSqlQuery class provides an interface for executing SQL + statements and navigating through the result set of a query. + + The QSqlQueryModel and QSqlTableModel classes described in the + next section provide a higher-level interface for accessing + databases. If you are unfamiliar with SQL, you might want to skip + directly to the next section (\l{Using the SQL Model Classes}). + + \section2 Executing a Query + + To execute an SQL statement, simply create a QSqlQuery object and + call QSqlQuery::exec() like this: + + \snippet sqldatabase/sqldatabase.cpp 31 + + The QSqlQuery constructor accepts an optional QSqlDatabase object + that specifies which database connection to use. In the example + above, we don't specify any connection, so the default connection + is used. + + If an error occurs, \l{QSqlQuery::exec()}{exec()} returns false. + The error is then available as QSqlQuery::lastError(). + + \section2 Navigating the Result Set + + QSqlQuery provides access to the result set one record at a time. + After the call to \l{QSqlQuery::exec()}{exec()}, QSqlQuery's + internal pointer is located one position \e{before} the first + record. We must call QSqlQuery::next() once to advance to the + first record, then \l{QSqlQuery::next()}{next()} again repeatedly + to access the other records, until it returns false. Here's a + typical loop that iterates over all the records in order: + + \snippet sqldatabase/sqldatabase.cpp 32 + + The QSqlQuery::value() function returns the value of a field in + the current record. Fields are specified as zero-based indexes. + QSqlQuery::value() returns a QVariant, a type that can hold + various C++ and core Qt data types such as \c int, QString, and + QByteArray. The different database types are automatically mapped + into the closest Qt equivalent. In the code snippet, we call + QVariant::toString() and QVariant::toInt() to convert + variants to QString and \c int. + + For an overview of the recommended types for use with Qt-supported + Databases, please refer to \l{Data Types for Qt-supported Database + Systems} {this table}. + + You can iterate back and forth using QSqlQuery::next(), + QSqlQuery::previous(), QSqlQuery::first(), QSqlQuery::last(), and + QSqlQuery::seek(). The current row index is returned by + QSqlQuery::at(), and the total number of rows in the result set + is available as QSqlQuery::size() for databases that support it. + + To determine whether a database driver supports a given feature, + use QSqlDriver::hasFeature(). In the following example, we call + QSqlQuery::size() to determine the size of a result set of + the underlying database supports that feature; otherwise, we + navigate to the last record and use the query's position to tell + us how many records there are. + + \snippet sqldatabase/sqldatabase.cpp 33 + + If you iterate through a result set only using next() and seek() + with positive values, you can call + QSqlQuery::setForwardOnly(true) before calling exec(). This is an + easy optimization that will speed up the query significantly when + operating on large result sets. + + \section2 Inserting, Updating, and Deleting Records + + QSqlQuery can execute arbitrary SQL statements, not just + \c{SELECT}s. The following example inserts a record into a table + using \c{INSERT}: + + \snippet sqldatabase/sqldatabase.cpp 34 + + If you want to insert many records at the same time, it is often + more efficient to separate the query from the actual values being + inserted. This can be done using placeholders. Qt supports two + placeholder syntaxes: named binding and positional binding. + Here's an example of named binding: + + \snippet sqldatabase/sqldatabase.cpp 35 + + Here's an example of positional binding: + + \snippet sqldatabase/sqldatabase.cpp 36 + + Both syntaxes work with all database drivers provided by Qt. If + the database supports the syntax natively, Qt simply forwards the + query to the DBMS; otherwise, Qt simulates the placeholder syntax + by preprocessing the query. The actual query that ends up being + executed by the DBMS is available as QSqlQuery::executedQuery(). + + When inserting multiple records, you only need to call + QSqlQuery::prepare() once. Then you call + \l{QSqlQuery::bindValue()}{bindValue()} or + \l{QSqlQuery::addBindValue()}{addBindValue()} followed by + \l{QSqlQuery::exec()}{exec()} as many times as necessary. + + Besides performance, one advantage of placeholders is that you + can easily specify arbitrary values without having to worry about + escaping special characters. + + Updating a record is similar to inserting it into a table: + + \snippet sqldatabase/sqldatabase.cpp 37 + + You can also use named or positional binding to associate + parameters to actual values. + + Finally, here's an example of a \c DELETE statement: + + \snippet sqldatabase/sqldatabase.cpp 38 + + \section2 Transactions + + If the underlying database engine supports transactions, + QSqlDriver::hasFeature(QSqlDriver::Transactions) will return + true. You can use QSqlDatabase::transaction() to initiate a + transaction, followed by the SQL commands you want to execute + within the context of the transaction, and then either + QSqlDatabase::commit() or QSqlDatabase::rollback(). When + using transactions you must start the transaction before you + create your query. + + Example: + + \snippet sqldatabase/sqldatabase.cpp 39 + + Transactions can be used to ensure that a complex operation is + atomic (for example, looking up a foreign key and creating a + record), or to provide a means of canceling a complex change in + the middle. + + \omit + It would be useful to mention transactions, and the fact that + some databases don't support them. + \endomit +*/ + +/*! + \page sql-model.html + \title Using the SQL Model Classes + \ingroup qt-sql + + \previouspage Executing SQL Statements + \contentspage SQL Programming + \nextpage Presenting Data in a Table View + + In addition to QSqlQuery, Qt offers three higher-level classes + for accessing databases. These classes are QSqlQueryModel, + QSqlTableModel, and QSqlRelationalTableModel. + + \table + \row \li QSqlQueryModel + \li A read-only model based on an arbitrary SQL query. + \row \li QSqlTableModel + \li A read-write model that works on a single table. + \row \li QSqlRelationalTableModel + \li A QSqlTableModel subclass with foreign key support. + \endtable + + These classes derive from QAbstractTableModel (which in turn + inherits from QAbstractItemModel) and make it easy to present + data from a database in an item view class such as QListView and + QTableView. This is explained in detail in the \l{Presenting Data + in a Table View} section. + + Another advantage of using these classes is that it can make your + code easier to adapt to other data sources. For example, if you + use QSqlTableModel and later decide to use XML files to store + data instead of a database, it is essentially just a matter of + replacing one data model with another. + + \section2 The SQL Query Model + + QSqlQueryModel offers a read-only model based on an SQL query. + + Example: + + \snippet sqldatabase/sqldatabase.cpp 40 + + After setting the query using QSqlQueryModel::setQuery(), you can + use QSqlQueryModel::record(int) to access the individual records. + You can also use QSqlQueryModel::data() and any of the other + functions inherited from QAbstractItemModel. + + There's also a \l{QSqlQueryModel::setQuery()}{setQuery()} + overload that takes a QSqlQuery object and operates on its result + set. This enables you to use any features of QSqlQuery to set up + the query (e.g., prepared queries). + + \section2 The SQL Table Model + + QSqlTableModel offers a read-write model that works on a single + SQL table at a time. + + Example: + + \snippet sqldatabase/sqldatabase.cpp 41 + + QSqlTableModel is a high-level alternative to QSqlQuery for + navigating and modifying individual SQL tables. It typically + results in less code and requires no knowledge of SQL syntax. + + Use QSqlTableModel::record() to retrieve a row in the table, and + QSqlTableModel::setRecord() to modify the row. For example, the + following code will increase every employee's salary by 10 per + cent: + + \snippet sqldatabase/sqldatabase.cpp 42 + + You can also use QSqlTableModel::data() and + QSqlTableModel::setData(), which are inherited from + QAbstractItemModel, to access the data. For example, here's how + to update a record using + \l{QSqlTableModel::setData()}{setData()}: + + \snippet sqldatabase/sqldatabase.cpp 43 + + Here's how to insert a row and populate it: + + \snippet sqldatabase/sqldatabase.cpp 44 + + Here's how to delete five consecutive rows: + + \snippet sqldatabase/sqldatabase.cpp 45 + \snippet sqldatabase/sqldatabase.cpp 46 + + The first argument to QSqlTableModel::removeRows() is the index + of the first row to delete. + + When you're finished changing a record, you should always call + QSqlTableModel::submitAll() to ensure that the changes are + written to the database. + + When and whether you actually \e need to call submitAll() depends + on the table's \l{QSqlTableModel::editStrategy()}{edit strategy}. + The default strategy is QSqlTableModel::OnRowChange, which + specifies that pending changes are applied to the database when + the user selects a different row. Other strategies are + QSqlTableModel::OnManualSubmit (where all changes are cached in + the model until you call submitAll()) and + QSqlTableModel::OnFieldChange (where no changes are cached). + These are mostly useful when QSqlTableModel is used with a view. + + QSqlTableModel::OnFieldChange seems to deliver the promise that + you never need to call submitAll() explicitly. There are two + pitfalls, though: + + \list + \li Without any caching, performance may drop significantly. + \li If you modify a primary key, the record might slip through + your fingers while you are trying to populate it. + \endlist + + \section2 The SQL Relational Table Model + + QSqlRelationalTableModel extends QSqlTableModel to provide + support for foreign keys. A foreign key is a 1-to-1 mapping + between a field in one table and the primary key field of another + table. For example, if a \c book table has a field called \c + authorid that refers to the author table's \c id field, we say + that \c authorid is a foreign key. + + \table + \row \li \inlineimage noforeignkeys.png + \li \inlineimage foreignkeys.png + \endtable + + The screenshot on the left shows a plain QSqlTableModel in a + QTableView. Foreign keys (\c city and \c country) aren't resolved + to human-readable values. The screenshot on the right shows a + QSqlRelationalTableModel, with foreign keys resolved into + human-readable text strings. + + The following code snippet shows how the QSqlRelationalTableModel + was set up: + + \snippet sql/relationaltablemodel/relationaltablemodel.cpp 0 + \codeline + \snippet sql/relationaltablemodel/relationaltablemodel.cpp 1 + \snippet sql/relationaltablemodel/relationaltablemodel.cpp 2 + + See the QSqlRelationalTableModel documentation for details. +*/ + +/*! + \page sql-presenting.html + \title Presenting Data in a Table View + \ingroup qt-sql + + \previouspage Using the SQL Model Classes + \contentspage SQL Programming + \nextpage Creating Data-Aware Forms + + The QSqlQueryModel, QSqlTableModel, and QSqlRelationalTableModel + classes can be used as a data source for Qt's view classes such + as QListView, QTableView, and QTreeView. In practice, QTableView + is by far the most common choice, because an SQL result set is + essentially a two-dimensional data structure. + + \image relationaltable.png A table view displaying a QSqlTableModel + + The following example creates a view based on an SQL data model: + + \snippet sqldatabase/sqldatabase.cpp 17 + \snippet sqldatabase/sqldatabase.cpp 18 + \snippet sqldatabase/sqldatabase.cpp 19 + + If the model is a read-write model (e.g., QSqlTableModel), the + view lets the user edit the fields. You can disable this by + calling + + \snippet sqldatabase/sqldatabase.cpp 20 + + You can use the same model as a data source for multiple views. + If the user edits the model through one of the views, the other + views will reflect the changes immediately. The + \l{sql/tablemodel}{Table Model} example shows how it works. + + View classes display a header at the top to label the columns. To + change the header texts, call + \l{QAbstractItemModel::setHeaderData()}{setHeaderData()} on the + model. The header's labels default to the table's field names. + For example: + + \snippet sql/relationaltablemodel/relationaltablemodel.cpp 3 + + QTableView also has a vertical header on the left with numbers + identifying the rows. If you insert rows programmatically using + QSqlTableModel::insertRows(), the new rows will be marked with an + asterisk (*) until they are submitted using + \l{QSqlTableModel::submitAll()}{submitAll()} or automatically + when the user moves to another record (assuming the + \l{QSqlTableModel::EditStrategy}{edit strategy} is + QSqlTableModel::OnRowChange). + + \image insertrowinmodelview.png Inserting a row in a model + + Likewise, if you remove rows using + \l{QSqlTableModel::removeRows()}{removeRows()}, the rows will be + marked with an exclamation mark (!) until the change is + submitted. + + The items in the view are rendered using a delegate. The default + delegate, QItemDelegate, handles the most common data types (\c + int, QString, QImage, etc.). The delegate is also responsible for + providing editor widgets (e.g., a combobox) when the user starts + editing an item in the view. You can create your own delegates by + subclassing QAbstractItemDelegate or QItemDelegate. See + \l{Model/View Programming} for more information. + + QSqlTableModel is optimized to operate on a single table at a + time. If you need a read-write model that operates on an + arbitrary result set, you can subclass QSqlQueryModel and + reimplement \l{QAbstractItemModel::flags()}{flags()} and + \l{QAbstractItemModel::setData()}{setData()} to make it + read-write. The following two functions make fields 1 and 2 of a + query model editable: + + \snippet sql/querymodel/editablesqlmodel.cpp 0 + \codeline + \snippet sql/querymodel/editablesqlmodel.cpp 1 + + The setFirstName() helper function is defined as follows: + + \snippet sql/querymodel/editablesqlmodel.cpp 2 + + The setLastName() function is similar. See the + \l{sql/querymodel}{Query Model} example for the complete source code. + + Subclassing a model makes it possible to customize it in many + ways: You can provide tooltips for the items, change the + background color, provide calculated values, provide different + values for viewing and editing, handle null values specially, and + more. See \l{Model/View Programming} as well as the \l + QAbstractItemView reference documentation for details. + + If all you need is to resolve a foreign key to a more + human-friendly string, you can use QSqlRelationalTableModel. For + best results, you should also use QSqlRelationalDelegate, a + delegate that provides combobox editors for editing foreign keys. + + \image relationaltable.png Editing a foreign key in a relational table + + The \l{sql/relationaltablemodel}{Relational Table Model} example + illustrates how to use QSqlRelationalTableModel in conjunction with + QSqlRelationalDelegate to provide tables with foreign key + support. +*/ + +/*! + \page sql-forms.html + \title Creating Data-Aware Forms + \ingroup qt-sql + + \previouspage Presenting Data in a Table View + \contentspage SQL Programming + + Using the SQL models described above, the contents of a database can + be presented to other model/view components. For some applications, + it is sufficient to present this data using a standard item view, + such as QTableView. However, users of record-based applications often + require a form-based user interface in which data from a specific + row or column in a database table is used to populate editor widgets + on a form. + + Such data-aware forms can be created with the QDataWidgetMapper class, + a generic model/view component that is used to map data from a model + to specific widgets in a user interface. + + QDataWidgetMapper operates on a specific database table, mapping items + in the table on a row-by-row or column-by-column basis. As a result, + using QDataWidgetMapper with a SQL model is as simple as using it with + any other table model. + + \image qdatawidgetmapper-simple.png + + The \l{sql/books}{Books} example shows how information can + be presented for easy access by using QDataWidgetMapper and a set of + simple input widgets. +*/ diff --git a/src/sql/kernel/qsql.qdoc b/src/sql/kernel/qsql.qdoc index 394c255b35..6fbfc0415d 100644 --- a/src/sql/kernel/qsql.qdoc +++ b/src/sql/kernel/qsql.qdoc @@ -35,7 +35,7 @@ \ingroup database - \sa {QtSql Module} + \sa {Qt SQL Module} */ /*! diff --git a/src/sql/kernel/qsqldatabase.cpp b/src/sql/kernel/qsqldatabase.cpp index d4633cea57..f44f475d6c 100644 --- a/src/sql/kernel/qsqldatabase.cpp +++ b/src/sql/kernel/qsqldatabase.cpp @@ -390,7 +390,7 @@ void QSqlDatabasePrivate::disable() snippet shows how to create and open a default connection to a PostgreSQL database: - \snippet doc/src/snippets/sqldatabase/sqldatabase.cpp 0 + \snippet sqldatabase/sqldatabase.cpp 0 Once the QSqlDatabase object has been created, set the connection parameters with setDatabaseName(), setUserName(), setPassword(), @@ -403,7 +403,7 @@ void QSqlDatabasePrivate::disable() {addDatabase()}. Subsequently, you can get the default connection by calling database() without the connection name argument: - \snippet doc/src/snippets/sqldatabase/sqldatabase.cpp 1 + \snippet sqldatabase/sqldatabase.cpp 1 QSqlDatabase is a value class. Changes made to a database connection via one instance of QSqlDatabase will affect other @@ -440,7 +440,7 @@ void QSqlDatabasePrivate::disable() If you have created your own custom driver, you must register it with registerSqlDriver(). - \sa QSqlDriver, QSqlQuery, {QtSql Module}, {Threads and the SQL Module} + \sa QSqlDriver, QSqlQuery, {Qt SQL Module}, {Threads and the SQL Module} */ /*! \fn QSqlDatabase QSqlDatabase::addDatabase(const QString &type, const QString &connectionName) @@ -472,7 +472,7 @@ void QSqlDatabasePrivate::disable() setHostName(), setPort(), and setConnectOptions(), and, finally, open(). - \sa database() removeDatabase() {Threads and the SQL Module} + \sa database(), removeDatabase(), {Threads and the SQL Module} */ QSqlDatabase QSqlDatabase::addDatabase(const QString &type, const QString &connectionName) { @@ -492,7 +492,7 @@ QSqlDatabase QSqlDatabase::addDatabase(const QString &type, const QString &conne connectionName does not exist in the list of databases, an invalid connection is returned. - \sa isOpen() {Threads and the SQL Module} + \sa isOpen(), {Threads and the SQL Module} */ QSqlDatabase QSqlDatabase::database(const QString& connectionName, bool open) @@ -512,11 +512,11 @@ QSqlDatabase QSqlDatabase::database(const QString& connectionName, bool open) Example: - \snippet doc/src/snippets/code/src_sql_kernel_qsqldatabase.cpp 0 + \snippet code/src_sql_kernel_qsqldatabase.cpp 0 The correct way to do it: - \snippet doc/src/snippets/code/src_sql_kernel_qsqldatabase.cpp 1 + \snippet code/src_sql_kernel_qsqldatabase.cpp 1 To remove the default connection, which may have been created with a call to addDatabase() not specifying a connection name, you can @@ -524,7 +524,7 @@ QSqlDatabase QSqlDatabase::database(const QString& connectionName, bool open) the database returned by database(). Note that if a default database hasn't been created an invalid database will be returned. - \sa database() connectionName() {Threads and the SQL Module} + \sa database(), connectionName(), {Threads and the SQL Module} */ void QSqlDatabase::removeDatabase(const QString& connectionName) @@ -600,7 +600,7 @@ QStringList QSqlDatabase::drivers() and don't want to compile it as a plugin. Example: - \snippet doc/src/snippets/code/src_sql_kernel_qsqldatabase.cpp 2 + \snippet code/src_sql_kernel_qsqldatabase.cpp 2 QSqlDatabase takes ownership of the \a creator pointer, so you mustn't delete it yourself. @@ -831,8 +831,8 @@ QSqlQuery QSqlDatabase::exec(const QString & query) const values. Returns true on success; otherwise returns false. Error information can be retrieved using lastError(). - \sa lastError() setDatabaseName() setUserName() setPassword() - \sa setHostName() setPort() setConnectOptions() + \sa lastError(), setDatabaseName(), setUserName(), setPassword(), + setHostName(), setPort(), setConnectOptions() */ bool QSqlDatabase::open() @@ -924,7 +924,7 @@ bool QSqlDatabase::transaction() Call lastError() to get information about errors. - \sa QSqlQuery::isActive() QSqlDriver::hasFeature() rollback() + \sa QSqlQuery::isActive(), QSqlDriver::hasFeature(), rollback() */ bool QSqlDatabase::commit() { @@ -945,7 +945,7 @@ bool QSqlDatabase::commit() Call lastError() to get information about errors. - \sa QSqlQuery::isActive() QSqlDriver::hasFeature() commit() + \sa QSqlQuery::isActive(), QSqlDriver::hasFeature(), commit() */ bool QSqlDatabase::rollback() { @@ -974,12 +974,12 @@ bool QSqlDatabase::rollback() connection string to open an \c .mdb file directly, instead of having to create a DSN entry in the ODBC manager: - \snippet doc/src/snippets/code/src_sql_kernel_qsqldatabase.cpp 3 + \snippet code/src_sql_kernel_qsqldatabase.cpp 3 There is no default value. - \sa databaseName() setUserName() setPassword() setHostName() - \sa setPort() setConnectOptions() open() + \sa databaseName(), setUserName(), setPassword(), setHostName(), + setPort(), setConnectOptions(), open() */ void QSqlDatabase::setDatabaseName(const QString& name) @@ -996,8 +996,8 @@ void QSqlDatabase::setDatabaseName(const QString& name) There is no default value. - \sa userName() setDatabaseName() setPassword() setHostName() - \sa setPort() setConnectOptions() open() + \sa userName(), setDatabaseName(), setPassword(), setHostName(), + setPort(), setConnectOptions(), open() */ void QSqlDatabase::setUserName(const QString& name) @@ -1018,8 +1018,8 @@ void QSqlDatabase::setUserName(const QString& name) Qt. Use the open() call that takes a password as parameter to avoid this behavior. - \sa password() setUserName() setDatabaseName() setHostName() - \sa setPort() setConnectOptions() open() + \sa password(), setUserName(), setDatabaseName(), setHostName(), + setPort(), setConnectOptions(), open() */ void QSqlDatabase::setPassword(const QString& password) @@ -1036,8 +1036,8 @@ void QSqlDatabase::setPassword(const QString& password) There is no default value. - \sa hostName() setUserName() setPassword() setDatabaseName() - \sa setPort() setConnectOptions() open() + \sa hostName(), setUserName(), setPassword(), setDatabaseName(), + setPort(), setConnectOptions(), open() */ void QSqlDatabase::setHostName(const QString& host) @@ -1054,8 +1054,8 @@ void QSqlDatabase::setHostName(const QString& host) There is no default value. - \sa port() setUserName() setPassword() setHostName() - \sa setDatabaseName() setConnectOptions() open() + \sa port(), setUserName(), setPassword(), setHostName(), + setDatabaseName(), setConnectOptions(), open() */ void QSqlDatabase::setPort(int port) @@ -1130,7 +1130,7 @@ int QSqlDatabase::port() const Returns the database driver used to access the database connection. - \sa addDatabase() drivers() + \sa addDatabase(), drivers() */ QSqlDriver* QSqlDatabase::driver() const @@ -1278,7 +1278,7 @@ QSqlRecord QSqlDatabase::record(const QString& tablename) const \endtable Examples: - \snippet doc/src/snippets/code/src_sql_kernel_qsqldatabase.cpp 4 + \snippet code/src_sql_kernel_qsqldatabase.cpp 4 Refer to the client library documentation for more information about the different options. @@ -1325,9 +1325,9 @@ bool QSqlDatabase::isDriverAvailable(const QString& name) application. For example, you can create a PostgreSQL connection with your own QPSQL driver like this: - \snippet doc/src/snippets/code/src_sql_kernel_qsqldatabase.cpp 5 + \snippet code/src_sql_kernel_qsqldatabase.cpp 5 \codeline - \snippet doc/src/snippets/code/src_sql_kernel_qsqldatabase.cpp 6 + \snippet code/src_sql_kernel_qsqldatabase.cpp 6 The above code sets up a PostgreSQL connection and instantiates a QPSQLDriver object. Next, addDatabase() is called to add the @@ -1346,7 +1346,7 @@ bool QSqlDatabase::isDriverAvailable(const QString& name) client library. Make sure the client library is in your linker's search path, and add lines like these to your \c{.pro} file: - \snippet doc/src/snippets/code/src_sql_kernel_qsqldatabase.cpp 7 + \snippet code/src_sql_kernel_qsqldatabase.cpp 7 The method described works for all the supplied drivers. The only difference will be in the driver constructor arguments. Here is a @@ -1423,7 +1423,7 @@ QSqlDatabase QSqlDatabase::addDatabase(QSqlDriver* driver, const QString& connec Returns true if the QSqlDatabase has a valid driver. Example: - \snippet doc/src/snippets/code/src_sql_kernel_qsqldatabase.cpp 8 + \snippet code/src_sql_kernel_qsqldatabase.cpp 8 */ bool QSqlDatabase::isValid() const { diff --git a/src/sql/kernel/qsqldriver.cpp b/src/sql/kernel/qsqldriver.cpp index f48673f28f..284ef84f2d 100644 --- a/src/sql/kernel/qsqldriver.cpp +++ b/src/sql/kernel/qsqldriver.cpp @@ -133,7 +133,7 @@ QSqlDriver::~QSqlDriver() /*! \since 5.0 - \fn QSqlDriver::notification(const QString &name, NotificationSource source, const QString & payload) + \fn QSqlDriver::notification(const QString &name, QSqlDriver::NotificationSource source, const QVariant & payload) This signal is emitted when the database posts an event notification that the driver subscribes to. \a name identifies the event notification, \a source indicates the signal source, @@ -682,11 +682,11 @@ QString QSqlDriver::formatValue(const QSqlField &field, bool trimStrings) const This example retrieves the handle for a connection to sqlite: - \snippet doc/src/snippets/code/src_sql_kernel_qsqldriver.cpp 0 + \snippet code/src_sql_kernel_qsqldriver.cpp 0 This snippet returns the handle for PostgreSQL or MySQL: - \snippet doc/src/snippets/code/src_sql_kernel_qsqldriver.cpp 1 + \snippet code/src_sql_kernel_qsqldriver.cpp 1 \sa QSqlResult::handle() */ @@ -696,36 +696,6 @@ QVariant QSqlDriver::handle() const } /*! - \fn QSqlRecord QSqlDriver::record(const QSqlQuery& query) const - - Use query.record() instead. -*/ - -/*! - \fn QSqlRecord QSqlDriver::recordInfo(const QString& tablename) const - - Use record() instead. -*/ - -/*! - \fn QSqlRecord QSqlDriver::recordInfo(const QSqlQuery& query) const - - Use query.record() instead. -*/ - -/*! - \fn QString QSqlDriver::nullText() const - - sqlStatement() is now used to generate SQL. Use tr("NULL") for example, instead. -*/ - -/*! - \fn QString QSqlDriver::formatValue(const QSqlField *field, bool trimStrings) const - - Use the other formatValue() overload instead. -*/ - -/*! This function is called to subscribe to event notifications from the database. \a name identifies the event notification. @@ -743,7 +713,7 @@ QVariant QSqlDriver::handle() const own QSqlDriver subclass, \since 4.4 - \sa unsubscribeFromNotification() subscribedToNotifications() QSqlDriver::hasFeature() + \sa unsubscribeFromNotification(), subscribedToNotifications(), QSqlDriver::hasFeature() */ bool QSqlDriver::subscribeToNotification(const QString &name) { @@ -767,7 +737,7 @@ bool QSqlDriver::subscribeToNotification(const QString &name) own QSqlDriver subclass, \since 4.4 - \sa subscribeToNotification() subscribedToNotifications() + \sa subscribeToNotification(), subscribedToNotifications() */ bool QSqlDriver::unsubscribeFromNotification(const QString &name) { @@ -782,7 +752,7 @@ bool QSqlDriver::unsubscribeFromNotification(const QString &name) own QSqlDriver subclass, \since 4.4 - \sa subscribeToNotification() unsubscribeFromNotification() + \sa subscribeToNotification(), unsubscribeFromNotification() */ QStringList QSqlDriver::subscribedToNotifications() const { diff --git a/src/sql/kernel/qsqlerror.cpp b/src/sql/kernel/qsqlerror.cpp index 79c7ee02c2..c1314a15a5 100644 --- a/src/sql/kernel/qsqlerror.cpp +++ b/src/sql/kernel/qsqlerror.cpp @@ -155,7 +155,7 @@ QSqlError::~QSqlError() Returns the text of the error as reported by the driver. This may contain database-specific descriptions. It may also be empty. - \sa setDriverText() databaseText() text() + \sa setDriverText(), databaseText(), text() */ QString QSqlError::driverText() const { @@ -165,7 +165,7 @@ QString QSqlError::driverText() const /*! Sets the driver error text to the value of \a driverText. - \sa driverText() setDatabaseText() text() + \sa driverText(), setDatabaseText(), text() */ void QSqlError::setDriverText(const QString& driverText) @@ -177,7 +177,7 @@ void QSqlError::setDriverText(const QString& driverText) Returns the text of the error as reported by the database. This may contain database-specific descriptions; it may be empty. - \sa setDatabaseText() driverText() text() + \sa setDatabaseText(), driverText(), text() */ QString QSqlError::databaseText() const @@ -188,7 +188,7 @@ QString QSqlError::databaseText() const /*! Sets the database error text to the value of \a databaseText. - \sa databaseText() setDriverText() text() + \sa databaseText(), setDriverText(), text() */ void QSqlError::setDatabaseText(const QString& databaseText) @@ -245,7 +245,7 @@ void QSqlError::setNumber(int number) This is a convenience function that returns databaseText() and driverText() concatenated into a single string. - \sa driverText() databaseText() + \sa driverText(), databaseText() */ QString QSqlError::text() const @@ -261,7 +261,7 @@ QString QSqlError::text() const Returns true if an error is set, otherwise false. Example: - \snippet doc/src/snippets/code/src_sql_kernel_qsqlerror.cpp 0 + \snippet code/src_sql_kernel_qsqlerror.cpp 0 \sa type() */ diff --git a/src/sql/kernel/qsqlfield.cpp b/src/sql/kernel/qsqlfield.cpp index 3160d25ef5..47162afb47 100644 --- a/src/sql/kernel/qsqlfield.cpp +++ b/src/sql/kernel/qsqlfield.cpp @@ -113,21 +113,21 @@ public: Field data values are stored as QVariants. Using an incompatible type is not permitted. For example: - \snippet doc/src/snippets/sqldatabase/sqldatabase.cpp 2 + \snippet sqldatabase/sqldatabase.cpp 2 However, the field will attempt to cast certain data types to the field data type where possible: - \snippet doc/src/snippets/sqldatabase/sqldatabase.cpp 3 + \snippet sqldatabase/sqldatabase.cpp 3 QSqlField objects are rarely created explicitly in application code. They are usually accessed indirectly through \l{QSqlRecord}s that already contain a list of fields. For example: - \snippet doc/src/snippets/sqldatabase/sqldatabase.cpp 4 + \snippet sqldatabase/sqldatabase.cpp 4 \dots - \snippet doc/src/snippets/sqldatabase/sqldatabase.cpp 5 - \snippet doc/src/snippets/sqldatabase/sqldatabase.cpp 6 + \snippet sqldatabase/sqldatabase.cpp 5 + \snippet sqldatabase/sqldatabase.cpp 6 A QSqlField object can provide some meta-data about the field, for example, its name(), variant type(), length(), precision(), @@ -157,7 +157,8 @@ public: Constructs an empty field called \a fieldName of variant type \a type. - \sa setRequiredStatus() setLength() setPrecision() setDefaultValue() setGenerated() setReadOnly() + \sa setRequiredStatus(), setLength(), setPrecision(), setDefaultValue(), + setGenerated(), setReadOnly() */ QSqlField::QSqlField(const QString& fieldName, QVariant::Type type) { @@ -216,7 +217,8 @@ QSqlField::~QSqlField() /*! Sets the required status of this field to \a required. - \sa requiredStatus() setType() setLength() setPrecision() setDefaultValue() setGenerated() setReadOnly() + \sa requiredStatus(), setType(), setLength(), setPrecision(), + setDefaultValue(), setGenerated(), setReadOnly() */ void QSqlField::setRequiredStatus(RequiredStatus required) { @@ -237,7 +239,8 @@ void QSqlField::setRequiredStatus(RequiredStatus required) maximum number of characters the string can hold; the meaning varies for other types. - \sa length() setType() setRequiredStatus() setPrecision() setDefaultValue() setGenerated() setReadOnly() + \sa length(), setType(), setRequiredStatus(), setPrecision(), + setDefaultValue(), setGenerated(), setReadOnly() */ void QSqlField::setLength(int fieldLength) { @@ -248,7 +251,8 @@ void QSqlField::setLength(int fieldLength) /*! Sets the field's \a precision. This only affects numeric fields. - \sa precision() setType() setRequiredStatus() setLength() setDefaultValue() setGenerated() setReadOnly() + \sa precision(), setType(), setRequiredStatus(), setLength(), + setDefaultValue(), setGenerated(), setReadOnly() */ void QSqlField::setPrecision(int precision) { @@ -259,7 +263,8 @@ void QSqlField::setPrecision(int precision) /*! Sets the default value used for this field to \a value. - \sa defaultValue() value() setType() setRequiredStatus() setLength() setPrecision() setGenerated() setReadOnly() + \sa defaultValue(), value(), setType(), setRequiredStatus(), + setLength(), setPrecision(), setGenerated(), setReadOnly() */ void QSqlField::setDefaultValue(const QVariant &value) { @@ -282,7 +287,8 @@ void QSqlField::setSqlType(int type) QSqlQueryModel and QSqlTableModel will generate SQL for this field. - \sa isGenerated() setType() setRequiredStatus() setLength() setPrecision() setDefaultValue() setReadOnly() + \sa isGenerated(), setType(), setRequiredStatus(), setLength(), + setPrecision(), setDefaultValue(), setReadOnly() */ void QSqlField::setGenerated(bool gen) { @@ -302,7 +308,7 @@ void QSqlField::setGenerated(bool gen) To set the value to NULL, use clear(). - \sa value() isReadOnly() defaultValue() + \sa value(), isReadOnly(), defaultValue() */ void QSqlField::setValue(const QVariant& value) @@ -316,7 +322,7 @@ void QSqlField::setValue(const QVariant& value) Clears the value of the field and sets it to NULL. If the field is read-only, nothing happens. - \sa setValue() isReadOnly() requiredStatus() + \sa setValue(), isReadOnly(), requiredStatus() */ void QSqlField::clear() @@ -384,7 +390,8 @@ QVariant::Type QSqlField::type() const /*! Set's the field's variant type to \a type. - \sa type() setRequiredStatus() setLength() setPrecision() setDefaultValue() setGenerated() setReadOnly() + \sa type(), setRequiredStatus(), setLength(), setPrecision(), + setDefaultValue(), setGenerated(), setReadOnly() */ void QSqlField::setType(QVariant::Type type) { @@ -399,7 +406,8 @@ void QSqlField::setType(QVariant::Type type) Returns true if the field's value is read-only; otherwise returns false. - \sa setReadOnly() type() requiredStatus() length() precision() defaultValue() isGenerated() + \sa setReadOnly(), type(), requiredStatus(), length(), precision(), + defaultValue(), isGenerated() */ bool QSqlField::isReadOnly() const { return d->ro; } @@ -424,7 +432,8 @@ void QSqlField::detach() Returns true if this is a required field; otherwise returns false. An \c INSERT will fail if a required field does not have a value. - \sa setRequiredStatus() type() length() precision() defaultValue() isGenerated() + \sa setRequiredStatus(), type(), length(), precision(), defaultValue(), + isGenerated() */ QSqlField::RequiredStatus QSqlField::requiredStatus() const { @@ -437,7 +446,8 @@ QSqlField::RequiredStatus QSqlField::requiredStatus() const If the returned value is negative, it means that the information is not available from the database. - \sa setLength() type() requiredStatus() precision() defaultValue() isGenerated() + \sa setLength(), type(), requiredStatus(), precision(), defaultValue(), + isGenerated() */ int QSqlField::length() const { @@ -451,7 +461,8 @@ int QSqlField::length() const If the returned value is negative, it means that the information is not available from the database. - \sa setPrecision() type() requiredStatus() length() defaultValue() isGenerated() + \sa setPrecision(), type(), requiredStatus(), length(), defaultValue(), + isGenerated() */ int QSqlField::precision() const { @@ -461,7 +472,8 @@ int QSqlField::precision() const /*! Returns the field's default value (which may be NULL). - \sa setDefaultValue() type() requiredStatus() length() precision() isGenerated() + \sa setDefaultValue(), type(), requiredStatus(), length(), precision(), + isGenerated() */ QVariant QSqlField::defaultValue() const { @@ -485,7 +497,8 @@ int QSqlField::typeID() const Returns true if the field is generated; otherwise returns false. - \sa setGenerated() type() requiredStatus() length() precision() defaultValue() + \sa setGenerated(), type(), requiredStatus(), length(), precision(), + defaultValue() */ bool QSqlField::isGenerated() const { @@ -523,12 +536,6 @@ QDebug operator<<(QDebug dbg, const QSqlField &f) #endif /*! - \fn void QSqlField::setNull() - - Use clear() instead. -*/ - -/*! Returns true if the value is auto-generated by the database, for example auto-increment primary key values. diff --git a/src/sql/kernel/qsqlquery.cpp b/src/sql/kernel/qsqlquery.cpp index e21a8f4956..78631b5e5f 100644 --- a/src/sql/kernel/qsqlquery.cpp +++ b/src/sql/kernel/qsqlquery.cpp @@ -148,7 +148,7 @@ QSqlQueryPrivate::~QSqlQueryPrivate() For example: - \snippet doc/src/snippets/sqldatabase/sqldatabase.cpp 7 + \snippet sqldatabase/sqldatabase.cpp 7 To access the data returned by a query, use value(int). Each field in the data returned by a \c SELECT statement is accessed @@ -161,7 +161,7 @@ QSqlQueryPrivate::~QSqlQueryPrivate() explained below). To convert a field name into an index, use record().\l{QSqlRecord::indexOf()}{indexOf()}, for example: - \snippet doc/src/snippets/sqldatabase/sqldatabase.cpp 8 + \snippet sqldatabase/sqldatabase.cpp 8 QSqlQuery supports prepared query execution and the binding of parameter values to placeholders. Some databases don't support @@ -190,19 +190,19 @@ QSqlQueryPrivate::~QSqlQueryPrivate() \b{Named binding using named placeholders:} - \snippet doc/src/snippets/sqldatabase/sqldatabase.cpp 9 + \snippet sqldatabase/sqldatabase.cpp 9 \b{Positional binding using named placeholders:} - \snippet doc/src/snippets/sqldatabase/sqldatabase.cpp 10 + \snippet sqldatabase/sqldatabase.cpp 10 \b{Binding values using positional placeholders (version 1):} - \snippet doc/src/snippets/sqldatabase/sqldatabase.cpp 11 + \snippet sqldatabase/sqldatabase.cpp 11 \b{Binding values using positional placeholders (version 2):} - \snippet doc/src/snippets/sqldatabase/sqldatabase.cpp 12 + \snippet sqldatabase/sqldatabase.cpp 12 \b{Binding values to a stored procedure:} @@ -210,7 +210,7 @@ QSqlQueryPrivate::~QSqlQueryPrivate() it a character through its in parameter, and taking its result in the out parameter. - \snippet doc/src/snippets/sqldatabase/sqldatabase.cpp 13 + \snippet sqldatabase/sqldatabase.cpp 13 Note that unbound parameters will retain their values. @@ -343,7 +343,7 @@ bool QSqlQuery::isNull(int field) const Example: - \snippet doc/src/snippets/sqldatabase/sqldatabase.cpp 34 + \snippet sqldatabase/sqldatabase.cpp 34 \sa isActive(), isValid(), next(), previous(), first(), last(), seek() @@ -384,7 +384,7 @@ bool QSqlQuery::exec(const QString& query) The fields are numbered from left to right using the text of the \c SELECT statement, e.g. in - \snippet doc/src/snippets/code/src_sql_kernel_qsqlquery.cpp 0 + \snippet code/src_sql_kernel_qsqlquery.cpp 0 field 0 is \c forename and field 1 is \c surname. Using \c{SELECT *} is not recommended because the order @@ -394,7 +394,7 @@ bool QSqlQuery::exec(const QString& query) exist, if the query is inactive, or if the query is positioned on an invalid record. - \sa previous() next() first() last() seek() isActive() isValid() + \sa previous(), next(), first(), last(), seek(), isActive(), isValid() */ QVariant QSqlQuery::value(int index) const @@ -411,7 +411,7 @@ QVariant QSqlQuery::value(int index) const function returns QSql::BeforeFirstRow or QSql::AfterLastRow, which are special negative values. - \sa previous() next() first() last() seek() isActive() isValid() + \sa previous(), next(), first(), last(), seek(), isActive(), isValid() */ int QSqlQuery::at() const @@ -495,7 +495,7 @@ const QSqlResult* QSqlQuery::result() const \endlist - \sa next() previous() first() last() at() isActive() isValid() + \sa next(), previous(), first(), last(), at(), isActive(), isValid() */ bool QSqlQuery::seek(int index, bool relative) { @@ -587,7 +587,7 @@ bool QSqlQuery::seek(int index, bool relative) the last record and false is returned. If the record is successfully retrieved, true is returned. - \sa previous() first() last() seek() at() isActive() isValid() + \sa previous(), first(), last(), seek(), at(), isActive(), isValid() */ bool QSqlQuery::next() { @@ -636,7 +636,7 @@ bool QSqlQuery::next() before the first record and false is returned. If the record is successfully retrieved, true is returned. - \sa next() first() last() seek() at() isActive() isValid() + \sa next(), first(), last(), seek(), at(), isActive(), isValid() */ bool QSqlQuery::previous() { @@ -671,7 +671,7 @@ bool QSqlQuery::previous() return false. Returns true if successful. If unsuccessful the query position is set to an invalid position and false is returned. - \sa next() previous() last() seek() at() isActive() isValid() + \sa next(), previous(), last(), seek(), at(), isActive(), isValid() */ bool QSqlQuery::first() { @@ -695,7 +695,7 @@ bool QSqlQuery::first() Returns true if successful. If unsuccessful the query position is set to an invalid position and false is returned. - \sa next() previous() first() seek() at() isActive() isValid() + \sa next(), previous(), first(), seek(), at(), isActive(), isValid() */ bool QSqlQuery::last() @@ -717,7 +717,7 @@ bool QSqlQuery::last() To determine the number of rows affected by a non-\c SELECT statement, use numRowsAffected(). - \sa isActive() numRowsAffected() QSqlDriver::hasFeature() + \sa isActive(), numRowsAffected(), QSqlDriver::hasFeature() */ int QSqlQuery::size() const { @@ -732,7 +732,7 @@ int QSqlQuery::size() const statements, the value is undefined; use size() instead. If the query is not \l{isActive()}{active}, -1 is returned. - \sa size() QSqlDriver::hasFeature() + \sa size(), QSqlDriver::hasFeature() */ int QSqlQuery::numRowsAffected() const @@ -850,7 +850,7 @@ void QSqlQuery::setForwardOnly(bool forward) Since the order of the columns is not defined, QSqlRecord::indexOf() is used to obtain the index of a column. - \snippet doc/src/snippets/code/src_sql_kernel_qsqlquery.cpp 1 + \snippet code/src_sql_kernel_qsqlquery.cpp 1 \sa value() */ @@ -895,7 +895,7 @@ void QSqlQuery::clear() Example: - \snippet doc/src/snippets/sqldatabase/sqldatabase.cpp 9 + \snippet sqldatabase/sqldatabase.cpp 9 \sa exec(), bindValue(), addBindValue() */ @@ -937,7 +937,7 @@ bool QSqlQuery::prepare(const QString& query) Note that the last error for this query is reset when exec() is called. - \sa prepare() bindValue() addBindValue() boundValue() boundValues() + \sa prepare(), bindValue(), addBindValue(), boundValue(), boundValues() */ bool QSqlQuery::exec() { @@ -968,11 +968,11 @@ bool QSqlQuery::exec() Example: - \snippet doc/src/snippets/code/src_sql_kernel_qsqlquery.cpp 2 + \snippet code/src_sql_kernel_qsqlquery.cpp 2 The example above inserts four new rows into \c myTable: - \snippet doc/src/snippets/code/src_sql_kernel_qsqlquery.cpp 3 + \snippet code/src_sql_kernel_qsqlquery.cpp 3 To bind NULL values, a null QVariant of the relevant type has to be added to the bound QVariantList; for example, \c @@ -1021,7 +1021,7 @@ bool QSqlQuery::execBatch(BatchExecutionMode mode) \endcode Binding to name will bind to the first :name, but not the second. - \sa addBindValue(), prepare(), exec(), boundValue() boundValues() + \sa addBindValue(), prepare(), exec(), boundValue(), boundValues() */ void QSqlQuery::bindValue(const QString& placeholder, const QVariant& val, QSql::ParamType paramType @@ -1051,7 +1051,7 @@ void QSqlQuery::bindValue(int pos, const QVariant& val, QSql::ParamType paramTyp To bind a NULL value, use a null QVariant; for example, use \c {QVariant(QVariant::String)} if you are binding a string. - \sa bindValue(), prepare(), exec(), boundValue() boundValues() + \sa bindValue(), prepare(), exec(), boundValue(), boundValues() */ void QSqlQuery::addBindValue(const QVariant& val, QSql::ParamType paramType) { @@ -1061,7 +1061,7 @@ void QSqlQuery::addBindValue(const QVariant& val, QSql::ParamType paramType) /*! Returns the value for the \a placeholder. - \sa boundValues() bindValue() addBindValue() + \sa boundValues(), bindValue(), addBindValue() */ QVariant QSqlQuery::boundValue(const QString& placeholder) const { @@ -1082,13 +1082,13 @@ QVariant QSqlQuery::boundValue(int pos) const With named binding, the bound values can be examined in the following ways: - \snippet doc/src/snippets/sqldatabase/sqldatabase.cpp 14 + \snippet sqldatabase/sqldatabase.cpp 14 With positional binding, the code becomes: - \snippet doc/src/snippets/sqldatabase/sqldatabase.cpp 15 + \snippet sqldatabase/sqldatabase.cpp 15 - \sa boundValue() bindValue() addBindValue() + \sa boundValue(), bindValue(), addBindValue() */ QMap<QString,QVariant> QSqlQuery::boundValues() const { @@ -1118,12 +1118,6 @@ QString QSqlQuery::executedQuery() const } /*! - \fn bool QSqlQuery::prev() - - Use previous() instead. -*/ - -/*! Returns the object ID of the most recent inserted row if the database supports it. An invalid QVariant will be returned if the query did not insert any value or if the database does not report @@ -1190,7 +1184,7 @@ QSql::NumericalPrecisionPolicy QSqlQuery::numericalPrecisionPolicy() const Sets the query to inactive. Bound values retain their values. - \sa prepare() exec() isActive() + \sa prepare(), exec(), isActive() */ void QSqlQuery::finish() { @@ -1230,7 +1224,8 @@ void QSqlQuery::finish() databases may have restrictions on which statements are allowed to be used in a SQL batch. - \sa QSqlDriver::hasFeature() setForwardOnly() next() isSelect() numRowsAffected() isActive() lastError() + \sa QSqlDriver::hasFeature(), setForwardOnly(), next(), isSelect(), + numRowsAffected(), isActive(), lastError() */ bool QSqlQuery::nextResult() { diff --git a/src/sql/kernel/qsqlrecord.cpp b/src/sql/kernel/qsqlrecord.cpp index 93ef58914b..4349661835 100644 --- a/src/sql/kernel/qsqlrecord.cpp +++ b/src/sql/kernel/qsqlrecord.cpp @@ -189,7 +189,7 @@ bool QSqlRecord::operator==(const QSqlRecord &other) const the record. If \a index is out of bounds, an invalid QVariant is returned. - \sa fieldName() isNull() + \sa fieldName(), isNull() */ QVariant QSqlRecord::value(int index) const @@ -264,7 +264,7 @@ QSqlField QSqlRecord::field(const QString &name) const /*! Append a copy of field \a field to the end of the record. - \sa insert() replace() remove() + \sa insert(), replace(), remove() */ void QSqlRecord::append(const QSqlField& field) @@ -276,7 +276,7 @@ void QSqlRecord::append(const QSqlField& field) /*! Inserts the field \a field at position \a pos in the record. - \sa append() replace() remove() + \sa append(), replace(), remove() */ void QSqlRecord::insert(int pos, const QSqlField& field) { @@ -288,7 +288,7 @@ void QSqlRecord::insert(int pos, const QSqlField& field) Replaces the field at position \a pos with the given \a field. If \a pos is out of range, nothing happens. - \sa append() insert() remove() + \sa append(), insert(), remove() */ void QSqlRecord::replace(int pos, const QSqlField& field) @@ -304,7 +304,7 @@ void QSqlRecord::replace(int pos, const QSqlField& field) Removes the field at position \a pos. If \a pos is out of range, nothing happens. - \sa append() insert() replace() + \sa append(), insert(), replace() */ void QSqlRecord::remove(int pos) @@ -319,7 +319,7 @@ void QSqlRecord::remove(int pos) /*! Removes all the record's fields. - \sa clearValues() isEmpty() + \sa clearValues(), isEmpty() */ void QSqlRecord::clear() @@ -332,7 +332,7 @@ void QSqlRecord::clear() Returns true if there are no fields in the record; otherwise returns false. - \sa append() insert() clear() + \sa append(), insert(), clear() */ bool QSqlRecord::isEmpty() const @@ -524,10 +524,4 @@ QDebug operator<<(QDebug dbg, const QSqlRecord &r) } #endif -/*! - \fn int QSqlRecord::position(const QString& name) const - - Use indexOf() instead. -*/ - QT_END_NAMESPACE diff --git a/src/sql/kernel/qsqlresult.cpp b/src/sql/kernel/qsqlresult.cpp index f9dbae306b..03e227bffc 100644 --- a/src/sql/kernel/qsqlresult.cpp +++ b/src/sql/kernel/qsqlresult.cpp @@ -953,7 +953,7 @@ void QSqlResult::virtual_hook(int, void *) Example: - \snippet doc/src/snippets/code/src_sql_kernel_qsqlresult.cpp 0 + \snippet code/src_sql_kernel_qsqlresult.cpp 0 Here, we insert two rows into a SQL table, with each row containing three values. @@ -1032,11 +1032,11 @@ bool QSqlResult::nextResult() This example retrieves the handle for a sqlite result: - \snippet doc/src/snippets/code/src_sql_kernel_qsqlresult.cpp 1 + \snippet code/src_sql_kernel_qsqlresult.cpp 1 This snippet returns the handle for PostgreSQL or MySQL: - \snippet doc/src/snippets/code/src_sql_kernel_qsqlresult.cpp 2 + \snippet code/src_sql_kernel_qsqlresult.cpp 2 \sa QSqlDriver::handle() */ diff --git a/src/sql/models/qsqlquerymodel.cpp b/src/sql/models/qsqlquerymodel.cpp index 85869e41ac..723767344c 100644 --- a/src/sql/models/qsqlquerymodel.cpp +++ b/src/sql/models/qsqlquerymodel.cpp @@ -111,7 +111,7 @@ void QSqlQueryModelPrivate::initColOffsets(int size) the lower-level QSqlQuery and can be used to provide data to view classes such as QTableView. For example: - \snippet doc/src/snippets/sqldatabase/sqldatabase.cpp 16 + \snippet sqldatabase/sqldatabase.cpp 16 We set the model's query, then we set up the labels displayed in the view header. @@ -119,13 +119,13 @@ void QSqlQueryModelPrivate::initColOffsets(int size) QSqlQueryModel can also be used to access a database programmatically, without binding it to a view: - \snippet doc/src/snippets/sqldatabase/sqldatabase.cpp 21 + \snippet sqldatabase/sqldatabase.cpp 21 The code snippet above extracts the \c salary field from record 4 in the result set of the query \c{SELECT * from employee}. Assuming that \c salary is column 2, we can rewrite the last line as follows: - \snippet doc/src/snippets/sqldatabase/sqldatabase.cpp 22 + \snippet sqldatabase/sqldatabase.cpp 22 The model is read-only by default. To make it read-write, you must subclass it and reimplement setData() and flags(). Another @@ -179,7 +179,7 @@ QSqlQueryModel::~QSqlQueryModel() To force fetching of the entire result set, you can use the following: - \snippet doc/src/snippets/code/src_sql_models_qsqlquerymodel.cpp 0 + \snippet code/src_sql_models_qsqlquerymodel.cpp 0 \a parent should always be an invalid QModelIndex. @@ -394,7 +394,7 @@ void QSqlQueryModel::setQuery(const QSqlQuery &query) was an error setting the query. Example: - \snippet doc/src/snippets/code/src_sql_models_qsqlquerymodel.cpp 1 + \snippet code/src_sql_models_qsqlquerymodel.cpp 1 \sa query(), queryChange(), lastError() */ @@ -529,7 +529,7 @@ QSqlRecord QSqlQueryModel::record() const By default, inserted columns are empty. To fill them with data, reimplement data() and handle any inserted column separately: - \snippet doc/src/snippets/sqldatabase/sqldatabase.cpp 23 + \snippet sqldatabase/sqldatabase.cpp 23 \sa removeColumns() */ diff --git a/src/sql/models/qsqlrelationaldelegate.cpp b/src/sql/models/qsqlrelationaldelegate.cpp index 79e026fe57..e58c68f139 100644 --- a/src/sql/models/qsqlrelationaldelegate.cpp +++ b/src/sql/models/qsqlrelationaldelegate.cpp @@ -53,7 +53,7 @@ QT_BEGIN_NAMESPACE use the class, simply call QAbstractItemView::setItemDelegate() on the view with an instance of QSqlRelationalDelegate: - \snippet examples/sql/relationaltablemodel/relationaltablemodel.cpp 4 + \snippet sql/relationaltablemodel/relationaltablemodel.cpp 4 The \l{sql/relationaltablemodel}{Relational Table Model} example (shown below) illustrates how to use QSqlRelationalDelegate in diff --git a/src/sql/models/qsqlrelationaltablemodel.cpp b/src/sql/models/qsqlrelationaltablemodel.cpp index a3d45576ae..6d0304e165 100644 --- a/src/sql/models/qsqlrelationaltablemodel.cpp +++ b/src/sql/models/qsqlrelationaltablemodel.cpp @@ -340,10 +340,10 @@ void QSqlRelationalTableModelPrivate::clearCache() The following code snippet shows how the QSqlRelationalTableModel was set up: - \snippet examples/sql/relationaltablemodel/relationaltablemodel.cpp 0 + \snippet sql/relationaltablemodel/relationaltablemodel.cpp 0 \codeline - \snippet examples/sql/relationaltablemodel/relationaltablemodel.cpp 1 - \snippet examples/sql/relationaltablemodel/relationaltablemodel.cpp 2 + \snippet sql/relationaltablemodel/relationaltablemodel.cpp 1 + \snippet sql/relationaltablemodel/relationaltablemodel.cpp 2 The setRelation() function calls establish a relationship between two tables. The first call specifies that column 2 in table \c @@ -359,7 +359,7 @@ void QSqlRelationalTableModelPrivate::clearCache() call QAbstractItemView::setItemDelegate() on the view with an instance of QSqlRelationalDelegate: - \snippet examples/sql/relationaltablemodel/relationaltablemodel.cpp 4 + \snippet sql/relationaltablemodel/relationaltablemodel.cpp 4 The \l{sql/relationaltablemodel} example illustrates how to use QSqlRelationalTableModel in conjunction with @@ -486,9 +486,9 @@ bool QSqlRelationalTableModel::setData(const QModelIndex &index, const QVariant Example: - \snippet examples/sql/relationaltablemodel/relationaltablemodel.cpp 0 + \snippet sql/relationaltablemodel/relationaltablemodel.cpp 0 \codeline - \snippet examples/sql/relationaltablemodel/relationaltablemodel.cpp 1 + \snippet sql/relationaltablemodel/relationaltablemodel.cpp 1 The setRelation() call specifies that column 2 in table \c employee is a foreign key that maps with field \c id of table \c diff --git a/src/sql/models/qsqltablemodel.cpp b/src/sql/models/qsqltablemodel.cpp index 40315da204..30c3f032e0 100644 --- a/src/sql/models/qsqltablemodel.cpp +++ b/src/sql/models/qsqltablemodel.cpp @@ -213,7 +213,7 @@ QSqlRecord QSqlTableModelPrivate::primaryValues(int row) const lower-level QSqlQuery and can be used to provide data to view classes such as QTableView. For example: - \snippet doc/src/snippets/sqldatabase/sqldatabase.cpp 24 + \snippet sqldatabase/sqldatabase.cpp 24 We set the SQL table's name and the edit strategy, then we set up the labels displayed in the view header. The edit strategy @@ -224,7 +224,7 @@ QSqlRecord QSqlTableModelPrivate::primaryValues(int row) const QSqlTableModel can also be used to access a database programmatically, without binding it to a view: - \snippet doc/src/snippets/sqldatabase/sqldatabase.cpp 21 + \snippet sqldatabase/sqldatabase.cpp 21 The code snippet above extracts the \c salary field from record 4 in the result set of the query \c{SELECT * from employee}. diff --git a/src/sql/sql.pro b/src/sql/sql.pro index dbeed14386..e3f81f3498 100644 --- a/src/sql/sql.pro +++ b/src/sql/sql.pro @@ -21,6 +21,7 @@ DEFINES += QT_NO_CAST_FROM_ASCII PRECOMPILED_HEADER = ../corelib/global/qt_pch.h SQL_P = sql +include(doc/doc.pri) include(kernel/kernel.pri) include(drivers/drivers.pri) include(models/models.pri) |
