1QSqlDatabase(3qt)                                            QSqlDatabase(3qt)
2
3
4

NAME

6       QSqlDatabase - Used to create SQL database connections and to provide
7       transaction handling
8

SYNOPSIS

10       #include <qsqldatabase.h>
11
12       Inherits QObject.
13
14   Public Members
15       ~QSqlDatabase ()
16       bool open ()
17       bool open ( const QString & user, const QString & password )
18       void close ()
19       bool isOpen () const
20       bool isOpenError () const
21       QStringList tables () const
22       QStringList tables ( QSql::TableType type ) const
23       QSqlIndex primaryIndex ( const QString & tablename ) const
24       QSqlRecord record ( const QString & tablename ) const
25       QSqlRecord record ( const QSqlQuery & query ) const
26       QSqlRecordInfo recordInfo ( const QString & tablename ) const
27       QSqlRecordInfo recordInfo ( const QSqlQuery & query ) const
28       QSqlQuery exec ( const QString & query = QString::null ) const
29       QSqlError lastError () const
30       bool transaction ()
31       bool commit ()
32       bool rollback ()
33       virtual void setDatabaseName ( const QString & name )
34       virtual void setUserName ( const QString & name )
35       virtual void setPassword ( const QString & password )
36       virtual void setHostName ( const QString & host )
37       virtual void setPort ( int p )
38       void setConnectOptions ( const QString & options = QString::null )
39       QString databaseName () const
40       QString userName () const
41       QString password () const
42       QString hostName () const
43       QString driverName () const
44       int port () const
45       QString connectOptions () const
46       QSqlDriver * driver () const
47
48   Static Public Members
49       QSqlDatabase * addDatabase ( const QString & type, const QString &
50           connectionName = defaultConnection )
51       QSqlDatabase * addDatabase ( QSqlDriver * driver, const QString &
52           connectionName = defaultConnection )
53       QSqlDatabase * database ( const QString & connectionName =
54           defaultConnection, bool open = TRUE )
55       void removeDatabase ( const QString & connectionName )
56       void removeDatabase ( QSqlDatabase * db )
57       bool contains ( const QString & connectionName = defaultConnection )
58       QStringList drivers ()
59       void registerSqlDriver ( const QString & name, const
60           QSqlDriverCreatorBase * creator )
61       bool isDriverAvailable ( const QString & name )
62
63   Properties
64       QString connectOptions - the database connect options
65       QString databaseName - the name of the database
66       QString hostName - the host name where the database resides
67       QString password - the password used to connect to the database
68       int port - the port used to connect to the database
69       QString userName - the user name connected to the database
70
71   Protected Members
72       QSqlDatabase ( const QString & type, const QString & name, QObject *
73           parent = 0, const char * objname = 0 )
74       QSqlDatabase ( QSqlDriver * driver, QObject * parent = 0, const char *
75           objname = 0 )
76

DESCRIPTION

78       The QSqlDatabase class is used to create SQL database connections and
79       to provide transaction handling.
80
81       Note that transaction handling is not supported by every SQL database.
82       You can find out whether transactions are supported using
83       QSqlDriver::hasFeature().
84
85       The QSqlDatabase class provides an abstract interface for accessing
86       many types of database backends. Database-specific drivers are used
87       internally to actually access and manipulate data, (see QSqlDriver).
88       Result set objects provide the interface for executing and manipulating
89       SQL queries (see QSqlQuery).
90
91       See also Database Classes.
92

MEMBER FUNCTION DOCUMENTATION

QSqlDatabase::QSqlDatabase ( const QString & type, const QString & name,

95       QObject * parent = 0, const char * objname = 0 ) [protected]
96       Creates a QSqlDatabase connection called name that uses the driver
97       referred to by type, with the parent parent and the object name
98       objname. If the type is not recognized, the database connection will
99       have no functionality.
100
101       The currently available drivers are:
102
103       <center>.nf
104
105       </center>
106
107       Additional third party drivers, including your own custom drivers, can
108       be loaded dynamically.
109
110       See also registerSqlDriver().
111

QSqlDatabase::QSqlDatabase ( QSqlDriver * driver, QObject * parent = 0, const

113       char * objname = 0 ) [protected]
114       This is an overloaded member function, provided for convenience. It
115       behaves essentially like the above function.
116
117       Creates a database connection using the driver driver, with the parent
118       parent and the object name objname.
119
120       Warning: The framework takes ownership of the driver pointer, so it
121       should not be deleted.
122

