1/****************************************************************************
2**
3** Copyright (C) 2022 The Qt Company Ltd.
4** Contact: https://www.qt.io/licensing/
5**
6** This file is part of the QtSql module of the Qt Toolkit.
7**
8** $QT_BEGIN_LICENSE:LGPL$
9** Commercial License Usage
10** Licensees holding valid commercial Qt licenses may use this file in
11** accordance with the commercial license agreement provided with the
12** Software or, alternatively, in accordance with the terms contained in
13** a written agreement between you and The Qt Company. For licensing terms
14** and conditions see https://www.qt.io/terms-conditions. For further
15** information use the contact form at https://www.qt.io/contact-us.
16**
17** GNU Lesser General Public License Usage
18** Alternatively, this file may be used under the terms of the GNU Lesser
19** General Public License version 3 as published by the Free Software
20** Foundation and appearing in the file LICENSE.LGPL3 included in the
21** packaging of this file. Please review the following information to
22** ensure the GNU Lesser General Public License version 3 requirements
23** will be met: https://www.gnu.org/licenses/lgpl-3.0.html.
24**
25** GNU General Public License Usage
26** Alternatively, this file may be used under the terms of the GNU
27** General Public License version 2.0 or (at your option) the GNU General
28** Public license version 3 or any later version approved by the KDE Free
29** Qt Foundation. The licenses are as published by the Free Software
30** Foundation and appearing in the file LICENSE.GPL2 and LICENSE.GPL3
31** included in the packaging of this file. Please review the following
32** information to ensure the GNU General Public License requirements will
33** be met: https://www.gnu.org/licenses/gpl-2.0.html and
34** https://www.gnu.org/licenses/gpl-3.0.html.
35**
36** $QT_END_LICENSE$
37**
38****************************************************************************/
39
40#include "qsqlquery.h"
41
42//#define QT_DEBUG_SQL
43
44#include "qdebug.h"
45#include "qelapsedtimer.h"
46#include "qatomic.h"
47#include "qsqlrecord.h"
48#include "qsqlresult.h"
49#include "qsqldriver.h"
50#include "qsqldatabase.h"
51#include "private/qsqlnulldriver_p.h"
52#include "qvector.h"
53#include "qmap.h"
54
55QT_BEGIN_NAMESPACE
56
57class QSqlQueryPrivate
58{
59public:
60 QSqlQueryPrivate(QSqlResult* result);
61 ~QSqlQueryPrivate();
62 QAtomicInt ref;
63 QSqlResult* sqlResult;
64
65 static QSqlQueryPrivate* shared_null();
66};
67
68Q_GLOBAL_STATIC_WITH_ARGS(QSqlQueryPrivate, nullQueryPrivate, (0))
69Q_GLOBAL_STATIC(QSqlNullDriver, nullDriver)
70Q_GLOBAL_STATIC_WITH_ARGS(QSqlNullResult, nullResult, (nullDriver()))
71
72QSqlQueryPrivate* QSqlQueryPrivate::shared_null()
73{
74 QSqlQueryPrivate *null = nullQueryPrivate();
75 null->ref.ref();
76 return null;
77}
78
79/*!
80\internal
81*/
82QSqlQueryPrivate::QSqlQueryPrivate(QSqlResult* result)
83 : ref(1), sqlResult(result)
84{
85 if (!sqlResult)
86 sqlResult = nullResult();
87}
88
89QSqlQueryPrivate::~QSqlQueryPrivate()
90{
91 QSqlResult *nr = nullResult();
92 if (!nr || sqlResult == nr)
93 return;
94 delete sqlResult;
95}
96
97/*!
98 \class QSqlQuery
99 \brief The QSqlQuery class provides a means of executing and
100 manipulating SQL statements.
101
102 \ingroup database
103 \ingroup shared
104
105 \inmodule QtSql
106
107 QSqlQuery encapsulates the functionality involved in creating,
108 navigating and retrieving data from SQL queries which are
109 executed on a \l QSqlDatabase. It can be used to execute DML
110 (data manipulation language) statements, such as \c SELECT, \c
111 INSERT, \c UPDATE and \c DELETE, as well as DDL (data definition
112 language) statements, such as \c{CREATE} \c{TABLE}. It can also
113 be used to execute database-specific commands which are not
114 standard SQL (e.g. \c{SET DATESTYLE=ISO} for PostgreSQL).
115
116 Successfully executed SQL statements set the query's state to
117 active so that isActive() returns \c true. Otherwise the query's
118 state is set to inactive. In either case, when executing a new SQL
119 statement, the query is positioned on an invalid record. An active
120 query must be navigated to a valid record (so that isValid()
121 returns \c true) before values can be retrieved.
122
123 For some databases, if an active query that is a \c{SELECT}
124 statement exists when you call \l{QSqlDatabase::}{commit()} or
125 \l{QSqlDatabase::}{rollback()}, the commit or rollback will
126 fail. See isActive() for details.
127
128 \target QSqlQuery examples
129
130 Navigating records is performed with the following functions:
131
132 \list
133 \li next()
134 \li previous()
135 \li first()
136 \li last()
137 \li seek()
138 \endlist
139
140 These functions allow the programmer to move forward, backward
141 or arbitrarily through the records returned by the query. If you
142 only need to move forward through the results (e.g., by using
143 next()), you can use setForwardOnly(), which will save a
144 significant amount of memory overhead and improve performance on
145 some databases. Once an active query is positioned on a valid
146 record, data can be retrieved using value(). All data is
147 transferred from the SQL backend using QVariants.
148
149 For example:
150
151 \snippet sqldatabase/sqldatabase.cpp 7
152
153 To access the data returned by a query, use value(int). Each
154 field in the data returned by a \c SELECT statement is accessed
155 by passing the field's position in the statement, starting from
156 0. This makes using \c{SELECT *} queries inadvisable because the
157 order of the fields returned is indeterminate.
158
159 For the sake of efficiency, there are no functions to access a
160 field by name (unless you use prepared queries with names, as
161 explained below). To convert a field name into an index, use
162 record().\l{QSqlRecord::indexOf()}{indexOf()}, for example:
163
164 \snippet sqldatabase/sqldatabase.cpp 8
165
166 QSqlQuery supports prepared query execution and the binding of
167 parameter values to placeholders. Some databases don't support
168 these features, so for those, Qt emulates the required
169 functionality. For example, the Oracle and ODBC drivers have
170 proper prepared query support, and Qt makes use of it; but for
171 databases that don't have this support, Qt implements the feature
172 itself, e.g. by replacing placeholders with actual values when a
173 query is executed. Use numRowsAffected() to find out how many rows
174 were affected by a non-\c SELECT query, and size() to find how
175 many were retrieved by a \c SELECT.
176
177 Oracle databases identify placeholders by using a colon-name
178 syntax, e.g \c{:name}. ODBC simply uses \c ? characters. Qt
179 supports both syntaxes, with the restriction that you can't mix
180 them in the same query.
181
182 You can retrieve the values of all the fields in a single variable
183 (a map) using boundValues().
184
185 \note Not all SQL operations support binding values. Refer to your database
186 system's documentation to check their availability.
187
188 \section1 Approaches to Binding Values
189
190 Below we present the same example using each of the four
191 different binding approaches, as well as one example of binding
192 values to a stored procedure.
193
194 \b{Named binding using named placeholders:}
195
196 \snippet sqldatabase/sqldatabase.cpp 9
197
198 \b{Positional binding using named placeholders:}
199
200 \snippet sqldatabase/sqldatabase.cpp 10
201
202 \b{Binding values using positional placeholders (version 1):}
203
204 \snippet sqldatabase/sqldatabase.cpp 11
205
206 \b{Binding values using positional placeholders (version 2):}
207
208 \snippet sqldatabase/sqldatabase.cpp 12
209
210 \b{Binding values to a stored procedure:}
211
212 This code calls a stored procedure called \c AsciiToInt(), passing
213 it a character through its in parameter, and taking its result in
214 the out parameter.
215
216 \snippet sqldatabase/sqldatabase.cpp 13
217
218 Note that unbound parameters will retain their values.
219
220 Stored procedures that uses the return statement to return values,
221 or return multiple result sets, are not fully supported. For specific
222 details see \l{SQL Database Drivers}.
223
224 \warning You must load the SQL driver and open the connection before a
225 QSqlQuery is created. Also, the connection must remain open while the
226 query exists; otherwise, the behavior of QSqlQuery is undefined.
227
228 \sa QSqlDatabase, QSqlQueryModel, QSqlTableModel, QVariant
229*/
230
231/*!
232 Constructs a QSqlQuery object which uses the QSqlResult \a result
233 to communicate with a database.
234*/
235
236QSqlQuery::QSqlQuery(QSqlResult *result)
237{
238 d = new QSqlQueryPrivate(result);
239}
240
241/*!
242 Destroys the object and frees any allocated resources.
243*/
244
245QSqlQuery::~QSqlQuery()
246{
247 if (!d->ref.deref())
248 delete d;
249}
250
251/*!
252 Constructs a copy of \a other.
253*/
254
255QSqlQuery::QSqlQuery(const QSqlQuery& other)
256{
257 d = other.d;
258 d->ref.ref();
259}
260
261/*!
262 \internal
263*/
264static void qInit(QSqlQuery *q, const QString& query, QSqlDatabase db)
265{
266 QSqlDatabase database = db;
267 if (!database.isValid())
268 database = QSqlDatabase::database(connectionName: QLatin1String(QSqlDatabase::defaultConnection), open: false);
269 if (database.isValid()) {
270 *q = QSqlQuery(database.driver()->createResult());
271 }
272 if (!query.isEmpty())
273 q->exec(query);
274}
275
276/*!
277 Constructs a QSqlQuery object using the SQL \a query and the
278 database \a db. If \a db is not specified, or is invalid, the application's
279 default database is used. If \a query is not an empty string, it
280 will be executed.
281
282 \sa QSqlDatabase
283*/
284QSqlQuery::QSqlQuery(const QString& query, QSqlDatabase db)
285{
286 d = QSqlQueryPrivate::shared_null();
287 qInit(q: this, query, db);
288}
289
290/*!
291 Constructs a QSqlQuery object using the database \a db.
292 If \a db is invalid, the application's default database will be used.
293
294 \sa QSqlDatabase
295*/
296
297QSqlQuery::QSqlQuery(QSqlDatabase db)
298{
299 d = QSqlQueryPrivate::shared_null();
300 qInit(q: this, query: QString(), db);
301}
302
303
304/*!
305 Assigns \a other to this object.
306*/
307
308QSqlQuery& QSqlQuery::operator=(const QSqlQuery& other)
309{
310 qAtomicAssign(d, x: other.d);
311 return *this;
312}
313
314/*!
315 Returns \c true if the query is not \l{isActive()}{active},
316 the query is not positioned on a valid record,
317 there is no such \a field, or the \a field is null; otherwise \c false.
318 Note that for some drivers, isNull() will not return accurate
319 information until after an attempt is made to retrieve data.
320
321 \sa isActive(), isValid(), value()
322*/
323
324bool QSqlQuery::isNull(int field) const
325{
326 return !d->sqlResult->isActive()
327 || !d->sqlResult->isValid()
328 || d->sqlResult->isNull(i: field);
329}
330
331/*!
332 \overload
333
334 Returns \c true if there is no field with this \a name; otherwise
335 returns isNull(int index) for the corresponding field index.
336
337 This overload is less efficient than \l{QSqlQuery::}{isNull()}
338*/
339
340bool QSqlQuery::isNull(const QString &name) const
341{
342 int index = d->sqlResult->record().indexOf(name);
343 if (index > -1)
344 return isNull(field: index);
345 qWarning(msg: "QSqlQuery::isNull: unknown field name '%s'", qPrintable(name));
346 return true;
347}
348
349/*!
350
351 Executes the SQL in \a query. Returns \c true and sets the query state
352 to \l{isActive()}{active} if the query was successful; otherwise
353 returns \c false. The \a query string must use syntax appropriate for
354 the SQL database being queried (for example, standard SQL).
355
356 After the query is executed, the query is positioned on an \e
357 invalid record and must be navigated to a valid record before data
358 values can be retrieved (for example, using next()).
359
360 Note that the last error for this query is reset when exec() is
361 called.
362
363 For SQLite, the query string can contain only one statement at a time.
364 If more than one statement is given, the function returns \c false.
365
366 Example:
367
368 \snippet sqldatabase/sqldatabase.cpp 34
369
370 \sa isActive(), isValid(), next(), previous(), first(), last(),
371 seek()
372*/
373
374bool QSqlQuery::exec(const QString& query)
375{
376#ifdef QT_DEBUG_SQL
377 QElapsedTimer t;
378 t.start();
379#endif
380 if (!driver()) {
381 qWarning(msg: "QSqlQuery::exec: called before driver has been set up");
382 return false;
383 }
384 if (d->ref.loadRelaxed() != 1) {
385 bool fo = isForwardOnly();
386 *this = QSqlQuery(driver()->createResult());
387 d->sqlResult->setNumericalPrecisionPolicy(d->sqlResult->numericalPrecisionPolicy());
388 setForwardOnly(fo);
389 } else {
390 d->sqlResult->clear();
391 d->sqlResult->setActive(false);
392 d->sqlResult->setLastError(QSqlError());
393 d->sqlResult->setAt(QSql::BeforeFirstRow);
394 d->sqlResult->setNumericalPrecisionPolicy(d->sqlResult->numericalPrecisionPolicy());
395 }
396 d->sqlResult->setQuery(query.trimmed());
397 if (!driver()->isOpen() || driver()->isOpenError()) {
398 qWarning(msg: "QSqlQuery::exec: database not open");
399 return false;
400 }
401 if (query.isEmpty()) {
402 qWarning(msg: "QSqlQuery::exec: empty query");
403 return false;
404 }
405
406 bool retval = d->sqlResult->reset(sqlquery: query);
407#ifdef QT_DEBUG_SQL
408 qDebug().nospace() << "Executed query (" << t.elapsed() << "ms, " << d->sqlResult->size()
409 << " results, " << d->sqlResult->numRowsAffected()
410 << " affected): " << d->sqlResult->lastQuery();
411#endif
412 return retval;
413}
414
415/*!
416 Returns the value of field \a index in the current record.
417
418 The fields are numbered from left to right using the text of the
419 \c SELECT statement, e.g. in
420
421 \snippet code/src_sql_kernel_qsqlquery_snippet.cpp 0
422
423 field 0 is \c forename and field 1 is \c
424 surname. Using \c{SELECT *} is not recommended because the order
425 of the fields in the query is undefined.
426
427 An invalid QVariant is returned if field \a index does not
428 exist, if the query is inactive, or if the query is positioned on
429 an invalid record.
430
431 \sa previous(), next(), first(), last(), seek(), isActive(), isValid()
432*/
433
434QVariant QSqlQuery::value(int index) const
435{
436 if (isActive() && isValid() && (index > -1))
437 return d->sqlResult->data(i: index);
438 qWarning(msg: "QSqlQuery::value: not positioned on a valid record");
439 return QVariant();
440}
441
442/*!
443 \overload
444
445 Returns the value of the field called \a name in the current record.
446 If field \a name does not exist an invalid variant is returned.
447
448 This overload is less efficient than \l{QSqlQuery::}{value()}
449*/
450
451QVariant QSqlQuery::value(const QString& name) const
452{
453 int index = d->sqlResult->record().indexOf(name);
454 if (index > -1)
455 return value(index);
456 qWarning(msg: "QSqlQuery::value: unknown field name '%s'", qPrintable(name));
457 return QVariant();
458}
459
460/*!
461 Returns the current internal position of the query. The first
462 record is at position zero. If the position is invalid, the
463 function returns QSql::BeforeFirstRow or
464 QSql::AfterLastRow, which are special negative values.
465
466 \sa previous(), next(), first(), last(), seek(), isActive(), isValid()
467*/
468
469int QSqlQuery::at() const
470{
471 return d->sqlResult->at();
472}
473
474/*!
475 Returns the text of the current query being used, or an empty
476 string if there is no current query text.
477
478 \sa executedQuery()
479*/
480
481QString QSqlQuery::lastQuery() const
482{
483 return d->sqlResult->lastQuery();
484}
485
486/*!
487 Returns the database driver associated with the query.
488*/
489
490const QSqlDriver *QSqlQuery::driver() const
491{
492 return d->sqlResult->driver();
493}
494
495/*!
496 Returns the result associated with the query.
497*/
498
499const QSqlResult* QSqlQuery::result() const
500{
501 return d->sqlResult;
502}
503
504/*!
505 Retrieves the record at position \a index, if available, and
506 positions the query on the retrieved record. The first record is at
507 position 0. Note that the query must be in an \l{isActive()}
508 {active} state and isSelect() must return true before calling this
509 function.
510
511 If \a relative is false (the default), the following rules apply:
512
513 \list
514
515 \li If \a index is negative, the result is positioned before the
516 first record and false is returned.
517
518 \li Otherwise, an attempt is made to move to the record at position
519 \a index. If the record at position \a index could not be retrieved,
520 the result is positioned after the last record and false is
521 returned. If the record is successfully retrieved, true is returned.
522
523 \endlist
524
525 If \a relative is true, the following rules apply:
526
527 \list
528
529 \li If the result is currently positioned before the first record and:
530 \list
531 \li \a index is negative or zero, there is no change, and false is
532 returned.
533 \li \a index is positive, an attempt is made to position the result
534 at absolute position \a index - 1, following the sames rule for non
535 relative seek, above.
536 \endlist
537
538 \li If the result is currently positioned after the last record and:
539 \list
540 \li \a index is positive or zero, there is no change, and false is
541 returned.
542 \li \a index is negative, an attempt is made to position the result
543 at \a index + 1 relative position from last record, following the
544 rule below.
545 \endlist
546
547 \li If the result is currently located somewhere in the middle, and
548 the relative offset \a index moves the result below zero, the result
549 is positioned before the first record and false is returned.
550
551 \li Otherwise, an attempt is made to move to the record \a index
552 records ahead of the current record (or \a index records behind the
553 current record if \a index is negative). If the record at offset \a
554 index could not be retrieved, the result is positioned after the
555 last record if \a index >= 0, (or before the first record if \a
556 index is negative), and false is returned. If the record is
557 successfully retrieved, true is returned.
558
559 \endlist
560
561 \sa next(), previous(), first(), last(), at(), isActive(), isValid()
562*/
563bool QSqlQuery::seek(int index, bool relative)
564{
565 if (!isSelect() || !isActive())
566 return false;
567 int actualIdx;
568 if (!relative) { // arbitrary seek
569 if (index < 0) {
570 d->sqlResult->setAt(QSql::BeforeFirstRow);
571 return false;
572 }
573 actualIdx = index;
574 } else {
575 switch (at()) { // relative seek
576 case QSql::BeforeFirstRow:
577 if (index > 0)
578 actualIdx = index - 1;
579 else {
580 return false;
581 }
582 break;
583 case QSql::AfterLastRow:
584 if (index < 0) {
585 d->sqlResult->fetchLast();
586 actualIdx = at() + index + 1;
587 } else {
588 return false;
589 }
590 break;
591 default:
592 if ((at() + index) < 0) {
593 d->sqlResult->setAt(QSql::BeforeFirstRow);
594 return false;
595 }
596 actualIdx = at() + index;
597 break;
598 }
599 }
600 // let drivers optimize
601 if (isForwardOnly() && actualIdx < at()) {
602 qWarning(msg: "QSqlQuery::seek: cannot seek backwards in a forward only query");
603 return false;
604 }
605 if (actualIdx == (at() + 1) && at() != QSql::BeforeFirstRow) {
606 if (!d->sqlResult->fetchNext()) {
607 d->sqlResult->setAt(QSql::AfterLastRow);
608 return false;
609 }
610 return true;
611 }
612 if (actualIdx == (at() - 1)) {
613 if (!d->sqlResult->fetchPrevious()) {
614 d->sqlResult->setAt(QSql::BeforeFirstRow);
615 return false;
616 }
617 return true;
618 }
619 if (!d->sqlResult->fetch(i: actualIdx)) {
620 d->sqlResult->setAt(QSql::AfterLastRow);
621 return false;
622 }
623 return true;
624}
625
626/*!
627
628 Retrieves the next record in the result, if available, and positions
629 the query on the retrieved record. Note that the result must be in
630 the \l{isActive()}{active} state and isSelect() must return true
631 before calling this function or it will do nothing and return false.
632
633 The following rules apply:
634
635 \list
636
637 \li If the result is currently located before the first record,
638 e.g. immediately after a query is executed, an attempt is made to
639 retrieve the first record.
640
641 \li If the result is currently located after the last record, there
642 is no change and false is returned.
643
644 \li If the result is located somewhere in the middle, an attempt is
645 made to retrieve the next record.
646
647 \endlist
648
649 If the record could not be retrieved, the result is positioned after
650 the last record and false is returned. If the record is successfully
651 retrieved, true is returned.
652
653 \sa previous(), first(), last(), seek(), at(), isActive(), isValid()
654*/
655bool QSqlQuery::next()
656{
657 if (!isSelect() || !isActive())
658 return false;
659
660 switch (at()) {
661 case QSql::BeforeFirstRow:
662 return d->sqlResult->fetchFirst();
663 case QSql::AfterLastRow:
664 return false;
665 default:
666 if (!d->sqlResult->fetchNext()) {
667 d->sqlResult->setAt(QSql::AfterLastRow);
668 return false;
669 }
670 return true;
671 }
672}
673
674/*!
675
676 Retrieves the previous record in the result, if available, and
677 positions the query on the retrieved record. Note that the result
678 must be in the \l{isActive()}{active} state and isSelect() must
679 return true before calling this function or it will do nothing and
680 return false.
681
682 The following rules apply:
683
684 \list
685
686 \li If the result is currently located before the first record, there
687 is no change and false is returned.
688
689 \li If the result is currently located after the last record, an
690 attempt is made to retrieve the last record.
691
692 \li If the result is somewhere in the middle, an attempt is made to
693 retrieve the previous record.
694
695 \endlist
696
697 If the record could not be retrieved, the result is positioned
698 before the first record and false is returned. If the record is
699 successfully retrieved, true is returned.
700
701 \sa next(), first(), last(), seek(), at(), isActive(), isValid()
702*/
703bool QSqlQuery::previous()
704{
705 if (!isSelect() || !isActive())
706 return false;
707 if (isForwardOnly()) {
708 qWarning(msg: "QSqlQuery::seek: cannot seek backwards in a forward only query");
709 return false;
710 }
711
712 switch (at()) {
713 case QSql::BeforeFirstRow:
714 return false;
715 case QSql::AfterLastRow:
716 return d->sqlResult->fetchLast();
717 default:
718 if (!d->sqlResult->fetchPrevious()) {
719 d->sqlResult->setAt(QSql::BeforeFirstRow);
720 return false;
721 }
722 return true;
723 }
724}
725
726/*!
727 Retrieves the first record in the result, if available, and
728 positions the query on the retrieved record. Note that the result
729 must be in the \l{isActive()}{active} state and isSelect() must
730 return true before calling this function or it will do nothing and
731 return false. Returns \c true if successful. If unsuccessful the query
732 position is set to an invalid position and false is returned.
733
734 \sa next(), previous(), last(), seek(), at(), isActive(), isValid()
735 */
736bool QSqlQuery::first()
737{
738 if (!isSelect() || !isActive())
739 return false;
740 if (isForwardOnly() && at() > QSql::BeforeFirstRow) {
741 qWarning(msg: "QSqlQuery::seek: cannot seek backwards in a forward only query");
742 return false;
743 }
744 return d->sqlResult->fetchFirst();
745}
746
747/*!
748
749 Retrieves the last record in the result, if available, and positions
750 the query on the retrieved record. Note that the result must be in
751 the \l{isActive()}{active} state and isSelect() must return true
752 before calling this function or it will do nothing and return false.
753 Returns \c true if successful. If unsuccessful the query position is
754 set to an invalid position and false is returned.
755
756 \sa next(), previous(), first(), seek(), at(), isActive(), isValid()
757*/
758
759bool QSqlQuery::last()
760{
761 if (!isSelect() || !isActive())
762 return false;
763 return d->sqlResult->fetchLast();
764}
765
766/*!
767 Returns the size of the result (number of rows returned), or -1 if
768 the size cannot be determined or if the database does not support
769 reporting information about query sizes. Note that for non-\c SELECT
770 statements (isSelect() returns \c false), size() will return -1. If the
771 query is not active (isActive() returns \c false), -1 is returned.
772
773 To determine the number of rows affected by a non-\c SELECT
774 statement, use numRowsAffected().
775
776 \sa isActive(), numRowsAffected(), QSqlDriver::hasFeature()
777*/
778int QSqlQuery::size() const
779{
780 if (isActive() && d->sqlResult->driver()->hasFeature(f: QSqlDriver::QuerySize))
781 return d->sqlResult->size();
782 return -1;
783}
784
785/*!
786 Returns the number of rows affected by the result's SQL statement,
787 or -1 if it cannot be determined. Note that for \c SELECT
788 statements, the value is undefined; use size() instead. If the query
789 is not \l{isActive()}{active}, -1 is returned.
790
791 \sa size(), QSqlDriver::hasFeature()
792*/
793
794int QSqlQuery::numRowsAffected() const
795{
796 if (isActive())
797 return d->sqlResult->numRowsAffected();
798 return -1;
799}
800
801/*!
802 Returns error information about the last error (if any) that
803 occurred with this query.
804
805 \sa QSqlError, QSqlDatabase::lastError()
806*/
807
808QSqlError QSqlQuery::lastError() const
809{
810 return d->sqlResult->lastError();
811}
812
813/*!
814 Returns \c true if the query is currently positioned on a valid
815 record; otherwise returns \c false.
816*/
817
818bool QSqlQuery::isValid() const
819{
820 return d->sqlResult->isValid();
821}
822
823/*!
824
825 Returns \c true if the query is \e{active}. An active QSqlQuery is one
826 that has been \l{QSqlQuery::exec()} {exec()'d} successfully but not
827 yet finished with. When you are finished with an active query, you
828 can make the query inactive by calling finish() or clear(), or
829 you can delete the QSqlQuery instance.
830
831 \note Of particular interest is an active query that is a \c{SELECT}
832 statement. For some databases that support transactions, an active
833 query that is a \c{SELECT} statement can cause a \l{QSqlDatabase::}
834 {commit()} or a \l{QSqlDatabase::} {rollback()} to fail, so before
835 committing or rolling back, you should make your active \c{SELECT}
836 statement query inactive using one of the ways listed above.
837
838 \sa isSelect()
839 */
840bool QSqlQuery::isActive() const
841{
842 return d->sqlResult->isActive();
843}
844
845/*!
846 Returns \c true if the current query is a \c SELECT statement;
847 otherwise returns \c false.
848*/
849
850bool QSqlQuery::isSelect() const
851{
852 return d->sqlResult->isSelect();
853}
854
855/*!
856 Returns \c true if you can only scroll forward through a result set;
857 otherwise returns \c false.
858
859 \sa setForwardOnly(), next()
860*/
861bool QSqlQuery::isForwardOnly() const
862{
863 return d->sqlResult->isForwardOnly();
864}
865
866/*!
867 Sets forward only mode to \a forward. If \a forward is true, only
868 next() and seek() with positive values, are allowed for navigating
869 the results.
870
871 Forward only mode can be (depending on the driver) more memory
872 efficient since results do not need to be cached. It will also
873 improve performance on some databases. For this to be true, you must
874 call \c setForwardOnly() before the query is prepared or executed.
875 Note that the constructor that takes a query and a database may
876 execute the query.
877
878 Forward only mode is off by default.
879
880 Setting forward only to false is a suggestion to the database engine,
881 which has the final say on whether a result set is forward only or
882 scrollable. isForwardOnly() will always return the correct status of
883 the result set.
884
885 \note Calling setForwardOnly after execution of the query will result
886 in unexpected results at best, and crashes at worst.
887
888 \note To make sure the forward-only query completed successfully,
889 the application should check lastError() for an error not only after
890 executing the query, but also after navigating the query results.
891
892 \warning PostgreSQL: While navigating the query results in forward-only
893 mode, do not execute any other SQL command on the same database
894 connection. This will cause the query results to be lost.
895
896 \sa isForwardOnly(), next(), seek(), QSqlResult::setForwardOnly()
897*/
898void QSqlQuery::setForwardOnly(bool forward)
899{
900 d->sqlResult->setForwardOnly(forward);
901}
902
903/*!
904 Returns a QSqlRecord containing the field information for the
905 current query. If the query points to a valid row (isValid() returns
906 true), the record is populated with the row's values. An empty
907 record is returned when there is no active query (isActive() returns
908 false).
909
910 To retrieve values from a query, value() should be used since
911 its index-based lookup is faster.
912
913 In the following example, a \c{SELECT * FROM} query is executed.
914 Since the order of the columns is not defined, QSqlRecord::indexOf()
915 is used to obtain the index of a column.
916
917 \snippet code/src_sql_kernel_qsqlquery.cpp 1
918
919 \sa value()
920*/
921QSqlRecord QSqlQuery::record() const
922{
923 QSqlRecord rec = d->sqlResult->record();
924
925 if (isValid()) {
926 for (int i = 0; i < rec.count(); ++i)
927 rec.setValue(i, val: value(index: i));
928 }
929 return rec;
930}
931
932/*!
933 Clears the result set and releases any resources held by the
934 query. Sets the query state to inactive. You should rarely if ever
935 need to call this function.
936*/
937void QSqlQuery::clear()
938{
939 *this = QSqlQuery(driver()->createResult());
940}
941
942/*!
943 Prepares the SQL query \a query for execution. Returns \c true if the
944 query is prepared successfully; otherwise returns \c false.
945
946 The query may contain placeholders for binding values. Both Oracle
947 style colon-name (e.g., \c{:surname}), and ODBC style (\c{?})
948 placeholders are supported; but they cannot be mixed in the same
949 query. See the \l{QSqlQuery examples}{Detailed Description} for
950 examples.
951
952 Portability notes: Some databases choose to delay preparing a query
953 until it is executed the first time. In this case, preparing a
954 syntactically wrong query succeeds, but every consecutive exec()
955 will fail.
956 When the database does not support named placeholders directly,
957 the placeholder can only contain characters in the range [a-zA-Z0-9_].
958
959 For SQLite, the query string can contain only one statement at a time.
960 If more than one statement is given, the function returns \c false.
961
962 Example:
963
964 \snippet sqldatabase/sqldatabase.cpp 9
965
966 \sa exec(), bindValue(), addBindValue()
967*/
968bool QSqlQuery::prepare(const QString& query)
969{
970 if (d->ref.loadRelaxed() != 1) {
971 bool fo = isForwardOnly();
972 *this = QSqlQuery(driver()->createResult());
973 setForwardOnly(fo);
974 d->sqlResult->setNumericalPrecisionPolicy(d->sqlResult->numericalPrecisionPolicy());
975 } else {
976 d->sqlResult->setActive(false);
977 d->sqlResult->setLastError(QSqlError());
978 d->sqlResult->setAt(QSql::BeforeFirstRow);
979 d->sqlResult->setNumericalPrecisionPolicy(d->sqlResult->numericalPrecisionPolicy());
980 }
981 if (!driver()) {
982 qWarning(msg: "QSqlQuery::prepare: no driver");
983 return false;
984 }
985 if (!driver()->isOpen() || driver()->isOpenError()) {
986 qWarning(msg: "QSqlQuery::prepare: database not open");
987 return false;
988 }
989 if (query.isEmpty()) {
990 qWarning(msg: "QSqlQuery::prepare: empty query");
991 return false;
992 }
993#ifdef QT_DEBUG_SQL
994 qDebug("\n QSqlQuery::prepare: %s", query.toLocal8Bit().constData());
995#endif
996 return d->sqlResult->savePrepare(sqlquery: query);
997}
998
999/*!
1000 Executes a previously prepared SQL query. Returns \c true if the query
1001 executed successfully; otherwise returns \c false.
1002
1003 Note that the last error for this query is reset when exec() is
1004 called.
1005
1006 \sa prepare(), bindValue(), addBindValue(), boundValue(), boundValues()
1007*/
1008bool QSqlQuery::exec()
1009{
1010#ifdef QT_DEBUG_SQL
1011 QElapsedTimer t;
1012 t.start();
1013#endif
1014 d->sqlResult->resetBindCount();
1015
1016 if (d->sqlResult->lastError().isValid())
1017 d->sqlResult->setLastError(QSqlError());
1018
1019 bool retval = d->sqlResult->exec();
1020#ifdef QT_DEBUG_SQL
1021 qDebug().nospace() << "Executed prepared query (" << t.elapsed() << "ms, "
1022 << d->sqlResult->size() << " results, " << d->sqlResult->numRowsAffected()
1023 << " affected): " << d->sqlResult->lastQuery();
1024#endif
1025 return retval;
1026}
1027
1028/*! \enum QSqlQuery::BatchExecutionMode
1029
1030 \value ValuesAsRows - Updates multiple rows. Treats every entry in a QVariantList as a value for updating the next row.
1031 \value ValuesAsColumns - Updates a single row. Treats every entry in a QVariantList as a single value of an array type.
1032*/
1033
1034/*!
1035 \since 4.2
1036
1037 Executes a previously prepared SQL query in a batch. All the bound
1038 parameters have to be lists of variants. If the database doesn't
1039 support batch executions, the driver will simulate it using
1040 conventional exec() calls.
1041
1042 Returns \c true if the query is executed successfully; otherwise
1043 returns \c false.
1044
1045 Example:
1046
1047 \snippet code/src_sql_kernel_qsqlquery.cpp 2
1048
1049 The example above inserts four new rows into \c myTable:
1050
1051 \snippet code/src_sql_kernel_qsqlquery_snippet.cpp 3
1052
1053 To bind NULL values, a null QVariant of the relevant type has to be
1054 added to the bound QVariantList; for example, \c
1055 {QVariant(QVariant::String)} should be used if you are using
1056 strings.
1057
1058 \note Every bound QVariantList must contain the same amount of
1059 variants.
1060
1061 \note The type of the QVariants in a list must not change. For
1062 example, you cannot mix integer and string variants within a
1063 QVariantList.
1064
1065 The \a mode parameter indicates how the bound QVariantList will be
1066 interpreted. If \a mode is \c ValuesAsRows, every variant within
1067 the QVariantList will be interpreted as a value for a new row. \c
1068 ValuesAsColumns is a special case for the Oracle driver. In this
1069 mode, every entry within a QVariantList will be interpreted as
1070 array-value for an IN or OUT value within a stored procedure. Note
1071 that this will only work if the IN or OUT value is a table-type
1072 consisting of only one column of a basic type, for example \c{TYPE
1073 myType IS TABLE OF VARCHAR(64) INDEX BY BINARY_INTEGER;}
1074
1075 \sa prepare(), bindValue(), addBindValue()
1076*/
1077bool QSqlQuery::execBatch(BatchExecutionMode mode)
1078{
1079 d->sqlResult->resetBindCount();
1080 return d->sqlResult->execBatch(arrayBind: mode == ValuesAsColumns);
1081}
1082
1083/*!
1084 Set the placeholder \a placeholder to be bound to value \a val in
1085 the prepared statement. Note that the placeholder mark (e.g \c{:})
1086 must be included when specifying the placeholder name. If \a
1087 paramType is QSql::Out or QSql::InOut, the placeholder will be
1088 overwritten with data from the database after the exec() call.
1089 In this case, sufficient space must be pre-allocated to store
1090 the result into.
1091
1092 To bind a NULL value, use a null QVariant; for example, use
1093 \c {QVariant(QVariant::String)} if you are binding a string.
1094
1095 \sa addBindValue(), prepare(), exec(), boundValue(), boundValues()
1096*/
1097void QSqlQuery::bindValue(const QString& placeholder, const QVariant& val,
1098 QSql::ParamType paramType
1099)
1100{
1101 d->sqlResult->bindValue(placeholder, val, type: paramType);
1102}
1103
1104/*!
1105 Set the placeholder in position \a pos to be bound to value \a val
1106 in the prepared statement. Field numbering starts at 0. If \a
1107 paramType is QSql::Out or QSql::InOut, the placeholder will be
1108 overwritten with data from the database after the exec() call.
1109*/
1110void QSqlQuery::bindValue(int pos, const QVariant& val, QSql::ParamType paramType)
1111{
1112 d->sqlResult->bindValue(pos, val, type: paramType);
1113}
1114
1115/*!
1116 Adds the value \a val to the list of values when using positional
1117 value binding. The order of the addBindValue() calls determines
1118 which placeholder a value will be bound to in the prepared query.
1119 If \a paramType is QSql::Out or QSql::InOut, the placeholder will be
1120 overwritten with data from the database after the exec() call.
1121
1122 To bind a NULL value, use a null QVariant; for example, use \c
1123 {QVariant(QVariant::String)} if you are binding a string.
1124
1125 \sa bindValue(), prepare(), exec(), boundValue(), boundValues()
1126*/
1127void QSqlQuery::addBindValue(const QVariant& val, QSql::ParamType paramType)
1128{
1129 d->sqlResult->addBindValue(val, type: paramType);
1130}
1131
1132/*!
1133 Returns the value for the \a placeholder.
1134
1135 \sa boundValues(), bindValue(), addBindValue()
1136*/
1137QVariant QSqlQuery::boundValue(const QString& placeholder) const
1138{
1139 return d->sqlResult->boundValue(placeholder);
1140}
1141
1142/*!
1143 Returns the value for the placeholder at position \a pos.
1144*/
1145QVariant QSqlQuery::boundValue(int pos) const
1146{
1147 return d->sqlResult->boundValue(pos);
1148}
1149
1150/*!
1151 Returns a map of the bound values.
1152
1153 With named binding, the bound values can be examined in the
1154 following ways:
1155
1156 \snippet sqldatabase/sqldatabase.cpp 14
1157
1158 With positional binding, the code becomes:
1159
1160 \snippet sqldatabase/sqldatabase.cpp 15
1161
1162 \sa boundValue(), bindValue(), addBindValue()
1163*/
1164QMap<QString,QVariant> QSqlQuery::boundValues() const
1165{
1166 QMap<QString,QVariant> map;
1167
1168 const QVector<QVariant> values(d->sqlResult->boundValues());
1169 for (int i = 0; i < values.count(); ++i)
1170 map[d->sqlResult->boundValueName(pos: i)] = values.at(i);
1171 return map;
1172}
1173
1174/*!
1175 Returns the last query that was successfully executed.
1176
1177 In most cases this function returns the same string as lastQuery().
1178 If a prepared query with placeholders is executed on a DBMS that
1179 does not support it, the preparation of this query is emulated. The
1180 placeholders in the original query are replaced with their bound
1181 values to form a new query. This function returns the modified
1182 query. It is mostly useful for debugging purposes.
1183
1184 \sa lastQuery()
1185*/
1186QString QSqlQuery::executedQuery() const
1187{
1188 return d->sqlResult->executedQuery();
1189}
1190
1191/*!
1192 Returns the object ID of the most recent inserted row if the
1193 database supports it. An invalid QVariant will be returned if the
1194 query did not insert any value or if the database does not report
1195 the id back. If more than one row was touched by the insert, the
1196 behavior is undefined.
1197
1198 For MySQL databases the row's auto-increment field will be returned.
1199
1200 \note For this function to work in PSQL, the table table must
1201 contain OIDs, which may not have been created by default. Check the
1202 \c default_with_oids configuration variable to be sure.
1203
1204 \sa QSqlDriver::hasFeature()
1205*/
1206QVariant QSqlQuery::lastInsertId() const
1207{
1208 return d->sqlResult->lastInsertId();
1209}
1210
1211/*!
1212
1213 Instruct the database driver to return numerical values with a
1214 precision specified by \a precisionPolicy.
1215
1216 The Oracle driver, for example, can retrieve numerical values as
1217 strings to prevent the loss of precision. If high precision doesn't
1218 matter, use this method to increase execution speed by bypassing
1219 string conversions.
1220
1221 Note: Drivers that don't support fetching numerical values with low
1222 precision will ignore the precision policy. You can use
1223 QSqlDriver::hasFeature() to find out whether a driver supports this
1224 feature.
1225
1226 Note: Setting the precision policy doesn't affect the currently
1227 active query. Call \l{exec()}{exec(QString)} or prepare() in order
1228 to activate the policy.
1229
1230 \sa QSql::NumericalPrecisionPolicy, numericalPrecisionPolicy()
1231*/
1232void QSqlQuery::setNumericalPrecisionPolicy(QSql::NumericalPrecisionPolicy precisionPolicy)
1233{
1234 d->sqlResult->setNumericalPrecisionPolicy(precisionPolicy);
1235}
1236
1237/*!
1238 Returns the current precision policy.
1239
1240 \sa QSql::NumericalPrecisionPolicy, setNumericalPrecisionPolicy()
1241*/
1242QSql::NumericalPrecisionPolicy QSqlQuery::numericalPrecisionPolicy() const
1243{
1244 return d->sqlResult->numericalPrecisionPolicy();
1245}
1246
1247/*!
1248 \since 4.3.2
1249
1250 Instruct the database driver that no more data will be fetched from
1251 this query until it is re-executed. There is normally no need to
1252 call this function, but it may be helpful in order to free resources
1253 such as locks or cursors if you intend to re-use the query at a
1254 later time.
1255
1256 Sets the query to inactive. Bound values retain their values.
1257
1258 \sa prepare(), exec(), isActive()
1259*/
1260void QSqlQuery::finish()
1261{
1262 if (isActive()) {
1263 d->sqlResult->setLastError(QSqlError());
1264 d->sqlResult->setAt(QSql::BeforeFirstRow);
1265 d->sqlResult->detachFromResultSet();
1266 d->sqlResult->setActive(false);
1267 }
1268}
1269
1270/*!
1271 \since 4.4
1272
1273 Discards the current result set and navigates to the next if available.
1274
1275 Some databases are capable of returning multiple result sets for
1276 stored procedures or SQL batches (a query strings that contains
1277 multiple statements). If multiple result sets are available after
1278 executing a query this function can be used to navigate to the next
1279 result set(s).
1280
1281 If a new result set is available this function will return true.
1282 The query will be repositioned on an \e invalid record in the new
1283 result set and must be navigated to a valid record before data
1284 values can be retrieved. If a new result set isn't available the
1285 function returns \c false and the query is set to inactive. In any
1286 case the old result set will be discarded.
1287
1288 When one of the statements is a non-select statement a count of
1289 affected rows may be available instead of a result set.
1290
1291 Note that some databases, i.e. Microsoft SQL Server, requires
1292 non-scrollable cursors when working with multiple result sets. Some
1293 databases may execute all statements at once while others may delay
1294 the execution until the result set is actually accessed, and some
1295 databases may have restrictions on which statements are allowed to
1296 be used in a SQL batch.
1297
1298 \sa QSqlDriver::hasFeature(), setForwardOnly(), next(), isSelect(),
1299 numRowsAffected(), isActive(), lastError()
1300*/
1301bool QSqlQuery::nextResult()
1302{
1303 if (isActive())
1304 return d->sqlResult->nextResult();
1305 return false;
1306}
1307
1308QT_END_NAMESPACE
1309

source code of qtbase/src/sql/kernel/qsqlquery.cpp