1QSqlDatabase(3qt) QSqlDatabase(3qt)
2
6 QSqlDatabase - Used to create SQL database connections and to provide
7 transaction handling
8
10 #include <qsqldatabase.h>
11 Inherits QObject.
13 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 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 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 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
78 The QSqlDatabase class is used to create SQL database connections and
79 to provide transaction handling.
80 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 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 See also Database Classes.
92
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 The currently available drivers are:
102 <center>.nf
104 </center>
106 Additional third party drivers, including your own custom drivers, can
108 be loaded dynamically.
109 See also registerSqlDriver().
111
113 char * objname = 0 ) [protected]
114 This is an overloaded member function, provided for convenience. It
115 behaves essentially like the above function.
116 Creates a database connection using the driver driver, with the parent
118 parent and the object name objname.
119 Warning: The framework takes ownership of the driver pointer, so it
121 should not be deleted.
122
124 Destroys the object and frees any allocated resources.
125
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 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 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 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 See also database() and removeDatabase().
149 Examples:
151
153 & connectionName = defaultConnection ) [static]
154 This is an overloaded member function, provided for convenience. It
155 behaves essentially like the above function.
156 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 #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 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 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 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 unix:LIBS += -lpq
188 win32:LIBS += libpqdll.lib
189 You will need to have the client library in your linker's search path.
191 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 <center>.nf
197 </center>
199 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 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 See also drivers().
211
213 Closes the database connection, freeing any resources acquired.
214 See also removeDatabase().
216
218 Commits a transaction to the database if the driver supports
219 transactions. Returns TRUE if the operation succeeded; otherwise
220 returns FALSE.
221 See also QSqlDriver::hasFeature() and rollback().
223
225 Returns the database connect options. See the "connectOptions" property
226 for details.
227
229 defaultConnection ) [static]
230 Returns TRUE if the list of database connections contains
231 connectionName; otherwise returns FALSE.
232
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 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 Examples:
248
250 Returns the name of the database. See the "databaseName" property for
251 details.
252
254 Returns the database driver used to access the database connection.
255
257 Returns the name of the driver used by the database connection.
258
260 Returns a list of all the available database drivers.
261 Note that if you want to iterate over the list, you should iterate over
263 a copy, e.g.
264 QStringList list = QSqlDatabase::drivers();
266 QStringList::Iterator it = list.begin();
267 while( it != list.end() ) {
268 myProcessing( *it );
269 ++it;
270 }
271
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 See also QSqlQuery and lastError().
279
281 Returns the host name where the database resides. See the "hostName"
282 property for details.
283
285 Returns TRUE if a driver called name is available; otherwise returns
286 FALSE.
287 See also drivers().
289
291 Returns TRUE if the database connection is currently open; otherwise
292 returns FALSE.
293
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
300 Returns information about the last error that occurred on the database.
301 See QSqlError for more information.
302 Examples:
304
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 See also lastError().
311 Examples:
313
315 This is an overloaded member function, provided for convenience. It
316 behaves essentially like the above function.
317 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 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 See also lastError().
327
329 Returns the password used to connect to the database. See the
330 "password" property for details.
331
333 Returns the port used to connect to the database. See the "port"
334 property for details.
335
337 Returns the primary index for table tablename. If no primary index
338 exists an empty QSqlIndex will be returned.
339
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 See also recordInfo().
347
349 This is an overloaded member function, provided for convenience. It
350 behaves essentially like the above function.
351 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 See also recordInfo().
357
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 See also QSqlRecordInfo, QSqlFieldInfo, and record().
364
366 This is an overloaded member function, provided for convenience. It
367 behaves essentially like the above function.
368 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 See also QSqlRecordInfo, QSqlFieldInfo, and record().
374
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 Example usage:
382 QSqlDatabase::registerSqlDriver( "MYDRIVER", new QSqlDriverCreator<MyDatabaseDriver> );
384 QSqlDatabase* db = QSqlDatabase::addDatabase( "MYDRIVER" );
385 ...
386 Warning: The framework takes ownership of the creator pointer, so it
388 should not be deleted.
389
391 Removes the database connection connectionName from the list of
392 database connections.
393 Warning: There should be no open queries on the database connection
395 when this function is called, otherwise a resource leak will occur.
396
398 This is an overloaded member function, provided for convenience. It
399 behaves essentially like the above function.
400 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 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
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 See also QSqlDriver::hasFeature(), commit(), and transaction().
415
417 )
418 Sets the database connect options to options. See the "connectOptions"
419 property for details.
420
422 Sets the name of the database to name. See the "databaseName" property
423 for details.
424
426 Sets the host name where the database resides to host. See the
427 "hostName" property for details.
428
430 Sets the password used to connect to the database to password. See the
431 "password" property for details.
432
434 Sets the port used to connect to the database to p. See the "port"
435 property for details.
436
438 Sets the user name connected to the database to name. See the
439 "userName" property for details.
440
442 Returns a list of the database's tables, system tables and views, as
443 specified by the parameter type.
444 Note that if you want to iterate over the list, you should iterate over
446 a copy, e.g.
447 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 Example: sql/sqltable/main.cpp.
456
458 This is an overloaded member function, provided for convenience. It
459 behaves essentially like the above function.
460 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 Note that if you want to iterate over the list, you should iterate over
466 a copy, e.g.
467 QStringList list = myDatabase.tables();
469 QStringList::Iterator it = list.begin();
470 while( it != list.end() ) {
471 myProcessing( *it );
472 ++it;
473 }
474
476 Begins a transaction on the database if the driver supports
477 transactions. Returns TRUE if the operation succeeded; otherwise
478 returns FALSE.
479 See also QSqlDriver::hasFeature(), commit(), and rollback().
481
483 Returns the user name connected to the database. See the "userName"
484 property for details.
485 Property Documentation
488 This property holds the database connect options.
489 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 <center>.nf
495 </center>
497 Example of usage:
499 ...
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 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 See also
528 Set this property's value with setConnectOptions() and get this
530 property's value with connectOptions().
531
533 This property holds the name of the database.
534 Note that the database name is the TNS Service Name for the QOCI8
536 (Oracle) driver.
537 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 ...
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 There is no default value.
553 Set this property's value with setDatabaseName() and get this
555 property's value with databaseName().
556
558 This property holds the host name where the database resides.
559 There is no default value.
561 Set this property's value with setHostName() and get this property's
563 value with hostName().
564
566 This property holds the password used to connect to the database.
567 There is no default value.
569 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 See also open().
575 Set this property's value with setPassword() and get this property's
577 value with password().
578
580 This property holds the port used to connect to the database.
581 There is no default value.
583 Set this property's value with setPort() and get this property's value
585 with port().
586
588 This property holds the user name connected to the database.
589 There is no default value.
591 Set this property's value with setUserName() and get this property's
593 value with userName().
594
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
606 Generated automatically from the source code.
607
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 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 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).
622Trolltech AS 2 February 2007 QSqlDatabase(3qt)