QSqlDatabase::~QSqlDatabase ()

124       Destroys the object and frees any allocated resources.
125

QSqlDatabase * QSqlDatabase::addDatabase ( const QString & type, const QString

127       & connectionName = defaultConnection ) [static]
128       Adds a database to the list of database connections using the driver
129       type and the connection name connectionName.
130
131       The database connection is referred to by connectionName. The newly
132       added database connection is returned. This pointer is owned by
133       QSqlDatabase and will be deleted on program exit or when
134       removeDatabase() is called.
135
136       If connectionName is not specified, the newly added database connection
137       becomes the default database connection for the application, and
138       subsequent calls to database() (without a database name parameter) will
139       return a pointer to it. If connectionName is given, use
140       database(connectionName) to retrieve a pointer to the database
141       connection.
142
143       Warning: If you add a database with the same name as an existing
144       database, the new database will replace the old one. This will happen
145       automatically if you call this function more than once without
146       specifying connectionName.
147
148       See also database() and removeDatabase().
149
150       Examples:
151

QSqlDatabase * QSqlDatabase::addDatabase ( QSqlDriver * driver, const QString

153       & connectionName = defaultConnection ) [static]
154       This is an overloaded member function, provided for convenience. It
155       behaves essentially like the above function.
156
157       This function is useful if you need to set up the database connection
158       and instantiate the driver yourself. If you do this, it is recommended
159       that you include the driver code in your own application. For example,
160       setting up a custom PostgreSQL connection and instantiating the QPSQL7
161       driver can be done the following way:
162
163           #include "qtdir/src/sql/drivers/psql/qsql_psql.cpp"
164       (We assume that qtdir is the directory where Qt is installed.) This
165       will pull in the code that is needed to use the PostgreSQL client
166       library and to instantiate a QPSQLDriver object, assuming that you have
167       the PostgreSQL headers somewhere in your include search path.
168
169           PGconn* con = PQconnectdb( "host=server user=bart password=simpson dbname=springfield" );
170           QPSQLDriver* drv =  new QPSQLDriver( con );
171           QSqlDatabase* db = QSqlDatabase::addDatabase( drv ); // becomes the new default connection
172           QSqlQuery q;
173           q.exec( "SELECT * FROM people" );
174           ...
175
176       The above code sets up a PostgreSQL connection and instantiates a
177       QPSQLDriver object. Next, addDatabase() is called to add the connection
178       to the known connections so that it can be used by the Qt SQL classes.
179       When a driver is instantiated with a connection handle (or set of
180       handles), Qt assumes that you have already opened the database
181       connection.
182
183       Remember that you must link your application against the database
184       client library as well. The simplest way to do this is to add lines
185       like those below to your .pro file:
186
187           unix:LIBS += -lpq
188           win32:LIBS += libpqdll.lib
189
190       You will need to have the client library in your linker's search path.
191
192       The method described above will work for all the drivers, the only
193       difference is the arguments the driver constructors take. Below is an
194       overview of the drivers and their constructor arguments.
195
196       <center>.nf
197
198       </center>
199
200       Note: The host name (or service name) is needed when constructing the
201       QTDSDriver for creating new connections for internal queries. This is
202       to prevent the simultaneous usage of several QSqlQuery/QSqlCursor
203       objects from blocking each other.
204
205       Warning: The SQL framework takes ownership of the driver pointer, and
206       it should not be deleted. The returned QSqlDatabase object is owned by
207       the framework and must not be deleted. If you want to explicitly remove
208       the connection, use removeDatabase()
209
210       See also drivers().
211

void QSqlDatabase::close ()

213       Closes the database connection, freeing any resources acquired.
214
215       See also removeDatabase().
216

bool QSqlDatabase::commit ()

218       Commits a transaction to the database if the driver supports
219       transactions. Returns TRUE if the operation succeeded; otherwise
220       returns FALSE.
221
222       See also QSqlDriver::hasFeature() and rollback().
223

QString QSqlDatabase::connectOptions () const

225       Returns the database connect options. See the "connectOptions" property
226       for details.
227

bool QSqlDatabase::contains ( const QString & connectionName =

229       defaultConnection ) [static]
230       Returns TRUE if the list of database connections contains
231       connectionName; otherwise returns FALSE.
232

