source: trunk/doc/src/sql-programming/sql-programming.qdoc@ 788

/****************************************************************************
**
** Copyright (C) 2010 Nokia Corporation and/or its subsidiary(-ies).
** All rights reserved.
** Contact: Nokia Corporation ([email protected])
**
** This file is part of the documentation of the Qt Toolkit.
**
** $QT_BEGIN_LICENSE:LGPL$
** Commercial Usage
** Licensees holding valid Qt Commercial licenses may use this file in
** accordance with the Qt Commercial License Agreement provided with the
** Software or, alternatively, in accordance with the terms contained in
** a written agreement between you and Nokia.
**
** GNU Lesser General Public License Usage
** Alternatively, this file may be used under the terms of the GNU Lesser
** General Public License version 2.1 as published by the Free Software
** Foundation and appearing in the file LICENSE.LGPL included in the
** packaging of this file.  Please review the following information to
** ensure the GNU Lesser General Public License version 2.1 requirements
** will be met: http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html.
**
** In addition, as a special exception, Nokia gives you certain additional
** rights.  These rights are described in the Nokia Qt LGPL Exception
** version 1.1, included in the file LGPL_EXCEPTION.txt in this package.
**
** GNU General Public License Usage
** Alternatively, this file may be used under the terms of the GNU
** General Public License version 3.0 as published by the Free Software
** Foundation and appearing in the file LICENSE.GPL included in the
** packaging of this file.  Please review the following information to
** ensure the GNU General Public License version 3.0 requirements will be
** met: http://www.gnu.org/copyleft/gpl.html.
**
** If you have questions regarding the use of this file, please contact
** Nokia at [email protected].
** $QT_END_LICENSE$
**
****************************************************************************/

/*!
    \group database
    \title Database Classes

    \brief Database related classes, e.g. for SQL databases.
*/

/*!
    \page sql-programming.html
    \title SQL Programming
    \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
    \o \l{Database Classes}
    \o \l{Connecting to Databases}
        \list
        \o \l{SQL Database Drivers}
        \endlist
    \o \l{Executing SQL Statements}
        \list
        \o \l{Recommended Use of Data Types in Databases}
        \endlist
    \o \l{Using the SQL Model Classes}
    \o \l{Presenting Data in a Table View}
    \o \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

    \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 doc/src/snippets/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 doc/src/snippets/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 doc/src/snippets/sqldatabase/sqldatabase.cpp 28
    \snippet doc/src/snippets/sqldatabase/sqldatabase.cpp 29
    \snippet doc/src/snippets/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
    
    \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 doc/src/snippets/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 doc/src/snippets/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 used with Qt supported
    Databases, please refer to \l{Recommended Use of Data Types in Databases}{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 avaliable 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.