QSqlDatabase * QSqlDatabase::database ( const QString & connectionName =

234       defaultConnection, bool open = TRUE ) [static]
235       Returns the database connection called connectionName. The database
236       connection must have been previously added with addDatabase(). If open
237       is TRUE (the default) and the database connection is not already open
238       it is opened now. If no connectionName is specified the default
239       connection is used. If connectionName does not exist in the list of
240       databases, 0 is returned. The pointer returned is owned by QSqlDatabase
241       and should not be deleted.
242
243       Warning: There are restrictions on the use of database connections in
244       threaded applications. Please see the Thread Support in Qt document for
245       more information about threading and SQL databases.
246
247       Examples:
248

QString QSqlDatabase::databaseName () const

250       Returns the name of the database. See the "databaseName" property for
251       details.
252

QSqlDriver * QSqlDatabase::driver () const

254       Returns the database driver used to access the database connection.
255

QString QSqlDatabase::driverName () const

257       Returns the name of the driver used by the database connection.
258

QStringList QSqlDatabase::drivers () [static]

260       Returns a list of all the available database drivers.
261
262       Note that if you want to iterate over the list, you should iterate over
263       a copy, e.g.
264
265           QStringList list = QSqlDatabase::drivers();
266           QStringList::Iterator it = list.begin();
267           while( it != list.end() ) {
268               myProcessing( *it );
269               ++it;
270           }
271

QSqlQuery QSqlDatabase::exec ( const QString & query = QString::null ) const

273       Executes a SQL statement (e.g. an INSERT, UPDATE or DELETE statement)
274       on the database, and returns a QSqlQuery object. Use lastError() to
275       retrieve error information. If query is QString::null, an empty,
276       invalid query is returned and lastError() is not affected.
277
278       See also QSqlQuery and lastError().
279

QString QSqlDatabase::hostName () const

281       Returns the host name where the database resides. See the "hostName"
282       property for details.
283

bool QSqlDatabase::isDriverAvailable ( const QString & name ) [static]

285       Returns TRUE if a driver called name is available; otherwise returns
286       FALSE.
287
288       See also drivers().
289

bool QSqlDatabase::isOpen () const

291       Returns TRUE if the database connection is currently open; otherwise
292       returns FALSE.
293

bool QSqlDatabase::isOpenError () const

295       Returns TRUE if there was an error opening the database connection;
296       otherwise returns FALSE. Error information can be retrieved using the
297       lastError() function.
298

QSqlError QSqlDatabase::lastError () const

300       Returns information about the last error that occurred on the database.
301       See QSqlError for more information.
302
303       Examples:
304

bool QSqlDatabase::open ()

306       Opens the database connection using the current connection values.
307       Returns TRUE on success; otherwise returns FALSE. Error information can
308       be retrieved using the lastError() function.
309
310       See also lastError().
311
312       Examples:
313

bool QSqlDatabase::open ( const QString & user, const QString & password )

315       This is an overloaded member function, provided for convenience. It
316       behaves essentially like the above function.
317
318       Opens the database connection using the given user name and password.
319       Returns TRUE on success; otherwise returns FALSE. Error information can
320       be retrieved using the lastError() function.
321
322       This function does not store the password it is given. Instead, the
323       password is passed directly to the driver for opening a connection and
324       is then discarded.
325
326       See also lastError().
327

QString QSqlDatabase::password () const

329       Returns the password used to connect to the database. See the
330       "password" property for details.
331

int QSqlDatabase::port () const

333       Returns the port used to connect to the database. See the "port"
334       property for details.
335

QSqlIndex QSqlDatabase::primaryIndex ( const QString & tablename ) const

337       Returns the primary index for table tablename. If no primary index
338       exists an empty QSqlIndex will be returned.
339

QSqlRecord QSqlDatabase::record ( const QString & tablename ) const

341       Returns a QSqlRecord populated with the names of all the fields in the
342       table (or view) called tablename. The order in which the fields appear
343       in the record is undefined. If no such table (or view) exists, an empty
344       record is returned.
345
346       See also recordInfo().
347

QSqlRecord QSqlDatabase::record ( const QSqlQuery & query ) const

349       This is an overloaded member function, provided for convenience. It
350       behaves essentially like the above function.
351
352       Returns a QSqlRecord populated with the names of all the fields used in
353       the SQL query. If the query is a "SELECT *" the order in which fields
354       appear in the record is undefined.
355
356       See also recordInfo().
357

QSqlRecordInfo QSqlDatabase::recordInfo ( const QString & tablename ) const

359       Returns a QSqlRecordInfo populated with meta data about the table or
360       view tablename. If no such table (or view) exists, an empty record is
361       returned.
362
363       See also QSqlRecordInfo, QSqlFieldInfo, and record().
364

QSqlRecordInfo QSqlDatabase::recordInfo ( const QSqlQuery & query ) const

366       This is an overloaded member function, provided for convenience. It
367       behaves essentially like the above function.
368
369       Returns a QSqlRecordInfo object with meta data for the QSqlQuery query.
370       Note that this overloaded function may return less information than the
371       recordInfo() function which takes the name of a table as parameter.
372
373       See also QSqlRecordInfo, QSqlFieldInfo, and record().
374

void QSqlDatabase::registerSqlDriver ( const QString & name, const

376       QSqlDriverCreatorBase * creator ) [static]
377       This function registers a new SQL driver called name, within the SQL
378       framework. This is useful if you have a custom SQL driver and don't
379       want to compile it as a plugin.
380
381       Example usage:
382
383           QSqlDatabase::registerSqlDriver( "MYDRIVER", new QSqlDriverCreator<MyDatabaseDriver> );
384           QSqlDatabase* db = QSqlDatabase::addDatabase( "MYDRIVER" );
385           ...
386
387       Warning: The framework takes ownership of the creator pointer, so it
388       should not be deleted.
389

void QSqlDatabase::removeDatabase ( const QString & connectionName ) [static]

391       Removes the database connection connectionName from the list of
392       database connections.
393
394       Warning: There should be no open queries on the database connection
395       when this function is called, otherwise a resource leak will occur.
396

void QSqlDatabase::removeDatabase ( QSqlDatabase * db ) [static]

398       This is an overloaded member function, provided for convenience. It
399       behaves essentially like the above function.
400
401       Removes the database connection db from the list of database
402       connections. The QSqlDatabase object is destroyed when it is removed
403       from the list.
404
405       Warning: The db pointer is not valid after this function has been
406       called. There should be no open queries on the database connection when
407       this function is called, otherwise a resource leak will occur.
408

bool QSqlDatabase::rollback ()

410       Rolls a transaction back on the database if the driver supports
411       transactions. Returns TRUE if the operation succeeded; otherwise
412       returns FALSE.
413
414       See also QSqlDriver::hasFeature(), commit(), and transaction().
415

void QSqlDatabase::setConnectOptions ( const QString & options = QString::null

417       )
418       Sets the database connect options to options. See the "connectOptions"
419       property for details.
420

void QSqlDatabase::setDatabaseName ( const QString & name ) [virtual]

422       Sets the name of the database to name. See the "databaseName" property
423       for details.
424

void QSqlDatabase::setHostName ( const QString & host ) [virtual]

426       Sets the host name where the database resides to host. See the
427       "hostName" property for details.
428

void QSqlDatabase::setPassword ( const QString & password ) [virtual]

430       Sets the password used to connect to the database to password. See the
431       "password" property for details.
432

void QSqlDatabase::setPort ( int p ) [virtual]

434       Sets the port used to connect to the database to p. See the "port"
435       property for details.
436

void QSqlDatabase::setUserName ( const QString & name ) [virtual]

438       Sets the user name connected to the database to name. See the
439       "userName" property for details.
440

QStringList QSqlDatabase::tables ( QSql::TableType type ) const

442       Returns a list of the database's tables, system tables and views, as
443       specified by the parameter type.
444
445       Note that if you want to iterate over the list, you should iterate over
446       a copy, e.g.
447
448           QStringList list = myDatabase.tables( QSql::Tables | QSql::Views );
449           QStringList::Iterator it = list.begin();
450           while( it != list.end() ) {
451               myProcessing( *it );
452               ++it;
453           }
454
455       Example: sql/sqltable/main.cpp.
456

QStringList QSqlDatabase::tables () const

458       This is an overloaded member function, provided for convenience. It
459       behaves essentially like the above function.
460
461       Returns a list of the database's tables that are visible to the user.
462       To include views or system tables, use the version of this function
463       that takes a table type parameter.
464
465       Note that if you want to iterate over the list, you should iterate over
466       a copy, e.g.
467
468           QStringList list = myDatabase.tables();
469           QStringList::Iterator it = list.begin();
470           while( it != list.end() ) {
471               myProcessing( *it );
472               ++it;
473           }
474

bool QSqlDatabase::transaction ()

476       Begins a transaction on the database if the driver supports
477       transactions. Returns TRUE if the operation succeeded; otherwise
478       returns FALSE.
479
480       See also QSqlDriver::hasFeature(), commit(), and rollback().
481

QString QSqlDatabase::userName () const

483       Returns the user name connected to the database. See the "userName"
484       property for details.
485
486   Property Documentation

QString connectOptions

488       This property holds the database connect options.
489
490       The format of the options string is a semi-colon separated list of
491       option names or option = value pairs. The options depend on the
492       database client used:
493
494       <center>.nf
495
496       </center>
497
498       Example of usage:
499
500           ...
501           // MySQL connection
502           db->setConnectOptions( "CLIENT_SSL;CLIENT_IGNORE_SPACE" ); // use an SSL connection to the server
503           if ( !db->open() ) {
504               db->setConnectOptions(); // clears the connect option string
505               ...
506           }
507           ...
508           // PostgreSQL connection
509           db->setConnectOptions( "requiressl=1" ); // enable PostgreSQL SSL connections
510           if ( !db->open() ) {
511               db->setConnectOptions(); // clear options
512               ...
513           }
514           ...
515           // ODBC connection
516           db->setConnectOptions( "SQL_ATTR_ACCESS_MODE=SQL_MODE_READ_ONLY;SQL_ATTR_TRACE=SQL_OPT_TRACE_ON" ); // set ODBC options
517           if ( !db->open() ) {
518               db->setConnectOptions(); // don't try to set this option
519               ...
520           }
521
522       Please refer to the client library documentation for more information
523       about the different options. The options will be set prior to opening
524       the database connection. Setting new options without re-opening the
525       connection does nothing.
526
527       See also
528
529       Set this property's value with setConnectOptions() and get this
530       property's value with connectOptions().
531

QString databaseName

533       This property holds the name of the database.
534
535       Note that the database name is the TNS Service Name for the QOCI8
536       (Oracle) driver.
537
538       For the QODBC3 driver it can either be a DSN, a DSN filename (the file
539       must have a .dsn extension), or a connection string. MS Access users
540       can for example use the following connection string to open a .mdb file
541       directly, instead of having to create a DSN entry in the ODBC manager:
542
543           ...
544           db = QSqlDatabase::addDatabase( "QODBC3" );
545           db->setDatabaseName( "DRIVER={Microsoft Access Driver (*.mdb)};FIL={MS Access};DBQ=myaccessfile.mdb" );
546           if ( db->open() ) {
547               // success!
548           }
549           ...
550       ("FIL" is the required spelling in Microsoft's API.)
551
552       There is no default value.
553
554       Set this property's value with setDatabaseName() and get this
555       property's value with databaseName().
556

QString hostName

558       This property holds the host name where the database resides.
559
560       There is no default value.
561
562       Set this property's value with setHostName() and get this property's
563       value with hostName().
564

QString password

566       This property holds the password used to connect to the database.
567
568       There is no default value.
569
570       Warning: This function stores the password in plain text within Qt. Use
571       the open() call that takes a password as parameter to avoid this
572       behaviour.
573
574       See also open().
575
576       Set this property's value with setPassword() and get this property's
577       value with password().
578

int port

580       This property holds the port used to connect to the database.
581
582       There is no default value.
583
584       Set this property's value with setPort() and get this property's value
585       with port().
586

QString userName

588       This property holds the user name connected to the database.
589
590       There is no default value.
591
592       Set this property's value with setUserName() and get this property's
593       value with userName().
594
595

SEE ALSO

597       http://doc.trolltech.com/qsqldatabase.html
598       http://www.trolltech.com/faq/tech.html
599
601       Copyright 1992-2007 Trolltech ASA, http://www.trolltech.com.  See the
602       license file included in the distribution for a complete license
603       statement.
604

AUTHOR

606       Generated automatically from the source code.
607

BUGS

609       If you find a bug in Qt, please report it as described in
610       http://doc.trolltech.com/bughowto.html.  Good bug reports help us to
611       help you. Thank you.
612
613       The definitive Qt documentation is provided in HTML format; it is
614       located at $QTDIR/doc/html and can be read using Qt Assistant or with a
615       web browser. This man page is provided as a convenience for those users
616       who prefer man pages, although this format is not officially supported
617       by Trolltech.
618
619       If you find errors in this manual page, please report them to qt-
620       bugs@trolltech.com.  Please include the name of the manual page
621       (qsqldatabase.3qt) and the Qt version (3.3.8).
622
623
624
625Trolltech AS                    2 February 2007              QSqlDatabase(3qt)
Impressum